TCP/TCPConnection.h
author Jens Alfke <jens@mooseyard.com>
Tue Jun 10 16:14:20 2008 -0700 (2008-06-10)
changeset 15 f723174fbc24
parent 7 5936db2c1987
child 16 6f608b552b77
permissions -rw-r--r--
Fixed: The -connection:failedToOpen: delegate method wasn't being called.
     1 //
     2 //  TCPConnection.h
     3 //  MYNetwork
     4 //
     5 //  Created by Jens Alfke on 5/18/08.
     6 //  Copyright 2008 Jens Alfke. All rights reserved.
     7 //
     8 
     9 #import "TCPEndpoint.h"
    10 #import <Security/Security.h>
    11 @class IPAddress;
    12 @class TCPReader, TCPWriter, TCPListener;
    13 @protocol TCPConnectionDelegate;
    14 
    15 
    16 typedef enum {
    17     kTCP_Disconnected = -1,
    18     kTCP_Closed,
    19     kTCP_Opening,
    20     kTCP_Open,
    21     kTCP_Closing
    22 } TCPConnectionStatus;
    23 
    24 
    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
    30 {
    31     @private
    32     TCPListener *_server;
    33     IPAddress *_address;
    34     BOOL _isIncoming, _checkedPeerCert;
    35     TCPConnectionStatus _status;
    36     TCPReader *_reader;
    37     TCPWriter *_writer;
    38     NSError *_error;
    39 }
    40 
    41 /** Initializes a TCPConnection to the given IP address.
    42     Afer configuring settings, you should call -open to begin the connection. */
    43 - (id) initToAddress: (IPAddress*)address;
    44 
    45 /** Initializes a TCPConnection to the given IP address, binding to a specific outgoing port
    46     number. (This is usually only necessary when attempting to tunnel through a NAT.) */
    47 - (id) initToAddress: (IPAddress*)address
    48            localPort: (UInt16)localPort;
    49 
    50 /** Initializes a TCPConnection to the given NSNetService's address and port.
    51     If the service's address cannot be resolved, nil is returned. */
    52 - (id) initToNetService: (NSNetService*)service;
    53 
    54 /** Initializes a TCPConnection from an incoming TCP socket.
    55     You don't usually need to call this; TCPListener does it automatically. */
    56 - (id) initIncomingFromSocket: (CFSocketNativeHandle)socket listener: (TCPListener*)listener;
    57 
    58 /** The delegate object that will be called when the connection opens, closes or receives messages. */
    59 @property (assign) id<TCPConnectionDelegate> delegate;
    60 
    61 /** The certificate(s) of the connected peer, if this connection uses SSL.
    62     The items in the array are SecCertificateRefs; use the Keychain API to work with them. */
    63 @property (readonly) NSArray *peerSSLCerts;
    64 
    65 /** Connection's current status */
    66 @property (readonly) TCPConnectionStatus status;
    67 
    68 /** Opens the connection. This happens asynchronously; wait for a delegate method to be called.
    69     You don't need to open incoming connections received via a TCPListener. */
    70 - (void) open;
    71 
    72 /** Closes the connection, after waiting for all in-progress messages to be sent or received.
    73     This happens asynchronously; wait for a delegate method to be called.*/
    74 - (void) close;
    75 
    76 /** Closes the connection, like -close, but if it hasn't closed by the time the timeout
    77     expires, it will disconnect the socket. */
    78 - (void) closeWithTimeout: (NSTimeInterval)timeout;
    79 
    80 /** Closes all open TCPConnections. */
    81 + (void) closeAllWithTimeout: (NSTimeInterval)timeout;
    82 
    83 /** Blocks until all open TCPConnections close. You should call +closeAllWithTimeout: first. */
    84 + (void) waitTillAllClosed;
    85 
    86 /** The IP address of the other peer. */
    87 @property (readonly,retain) IPAddress *address;
    88 
    89 /** The TCPListener that created this incoming connection, or nil */
    90 @property (readonly) TCPListener *server;
    91 
    92 /** Is this an incoming connection, received via a TCPListener? */
    93 @property (readonly) BOOL isIncoming;
    94 
    95 /** The fatal error, if any, 
    96     that caused the connection to fail to open or to disconnect unexpectedly. */
    97 @property (readonly) NSError *error;
    98 
    99 /** The actual security level of this connection. 
   100     Value is nil or one of the security level constants from NSStream.h,
   101     such as NSStreamSocketSecurityLevelTLSv1. */
   102 @property (readonly) NSString* actualSecurityLevel;
   103 
   104 
   105 @property (readonly) TCPReader *reader;
   106 @property (readonly) TCPWriter *writer;
   107 
   108 
   109 // protected:
   110 - (Class) readerClass;
   111 - (Class) writerClass;
   112 
   113 @end
   114 
   115 
   116 
   117 /** The delegate messages sent by TCPConnection.
   118     All methods are optional. */
   119 @protocol TCPConnectionDelegate <NSObject>
   120 @optional
   121 /** Called after the connection successfully opens. */
   122 - (void) connectionDidOpen: (TCPConnection*)connection;
   123 /** Called after the connection fails to open due to an error. */
   124 - (void) connection: (TCPConnection*)connection failedToOpen: (NSError*)error;
   125 /** Called when the identity of the peer is known, if using an SSL connection and the SSL
   126     settings say to check the peer's certificate.
   127     This happens, if at all, after the -connectionDidOpen: call. */
   128 - (BOOL) connection: (TCPConnection*)connection authorizeSSLPeer: (SecCertificateRef)peerCert;
   129 /** Called after the connection closes. */
   130 - (void) connectionDidClose: (TCPConnection*)connection;
   131 @end