* Added more documentation.
* Minor API changes.
5 // Created by Jens Alfke on 5/18/08.
6 // Copyright 2008 Jens Alfke. All rights reserved.
9 #import "TCPEndpoint.h"
11 @class TCPReader, TCPWriter, TCPListener;
12 @protocol TCPConnectionDelegate;
16 kTCP_Disconnected = -1,
21 } TCPConnectionStatus;
24 /** A generic class that manages a TCP socket connection.
25 It creates a TCPReader and a TCPWriter to handle I/O.
26 TCPConnection itself mostly deals with SSL setup and opening/closing the socket.
27 (The SSL related methods are inherited from TCPEndpoint.) */
28 @interface TCPConnection : TCPEndpoint
33 BOOL _isIncoming, _checkedPeerCert;
34 TCPConnectionStatus _status;
40 /** Initializes a TCPConnection to the given IP address.
41 Afer configuring settings, you should call -open to begin the connection. */
42 - (id) initToAddress: (IPAddress*)address;
44 /** Initializes a TCPConnection to the given IP address, binding to a specific outgoing port
45 number. (This is usually only necessary when attempting to tunnel through a NAT.) */
46 - (id) initToAddress: (IPAddress*)address
47 localPort: (UInt16)localPort;
49 /** Initializes a TCPConnection from an incoming TCP socket.
50 You don't usually need to call this; TCPListener does it automatically. */
51 - (id) initIncomingFromSocket: (CFSocketNativeHandle)socket listener: (TCPListener*)listener;
53 /** The delegate object that will be called when the connection opens, closes or receives messages. */
54 @property (assign) id<TCPConnectionDelegate> delegate;
56 /** The certificate(s) of the connected peer, if this connection uses SSL.
57 The items in the array are SecCertificateRefs; use the Keychain API to work with them. */
58 @property (readonly) NSArray *peerSSLCerts;
60 /** Connection's current status */
61 @property (readonly) TCPConnectionStatus status;
63 /** Opens the connection. This happens asynchronously; wait for a delegate method to be called.
64 You don't need to open incoming connections received via a TCPListener. */
67 /** Closes the connection, after waiting for all in-progress messages to be sent or received.
68 This happens asynchronously; wait for a delegate method to be called.*/
71 /** Closes the connection, like -close, but if it hasn't closed by the time the timeout
72 expires, it will disconnect the socket. */
73 - (void) closeWithTimeout: (NSTimeInterval)timeout;
75 /** Closes all open TCPConnections. */
76 + (void) closeAllWithTimeout: (NSTimeInterval)timeout;
78 /** Blocks until all open TCPConnections close. You should call +closeAllWithTimeout: first. */
79 + (void) waitTillAllClosed;
81 /** The IP address of the other peer. */
82 @property (readonly) IPAddress *address;
84 /** The TCPListener that created this incoming connection, or nil */
85 @property (readonly) TCPListener *server;
87 /** Is this an incoming connection, received via a TCPListener? */
88 @property (readonly) BOOL isIncoming;
90 /** The fatal error, if any,
91 that caused the connection to fail to open or to disconnect unexpectedly. */
92 @property (readonly) NSError *error;
94 /** The actual security level of this connection.
95 Value is nil or one of the security level constants from NSStream.h,
96 such as NSStreamSocketSecurityLevelTLSv1. */
97 @property (readonly) NSString* actualSecurityLevel;
100 @property (readonly) TCPReader *reader;
101 @property (readonly) TCPWriter *writer;
105 - (Class) readerClass;
106 - (Class) writerClass;
112 /** The delegate messages sent by TCPConnection.
113 All methods are optional. */
114 @protocol TCPConnectionDelegate <NSObject>
116 /** Called after the connection successfully opens. */
117 - (void) connectionDidOpen: (TCPConnection*)connection;
118 /** Called after the connection fails to open due to an error. */
119 - (void) connection: (TCPConnection*)connection failedToOpen: (NSError*)error;
120 /** Called when the identity of the peer is known, if using an SSL connection and the SSL
121 settings say to check the peer's certificate.
122 This happens, if at all, after the -connectionDidOpen: call. */
123 - (BOOL) connection: (TCPConnection*)connection authorizeSSLPeer: (SecCertificateRef)peerCert;
124 /** Called after the connection closes. */
125 - (void) connectionDidClose: (TCPConnection*)connection;