1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/TCP/TCPConnection.h	Sat May 24 13:26:02 2008 -0700
     1.3 @@ -0,0 +1,124 @@
     1.4 +//
     1.5 +//  TCPConnection.h
     1.6 +//  MYNetwork
     1.7 +//
     1.8 +//  Created by Jens Alfke on 5/18/08.
     1.9 +//  Copyright 2008 Jens Alfke. All rights reserved.
    1.10 +//
    1.11 +
    1.12 +#import "TCPEndpoint.h"
    1.13 +@class IPAddress;
    1.14 +@class TCPReader, TCPWriter, TCPListener;
    1.15 +@protocol TCPConnectionDelegate;
    1.16 +
    1.17 +
    1.18 +typedef enum {
    1.19 +    kTCP_Disconnected = -1,
    1.20 +    kTCP_Closed,
    1.21 +    kTCP_Opening,
    1.22 +    kTCP_Open,
    1.23 +    kTCP_Closing
    1.24 +} TCPConnectionStatus;
    1.25 +
    1.26 +
    1.27 +/** A generic class that manages a TCP socket connection.
    1.28 +    It creates a TCPReader and a TCPWriter to handle I/O.
    1.29 +    TCPConnection itself mostly deals with SSL setup and opening/closing the socket. */
    1.30 +@interface TCPConnection : TCPEndpoint
    1.31 +{
    1.32 +    @private
    1.33 +    TCPListener *_server;
    1.34 +    IPAddress *_address;
    1.35 +    BOOL _isIncoming, _checkedPeerCert;
    1.36 +    TCPConnectionStatus _status;
    1.37 +    TCPReader *_reader;
    1.38 +    TCPWriter *_writer;
    1.39 +    NSError *_error;
    1.40 +}
    1.41 +
    1.42 +/** Initializes a TCPConnection to the given IP address.
    1.43 +    Afer configuring settings, you should call -open to begin the connection. */
    1.44 +- (id) initToAddress: (IPAddress*)address;
    1.45 +
    1.46 +/** Initializes a TCPConnection to the given IP address, binding to a specific outgoing port
    1.47 +    number. (This is usually only necessary when attempting to tunnel through a NAT.) */
    1.48 +- (id) initToAddress: (IPAddress*)address
    1.49 +           localPort: (UInt16)localPort;
    1.50 +
    1.51 +/** Initializes a TCPConnection from an incoming TCP socket.
    1.52 +    You don't usually need to call this; TCPListener does it automatically. */
    1.53 +- (id) initIncomingFromSocket: (CFSocketNativeHandle)socket listener: (TCPListener*)listener;
    1.54 +
    1.55 +/** The delegate object that will be called when the connection opens, closes or receives messages. */
    1.56 +@property (assign) id<TCPConnectionDelegate> delegate;
    1.57 +
    1.58 +/** The certificate(s) of the connected peer, if this connection uses SSL.
    1.59 +    The items in the array are SecCertificateRefs; use the Keychain API to work with them. */
    1.60 +@property (readonly) NSArray *peerSSLCerts;
    1.61 +
    1.62 +/** Connection's current status */
    1.63 +@property (readonly) TCPConnectionStatus status;
    1.64 +
    1.65 +/** Opens the connection. This happens asynchronously; wait for a delegate method to be called.
    1.66 +    You don't need to open incoming connections received via a TCPListener. */
    1.67 +- (void) open;
    1.68 +
    1.69 +/** Closes the connection, after waiting for all in-progress messages to be sent or received.
    1.70 +    This happens asynchronously; wait for a delegate method to be called.*/
    1.71 +- (void) close;
    1.72 +
    1.73 +/** Closes the connection, like -close, but if it hasn't closed by the time the timeout
    1.74 +    expires, it will disconnect the socket. */
    1.75 +- (void) closeWithTimeout: (NSTimeInterval)timeout;
    1.76 +
    1.77 +/** Closes all open TCPConnections. */
    1.78 ++ (void) closeAllWithTimeout: (NSTimeInterval)timeout;
    1.79 +
    1.80 +/** Blocks until all open TCPConnections close. You should call +closeAllWithTimeout: first. */
    1.81 ++ (void) waitTillAllClosed;
    1.82 +
    1.83 +/** The IP address of the other peer. */
    1.84 +@property (readonly) IPAddress *address;
    1.85 +
    1.86 +/** The TCPListener that created this incoming connection, or nil */
    1.87 +@property (readonly) TCPListener *server;
    1.88 +
    1.89 +/** Is this an incoming connection, received via a TCPListener? */
    1.90 +@property (readonly) BOOL isIncoming;
    1.91 +
    1.92 +/** The fatal error, if any, 
    1.93 +    that caused the connection to fail to open or to disconnect unexpectedly. */
    1.94 +@property (readonly) NSError *error;
    1.95 +
    1.96 +/** The actual security level of this connection. 
    1.97 +    Value is nil or one of the security level constants from NSStream.h,
    1.98 +    such as NSStreamSocketSecurityLevelTLSv1. */
    1.99 +@property (readonly) NSString* actualSecurityLevel;
   1.100 +
   1.101 +
   1.102 +@property (readonly) TCPReader *reader;
   1.103 +@property (readonly) TCPWriter *writer;
   1.104 +
   1.105 +
   1.106 +// protected:
   1.107 +- (Class) readerClass;
   1.108 +- (Class) writerClass;
   1.109 +
   1.110 +@end
   1.111 +
   1.112 +
   1.113 +
   1.114 +/** The delegate messages sent by TCPConnection. */
   1.115 +@protocol TCPConnectionDelegate <NSObject>
   1.116 +@optional
   1.117 +/** Called after the connection successfully opens. */
   1.118 +- (void) connectionDidOpen: (TCPConnection*)connection;
   1.119 +/** Called after the connection fails to open due to an error. */
   1.120 +- (void) connection: (TCPConnection*)connection failedToOpen: (NSError*)error;
   1.121 +/** Called when the identity of the peer is known, if using an SSL connection and the SSL
   1.122 +    settings say to check the peer's certificate.
   1.123 +    This happens, if at all, after the -connectionDidOpen: call. */
   1.124 +- (BOOL) connection: (TCPConnection*)connection authorizeSSLPeer: (SecCertificateRef)peerCert;
   1.125 +/** Called after the connection closes. */
   1.126 +- (void) connectionDidClose: (TCPConnection*)connection;
   1.127 +@end