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