1.1 --- a/TCP/TCPListener.h	Fri May 23 17:37:36 2008 -0700
     1.2 +++ b/TCP/TCPListener.h	Tue Jun 03 22:24:21 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