5 // Created by Jens Alfke on 5/18/08.
6 // Copyright 2008 Jens Alfke. All rights reserved.
9 #import "TCPEndpoint.h"
10 #import <Security/Security.h>
12 @class TCPReader, TCPWriter, TCPListener;
13 @protocol TCPConnectionDelegate;
17 kTCP_Disconnected = -1,
22 } TCPConnectionStatus;
25 /** A generic class that manages a TCP socket connection.
26 It creates a TCPReader and a TCPWriter to handle I/O.
27 TCPConnection itself mostly deals with SSL setup and opening/closing the socket.
28 (The SSL related methods are inherited from TCPEndpoint.) */
29 @interface TCPConnection : TCPEndpoint
34 BOOL _isIncoming, _checkedPeerCert;
35 TCPConnectionStatus _status;
39 NSTimeInterval _openTimeout;
42 /** Initializes a TCPConnection to the given IP address.
43 Afer configuring settings, you should call -open to begin the connection. */
44 - (id) initToAddress: (IPAddress*)address;
46 /** Initializes a TCPConnection to the given NSNetService's address and port.
47 If the service's address cannot be resolved, nil is returned. */
48 - (id) initToNetService: (NSNetService*)service;
50 /** Initializes a TCPConnection from an incoming TCP socket.
51 You don't usually need to call this; TCPListener does it automatically. */
52 - (id) initIncomingFromSocket: (CFSocketNativeHandle)socket listener: (TCPListener*)listener;
54 /** Timeout for waiting to open a connection. (Default is zero, meaning the OS default timeout.) */
55 @property NSTimeInterval openTimeout;
57 /** The delegate object that will be called when the connection opens, closes or receives messages. */
58 @property (assign) id<TCPConnectionDelegate> delegate;
60 /** The certificate(s) of the connected peer, if this connection uses SSL.
61 The items in the array are SecCertificateRefs; use the Keychain API to work with them. */
62 @property (readonly) NSArray *peerSSLCerts;
64 /** Connection's current status */
65 @property (readonly) TCPConnectionStatus status;
67 /** Opens the connection. This happens asynchronously; wait for a delegate method to be called.
68 You don't need to open incoming connections received via a TCPListener. */
71 /** Closes the connection, after waiting for all in-progress messages to be sent or received.
72 This happens asynchronously; wait for a delegate method to be called.*/
75 /** Closes the connection, like -close, but if it hasn't closed by the time the timeout
76 expires, it will disconnect the socket. */
77 - (void) closeWithTimeout: (NSTimeInterval)timeout;
79 /** Closes all open TCPConnections. */
80 + (void) closeAllWithTimeout: (NSTimeInterval)timeout;
82 /** Blocks until all open TCPConnections close. You should call +closeAllWithTimeout: first. */
83 + (void) waitTillAllClosed;
85 /** The IP address of the other peer. */
86 @property (readonly,retain) IPAddress *address;
88 /** The TCPListener that created this incoming connection, or nil */
89 @property (readonly) TCPListener *server;
91 /** Is this an incoming connection, received via a TCPListener? */
92 @property (readonly) BOOL isIncoming;
94 /** The fatal error, if any,
95 that caused the connection to fail to open or to disconnect unexpectedly. */
96 @property (readonly) NSError *error;
98 /** The actual security level of this connection.
99 Value is nil or one of the security level constants from NSStream.h,
100 such as NSStreamSocketSecurityLevelTLSv1. */
101 @property (readonly) NSString* actualSecurityLevel;
104 @property (readonly) TCPReader *reader;
105 @property (readonly) TCPWriter *writer;
109 - (Class) readerClass;
110 - (Class) writerClass;
111 - (void) _beginClose;
118 /** The delegate messages sent by TCPConnection.
119 All methods are optional. */
120 @protocol TCPConnectionDelegate <NSObject>
122 /** Called after the connection successfully opens. */
123 - (void) connectionDidOpen: (TCPConnection*)connection;
124 /** Called after the connection fails to open due to an error. */
125 - (void) connection: (TCPConnection*)connection failedToOpen: (NSError*)error;
126 /** Called when the identity of the peer is known, if using an SSL connection and the SSL
127 settings say to check the peer's certificate.
128 This happens, if at all, after the -connectionDidOpen: call. */
129 - (BOOL) connection: (TCPConnection*)connection authorizeSSLPeer: (SecCertificateRef)peerCert;
130 /** Called after the connection closes.
131 You can check the connection's error property to see if it was normal or abnormal. */
132 - (void) connectionDidClose: (TCPConnection*)connection;