1.1 --- a/TCP/TCPListener.h Fri May 23 17:37:36 2008 -0700
1.2 +++ b/TCP/TCPListener.h Tue Jun 10 16:14:20 2008 -0700
1.3 @@ -11,11 +11,17 @@
1.4
1.5
1.6 /** Generic TCP-based server that listens for incoming connections on a port.
1.7 +
1.8 For each incoming connection, it creates an instance of (a subclass of) the generic TCP
1.9 client class TCPClient. The -connectionClass property lets you customize which subclass
1.10 to use.
1.11 - TCPListener supports Bonjour advertisements for the service, and automatic port renumbering
1.12 - if there are conflicts. */
1.13 +
1.14 + TCPListener supports SSL, Bonjour advertisements for the service, and automatic port renumbering
1.15 + if there are conflicts. (The SSL related methods are inherited from TCPEndpoint.)
1.16 +
1.17 + You will almost always need to implement the TCPListenerDelegate protocol in your own
1.18 + code, and set an instance as the listener's delegate property, in order to be informed
1.19 + of important events such as incoming connections. */
1.20 @interface TCPListener : TCPEndpoint
1.21 {
1.22 @private
1.23 @@ -40,6 +46,8 @@
1.24 /** The subclass of TCPConnection that will be instantiated. */
1.25 @property Class connectionClass;
1.26
1.27 +/** Delegate object that will be called when interesting things happen to the listener --
1.28 + most importantly, when a new incoming connection is accepted. */
1.29 @property (assign) id<TCPListenerDelegate> delegate;
1.30
1.31 /** Should the server listen for IPv6 connections (on the same port number)? Defaults to NO. */
1.32 @@ -58,6 +66,9 @@
1.33 changes are ignored while the server is open.) */
1.34 - (BOOL) open: (NSError **)error;
1.35
1.36 +/** Opens the server, without returning a specific error code.
1.37 + (In case of error the delegate's -listener:failedToOpen: method will be called with the
1.38 + error code, anyway.) */
1.39 - (BOOL) open;
1.40
1.41 /** Closes the server. */
1.42 @@ -94,14 +105,30 @@
1.43
1.44 #pragma mark -
1.45
1.46 -/** The delegate messages sent by TCPListener. */
1.47 +/** The delegate messages sent by TCPListener.
1.48 + All are optional except -listener:didAcceptConnection:. */
1.49 @protocol TCPListenerDelegate <NSObject>
1.50
1.51 +/** Called after an incoming connection arrives and is opened;
1.52 + the connection is now ready to send and receive data.
1.53 + To control whether or not a connection should be accepted, implement the
1.54 + -listener:shouldAcceptConnectionFrom: method.
1.55 + To use a different class than TCPConnection, set the listener's -connectionClass property.
1.56 + (This is the only required delegate method; the others are optional to implement.) */
1.57 - (void) listener: (TCPListener*)listener didAcceptConnection: (TCPConnection*)connection;
1.58
1.59 @optional
1.60 +/** Called after the listener successfully opens. */
1.61 - (void) listenerDidOpen: (TCPListener*)listener;
1.62 +/** Called if the listener fails to open due to an error. */
1.63 - (void) listener: (TCPListener*)listener failedToOpen: (NSError*)error;
1.64 +/** Called after the listener closes. */
1.65 - (void) listenerDidClose: (TCPListener*)listener;
1.66 +/** Called when an incoming connection request arrives, but before the conncetion is opened;
1.67 + return YES to accept the connection, NO to refuse it.
1.68 + This method can only use criteria like the peer IP address, or the number of currently
1.69 + open connections, to determine whether to accept. If you also want to check the
1.70 + peer's SSL certificate, then return YES from this method, and use the TCPConnection
1.71 + delegate method -connection:authorizeSSLPeer: to examine the certificate. */
1.72 - (BOOL) listener: (TCPListener*)listener shouldAcceptConnectionFrom: (IPAddress*)address;
1.73 @end