TCP/TCPListener.h
author Dan Preston <danpreston@codechemistry.com>
Tue May 05 14:46:42 2009 -0700 (2009-05-05)
changeset 36 5165944a89b3
parent 2 9fdd8dba529c
child 44 d8a559a39284
permissions -rwxr-xr-x
Fixed a double release in a garbage collected environment.
     1 //
     2 //  TCPListener.m
     3 //  MYNetwork
     4 //
     5 //  Created by Jens Alfke on 5/10/08.
     6 //  Copyright 2008 Jens Alfke. All rights reserved.
     7 
     8 #import "TCPEndpoint.h"
     9 @class TCPConnection, IPAddress;
    10 @protocol TCPListenerDelegate;
    11 
    12 
    13 /** Generic TCP-based server that listens for incoming connections on a port.
    14 
    15     For each incoming connection, it creates an instance of (a subclass of) the generic TCP
    16     client class TCPClient. The -connectionClass property lets you customize which subclass
    17     to use.
    18  
    19     TCPListener supports SSL, Bonjour advertisements for the service, and automatic port renumbering
    20     if there are conflicts. (The SSL related methods are inherited from TCPEndpoint.) 
    21  
    22     You will almost always need to implement the TCPListenerDelegate protocol in your own
    23     code, and set an instance as the listener's delegate property, in order to be informed
    24     of important events such as incoming connections. */
    25 @interface TCPListener : TCPEndpoint 
    26 {
    27     @private
    28     uint16_t _port;
    29     BOOL _pickAvailablePort;
    30     BOOL _useIPv6;
    31     CFSocketRef _ipv4socket;
    32     CFSocketRef _ipv6socket;
    33     
    34     NSString *_bonjourServiceType, *_bonjourServiceName;
    35     NSNetService *_netService;
    36     NSDictionary *_bonjourTXTRecord;
    37     BOOL _bonjourPublished;
    38     NSInteger /*NSNetServicesError*/ _bonjourError;
    39 
    40     Class _connectionClass;
    41 }
    42 
    43 /** Initializes a new TCPListener that will listen on the given port when opened. */
    44 - (id) initWithPort: (UInt16)port;
    45 
    46 /** The subclass of TCPConnection that will be instantiated. */
    47 @property Class connectionClass;
    48 
    49 /** Delegate object that will be called when interesting things happen to the listener --
    50     most importantly, when a new incoming connection is accepted. */
    51 @property (assign) id<TCPListenerDelegate> delegate;
    52 
    53 /** Should the server listen for IPv6 connections (on the same port number)? Defaults to NO. */
    54 @property BOOL useIPv6;
    55 
    56 /** The port number to listen on.
    57     If the pickAvailablePort property is enabled, this value may be updated after the server opens
    58     to reflect the actual port number being used. */
    59 @property uint16_t port;
    60 
    61 /** Should the server pick a higher port number if the desired port is already in use?
    62     Defaults to NO. If enabled, the port number will be incremented until a free port is found. */
    63 @property BOOL pickAvailablePort;
    64 
    65 /** Opens the server. You must call this after configuring all desired properties (property
    66     changes are ignored while the server is open.) */
    67 - (BOOL) open: (NSError **)error;
    68 
    69 /** Opens the server, without returning a specific error code.
    70     (In case of error the delegate's -listener:failedToOpen: method will be called with the
    71     error code, anyway.) */
    72 - (BOOL) open;
    73 
    74 /** Closes the server. */
    75 - (void) close;
    76 
    77 /** Is the server currently open? */
    78 @property (readonly) BOOL isOpen;
    79 
    80 
    81 #pragma mark BONJOUR:
    82 
    83 /** The Bonjour service type to advertise. Defaults to nil; setting it implicitly enables Bonjour.
    84     The value should look like e.g. "_http._tcp."; for details, see the NSNetService documentation. */
    85 @property (copy) NSString *bonjourServiceType;
    86 
    87 /** The Bonjour service name to advertise. Defaults to nil, meaning that a default name will be
    88     automatically generated if Bonjour is enabled (by setting -bonjourServiceType). */
    89 @property (copy) NSString *bonjourServiceName;
    90 
    91 /** The dictionary form of the Bonjour TXT record: metadata about the service that can be browsed
    92     by peers. Changes to this dictionary will be pushed in near-real-time to interested peers. */
    93 @property (copy) NSDictionary *bonjourTXTRecord;
    94 
    95 /** Is this service currently published/advertised via Bonjour? */
    96 @property (readonly) BOOL bonjourPublished;
    97 
    98 /** Current error status of Bonjour service advertising. See NSNetServicesError for error codes. */
    99 @property (readonly) NSInteger /*NSNetServicesError*/ bonjourError;
   100 
   101 /** The NSNetService being published. */
   102 @property (readonly) NSNetService* bonjourService;
   103 
   104 
   105 @end
   106 
   107 
   108 
   109 #pragma mark -
   110 
   111 /** The delegate messages sent by TCPListener.
   112     All are optional except -listener:didAcceptConnection:. */
   113 @protocol TCPListenerDelegate <NSObject>
   114 
   115 /** Called after an incoming connection arrives and is opened;
   116     the connection is now ready to send and receive data.
   117     To control whether or not a connection should be accepted, implement the
   118     -listener:shouldAcceptConnectionFrom: method.
   119     To use a different class than TCPConnection, set the listener's -connectionClass property.
   120     (This is the only required delegate method; the others are optional to implement.) */
   121 - (void) listener: (TCPListener*)listener didAcceptConnection: (TCPConnection*)connection;
   122 
   123 @optional
   124 /** Called after the listener successfully opens. */
   125 - (void) listenerDidOpen: (TCPListener*)listener;
   126 /** Called if the listener fails to open due to an error. */
   127 - (void) listener: (TCPListener*)listener failedToOpen: (NSError*)error;
   128 /** Called after the listener closes. */
   129 - (void) listenerDidClose: (TCPListener*)listener;
   130 /** Called when an incoming connection request arrives, but before the conncetion is opened;
   131     return YES to accept the connection, NO to refuse it.
   132     This method can only use criteria like the peer IP address, or the number of currently
   133     open connections, to determine whether to accept. If you also want to check the
   134     peer's SSL certificate, then return YES from this method, and use the TCPConnection
   135     delegate method -connection:authorizeSSLPeer: to examine the certificate. */
   136 - (BOOL) listener: (TCPListener*)listener shouldAcceptConnectionFrom: (IPAddress*)address;
   137 @end