PageRenderTime 57ms CodeModel.GetById 19ms app.highlight 25ms RepoModel.GetById 1ms app.codeStats 1ms

/Vendor/CocoaAsyncSocket/GCDAsyncSocket.h

https://github.com/lujingyu/XMPPFramework
C++ Header | 1175 lines | 183 code | 94 blank | 898 comment | 0 complexity | 7e20d67791173a1be0678b5024f094d9 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1//  
   2//  GCDAsyncSocket.h
   3//  
   4//  This class is in the public domain.
   5//  Originally created by Robbie Hanson in Q3 2010.
   6//  Updated and maintained by Deusty LLC and the Apple development community.
   7//  
   8//  https://github.com/robbiehanson/CocoaAsyncSocket
   9//
  10
  11#import <Foundation/Foundation.h>
  12#import <Security/Security.h>
  13#import <Security/SecureTransport.h>
  14#import <dispatch/dispatch.h>
  15#import <Availability.h>
  16
  17#include <sys/socket.h> // AF_INET, AF_INET6
  18
  19@class GCDAsyncReadPacket;
  20@class GCDAsyncWritePacket;
  21@class GCDAsyncSocketPreBuffer;
  22
  23extern NSString *const GCDAsyncSocketException;
  24extern NSString *const GCDAsyncSocketErrorDomain;
  25
  26extern NSString *const GCDAsyncSocketQueueName;
  27extern NSString *const GCDAsyncSocketThreadName;
  28
  29extern NSString *const GCDAsyncSocketManuallyEvaluateTrust;
  30#if TARGET_OS_IPHONE
  31extern NSString *const GCDAsyncSocketUseCFStreamForTLS;
  32#endif
  33#define GCDAsyncSocketSSLPeerName     (NSString *)kCFStreamSSLPeerName
  34#define GCDAsyncSocketSSLCertificates (NSString *)kCFStreamSSLCertificates
  35#define GCDAsyncSocketSSLIsServer     (NSString *)kCFStreamSSLIsServer
  36extern NSString *const GCDAsyncSocketSSLPeerID;
  37extern NSString *const GCDAsyncSocketSSLProtocolVersionMin;
  38extern NSString *const GCDAsyncSocketSSLProtocolVersionMax;
  39extern NSString *const GCDAsyncSocketSSLSessionOptionFalseStart;
  40extern NSString *const GCDAsyncSocketSSLSessionOptionSendOneByteRecord;
  41extern NSString *const GCDAsyncSocketSSLCipherSuites;
  42#if !TARGET_OS_IPHONE
  43extern NSString *const GCDAsyncSocketSSLDiffieHellmanParameters;
  44#endif
  45
  46#define GCDAsyncSocketLoggingContext 65535
  47
  48
  49enum GCDAsyncSocketError
  50{
  51	GCDAsyncSocketNoError = 0,           // Never used
  52	GCDAsyncSocketBadConfigError,        // Invalid configuration
  53	GCDAsyncSocketBadParamError,         // Invalid parameter was passed
  54	GCDAsyncSocketConnectTimeoutError,   // A connect operation timed out
  55	GCDAsyncSocketReadTimeoutError,      // A read operation timed out
  56	GCDAsyncSocketWriteTimeoutError,     // A write operation timed out
  57	GCDAsyncSocketReadMaxedOutError,     // Reached set maxLength without completing
  58	GCDAsyncSocketClosedError,           // The remote peer closed the connection
  59	GCDAsyncSocketOtherError,            // Description provided in userInfo
  60};
  61typedef enum GCDAsyncSocketError GCDAsyncSocketError;
  62
  63////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  64#pragma mark -
  65////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  66
  67@interface GCDAsyncSocket : NSObject
  68
  69/**
  70 * GCDAsyncSocket uses the standard delegate paradigm,
  71 * but executes all delegate callbacks on a given delegate dispatch queue.
  72 * This allows for maximum concurrency, while at the same time providing easy thread safety.
  73 * 
  74 * You MUST set a delegate AND delegate dispatch queue before attempting to
  75 * use the socket, or you will get an error.
  76 * 
  77 * The socket queue is optional.
  78 * If you pass NULL, GCDAsyncSocket will automatically create it's own socket queue.
  79 * If you choose to provide a socket queue, the socket queue must not be a concurrent queue.
  80 * If you choose to provide a socket queue, and the socket queue has a configured target queue,
  81 * then please see the discussion for the method markSocketQueueTargetQueue.
  82 * 
  83 * The delegate queue and socket queue can optionally be the same.
  84**/
  85- (id)init;
  86- (id)initWithSocketQueue:(dispatch_queue_t)sq;
  87- (id)initWithDelegate:(id)aDelegate delegateQueue:(dispatch_queue_t)dq;
  88- (id)initWithDelegate:(id)aDelegate delegateQueue:(dispatch_queue_t)dq socketQueue:(dispatch_queue_t)sq;
  89
  90#pragma mark Configuration
  91
  92@property (atomic, weak, readwrite) id delegate;
  93@property (atomic, strong, readwrite) dispatch_queue_t delegateQueue;
  94
  95- (void)getDelegate:(id *)delegatePtr delegateQueue:(dispatch_queue_t *)delegateQueuePtr;
  96- (void)setDelegate:(id)delegate delegateQueue:(dispatch_queue_t)delegateQueue;
  97
  98/**
  99 * If you are setting the delegate to nil within the delegate's dealloc method,
 100 * you may need to use the synchronous versions below.
 101**/
 102- (void)synchronouslySetDelegate:(id)delegate;
 103- (void)synchronouslySetDelegateQueue:(dispatch_queue_t)delegateQueue;
 104- (void)synchronouslySetDelegate:(id)delegate delegateQueue:(dispatch_queue_t)delegateQueue;
 105
 106/**
 107 * By default, both IPv4 and IPv6 are enabled.
 108 * 
 109 * For accepting incoming connections, this means GCDAsyncSocket automatically supports both protocols,
 110 * and can simulataneously accept incoming connections on either protocol.
 111 * 
 112 * For outgoing connections, this means GCDAsyncSocket can connect to remote hosts running either protocol.
 113 * If a DNS lookup returns only IPv4 results, GCDAsyncSocket will automatically use IPv4.
 114 * If a DNS lookup returns only IPv6 results, GCDAsyncSocket will automatically use IPv6.
 115 * If a DNS lookup returns both IPv4 and IPv6 results, the preferred protocol will be chosen.
 116 * By default, the preferred protocol is IPv4, but may be configured as desired.
 117**/
 118
 119@property (atomic, assign, readwrite, getter=isIPv4Enabled) BOOL IPv4Enabled;
 120@property (atomic, assign, readwrite, getter=isIPv6Enabled) BOOL IPv6Enabled;
 121
 122@property (atomic, assign, readwrite, getter=isIPv4PreferredOverIPv6) BOOL IPv4PreferredOverIPv6;
 123
 124/**
 125 * User data allows you to associate arbitrary information with the socket.
 126 * This data is not used internally by socket in any way.
 127**/
 128@property (atomic, strong, readwrite) id userData;
 129
 130#pragma mark Accepting
 131
 132/**
 133 * Tells the socket to begin listening and accepting connections on the given port.
 134 * When a connection is accepted, a new instance of GCDAsyncSocket will be spawned to handle it,
 135 * and the socket:didAcceptNewSocket: delegate method will be invoked.
 136 * 
 137 * The socket will listen on all available interfaces (e.g. wifi, ethernet, etc)
 138**/
 139- (BOOL)acceptOnPort:(uint16_t)port error:(NSError **)errPtr;
 140
 141/**
 142 * This method is the same as acceptOnPort:error: with the
 143 * additional option of specifying which interface to listen on.
 144 * 
 145 * For example, you could specify that the socket should only accept connections over ethernet,
 146 * and not other interfaces such as wifi.
 147 * 
 148 * The interface may be specified by name (e.g. "en1" or "lo0") or by IP address (e.g. "192.168.4.34").
 149 * You may also use the special strings "localhost" or "loopback" to specify that
 150 * the socket only accept connections from the local machine.
 151 * 
 152 * You can see the list of interfaces via the command line utility "ifconfig",
 153 * or programmatically via the getifaddrs() function.
 154 * 
 155 * To accept connections on any interface pass nil, or simply use the acceptOnPort:error: method.
 156**/
 157- (BOOL)acceptOnInterface:(NSString *)interface port:(uint16_t)port error:(NSError **)errPtr;
 158
 159#pragma mark Connecting
 160
 161/**
 162 * Connects to the given host and port.
 163 * 
 164 * This method invokes connectToHost:onPort:viaInterface:withTimeout:error:
 165 * and uses the default interface, and no timeout.
 166**/
 167- (BOOL)connectToHost:(NSString *)host onPort:(uint16_t)port error:(NSError **)errPtr;
 168
 169/**
 170 * Connects to the given host and port with an optional timeout.
 171 * 
 172 * This method invokes connectToHost:onPort:viaInterface:withTimeout:error: and uses the default interface.
 173**/
 174- (BOOL)connectToHost:(NSString *)host
 175               onPort:(uint16_t)port
 176          withTimeout:(NSTimeInterval)timeout
 177                error:(NSError **)errPtr;
 178
 179/**
 180 * Connects to the given host & port, via the optional interface, with an optional timeout.
 181 * 
 182 * The host may be a domain name (e.g. "deusty.com") or an IP address string (e.g. "192.168.0.2").
 183 * The host may also be the special strings "localhost" or "loopback" to specify connecting
 184 * to a service on the local machine.
 185 * 
 186 * The interface may be a name (e.g. "en1" or "lo0") or the corresponding IP address (e.g. "192.168.4.35").
 187 * The interface may also be used to specify the local port (see below).
 188 * 
 189 * To not time out use a negative time interval.
 190 * 
 191 * This method will return NO if an error is detected, and set the error pointer (if one was given).
 192 * Possible errors would be a nil host, invalid interface, or socket is already connected.
 193 * 
 194 * If no errors are detected, this method will start a background connect operation and immediately return YES.
 195 * The delegate callbacks are used to notify you when the socket connects, or if the host was unreachable.
 196 * 
 197 * Since this class supports queued reads and writes, you can immediately start reading and/or writing.
 198 * All read/write operations will be queued, and upon socket connection,
 199 * the operations will be dequeued and processed in order.
 200 * 
 201 * The interface may optionally contain a port number at the end of the string, separated by a colon.
 202 * This allows you to specify the local port that should be used for the outgoing connection. (read paragraph to end)
 203 * To specify both interface and local port: "en1:8082" or "192.168.4.35:2424".
 204 * To specify only local port: ":8082".
 205 * Please note this is an advanced feature, and is somewhat hidden on purpose.
 206 * You should understand that 99.999% of the time you should NOT specify the local port for an outgoing connection.
 207 * If you think you need to, there is a very good chance you have a fundamental misunderstanding somewhere.
 208 * Local ports do NOT need to match remote ports. In fact, they almost never do.
 209 * This feature is here for networking professionals using very advanced techniques.
 210**/
 211- (BOOL)connectToHost:(NSString *)host
 212               onPort:(uint16_t)port
 213         viaInterface:(NSString *)interface
 214          withTimeout:(NSTimeInterval)timeout
 215                error:(NSError **)errPtr;
 216
 217/**
 218 * Connects to the given address, specified as a sockaddr structure wrapped in a NSData object.
 219 * For example, a NSData object returned from NSNetService's addresses method.
 220 * 
 221 * If you have an existing struct sockaddr you can convert it to a NSData object like so:
 222 * struct sockaddr sa  -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];
 223 * struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];
 224 * 
 225 * This method invokes connectToAdd
 226**/
 227- (BOOL)connectToAddress:(NSData *)remoteAddr error:(NSError **)errPtr;
 228
 229/**
 230 * This method is the same as connectToAddress:error: with an additional timeout option.
 231 * To not time out use a negative time interval, or simply use the connectToAddress:error: method.
 232**/
 233- (BOOL)connectToAddress:(NSData *)remoteAddr withTimeout:(NSTimeInterval)timeout error:(NSError **)errPtr;
 234
 235/**
 236 * Connects to the given address, using the specified interface and timeout.
 237 * 
 238 * The address is specified as a sockaddr structure wrapped in a NSData object.
 239 * For example, a NSData object returned from NSNetService's addresses method.
 240 * 
 241 * If you have an existing struct sockaddr you can convert it to a NSData object like so:
 242 * struct sockaddr sa  -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];
 243 * struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];
 244 * 
 245 * The interface may be a name (e.g. "en1" or "lo0") or the corresponding IP address (e.g. "192.168.4.35").
 246 * The interface may also be used to specify the local port (see below).
 247 * 
 248 * The timeout is optional. To not time out use a negative time interval.
 249 * 
 250 * This method will return NO if an error is detected, and set the error pointer (if one was given).
 251 * Possible errors would be a nil host, invalid interface, or socket is already connected.
 252 * 
 253 * If no errors are detected, this method will start a background connect operation and immediately return YES.
 254 * The delegate callbacks are used to notify you when the socket connects, or if the host was unreachable.
 255 * 
 256 * Since this class supports queued reads and writes, you can immediately start reading and/or writing.
 257 * All read/write operations will be queued, and upon socket connection,
 258 * the operations will be dequeued and processed in order.
 259 * 
 260 * The interface may optionally contain a port number at the end of the string, separated by a colon.
 261 * This allows you to specify the local port that should be used for the outgoing connection. (read paragraph to end)
 262 * To specify both interface and local port: "en1:8082" or "192.168.4.35:2424".
 263 * To specify only local port: ":8082".
 264 * Please note this is an advanced feature, and is somewhat hidden on purpose.
 265 * You should understand that 99.999% of the time you should NOT specify the local port for an outgoing connection.
 266 * If you think you need to, there is a very good chance you have a fundamental misunderstanding somewhere.
 267 * Local ports do NOT need to match remote ports. In fact, they almost never do.
 268 * This feature is here for networking professionals using very advanced techniques.
 269**/
 270- (BOOL)connectToAddress:(NSData *)remoteAddr
 271            viaInterface:(NSString *)interface
 272             withTimeout:(NSTimeInterval)timeout
 273                   error:(NSError **)errPtr;
 274
 275#pragma mark Disconnecting
 276
 277/**
 278 * Disconnects immediately (synchronously). Any pending reads or writes are dropped.
 279 * 
 280 * If the socket is not already disconnected, an invocation to the socketDidDisconnect:withError: delegate method
 281 * will be queued onto the delegateQueue asynchronously (behind any previously queued delegate methods).
 282 * In other words, the disconnected delegate method will be invoked sometime shortly after this method returns.
 283 * 
 284 * Please note the recommended way of releasing a GCDAsyncSocket instance (e.g. in a dealloc method)
 285 * [asyncSocket setDelegate:nil];
 286 * [asyncSocket disconnect];
 287 * [asyncSocket release];
 288 * 
 289 * If you plan on disconnecting the socket, and then immediately asking it to connect again,
 290 * you'll likely want to do so like this:
 291 * [asyncSocket setDelegate:nil];
 292 * [asyncSocket disconnect];
 293 * [asyncSocket setDelegate:self];
 294 * [asyncSocket connect...];
 295**/
 296- (void)disconnect;
 297
 298/**
 299 * Disconnects after all pending reads have completed.
 300 * After calling this, the read and write methods will do nothing.
 301 * The socket will disconnect even if there are still pending writes.
 302**/
 303- (void)disconnectAfterReading;
 304
 305/**
 306 * Disconnects after all pending writes have completed.
 307 * After calling this, the read and write methods will do nothing.
 308 * The socket will disconnect even if there are still pending reads.
 309**/
 310- (void)disconnectAfterWriting;
 311
 312/**
 313 * Disconnects after all pending reads and writes have completed.
 314 * After calling this, the read and write methods will do nothing.
 315**/
 316- (void)disconnectAfterReadingAndWriting;
 317
 318#pragma mark Diagnostics
 319
 320/**
 321 * Returns whether the socket is disconnected or connected.
 322 * 
 323 * A disconnected socket may be recycled.
 324 * That is, it can used again for connecting or listening.
 325 * 
 326 * If a socket is in the process of connecting, it may be neither disconnected nor connected.
 327**/
 328@property (atomic, readonly) BOOL isDisconnected;
 329@property (atomic, readonly) BOOL isConnected;
 330
 331/**
 332 * Returns the local or remote host and port to which this socket is connected, or nil and 0 if not connected.
 333 * The host will be an IP address.
 334**/
 335@property (atomic, readonly) NSString *connectedHost;
 336@property (atomic, readonly) uint16_t  connectedPort;
 337
 338@property (atomic, readonly) NSString *localHost;
 339@property (atomic, readonly) uint16_t  localPort;
 340
 341/**
 342 * Returns the local or remote address to which this socket is connected,
 343 * specified as a sockaddr structure wrapped in a NSData object.
 344 * 
 345 * @seealso connectedHost
 346 * @seealso connectedPort
 347 * @seealso localHost
 348 * @seealso localPort
 349**/
 350@property (atomic, readonly) NSData *connectedAddress;
 351@property (atomic, readonly) NSData *localAddress;
 352
 353/**
 354 * Returns whether the socket is IPv4 or IPv6.
 355 * An accepting socket may be both.
 356**/
 357@property (atomic, readonly) BOOL isIPv4;
 358@property (atomic, readonly) BOOL isIPv6;
 359
 360/**
 361 * Returns whether or not the socket has been secured via SSL/TLS.
 362 * 
 363 * See also the startTLS method.
 364**/
 365@property (atomic, readonly) BOOL isSecure;
 366
 367#pragma mark Reading
 368
 369// The readData and writeData methods won't block (they are asynchronous).
 370// 
 371// When a read is complete the socket:didReadData:withTag: delegate method is dispatched on the delegateQueue.
 372// When a write is complete the socket:didWriteDataWithTag: delegate method is dispatched on the delegateQueue.
 373// 
 374// You may optionally set a timeout for any read/write operation. (To not timeout, use a negative time interval.)
 375// If a read/write opertion times out, the corresponding "socket:shouldTimeout..." delegate method
 376// is called to optionally allow you to extend the timeout.
 377// Upon a timeout, the "socket:didDisconnectWithError:" method is called
 378// 
 379// The tag is for your convenience.
 380// You can use it as an array index, step number, state id, pointer, etc.
 381
 382/**
 383 * Reads the first available bytes that become available on the socket.
 384 * 
 385 * If the timeout value is negative, the read operation will not use a timeout.
 386**/
 387- (void)readDataWithTimeout:(NSTimeInterval)timeout tag:(long)tag;
 388
 389/**
 390 * Reads the first available bytes that become available on the socket.
 391 * The bytes will be appended to the given byte buffer starting at the given offset.
 392 * The given buffer will automatically be increased in size if needed.
 393 * 
 394 * If the timeout value is negative, the read operation will not use a timeout.
 395 * If the buffer if nil, the socket will create a buffer for you.
 396 * 
 397 * If the bufferOffset is greater than the length of the given buffer,
 398 * the method will do nothing, and the delegate will not be called.
 399 * 
 400 * If you pass a buffer, you must not alter it in any way while the socket is using it.
 401 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
 402 * That is, it will reference the bytes that were appended to the given buffer via
 403 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
 404**/
 405- (void)readDataWithTimeout:(NSTimeInterval)timeout
 406					 buffer:(NSMutableData *)buffer
 407			   bufferOffset:(NSUInteger)offset
 408						tag:(long)tag;
 409
 410/**
 411 * Reads the first available bytes that become available on the socket.
 412 * The bytes will be appended to the given byte buffer starting at the given offset.
 413 * The given buffer will automatically be increased in size if needed.
 414 * A maximum of length bytes will be read.
 415 * 
 416 * If the timeout value is negative, the read operation will not use a timeout.
 417 * If the buffer if nil, a buffer will automatically be created for you.
 418 * If maxLength is zero, no length restriction is enforced.
 419 * 
 420 * If the bufferOffset is greater than the length of the given buffer,
 421 * the method will do nothing, and the delegate will not be called.
 422 * 
 423 * If you pass a buffer, you must not alter it in any way while the socket is using it.
 424 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
 425 * That is, it will reference the bytes that were appended to the given buffer  via
 426 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
 427**/
 428- (void)readDataWithTimeout:(NSTimeInterval)timeout
 429                     buffer:(NSMutableData *)buffer
 430               bufferOffset:(NSUInteger)offset
 431                  maxLength:(NSUInteger)length
 432                        tag:(long)tag;
 433
 434/**
 435 * Reads the given number of bytes.
 436 * 
 437 * If the timeout value is negative, the read operation will not use a timeout.
 438 * 
 439 * If the length is 0, this method does nothing and the delegate is not called.
 440**/
 441- (void)readDataToLength:(NSUInteger)length withTimeout:(NSTimeInterval)timeout tag:(long)tag;
 442
 443/**
 444 * Reads the given number of bytes.
 445 * The bytes will be appended to the given byte buffer starting at the given offset.
 446 * The given buffer will automatically be increased in size if needed.
 447 * 
 448 * If the timeout value is negative, the read operation will not use a timeout.
 449 * If the buffer if nil, a buffer will automatically be created for you.
 450 * 
 451 * If the length is 0, this method does nothing and the delegate is not called.
 452 * If the bufferOffset is greater than the length of the given buffer,
 453 * the method will do nothing, and the delegate will not be called.
 454 * 
 455 * If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
 456 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
 457 * That is, it will reference the bytes that were appended to the given buffer via
 458 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
 459**/
 460- (void)readDataToLength:(NSUInteger)length
 461             withTimeout:(NSTimeInterval)timeout
 462                  buffer:(NSMutableData *)buffer
 463            bufferOffset:(NSUInteger)offset
 464                     tag:(long)tag;
 465
 466/**
 467 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
 468 * 
 469 * If the timeout value is negative, the read operation will not use a timeout.
 470 * 
 471 * If you pass nil or zero-length data as the "data" parameter,
 472 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
 473 * 
 474 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
 475 * If you're developing your own custom protocol, be sure your separator can not occur naturally as
 476 * part of the data between separators.
 477 * For example, imagine you want to send several small documents over a socket.
 478 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
 479 * In this particular example, it would be better to use a protocol similar to HTTP with
 480 * a header that includes the length of the document.
 481 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.
 482 * 
 483 * The given data (separator) parameter should be immutable.
 484 * For performance reasons, the socket will retain it, not copy it.
 485 * So if it is immutable, don't modify it while the socket is using it.
 486**/
 487- (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;
 488
 489/**
 490 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
 491 * The bytes will be appended to the given byte buffer starting at the given offset.
 492 * The given buffer will automatically be increased in size if needed.
 493 * 
 494 * If the timeout value is negative, the read operation will not use a timeout.
 495 * If the buffer if nil, a buffer will automatically be created for you.
 496 * 
 497 * If the bufferOffset is greater than the length of the given buffer,
 498 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
 499 * 
 500 * If you pass a buffer, you must not alter it in any way while the socket is using it.
 501 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
 502 * That is, it will reference the bytes that were appended to the given buffer via
 503 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
 504 * 
 505 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
 506 * If you're developing your own custom protocol, be sure your separator can not occur naturally as
 507 * part of the data between separators.
 508 * For example, imagine you want to send several small documents over a socket.
 509 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
 510 * In this particular example, it would be better to use a protocol similar to HTTP with
 511 * a header that includes the length of the document.
 512 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.
 513 * 
 514 * The given data (separator) parameter should be immutable.
 515 * For performance reasons, the socket will retain it, not copy it.
 516 * So if it is immutable, don't modify it while the socket is using it.
 517**/
 518- (void)readDataToData:(NSData *)data
 519           withTimeout:(NSTimeInterval)timeout
 520                buffer:(NSMutableData *)buffer
 521          bufferOffset:(NSUInteger)offset
 522                   tag:(long)tag;
 523
 524/**
 525 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
 526 * 
 527 * If the timeout value is negative, the read operation will not use a timeout.
 528 * 
 529 * If maxLength is zero, no length restriction is enforced.
 530 * Otherwise if maxLength bytes are read without completing the read,
 531 * it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.
 532 * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
 533 * 
 534 * If you pass nil or zero-length data as the "data" parameter,
 535 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
 536 * If you pass a maxLength parameter that is less than the length of the data parameter,
 537 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
 538 * 
 539 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
 540 * If you're developing your own custom protocol, be sure your separator can not occur naturally as
 541 * part of the data between separators.
 542 * For example, imagine you want to send several small documents over a socket.
 543 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
 544 * In this particular example, it would be better to use a protocol similar to HTTP with
 545 * a header that includes the length of the document.
 546 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.
 547 * 
 548 * The given data (separator) parameter should be immutable.
 549 * For performance reasons, the socket will retain it, not copy it.
 550 * So if it is immutable, don't modify it while the socket is using it.
 551**/
 552- (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout maxLength:(NSUInteger)length tag:(long)tag;
 553
 554/**
 555 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
 556 * The bytes will be appended to the given byte buffer starting at the given offset.
 557 * The given buffer will automatically be increased in size if needed.
 558 * 
 559 * If the timeout value is negative, the read operation will not use a timeout.
 560 * If the buffer if nil, a buffer will automatically be created for you.
 561 * 
 562 * If maxLength is zero, no length restriction is enforced.
 563 * Otherwise if maxLength bytes are read without completing the read,
 564 * it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.
 565 * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
 566 * 
 567 * If you pass a maxLength parameter that is less than the length of the data (separator) parameter,
 568 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
 569 * If the bufferOffset is greater than the length of the given buffer,
 570 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
 571 * 
 572 * If you pass a buffer, you must not alter it in any way while the socket is using it.
 573 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
 574 * That is, it will reference the bytes that were appended to the given buffer via
 575 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
 576 * 
 577 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
 578 * If you're developing your own custom protocol, be sure your separator can not occur naturally as
 579 * part of the data between separators.
 580 * For example, imagine you want to send several small documents over a socket.
 581 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
 582 * In this particular example, it would be better to use a protocol similar to HTTP with
 583 * a header that includes the length of the document.
 584 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.
 585 * 
 586 * The given data (separator) parameter should be immutable.
 587 * For performance reasons, the socket will retain it, not copy it.
 588 * So if it is immutable, don't modify it while the socket is using it.
 589**/
 590- (void)readDataToData:(NSData *)data
 591           withTimeout:(NSTimeInterval)timeout
 592                buffer:(NSMutableData *)buffer
 593          bufferOffset:(NSUInteger)offset
 594             maxLength:(NSUInteger)length
 595                   tag:(long)tag;
 596
 597/**
 598 * Returns progress of the current read, from 0.0 to 1.0, or NaN if no current read (use isnan() to check).
 599 * The parameters "tag", "done" and "total" will be filled in if they aren't NULL.
 600**/
 601- (float)progressOfReadReturningTag:(long *)tagPtr bytesDone:(NSUInteger *)donePtr total:(NSUInteger *)totalPtr;
 602
 603#pragma mark Writing
 604
 605/**
 606 * Writes data to the socket, and calls the delegate when finished.
 607 * 
 608 * If you pass in nil or zero-length data, this method does nothing and the delegate will not be called.
 609 * If the timeout value is negative, the write operation will not use a timeout.
 610 * 
 611 * Thread-Safety Note:
 612 * If the given data parameter is mutable (NSMutableData) then you MUST NOT alter the data while
 613 * the socket is writing it. In other words, it's not safe to alter the data until after the delegate method
 614 * socket:didWriteDataWithTag: is invoked signifying that this particular write operation has completed.
 615 * This is due to the fact that GCDAsyncSocket does NOT copy the data. It simply retains it.
 616 * This is for performance reasons. Often times, if NSMutableData is passed, it is because
 617 * a request/response was built up in memory. Copying this data adds an unwanted/unneeded overhead.
 618 * If you need to write data from an immutable buffer, and you need to alter the buffer before the socket
 619 * completes writing the bytes (which is NOT immediately after this method returns, but rather at a later time
 620 * when the delegate method notifies you), then you should first copy the bytes, and pass the copy to this method.
 621**/
 622- (void)writeData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;
 623
 624/**
 625 * Returns progress of the current write, from 0.0 to 1.0, or NaN if no current write (use isnan() to check).
 626 * The parameters "tag", "done" and "total" will be filled in if they aren't NULL.
 627**/
 628- (float)progressOfWriteReturningTag:(long *)tagPtr bytesDone:(NSUInteger *)donePtr total:(NSUInteger *)totalPtr;
 629
 630#pragma mark Security
 631
 632/**
 633 * Secures the connection using SSL/TLS.
 634 * 
 635 * This method may be called at any time, and the TLS handshake will occur after all pending reads and writes
 636 * are finished. This allows one the option of sending a protocol dependent StartTLS message, and queuing
 637 * the upgrade to TLS at the same time, without having to wait for the write to finish.
 638 * Any reads or writes scheduled after this method is called will occur over the secured connection.
 639 *
 640 * ==== The available TOP-LEVEL KEYS are:
 641 * 
 642 * - GCDAsyncSocketManuallyEvaluateTrust
 643 *     The value must be of type NSNumber, encapsulating a BOOL value.
 644 *     If you set this to YES, then the underlying SecureTransport system will not evaluate the SecTrustRef of the peer.
 645 *     Instead it will pause at the moment evaulation would typically occur,
 646 *     and allow us to handle the security evaluation however we see fit.
 647 *     So GCDAsyncSocket will invoke the delegate method socket:shouldTrustPeer: passing the SecTrustRef.
 648 *
 649 *     Note that if you set this option, then all other configuration keys are ignored.
 650 *     Evaluation will be completely up to you during the socket:didReceiveTrust:completionHandler: delegate method.
 651 *
 652 *     For more information on trust evaluation see:
 653 *     Apple's Technical Note TN2232 - HTTPS Server Trust Evaluation
 654 *     https://developer.apple.com/library/ios/technotes/tn2232/_index.html
 655 *     
 656 *     If unspecified, the default value is NO.
 657 *
 658 * - GCDAsyncSocketUseCFStreamForTLS (iOS only)
 659 *     The value must be of type NSNumber, encapsulating a BOOL value.
 660 *     By default GCDAsyncSocket will use the SecureTransport layer to perform encryption.
 661 *     This gives us more control over the security protocol (many more configuration options),
 662 *     plus it allows us to optimize things like sys calls and buffer allocation.
 663 *     
 664 *     However, if you absolutely must, you can instruct GCDAsyncSocket to use the old-fashioned encryption
 665 *     technique by going through the CFStream instead. So instead of using SecureTransport, GCDAsyncSocket
 666 *     will instead setup a CFRead/CFWriteStream. And then set the kCFStreamPropertySSLSettings property
 667 *     (via CFReadStreamSetProperty / CFWriteStreamSetProperty) and will pass the given options to this method.
 668 *     
 669 *     Thus all the other keys in the given dictionary will be ignored by GCDAsyncSocket,
 670 *     and will passed directly CFReadStreamSetProperty / CFWriteStreamSetProperty.
 671 *     For more infomation on these keys, please see the documentation for kCFStreamPropertySSLSettings.
 672 *
 673 *     If unspecified, the default value is NO.
 674 *
 675 * ==== The available CONFIGURATION KEYS are:
 676 *
 677 * - kCFStreamSSLPeerName
 678 *     The value must be of type NSString.
 679 *     It should match the name in the X.509 certificate given by the remote party.
 680 *     See Apple's documentation for SSLSetPeerDomainName.
 681 *
 682 * - kCFStreamSSLCertificates
 683 *     The value must be of type NSArray.
 684 *     See Apple's documentation for SSLSetCertificate.
 685 *
 686 * - kCFStreamSSLIsServer
 687 *     The value must be of type NSNumber, encapsulationg a BOOL value.
 688 *     See Apple's documentation for SSLCreateContext for iOS.
 689 *     This is optional for iOS. If not supplied, a NO value is the default.
 690 *     This is not needed for Mac OS X, and the value is ignored.
 691 *
 692 * - GCDAsyncSocketSSLPeerID
 693 *     The value must be of type NSData.
 694 *     You must set this value if you want to use TLS session resumption.
 695 *     See Apple's documentation for SSLSetPeerID.
 696 *
 697 * - GCDAsyncSocketSSLProtocolVersionMin
 698 * - GCDAsyncSocketSSLProtocolVersionMax
 699 *     The value(s) must be of type NSNumber, encapsulting a SSLProtocol value.
 700 *     See Apple's documentation for SSLSetProtocolVersionMin & SSLSetProtocolVersionMax.
 701 *     See also the SSLProtocol typedef.
 702 * 
 703 * - GCDAsyncSocketSSLSessionOptionFalseStart
 704 *     The value must be of type NSNumber, encapsulating a BOOL value.
 705 *     See Apple's documentation for kSSLSessionOptionFalseStart.
 706 * 
 707 * - GCDAsyncSocketSSLSessionOptionSendOneByteRecord
 708 *     The value must be of type NSNumber, encapsulating a BOOL value.
 709 *     See Apple's documentation for kSSLSessionOptionSendOneByteRecord.
 710 * 
 711 * - GCDAsyncSocketSSLCipherSuites
 712 *     The values must be of type NSArray.
 713 *     Each item within the array must be a NSNumber, encapsulating
 714 *     See Apple's documentation for SSLSetEnabledCiphers.
 715 *     See also the SSLCipherSuite typedef.
 716 *
 717 * - GCDAsyncSocketSSLDiffieHellmanParameters (Mac OS X only)
 718 *     The value must be of type NSData.
 719 *     See Apple's documentation for SSLSetDiffieHellmanParams.
 720 * 
 721 * ==== The following UNAVAILABLE KEYS are: (with throw an exception)
 722 * 
 723 * - kCFStreamSSLAllowsAnyRoot (UNAVAILABLE)
 724 *     You MUST use manual trust evaluation instead (see GCDAsyncSocketManuallyEvaluateTrust).
 725 *     Corresponding deprecated method: SSLSetAllowsAnyRoot
 726 * 
 727 * - kCFStreamSSLAllowsExpiredRoots (UNAVAILABLE)
 728 *     You MUST use manual trust evaluation instead (see GCDAsyncSocketManuallyEvaluateTrust).
 729 *     Corresponding deprecated method: SSLSetAllowsExpiredRoots
 730 *
 731 * - kCFStreamSSLAllowsExpiredCertificates (UNAVAILABLE)
 732 *     You MUST use manual trust evaluation instead (see GCDAsyncSocketManuallyEvaluateTrust).
 733 *     Corresponding deprecated method: SSLSetAllowsExpiredCerts
 734 *
 735 * - kCFStreamSSLValidatesCertificateChain (UNAVAILABLE)
 736 *     You MUST use manual trust evaluation instead (see GCDAsyncSocketManuallyEvaluateTrust).
 737 *     Corresponding deprecated method: SSLSetEnableCertVerify
 738 *
 739 * - kCFStreamSSLLevel (UNAVAILABLE)
 740 *     You MUST use GCDAsyncSocketSSLProtocolVersionMin & GCDAsyncSocketSSLProtocolVersionMin instead.
 741 *     Corresponding deprecated method: SSLSetProtocolVersionEnabled
 742 *
 743 * 
 744 * Please refer to Apple's documentation for corresponding SSLFunctions.
 745 *
 746 * If you pass in nil or an empty dictionary, the default settings will be used.
 747 * 
 748 * IMPORTANT SECURITY NOTE:
 749 * The default settings will check to make sure the remote party's certificate is signed by a
 750 * trusted 3rd party certificate agency (e.g. verisign) and that the certificate is not expired.
 751 * However it will not verify the name on the certificate unless you
 752 * give it a name to verify against via the kCFStreamSSLPeerName key.
 753 * The security implications of this are important to understand.
 754 * Imagine you are attempting to create a secure connection to MySecureServer.com,
 755 * but your socket gets directed to MaliciousServer.com because of a hacked DNS server.
 756 * If you simply use the default settings, and MaliciousServer.com has a valid certificate,
 757 * the default settings will not detect any problems since the certificate is valid.
 758 * To properly secure your connection in this particular scenario you
 759 * should set the kCFStreamSSLPeerName property to "MySecureServer.com".
 760 * 
 761 * You can also perform additional validation in socketDidSecure.
 762**/
 763- (void)startTLS:(NSDictionary *)tlsSettings;
 764
 765#pragma mark Advanced
 766
 767/**
 768 * Traditionally sockets are not closed until the conversation is over.
 769 * However, it is technically possible for the remote enpoint to close its write stream.
 770 * Our socket would then be notified that there is no more data to be read,
 771 * but our socket would still be writeable and the remote endpoint could continue to receive our data.
 772 * 
 773 * The argument for this confusing functionality stems from the idea that a client could shut down its
 774 * write stream after sending a request to the server, thus notifying the server there are to be no further requests.
 775 * In practice, however, this technique did little to help server developers.
 776 * 
 777 * To make matters worse, from a TCP perspective there is no way to tell the difference from a read stream close
 778 * and a full socket close. They both result in the TCP stack receiving a FIN packet. The only way to tell
 779 * is by continuing to write to the socket. If it was only a read stream close, then writes will continue to work.
 780 * Otherwise an error will be occur shortly (when the remote end sends us a RST packet).
 781 * 
 782 * In addition to the technical challenges and confusion, many high level socket/stream API's provide
 783 * no support for dealing with the problem. If the read stream is closed, the API immediately declares the
 784 * socket to be closed, and shuts down the write stream as well. In fact, this is what Apple's CFStream API does.
 785 * It might sound like poor design at first, but in fact it simplifies development.
 786 * 
 787 * The vast majority of the time if the read stream is closed it's because the remote endpoint closed its socket.
 788 * Thus it actually makes sense to close the socket at this point.
 789 * And in fact this is what most networking developers want and expect to happen.
 790 * However, if you are writing a server that interacts with a plethora of clients,
 791 * you might encounter a client that uses the discouraged technique of shutting down its write stream.
 792 * If this is the case, you can set this property to NO,
 793 * and make use of the socketDidCloseReadStream delegate method.
 794 * 
 795 * The default value is YES.
 796**/
 797@property (atomic, assign, readwrite) BOOL autoDisconnectOnClosedReadStream;
 798
 799/**
 800 * GCDAsyncSocket maintains thread safety by using an internal serial dispatch_queue.
 801 * In most cases, the instance creates this queue itself.
 802 * However, to allow for maximum flexibility, the internal queue may be passed in the init method.
 803 * This allows for some advanced options such as controlling socket priority via target queues.
 804 * However, when one begins to use target queues like this, they open the door to some specific deadlock issues.
 805 * 
 806 * For example, imagine there are 2 queues:
 807 * dispatch_queue_t socketQueue;
 808 * dispatch_queue_t socketTargetQueue;
 809 * 
 810 * If you do this (pseudo-code):
 811 * socketQueue.targetQueue = socketTargetQueue;
 812 * 
 813 * Then all socketQueue operations will actually get run on the given socketTargetQueue.
 814 * This is fine and works great in most situations.
 815 * But if you run code directly from within the socketTargetQueue that accesses the socket,
 816 * you could potentially get deadlock. Imagine the following code:
 817 * 
 818 * - (BOOL)socketHasSomething
 819 * {
 820 *     __block BOOL result = NO;
 821 *     dispatch_block_t block = ^{
 822 *         result = [self someInternalMethodToBeRunOnlyOnSocketQueue];
 823 *     }
 824 *     if (is_executing_on_queue(socketQueue))
 825 *         block();
 826 *     else
 827 *         dispatch_sync(socketQueue, block);
 828 *     
 829 *     return result;
 830 * }
 831 * 
 832 * What happens if you call this method from the socketTargetQueue? The result is deadlock.
 833 * This is because the GCD API offers no mechanism to discover a queue's targetQueue.
 834 * Thus we have no idea if our socketQueue is configured with a targetQueue.
 835 * If we had this information, we could easily avoid deadlock.
 836 * But, since these API's are missing or unfeasible, you'll have to explicitly set it.
 837 * 
 838 * IF you pass a socketQueue via the init method,
 839 * AND you've configured the passed socketQueue with a targetQueue,
 840 * THEN you should pass the end queue in the target hierarchy.
 841 * 
 842 * For example, consider the following queue hierarchy:
 843 * socketQueue -> ipQueue -> moduleQueue
 844 *
 845 * This example demonstrates priority shaping within some server.
 846 * All incoming client connections from the same IP address are executed on the same target queue.
 847 * And all connections for a particular module are executed on the same target queue.
 848 * Thus, the priority of all networking for the entire module can be changed on the fly.
 849 * Additionally, networking traffic from a single IP cannot monopolize the module.
 850 * 
 851 * Here's how you would accomplish something like that:
 852 * - (dispatch_queue_t)newSocketQueueForConnectionFromAddress:(NSData *)address onSocket:(GCDAsyncSocket *)sock
 853 * {
 854 *     dispatch_queue_t socketQueue = dispatch_queue_create("", NULL);
 855 *     dispatch_queue_t ipQueue = [self ipQueueForAddress:address];
 856 *     
 857 *     dispatch_set_target_queue(socketQueue, ipQueue);
 858 *     dispatch_set_target_queue(iqQueue, moduleQueue);
 859 *     
 860 *     return socketQueue;
 861 * }
 862 * - (void)socket:(GCDAsyncSocket *)sock didAcceptNewSocket:(GCDAsyncSocket *)newSocket
 863 * {
 864 *     [clientConnections addObject:newSocket];
 865 *     [newSocket markSocketQueueTargetQueue:moduleQueue];
 866 * }
 867 * 
 868 * Note: This workaround is ONLY needed if you intend to execute code directly on the ipQueue or moduleQueue.
 869 * This is often NOT the case, as such queues are used solely for execution shaping.
 870**/
 871- (void)markSocketQueueTargetQueue:(dispatch_queue_t)socketQueuesPreConfiguredTargetQueue;
 872- (void)unmarkSocketQueueTargetQueue:(dispatch_queue_t)socketQueuesPreviouslyConfiguredTargetQueue;
 873
 874/**
 875 * It's not thread-safe to access certain variables from outside the socket's internal queue.
 876 * 
 877 * For example, the socket file descriptor.
 878 * File descriptors are simply integers which reference an index in the per-process file table.
 879 * However, when one requests a new file descriptor (by opening a file or socket),
 880 * the file descriptor returned is guaranteed to be the lowest numbered unused descriptor.
 881 * So if we're not careful, the following could be possible:
 882 * 
 883 * - Thread A invokes a method which returns the socket's file descriptor.
 884 * - The socket is closed via the socket's internal queue on thread B.
 885 * - Thread C opens a file, and subsequently receives the file descriptor that was previously the socket's FD.
 886 * - Thread A is now accessing/altering the file instead of the socket.
 887 * 
 888 * In addition to this, other variables are not actually objects,
 889 * and thus cannot be retained/released or even autoreleased.
 890 * An example is the sslContext, of type SSLContextRef, which is actually a malloc'd struct.
 891 * 
 892 * Although there are internal variables that make it difficult to maintain thread-safety,
 893 * it is important to provide access to these variables
 894 * to ensure this class can be used in a wide array of environments.
 895 * This method helps to accomplish this by invoking the current block on the socket's internal queue.
 896 * The methods below can be invoked from within the block to access
 897 * those generally thread-unsafe internal variables in a thread-safe manner.
 898 * The given block will be invoked synchronously on the socket's internal queue.
 899 * 
 900 * If you save references to any protected variables and use them outside the block, you do so at your own peril.
 901**/
 902- (void)performBlock:(dispatch_block_t)block;
 903
 904/**
 905 * These methods are only available from within the context of a performBlock: invocation.
 906 * See the documentation for the performBlock: method above.
 907 * 
 908 * Provides access to the socket's file descriptor(s).
 909 * If the socket is a server socket (is accepting incoming connections),
 910 * it might actually have multiple internal socket file descriptors - one for IPv4 and one for IPv6.
 911**/
 912- (int)socketFD;
 913- (int)socket4FD;
 914- (int)socket6FD;
 915
 916#if TARGET_OS_IPHONE
 917
 918/**
 919 * These methods are only available from within the context of a performBlock: invocation.
 920 * See the documentation for the performBlock: method above.
 921 * 
 922 * Provides access to the socket's internal CFReadStream/CFWriteStream.
 923 * 
 924 * These streams are only used as workarounds for specific iOS shortcomings:
 925 * 
 926 * - Apple has decided to keep the SecureTransport framework private is iOS.
 927 *   This means the only supplied way to do SSL/TLS is via CFStream or some other API layered on top of it.
 928 *   Thus, in order to provide SSL/TLS support on iOS we are forced to rely on CFStream,
 929 *   instead of the preferred and faster and more powerful SecureTransport.
 930 * 
 931 * - If a socket doesn't have backgrounding enabled, and that socket is closed while the app is backgrounded,
 932 *   Apple only bothers to notify us via the CFStream API.
 933 *   The faster and more powerful GCD API isn't notified properly in this case.
 934 * 
 935 * See also: (BOOL)enableBackgroundingOnSocket
 936**/
 937- (CFReadStreamRef)readStream;
 938- (CFWriteStreamRef)writeStream;
 939
 940/**
 941 * This method is only available from within the context of a performBlock: invocation.
 942 * See the documentation for the performBlock: method above.
 943 * 
 944 * Configures the socket to allow it to operate when the iOS application has been backgrounded.
 945 * In other words, this method creates a read & write stream, and invokes:
 946 * 
 947 * CFReadStreamSetProperty(readStream, kCFStreamNetworkServiceType, kCFStreamNetworkServiceTypeVoIP);
 948 * CFWriteStreamSetProperty(writeStream, kCFStreamNetworkServiceType, kCFStreamNetworkServiceTypeVoIP);
 949 * 
 950 * Returns YES if successful, NO otherwise.
 951 * 
 952 * Note: Apple does not officially support backgrounding server sockets.
 953 * That is, if your socket is accepting incoming connections, Apple does not officially support
 954 * allowing iOS applications to accept incoming connections while an app is backgrounded.
 955 * 
 956 * Example usage:
 957 * 
 958 * - (void)socket:(GCDAsyncSocket *)sock didConnectToHost:(NSString *)host port:(uint16_t)port
 959 * {
 960 *     [asyncSocket performBlock:^{
 961 *         [asyncSocket enableBackgroundingOnSocket];
 962 *     }];
 963 * }
 964**/
 965- (BOOL)enableBackgroundingOnSocket;
 966
 967#endif
 968
 969/**
 970 * This method is only available from within the context of a performBlock: invocation.
 971 * See the documentation for the performBlock: method above.
 972 * 
 973 * Provides access to the socket's SSLContext, if SSL/TLS has been started on the socket.
 974**/
 975- (SSLContextRef)sslContext;
 976
 977#pragma mark Utilities
 978
 979/**
 980 * The address lookup utility used by the class.
 981 * This method is synchronous, so it's recommended you use it on a background thread/queue.
 982 * 
 983 * The special strings "localhost" and "loopback" return the loopback address for IPv4 and IPv6.
 984 * 
 985 * @returns
 986 *   A mutable array with all IPv4 and IPv6 addresses returned by getaddrinfo.
 987 *   The addresses are specifically for TCP connections.
 988 *   You can filter the addresses, if needed, using the other utility methods provided by the class.
 989**/
 990+ (NSMutableArray *)lookupHost:(NSString *)host port:(uint16_t)port error:(NSError **)errPtr;
 991
 992/**
 993 * Extracting host and port information from raw address data.
 994**/
 995
 996+ (NSString *)hostFromAddress:(NSData *)address;
 997+ (uint16_t)portFromAddress:(NSData *)address;
 998
 999+ (BOOL)isIPv4Address:(NSData *)address;
1000+ (BOOL)isIPv6Address:(NSData *)address;
1001
1002+ (BOOL)getHost:(NSString **)hostPtr port:(uint16_t *)portPtr fromAddress:(NSData *)address;
1003
1004+ (BOOL)getHost:(NSString **)hostPtr port:(uint16_t *)portPtr family:(sa_family_t *)afPtr fromAddress:(NSData *)address;
1005
1006/**
1007 * A few common line separators, for use with the readDataToData:... methods.
1008**/
1009+ (NSData *)CRLFData;   // 0x0D0A
1010+ (NSData *)CRData;     // 0x0D
1011+ (NSData *)LFData;     // 0x0A
1012+ (NSData *)ZeroData;   // 0x00
1013
1014@end
1015
1016////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
1017#pragma mark -
1018////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
1019
1020@protocol GCDAsyncSocketDelegate
1021@optional
1022
1023/**
1024 * This method is called immediately prior to socket:didAcceptNewSocket:.
1025 * It optionally allows a listening socket to specify the socketQueue for a new accepted socket.
1026 * If this method is not implemented, or returns NULL, the new accepted socket will create its own default queue.
1027 * 
1028 * Since you cannot autorelease…

Large files files are truncated, but you can click here to view the full file