IOS Streaming Browser 1.0
An IOS streaming browser to stream the display to others or to a projector

/Users/willrubel/IOS-Streaming-Browser/IOS-Streaming-Browser/GCDAsyncSocket.h

Go to the documentation of this file.
00001 //  
00002 //  GCDAsyncSocket.h
00003 //  
00004 //  This class is in the public domain.
00005 //  Originally created by Robbie Hanson in Q3 2010.
00006 //  Updated and maintained by Deusty LLC and the Mac development community.
00007 //  
00008 //  http://code.google.com/p/cocoaasyncsocket/
00009 //
00010 
00011 #import <Foundation/Foundation.h>
00012 #import <Security/Security.h>
00013 #import <dispatch/dispatch.h>
00014 
00015 @class GCDAsyncReadPacket;
00016 @class GCDAsyncWritePacket;
00017 
00018 extern NSString *const GCDAsyncSocketException;
00019 extern NSString *const GCDAsyncSocketErrorDomain;
00020 
00021 #if !TARGET_OS_IPHONE
00022 extern NSString *const GCDAsyncSocketSSLCipherSuites;
00023 extern NSString *const GCDAsyncSocketSSLDiffieHellmanParameters;
00024 #endif
00025 
00026 /** 
00027  *
00028  * \enum GCDAsyncSocketError
00029  *
00030  * \brief Creates a data type consisting of a set of named values for holding the various socket errors 
00031 **/
00032 enum GCDAsyncSocketError
00033 {
00034         GCDAsyncSocketNoError = 0,           ///< Never used
00035         GCDAsyncSocketBadConfigError,        ///< Invalid configuration
00036         GCDAsyncSocketBadParamError,         ///< Invalid parameter was passed
00037         GCDAsyncSocketConnectTimeoutError,   ///< A connect operation timed out
00038         GCDAsyncSocketReadTimeoutError,      ///< A read operation timed out
00039         GCDAsyncSocketWriteTimeoutError,     ///< A write operation timed out
00040         GCDAsyncSocketReadMaxedOutError,     ///< Reached set maxLength without completing
00041         GCDAsyncSocketClosedError,           ///< The remote peer closed the connection
00042         GCDAsyncSocketOtherError,            ///< Description provided in userInfo
00043 };
00044 typedef enum GCDAsyncSocketError GCDAsyncSocketError;
00045 
00046 
00047 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00048 #pragma mark -
00049 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00050 
00051 @interface GCDAsyncSocket : NSObject
00052 {
00053     /**
00054      
00055     **/
00056         UInt16 flags;
00057     
00058     
00059     /**
00060      
00061     **/
00062         UInt16 config;
00063         
00064     /**
00065      
00066     **/
00067         id delegate;
00068     
00069     /**
00070         Dispatch queues are lightweight objects to which blocks may be submitted.
00071         The system manages a pool of threads which process dispatch queues and invoke blocks submitted to them.
00072     **/
00073         dispatch_queue_t delegateQueue;  //dispatch queue
00074         
00075     /**
00076       IP version 4 socket file descriptor
00077     **/
00078         int socket4FD;  
00079 
00080         /**
00081       IP version 6 socket file descriptor
00082     **/
00083     int socket6FD;  
00084 
00085         int connectIndex; 
00086     
00087     /**
00088         Object-oriented wrappers for byte buffers
00089         IP version 4 interface
00090     **/
00091         NSData * connectInterface4;  
00092     
00093     /**
00094         IP version 6 interface
00095     **/
00096         NSData * connectInterface6;  
00097         
00098     /**
00099         The dispatch queue upon which blocks are submitted
00100     **/
00101         dispatch_queue_t socketQueue;  
00102         
00103     /**
00104      Dispatch sources are used to automatically submit event handler blocks to dispatch queues in response to external events.
00105     **/
00106         dispatch_source_t accept4Source; 
00107     
00108     /**
00109      Dispatch sources are used to automatically submit event handler blocks to dispatch queues in response to external events.
00110      **/
00111         dispatch_source_t accept6Source;
00112     
00113     /**
00114      Dispatch sources are used to automatically submit event handler blocks to dispatch queues in response to external events.
00115      **/
00116         dispatch_source_t connectTimer;
00117     
00118     /**
00119      Dispatch sources are used to automatically submit event handler blocks to dispatch queues in response to external events.
00120      **/
00121         dispatch_source_t readSource;
00122     
00123     /**
00124      Dispatch sources are used to automatically submit event handler blocks to dispatch queues in response to external events.
00125      **/
00126         dispatch_source_t writeSource;
00127     
00128     /**
00129      Dispatch sources are used to automatically submit event handler blocks to dispatch queues in response to external events.
00130      **/
00131         dispatch_source_t readTimer;
00132     
00133     /**
00134      Dispatch sources are used to automatically submit event handler blocks to dispatch queues in response to external events.
00135      **/
00136         dispatch_source_t writeTimer;
00137         
00138     
00139     /**
00140       The read queue
00141     **/
00142         NSMutableArray *readQueue;  
00143     
00144     /**
00145         the write queue
00146     **/
00147         NSMutableArray *writeQueue;  
00148         
00149     
00150     /**
00151       the read packet
00152     **/
00153         GCDAsyncReadPacket *currentRead; 
00154     
00155     /**
00156       the write packet
00157     **/
00158         GCDAsyncWritePacket *currentWrite; 
00159         
00160     /**
00161     // socket file descriptor bytes available
00162     // Value is 0 to 2,147,483,647
00163     **/
00164         unsigned long socketFDBytesAvailable;  
00165         
00166     /**
00167         A partial read buffer for buffering the host request
00168     **/
00169         NSMutableData *partialReadBuffer;  
00170                 
00171 #if TARGET_OS_IPHONE
00172     
00173     /**
00174         A struct for holding client information
00175     **/
00176         CFStreamClientContext streamContext;
00177     
00178     /**
00179         Is the interface for reading a byte stream either synchronously or asynchronously.
00180     **/
00181         CFReadStreamRef readStream;
00182     
00183     /**
00184         Is the interface for writing a byte stream either synchronously or asynchronously
00185     **/
00186         CFWriteStreamRef writeStream;
00187     
00188 #else
00189     
00190     /**
00191       the SSL context reference
00192     **/
00193         SSLContextRef sslContext; 
00194     
00195     /**
00196         The SSL read buffer for buffering the host response
00197     **/
00198         NSMutableData *sslReadBuffer; 
00199     
00200     /**
00201         size of the SSL write cache
00202     **/
00203         size_t sslWriteCachedLength; 
00204     
00205 #endif
00206         
00207     /**
00208         user data
00209     **/
00210         id userData; 
00211 }
00212 
00213 /**
00214     GCDAsyncSocket uses the standard delegate paradigm, but executes all delegate callbacks on a given delegate dispatch queue.
00215     This allows for maximum concurrency, while at the same time providing easy thread safety.
00216  
00217     You MUST set a delegate AND delegate dispatch queue before attempting to use the socket, or you will get an error.
00218  
00219     The socket queue is optional.
00220     If you pass NULL, GCDAsyncSocket will automatically create it's own socket queue.
00221  
00222     If you choose to provide a socket queue, the socket queue must not be a concurrent queue.
00223  
00224     The delegate queue and socket queue can optionally be the same.
00225 **/
00226 - (id)init;
00227 
00228 /**
00229     Initialize the GCDAsyncSocket with a socket queue
00230  
00231     param dispatch_queue_t
00232     returns id (self)
00233 **/
00234 - (id)initWithSocketQueue:(dispatch_queue_t)sq;
00235 
00236 /**
00237     Initialize the GCDAsyncSocket with a delegate and delegate queue
00238     param dispatch_queue_t
00239     returns id (self)
00240 **/
00241 - (id)initWithDelegate:(id)aDelegate delegateQueue:(dispatch_queue_t)dq;
00242 
00243 /**
00244     Initialize the GCDAsyncSocket with a delegate, delegate queue, and socket queue
00245     param id
00246     param dispatch_queue_t
00247     param dispatch_queue_t
00248     returns id
00249 **/
00250 - (id)initWithDelegate:(id)aDelegate delegateQueue:(dispatch_queue_t)dq socketQueue:(dispatch_queue_t)sq;
00251 
00252 #pragma mark Configuration
00253 
00254 /**
00255     Gets the delegate
00256     returns id
00257 **/
00258 - (id)delegate;
00259 
00260 /**
00261     Sets the delegate
00262     param id
00263 **/
00264 - (void)setDelegate:(id)delegate;
00265 
00266 /**
00267     Synchronously sets the delegate
00268     param id
00269 **/
00270 - (void)synchronouslySetDelegate:(id)delegate;
00271 
00272 /**
00273     Get the delegate queue
00274     returns dispatch_queue_t
00275 **/
00276 - (dispatch_queue_t)delegateQueue;
00277 
00278 /**
00279     Set the delegate queue
00280     param dispatch_queue_t
00281 **/
00282 - (void)setDelegateQueue:(dispatch_queue_t)delegateQueue;
00283 
00284 /**
00285     param dispatch_queue_t
00286 **/
00287 - (void)synchronouslySetDelegateQueue:(dispatch_queue_t)delegateQueue;
00288 
00289 /**
00290     Get delegate and delegate queue
00291     param id
00292     param dispatch_queue_t
00293 **/
00294 - (void)getDelegate:(id *)delegatePtr delegateQueue:(dispatch_queue_t *)delegateQueuePtr;
00295 
00296 /**
00297     Set the delegate and delegate queue
00298     param id
00299     param dispatch_queue_t
00300 **/
00301 - (void)setDelegate:(id)delegate delegateQueue:(dispatch_queue_t)delegateQueue;
00302 
00303 /**
00304     Synchronously set the delegate and delegate queue
00305     param id
00306     param dispatch_queue_t
00307 **/
00308 - (void)synchronouslySetDelegate:(id)delegate delegateQueue:(dispatch_queue_t)delegateQueue;
00309 
00310 /**
00311  * Traditionally sockets are not closed until the conversation is over.
00312  * However, it is technically possible for the remote endpoint to close its write stream.
00313  * Our socket would then be notified that there is no more data to be read,
00314  * but our socket would still be writeable and the remote endpoint could continue to receive our data.
00315  * 
00316  * The argument for this confusing functionality stems from the idea that a client could shut down its
00317  * write stream after sending a request to the server, thus notifying the server there are to be no further requests.
00318  * In practice, however, this technique did little to help server developers.
00319  * 
00320  * To make matters worse, from a TCP perspective there is no way to tell the difference from a read stream close
00321  * and a full socket close. They both result in the TCP stack receiving a FIN packet. The only way to tell
00322  * is by continuing to write to the socket. If it was only a read stream close, then writes will continue to work.
00323  * Otherwise an error will be occur shortly (when the remote end sends us a RST (reset) packet).
00324  * 
00325  * In addition to the technical challenges and confusion, many high level socket/stream API's provide
00326  * no support for dealing with the problem. If the read stream is closed, the API immediately declares the
00327  * socket to be closed, and shuts down the write stream as well. In fact, this is what Apple's CFStream API does.
00328  * It might sound like poor design at first, but in fact it simplifies development.
00329  * 
00330  * The vast majority of the time if the read stream is closed it's because the remote endpoint closed its socket.
00331  * Thus it actually makes sense to close the socket at this point.
00332  * And in fact this is what most networking developers want and expect to happen.
00333  * However, if you are writing a server that interacts with a plethora of clients,
00334  * you might encounter a client that uses the discouraged technique of shutting down its write stream.
00335  * If this is the case, you can set this property to NO,
00336  * and make use of the socketDidCloseReadStream delegate method.
00337  * 
00338  * The default value is YES.
00339 **/
00340 
00341 /**
00342     Whether automatically disconnecting upon the closing of a read stream
00343     returns BOOL
00344 **/
00345 - (BOOL)autoDisconnectOnClosedReadStream;
00346 
00347 /**
00348     Sets the flag for whether automatically disconnecting upon the closing of a read stream
00349     param BOOL
00350 **/
00351 - (void)setAutoDisconnectOnClosedReadStream:(BOOL)flag;
00352 
00353 /**
00354  * By default, both IPv4 and IPv6 are enabled.
00355  * 
00356  * For accepting incoming connections, this means GCDAsyncSocket automatically supports both protocols,
00357  * and can simulataneously accept incoming connections on either protocol.
00358  * 
00359  * For outgoing connections, this means GCDAsyncSocket can connect to remote hosts running either protocol.
00360  * If a DNS lookup returns only IPv4 results, GCDAsyncSocket will automatically use IPv4.
00361  * If a DNS lookup returns only IPv6 results, GCDAsyncSocket will automatically use IPv6.
00362  * If a DNS lookup returns both IPv4 and IPv6 results, the preferred protocol will be chosen.
00363  * By default, the preferred protocol is IPv4, but may be configured as desired.
00364 **/
00365 
00366 /**
00367     Whether IP version 4 is enabled
00368     returns BOOL
00369 **/
00370 - (BOOL)isIPv4Enabled;
00371 
00372 /**
00373     Set the flag for whether IP version 4 protocol is enabled
00374     param BOOL
00375 **/
00376 - (void)setIPv4Enabled:(BOOL)flag;
00377 
00378 
00379 /**
00380     Whether IP version 6 protocol is enabled
00381     returns BOOL
00382 **/
00383 - (BOOL)isIPv6Enabled;
00384 
00385 
00386 /**
00387     Set the flag for whether IP version 6 protocol is enabled
00388     param BOOL
00389 **/
00390 - (void)setIPv6Enabled:(BOOL)flag;
00391 
00392 
00393 /**
00394     Whether IP version 4 protocol is preferred over IP version 6 protocol
00395     returns BOOL
00396 **/
00397 - (BOOL)isIPv4PreferredOverIPv6;
00398 
00399 
00400 /**
00401     Set the flag for whether IP version 4 protocol is preferred over IP version 6
00402     param BOOL
00403 **/
00404 - (void)setPreferIPv4OverIPv6:(BOOL)flag;
00405 
00406 /**
00407     User data allows you to associate arbitrary information with the socket.
00408     This data is not used internally by socket in any way.
00409     returns id
00410 **/
00411 - (id)userData;
00412 
00413 /**
00414     param id
00415 **/
00416 - (void)setUserData:(id)arbitraryUserData;
00417 
00418 #pragma mark Accepting
00419 
00420 /**
00421     Tells the socket to begin listening and accepting connections on the given port.
00422 
00423     When a connection is accepted, a new instance of GCDAsyncSocket will be spawned to handle it, and the socket:didAcceptNewSocket: delegate method will be invoked.
00424  
00425     The socket will listen on all available interfaces (e.g. wifi, ethernet, etc)
00426     param (UInt16) port
00427     param NSError
00428     returns BOOL
00429 **/
00430 - (BOOL)acceptOnPort:(UInt16)port error:(NSError **)errPtr;
00431 
00432 
00433 /**
00434  * This method is the same as acceptOnPort:error: with the
00435  * additional option of specifying which interface to listen on.
00436  * 
00437  * For example, you could specify that the socket should only accept connections over ethernet,
00438  * and not other interfaces such as wifi.
00439  * 
00440  * The interface may be specified by name (e.g. "en1" or "lo0") or by IP address (e.g. "192.168.4.34").
00441  * You may also use the special strings "localhost" or "loopback" to specify that
00442  * the socket only accept connections from the local machine.
00443  * 
00444  * You can see the list of interfaces via the command line utility "ifconfig",
00445  * or programmatically via the getifaddrs() function.
00446  * 
00447  * To accept connections on any interface pass nil, or simply use the acceptOnPort:error: method.
00448 **/
00449 - (BOOL)acceptOnInterface:(NSString *)interface port:(UInt16)port error:(NSError **)errPtr;
00450 
00451 #pragma mark Connecting
00452 
00453 /**
00454     Connects to the given host and port.
00455  
00456     This method invokes connectToHost:onPort:viaInterface:withTimeout:error: and uses the default interface, and no timeout.
00457     param NSString
00458     param UInt16
00459     returns BOOL
00460 **/
00461 - (BOOL)connectToHost:(NSString *)host onPort:(UInt16)port error:(NSError **)errPtr;
00462 
00463 /**
00464     Connects to the given host and port with an optional timeout.
00465  
00466     This method invokes connectToHost:onPort:viaInterface:withTimeout:error: and uses the default interface.
00467     param NSString
00468     param UInt16
00469     param NSTimeInterval
00470     param NSError
00471     returns BOOL
00472 **/
00473 - (BOOL)connectToHost:(NSString *)host
00474                onPort:(UInt16)port
00475           withTimeout:(NSTimeInterval)timeout
00476                 error:(NSError **)errPtr;
00477 
00478 /**
00479  * Connects to the given host & port, via the optional interface, with an optional timeout.
00480  * 
00481  * The host may be a domain name (e.g. "deusty.com") or an IP address string (e.g. "192.168.0.2").
00482  * The interface may be a name (e.g. "en1" or "lo0") or the corresponding IP address (e.g. "192.168.4.35").
00483  * The interface may also be used to specify the local port (see below).
00484  * 
00485  * To not time out use a negative time interval.
00486  * 
00487  * This method will return NO if an error is detected, and set the error pointer (if one was given).
00488  * Possible errors would be a nil host, invalid interface, or socket is already connected.
00489  * 
00490  * If no errors are detected, this method will start a background connect operation and immediately return YES.
00491  * The delegate callbacks are used to notify you when the socket connects, or if the host was unreachable.
00492  * 
00493  * Since this class supports queued reads and writes, you can immediately start reading and/or writing.
00494  * All read/write operations will be queued, and upon socket connection,
00495  * the operations will be dequeued and processed in order.
00496  * 
00497  * The interface may optionally contain a port number at the end of the string, separated by a colon.
00498  * This allows you to specify the local port that should be used for the outgoing connection. (read paragraph to end)
00499  * To specify both interface and local port: "en1:8082" or "192.168.4.35:2424".
00500  * To specify only local port: ":8082".
00501  * Please note this is an advanced feature, and is somewhat hidden on purpose.
00502  * You should understand that 99.999% of the time you should NOT specify the local port for an outgoing connection.
00503  * If you think you need to, there is a very good chance you have a fundamental misunderstanding somewhere.
00504  * Local ports do NOT need to match remote ports. In fact, they almost never do.
00505  * This feature is here for networking professionals using very advanced techniques.
00506 **/
00507 - (BOOL)connectToHost:(NSString *)host
00508                onPort:(UInt16)port
00509          viaInterface:(NSString *)interface
00510           withTimeout:(NSTimeInterval)timeout
00511                 error:(NSError **)errPtr;
00512 
00513 /**
00514  * Connects to the given address, specified as a sockaddr structure wrapped in a NSData object.
00515  * For example, a NSData object returned from NSNetservice's addresses method.
00516  * 
00517  * If you have an existing struct sockaddr you can convert it to a NSData object like so:
00518  * struct sockaddr sa  -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];
00519  * struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];
00520  * 
00521  * This method invokes connectToAdd
00522 **/
00523 - (BOOL)connectToAddress:(NSData *)remoteAddr error:(NSError **)errPtr;
00524 
00525 /**
00526     This method is the same as connectToAddress:error: with an additional timeout option.
00527     To not time out use a negative time interval, or simply use the connectToAddress:error: method.
00528     param NSData
00529     param NSTimeInterval
00530     param NSError
00531     returns BOOL
00532 **/
00533 - (BOOL)connectToAddress:(NSData *)remoteAddr withTimeout:(NSTimeInterval)timeout error:(NSError **)errPtr;
00534 
00535 /**
00536     Connects to the given address, using the specified interface and timeout.
00537  
00538     The address is specified as a sockaddr structure wrapped in a NSData object.
00539     For example, a NSData object returned from NSNetservice's addresses method.
00540  
00541     If you have an existing struct sockaddr you can convert it to a NSData object like so:
00542     struct sockaddr sa  -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];
00543     struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];
00544  
00545     The interface may be a name (e.g. "en1" or "lo0") or the corresponding IP address (e.g. "192.168.4.35").
00546     The interface may also be used to specify the local port (see below).
00547   
00548     The timeout is optional. To not time out use a negative time interval.
00549   
00550     This method will return NO if an error is detected, and set the error pointer (if one was given).
00551     Possible errors would be a nil host, invalid interface, or socket is already connected.
00552   
00553     If no errors are detected, this method will start a background connect operation and immediately return YES.
00554     The delegate callbacks are used to notify you when the socket connects, or if the host was unreachable.
00555   
00556     Since this class supports queued reads and writes, you can immediately start reading and/or writing.
00557     All read/write operations will be queued, and upon socket connection, the operations will be dequeued and processed in order.
00558   
00559     The interface may optionally contain a port number at the end of the string, separated by a colon.
00560     This allows you to specify the local port that should be used for the outgoing connection. (read paragraph to end)
00561     To specify both interface and local port: "en1:8082" or "192.168.4.35:2424".
00562     To specify only local port: ":8082".
00563     Please note this is an advanced feature, and is somewhat hidden on purpose.
00564     You should understand that 99.999% of the time you should NOT specify the local port for an outgoing connection.
00565     If you think you need to, there is a very good chance you have a fundamental misunderstanding somewhere.
00566     Local ports do NOT need to match remote ports. In fact, they almost never do.
00567     This feature is here for networking professionals using very advanced techniques.
00568  
00569     param NSData
00570     param NSString
00571     param NSTimeInterval
00572     param NSError
00573     returns BOOL
00574 **/
00575 - (BOOL)connectToAddress:(NSData *)remoteAddr
00576             viaInterface:(NSString *)interface
00577              withTimeout:(NSTimeInterval)timeout
00578                    error:(NSError **)errPtr; // pointer to a pointer
00579 
00580 #pragma mark Disconnecting
00581 
00582 /**
00583  * Disconnects immediately (synchronously). Any pending reads or writes are dropped.
00584  * If the socket is not already disconnected, the socketDidDisconnect delegate method
00585  * will be called immediately, before this method returns.
00586  * 
00587  * Please note the recommended way of releasing an AsyncSocket instance (e.g. in a dealloc method)
00588  * [asyncSocket setDelegate:nil];
00589  * [asyncSocket disconnect];
00590  * [asyncSocket release];
00591 **/
00592 - (void)disconnect;
00593 
00594 /**
00595  * Disconnects after all pending reads have completed.
00596  * After calling this, the read and write methods will do nothing.
00597  * The socket will disconnect even if there are still pending writes.
00598 **/
00599 - (void)disconnectAfterReading;
00600 
00601 /**
00602  * Disconnects after all pending writes have completed.
00603  * After calling this, the read and write methods will do nothing.
00604  * The socket will disconnect even if there are still pending reads.
00605 **/
00606 - (void)disconnectAfterWriting;
00607 
00608 /**
00609  * Disconnects after all pending reads and writes have completed.
00610  * After calling this, the read and write methods will do nothing.
00611 **/
00612 - (void)disconnectAfterReadingAndWriting;
00613 
00614 #pragma mark Diagnostics
00615 
00616 /**
00617  * Returns whether the socket is disconnected or connected.
00618  * 
00619  * A disconnected socket may be recycled.
00620  * That is, it can used again for connecting or listening.
00621  * 
00622  * If a socket is in the process of connecting, it may be neither disconnected nor connected.
00623 **/
00624 - (BOOL)isDisconnected;
00625 
00626 /**
00627     returns BOOL
00628 **/
00629 - (BOOL)isConnected;
00630 
00631 /**
00632  * Returns the local or remote host and port to which this socket is connected, or nil and 0 if not connected.
00633  * The host will be an IP address.
00634 **/
00635 - (NSString *)connectedHost;
00636 
00637 /**
00638     returns UInt16
00639 **/
00640 - (UInt16)connectedPort;
00641 
00642 /**
00643     returns NSString
00644 **/
00645 - (NSString *)localHost;
00646 
00647 /**
00648     returns UInt16
00649 **/
00650 - (UInt16)localPort;
00651 
00652 /**
00653     Returns the local or remote address to which this socket is connected, specified as a sockaddr structure wrapped in a NSData object.
00654  
00655     See also the connectedHost, connectedPort, localHost and localPort methods.
00656  
00657     returns NSData
00658 **/
00659 - (NSData *)connectedAddress;
00660 
00661 
00662 /**
00663     returns NSData
00664 **/
00665 - (NSData *)localAddress;
00666 
00667 /**
00668     Returns whether the socket is IPv4 or IPv6.
00669     An accepting socket may be both.
00670     returns BOOL
00671 **/
00672 - (BOOL)isIPv4;
00673 
00674 /**
00675     returns BOOL
00676 **/
00677 - (BOOL)isIPv6;
00678 
00679 #pragma mark Reading
00680 
00681 // The readData and writeData methods won't block (they are asynchronous).
00682 // 
00683 // When a read is complete the socket:didReadData:withTag: delegate method is dispatched on the delegateQueue.
00684 // When a write is complete the socket:didWriteDataWithTag: delegate method is dispatched on the delegateQueue.
00685 // 
00686 // You may optionally set a timeout for any read/write operation. (To not timeout, use a negative time interval.)
00687 // If a read/write opertion times out, the corresponding "socket:shouldTimeout..." delegate method
00688 // is called to optionally allow you to extend the timeout.
00689 // Upon a timeout, the "socket:willDisconnectWithError:" method is called, followed by "socketDidDisconnect".
00690 // 
00691 // The tag is for your convenience.
00692 // You can use it as an array index, step number, state id, pointer, etc.
00693 
00694 /**
00695  * Reads the first available bytes that become available on the socket.
00696  * 
00697  * If the timeout value is negative, the read operation will not use a timeout.
00698 **/
00699 - (void)readDataWithTimeout:(NSTimeInterval)timeout tag:(long)tag;
00700 
00701 /**
00702  * Reads the first available bytes that become available on the socket.
00703  * The bytes will be appended to the given byte buffer starting at the given offset.
00704  * The given buffer will automatically be increased in size if needed.
00705  * 
00706  * If the timeout value is negative, the read operation will not use a timeout.
00707  * If the buffer if nil, the socket will create a buffer for you.
00708  * 
00709  * If the bufferOffset is greater than the length of the given buffer,
00710  * the method will do nothing, and the delegate will not be called.
00711  * 
00712  * If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
00713  * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
00714  * That is, it will reference the bytes that were appended to the given buffer.
00715 **/
00716 - (void)readDataWithTimeout:(NSTimeInterval)timeout
00717                                          buffer:(NSMutableData *)buffer
00718                            bufferOffset:(NSUInteger)offset
00719                                                 tag:(long)tag;
00720 
00721 /**
00722  * Reads the first available bytes that become available on the socket.
00723  * The bytes will be appended to the given byte buffer starting at the given offset.
00724  * The given buffer will automatically be increased in size if needed.
00725  * A maximum of length bytes will be read.
00726  * 
00727  * If the timeout value is negative, the read operation will not use a timeout.
00728  * If the buffer if nil, a buffer will automatically be created for you.
00729  * If maxLength is zero, no length restriction is enforced.
00730  * 
00731  * If the bufferOffset is greater than the length of the given buffer,
00732  * the method will do nothing, and the delegate will not be called.
00733  * 
00734  * If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
00735  * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
00736  * That is, it will reference the bytes that were appended to the given buffer.
00737 **/
00738 - (void)readDataWithTimeout:(NSTimeInterval)timeout
00739                      buffer:(NSMutableData *)buffer
00740                bufferOffset:(NSUInteger)offset
00741                   maxLength:(NSUInteger)length
00742                         tag:(long)tag;
00743 
00744 /**
00745  * Reads the given number of bytes.
00746  * 
00747  * If the timeout value is negative, the read operation will not use a timeout.
00748  * 
00749  * If the length is 0, this method does nothing and the delegate is not called.
00750 **/
00751 - (void)readDataToLength:(NSUInteger)length withTimeout:(NSTimeInterval)timeout tag:(long)tag;
00752 
00753 /**
00754  * Reads the given number of bytes.
00755  * The bytes will be appended to the given byte buffer starting at the given offset.
00756  * The given buffer will automatically be increased in size if needed.
00757  * 
00758  * If the timeout value is negative, the read operation will not use a timeout.
00759  * If the buffer if nil, a buffer will automatically be created for you.
00760  * 
00761  * If the length is 0, this method does nothing and the delegate is not called.
00762  * If the bufferOffset is greater than the length of the given buffer,
00763  * the method will do nothing, and the delegate will not be called.
00764  * 
00765  * If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
00766  * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
00767  * That is, it will reference the bytes that were appended to the given buffer.
00768 **/
00769 - (void)readDataToLength:(NSUInteger)length
00770              withTimeout:(NSTimeInterval)timeout
00771                   buffer:(NSMutableData *)buffer
00772             bufferOffset:(NSUInteger)offset
00773                      tag:(long)tag;
00774 
00775 /**
00776  * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
00777  * 
00778  * If the timeout value is negative, the read operation will not use a timeout.
00779  * 
00780  * If you pass nil or zero-length data as the "data" parameter,
00781  * the method will do nothing, and the delegate will not be called.
00782  * 
00783  * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
00784  * Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
00785  * a character, the read will prematurely end.
00786 **/
00787 - (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;
00788 
00789 /**
00790  * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
00791  * The bytes will be appended to the given byte buffer starting at the given offset.
00792  * The given buffer will automatically be increased in size if needed.
00793  * 
00794  * If the timeout value is negative, the read operation will not use a timeout.
00795  * If the buffer if nil, a buffer will automatically be created for you.
00796  * 
00797  * If the bufferOffset is greater than the length of the given buffer,
00798  * the method will do nothing, and the delegate will not be called.
00799  * 
00800  * If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
00801  * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
00802  * That is, it will reference the bytes that were appended to the given buffer.
00803  * 
00804  * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
00805  * Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
00806  * a character, the read will prematurely end.
00807 **/
00808 - (void)readDataToData:(NSData *)data
00809            withTimeout:(NSTimeInterval)timeout
00810                 buffer:(NSMutableData *)buffer
00811           bufferOffset:(NSUInteger)offset
00812                    tag:(long)tag;
00813 
00814 /**
00815  * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
00816  * 
00817  * If the timeout value is negative, the read operation will not use a timeout.
00818  * 
00819  * If maxLength is zero, no length restriction is enforced.
00820  * Otherwise if maxLength bytes are read without completing the read,
00821  * it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.
00822  * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
00823  * 
00824  * If you pass nil or zero-length data as the "data" parameter,
00825  * the method will do nothing, and the delegate will not be called.
00826  * If you pass a maxLength parameter that is less than the length of the data parameter,
00827  * the method will do nothing, and the delegate will not be called.
00828  * 
00829  * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
00830  * Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
00831  * a character, the read will prematurely end.
00832 **/
00833 - (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout maxLength:(NSUInteger)length tag:(long)tag;
00834 
00835 /**
00836  * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
00837  * The bytes will be appended to the given byte buffer starting at the given offset.
00838  * The given buffer will automatically be increased in size if needed.
00839  * 
00840  * If the timeout value is negative, the read operation will not use a timeout.
00841  * If the buffer if nil, a buffer will automatically be created for you.
00842  * 
00843  * If maxLength is zero, no length restriction is enforced.
00844  * Otherwise if maxLength bytes are read without completing the read,
00845  * it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.
00846  * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
00847  * 
00848  * If you pass a maxLength parameter that is less than the length of the data parameter,
00849  * the method will do nothing, and the delegate will not be called.
00850  * If the bufferOffset is greater than the length of the given buffer,
00851  * the method will do nothing, and the delegate will not be called.
00852  * 
00853  * If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
00854  * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
00855  * That is, it will reference the bytes that were appended to the given buffer.
00856  * 
00857  * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
00858  * Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
00859  * a character, the read will prematurely end.
00860 **/
00861 - (void)readDataToData:(NSData *)data
00862            withTimeout:(NSTimeInterval)timeout
00863                 buffer:(NSMutableData *)buffer
00864           bufferOffset:(NSUInteger)offset
00865              maxLength:(NSUInteger)length
00866                    tag:(long)tag;
00867 
00868 #pragma mark Writing
00869 
00870 /**
00871  * Writes data to the socket, and calls the delegate when finished.
00872  * 
00873  * If you pass in nil or zero-length data, this method does nothing and the delegate will not be called.
00874  * If the timeout value is negative, the write operation will not use a timeout.
00875 **/
00876 - (void)writeData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;
00877 
00878 #pragma mark Security
00879 
00880 /**
00881  * Secures the connection using SSL/TLS.
00882  * 
00883  * This method may be called at any time, and the TLS handshake will occur after all pending reads and writes
00884  * are finished. This allows one the option of sending a protocol dependent StartTLS message, and queuing
00885  * the upgrade to TLS at the same time, without having to wait for the write to finish.
00886  * Any reads or writes scheduled after this method is called will occur over the secured connection.
00887  * 
00888  * The possible keys and values for the TLS settings are well documented.
00889  * Some possible keys are:
00890  * - kCFStreamSSLLevel
00891  * - kCFStreamSSLAllowsExpiredCertificates
00892  * - kCFStreamSSLAllowsExpiredRoots
00893  * - kCFStreamSSLAllowsAnyRoot
00894  * - kCFStreamSSLValidatesCertificateChain
00895  * - kCFStreamSSLPeerName
00896  * - kCFStreamSSLCertificates
00897  * - kCFStreamSSLIsServer
00898  * 
00899  * Please refer to Apple's documentation for associated values, as well as other possible keys.
00900  * 
00901  * If you pass in nil or an empty dictionary, the default settings will be used.
00902  * 
00903  * The default settings will check to make sure the remote party's certificate is signed by a
00904  * trusted 3rd party certificate agency (e.g. verisign) and that the certificate is not expired.
00905  * However it will not verify the name on the certificate unless you
00906  * give it a name to verify against via the kCFStreamSSLPeerName key.
00907  * The security implications of this are important to understand.
00908  * Imagine you are attempting to create a secure connection to MySecureServer.com,
00909  * but your socket gets directed to MaliciousServer.com because of a hacked DNS server.
00910  * If you simply use the default settings, and MaliciousServer.com has a valid certificate,
00911  * the default settings will not detect any problems since the certificate is valid.
00912  * To properly secure your connection in this particular scenario you
00913  * should set the kCFStreamSSLPeerName property to "MySecureServer.com".
00914  * If you do not know the peer name of the remote host in advance (for example, you're not sure
00915  * if it will be "domain.com" or "www.domain.com"), then you can use the default settings to validate the
00916  * certificate, and then use the X509Certificate class to verify the issuer after the socket has been secured.
00917  * The X509Certificate class is part of the CocoaAsyncSocket open source project.
00918  **/
00919 - (void)startTLS:(NSDictionary *)tlsSettings;
00920 
00921 #pragma mark Advanced
00922 
00923 /**
00924  * It's not thread-safe to access certain variables from outside the socket's internal queue.
00925  * 
00926  * For example, the socket file descriptor.
00927  * File descriptors are simply integers which reference an index in the per-process file table.
00928  * However, when one requests a new file descriptor (by opening a file or socket),
00929  * the file descriptor returned is guaranteed to be the lowest numbered unused descriptor.
00930  * So if we're not careful, the following could be possible:
00931  * 
00932  * - Thread A invokes a method which returns the socket's file descriptor.
00933  * - The socket is closed via the socket's internal queue on thread B.
00934  * - Thread C opens a file, and subsequently receives the file descriptor that was previously the socket's FD.
00935  * - Thread A is now accessing/altering the file instead of the socket.
00936  * 
00937  * In addition to this, other variables are not actually objects,
00938  * and thus cannot be retained/released or even autoreleased.
00939  * An example is the sslContext, of type SSLContextRef, which is actually a malloc'd struct.
00940  * 
00941  * Although there are internal variables that make it difficult to maintain thread-safety,
00942  * it is important to provide access to these variables
00943  * to ensure this class can be used in a wide array of environments.
00944  * This method helps to accomplish this by invoking the current block on the socket's internal queue.
00945  * The methods below can be invoked from within the block to access
00946  * those generally thread-unsafe internal variables in a thread-safe manner.
00947  * The given block will be invoked synchronously on the socket's internal queue.
00948  * 
00949  * If you save references to any protected variables and use them outside the block, you do so at your own peril.
00950 **/
00951 - (void)performBlock:(dispatch_block_t)block;
00952 
00953 /**
00954  * These methods are only available from within the context of a performBlock: invocation.
00955  * See the documentation for the performBlock: method above.
00956  * 
00957  * Provides access to the socket's file descriptor(s).
00958  * If the socket is a server socket (is accepting incoming connections),
00959  * it might actually have multiple internal socket file descriptors - one for IPv4 and one for IPv6.
00960 **/
00961 - (int)socketFD;
00962 
00963 /**
00964     returns int
00965 **/
00966 - (int)socket4FD;
00967 
00968 /**
00969     returns int
00970 **/
00971 - (int)socket6FD;
00972 
00973 #if TARGET_OS_IPHONE
00974 
00975 /**
00976  * These methods are only available from within the context of a performBlock: invocation.
00977  * See the documentation for the performBlock: method above.
00978  * 
00979  * Provides access to the socket's internal read/write streams.
00980  * These streams are normally only created if startTLS has been invoked to start SSL/TLS (see note below),
00981  * but if these methods are invoked, the read/write streams will be created automatically so that you may use them.
00982  * 
00983  * See also: (BOOL)enableBackgroundingOnSocket
00984  * 
00985  * Note: Apple has decided to keep the SecureTransport framework private is iOS.
00986  * This means the only supplied way to do SSL/TLS is via CFStream or some other API layered on top of it.
00987  * Thus, in order to provide SSL/TLS support on iOS we are forced to rely on CFStream,
00988  * instead of the preferred and faster and more powerful SecureTransport.
00989 **/
00990 - (CFReadStreamRef)readStream;
00991 
00992 /**
00993     returns CFWriteStreamRef
00994 **/
00995 - (CFWriteStreamRef)writeStream;
00996 
00997 /**
00998  * This method is only available from within the context of a performBlock: invocation.
00999  * See the documentation for the performBlock: method above.
01000  * 
01001  * Configures the socket to allow it to operate when the iOS application has been backgrounded.
01002  * In other words, this method creates a read & write stream, and invokes:
01003  * 
01004  * CFReadStreamSetProperty(readStream, kCFStreamNetworkServiceType, kCFStreamNetworkServiceTypeVoIP);
01005  * CFWriteStreamSetProperty(writeStream, kCFStreamNetworkServiceType, kCFStreamNetworkServiceTypeVoIP);
01006  * 
01007  * Returns YES if successful, NO otherwise.
01008  * 
01009  * Note: Apple does not officially support backgrounding server sockets.
01010  * That is, if your socket is accepting incoming connections, Apple does not officially support
01011  * allowing iOS applications to accept incoming connections while an app is backgrounded.
01012  * 
01013  * Example usage:
01014  * 
01015  * - (void)socket:(GCDAsyncSocket *)sock didConnectToHost:(NSString *)host port:(UInt16)port
01016  * {
01017  *     [asyncSocket performBlock:^{
01018  *         [asyncSocket enableBackgroundingOnSocket];
01019  *     }];
01020  * }
01021 **/
01022 - (BOOL)enableBackgroundingOnSocket;
01023 
01024 /**
01025  * This method is only available from within the context of a performBlock: invocation.
01026  * See the documentation for the performBlock: method above.
01027  * 
01028  * This method should be used in place of the usual enableBackgroundingOnSocket method if
01029  * you later plan on securing the socket with SSL/TLS via the startTLS method.
01030  * 
01031  * This is due to a bug in iOS. Description of the bug:
01032  * 
01033  * First of all, Apple has decided to keep the SecureTransport framework private in iOS.
01034  * This removes the preferred, faster, and more powerful way of doing SSL/TLS.
01035  * The only option they have given us on iOS is to use CFStream.
01036  * 
01037  * In addition to this, Apple does not allow us to enable SSL/TLS on a stream after it has been opened.
01038  * This effectively breaks many newer protocols which negotiate upgrades to TLS in-band (such as XMPP).
01039  * 
01040  * And on top of that, if we flag a socket for backgrounding, that flag doesn't take effect until
01041  * after we have opened the socket. And if we try to flag the socket for backgrounding after we've opened
01042  * the socket, the flagging fails.
01043  * 
01044  * So the order of operations matters, and the ONLY order that works is this:
01045  * 
01046  * - Create read and write stream
01047  * - Mark streams for backgrounding
01048  * - Setup SSL on streams
01049  * - Open streams
01050  * 
01051  * So the caveat is that this method will mark the socket for backgrounding,
01052  * but it will not open the read and write streams. (Because if it did, later attempts to start TLS would fail.)
01053  * Thus the socket will not actually support backgrounding until after the startTLS method has been called.
01054 **/
01055 - (BOOL)enableBackgroundingOnSocketWithCaveat;
01056 
01057 #else
01058 
01059 /**
01060  * This method is only available from within the context of a performBlock: invocation.
01061  * See the documentation for the performBlock: method above.
01062  * 
01063  * Provides access to the socket's SSLContext, if SSL/TLS has been started on the socket.
01064 **/
01065 - (SSLContextRef)sslContext;
01066 
01067 #endif
01068 
01069 #pragma mark Utilities
01070 
01071 /***************************************************************
01072  * Extracting host and port information from raw address data.
01073 *****************************************************************/
01074 
01075 /**
01076     Class method
01077     Gets the host from an address
01078     param NSData
01079     returns NSString
01080 **/
01081 + (NSString *)hostFromAddress:(NSData *)address;
01082 
01083 /**
01084     Class method
01085     Get the port from an address
01086     param NSData
01087     returns UInt16
01088 **/
01089 + (UInt16)portFromAddress:(NSData *)address;
01090 
01091 /**
01092     Class method
01093     param NSString (pointer to a pointer)
01094     param UInt16
01095     param NSData
01096     returns BOOL
01097 **/
01098 + (BOOL)getHost:(NSString **)hostPtr port:(UInt16 *)portPtr fromAddress:(NSData *)address;
01099 
01100 /**
01101  * A few common line separators, for use with the readDataToData:... methods.
01102 **/
01103 
01104 /**
01105     Class method
01106     returns NSData
01107 **/
01108 + (NSData *)CRLFData;   // 0x0D0A - Carriage return and line feed
01109 
01110 /**
01111     Class method
01112     returns NSData
01113 **/
01114 + (NSData *)CRData;     // 0x0D  - Carriage return
01115 
01116 /**
01117     Class method
01118     returns NSData
01119 **/
01120 + (NSData *)LFData;     // 0x0A - line feed
01121 
01122 /**
01123     Class method
01124     returns NSData
01125 **/
01126 + (NSData *)ZeroData;   // 0x00 - empty NSData object
01127 
01128 @end
01129 
01130 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
01131 #pragma mark -
01132 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
01133 
01134 @protocol GCDAsyncSocketDelegate
01135 @optional
01136 
01137 /**
01138  * This method is called immediately prior to socket:didAcceptNewSocket:.
01139  * It optionally allows a listening socket to specify the socketQueue for a new accepted socket.
01140  * If this method is not implemented, or returns NULL, the new accepted socket will create its own default queue.
01141  * 
01142  * Since you cannot autorelease a dispatch_queue,
01143  * this method uses the "new" prefix in its name to specify that the returned queue has been retained.
01144  * 
01145  * Thus you could do something like this in the implementation:
01146  * return dispatch_queue_create("MyQueue", NULL);
01147  * 
01148  * If you are placing multiple sockets on the same queue,
01149  * then care should be taken to increment the retain count each time this method is invoked.
01150  * 
01151  * For example, your implementation might look something like this:
01152  * dispatch_retain(myExistingQueue);
01153  * return myExistingQueue;
01154 **/
01155 - (dispatch_queue_t)newSocketQueueForConnectionFromAddress:(NSData *)address onSocket:(GCDAsyncSocket *)sock;
01156 
01157 /**
01158  * Called when a socket accepts a connection.
01159  * Another socket is automatically spawned to handle it.
01160  * 
01161  * You must retain the newSocket if you wish to handle the connection.
01162  * Otherwise the newSocket instance will be released and the spawned connection will be closed.
01163  * 
01164  * By default the new socket will have the same delegate and delegateQueue.
01165  * You may, of course, change this at any time.
01166 **/
01167 - (void)socket:(GCDAsyncSocket *)sock didAcceptNewSocket:(GCDAsyncSocket *)newSocket;
01168 
01169 /**
01170  * Called when a socket connects and is ready for reading and writing.
01171  * The host parameter will be an IP address, not a DNS name.
01172 **/
01173 - (void)socket:(GCDAsyncSocket *)sock didConnectToHost:(NSString *)host port:(UInt16)port;
01174 
01175 /**
01176     Called when a socket has completed reading the requested data into memory.
01177     Not called if there is an error.
01178     param NCDAsyncSocket
01179     param NSData
01180     param long
01181 **/
01182 - (void)socket:(GCDAsyncSocket *)sock didReadData:(NSData *)data withTag:(long)tag;
01183 
01184 /**
01185  * Called when a socket has read in data, but has not yet completed the read.
01186  * This would occur if using readToData: or readToLength: methods.
01187  * It may be used to for things such as updating progress bars.
01188 **/
01189 - (void)socket:(GCDAsyncSocket *)sock didReadPartialDataOfLength:(NSUInteger)partialLength tag:(long)tag;
01190 
01191 /**
01192  * Called when a socket has completed writing the requested data. Not called if there is an error.
01193 **/
01194 - (void)socket:(GCDAsyncSocket *)sock didWriteDataWithTag:(long)tag;
01195 
01196 /**
01197  * Called when a socket has written some data, but has not yet completed the entire write.
01198  * It may be used to for things such as updating progress bars.
01199 **/
01200 - (void)socket:(GCDAsyncSocket *)sock didWritePartialDataOfLength:(NSUInteger)partialLength tag:(long)tag;
01201 
01202 /**
01203  * Called if a read operation has reached its timeout without completing.
01204  * This method allows you to optionally extend the timeout.
01205  * If you return a positive time interval (> 0) the read's timeout will be extended by the given amount.
01206  * If you don't implement this method, or return a non-positive time interval (<= 0) the read will timeout as usual.
01207  * 
01208  * The elapsed parameter is the sum of the original timeout, plus any additions previously added via this method.
01209  * The length parameter is the number of bytes that have been read so far for the read operation.
01210  * 
01211  * Note that this method may be called multiple times for a single read if you return positive numbers.
01212 **/
01213 - (NSTimeInterval)socket:(GCDAsyncSocket *)sock shouldTimeoutReadWithTag:(long)tag
01214             elapsed:(NSTimeInterval)elapsed
01215             bytesDone:(NSUInteger)length;
01216 
01217 /**
01218     Called if a write operation has reached its timeout without completing.
01219  
01220     This method allows you to optionally extend the timeout.
01221  
01222     If you return a positive time interval (> 0) the write's timeout will be extended by the given amount.
01223  
01224     If you don't implement this method, or return a non-positive time interval (<= 0) the write will timeout as usual.
01225  
01226     The elapsed parameter is the sum of the original timeout, plus any additions previously added via this method.
01227  
01228     The length parameter is the number of bytes that have been written so far for the write operation.
01229 
01230     Note that this method may be called multiple times for a single write if you return positive numbers.
01231  
01232     param GCDAsyncSocket
01233     param long
01234     param NSTimeInterval
01235     param NSUInteger
01236     returns NSTimeInterval
01237 **/
01238 - (NSTimeInterval)socket:(GCDAsyncSocket *)sock shouldTimeoutWriteWithTag:(long)tag
01239         elapsed:(NSTimeInterval)elapsed
01240         bytesDone:(NSUInteger)length;
01241 
01242 /**
01243     Conditionally called if the read stream closes, but the write stream may still be writeable.
01244 
01245     This delegate method is only called if autoDisconnectOnClosedReadStream has been set to NO.
01246     See the discussion on the autoDisconnectOnClosedReadStream method for more information.
01247     param GCDAsyncSocket
01248 **/
01249 - (void)socketDidCloseReadStream:(GCDAsyncSocket *)sock;
01250 
01251 /**
01252     Called when a socket disconnects with or without error.
01253  
01254     If you call the disconnect method, and the socket wasn't already disconnected, this delegate method will be called before the disconnect method returns.
01255     param GCDAsyncSocket
01256     param NSError
01257 **/
01258 - (void)socketDidDisconnect:(GCDAsyncSocket *)sock withError:(NSError *)err;
01259 
01260 /**
01261     Called after the socket has successfully completed SSL/TLS negotiation.
01262  
01263     This method is not called unless you use the provided startTLS method.
01264  
01265     If a SSL/TLS negotiation fails (invalid certificate, etc) then the socket will immediately close, and the socketDidDisconnect:withError: delegate method will be called with the specific SSL error code.
01266     param GCDAsyncSocket
01267 **/
01268 - (void)socketDidSecure:(GCDAsyncSocket *)sock;
01269 
01270 @end
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Properties Defines