/Vendor/CocoaAsyncSocket/GCDAsyncSocket.h
C++ Header | 1175 lines | 183 code | 94 blank | 898 comment | 0 complexity | 7e20d67791173a1be0678b5024f094d9 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 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 a dispatch_queue, 1029 * this method uses the "new" prefix in its name to specify that the returned queue has been retained. 1030 * 1031 * Thus you could do something like this in the implementation: 1032 * return dispatch_queue_create("MyQueue", NULL); 1033 * 1034 * If you are placing multiple sockets on the same queue, 1035 * then care should be taken to increment the retain count each time this method is invoked. 1036 * 1037 * For example, your implementation might look something like this: 1038 * dispatch_retain(myExistingQueue); 1039 * return myExistingQueue; 1040**/ 1041- (dispatch_queue_t)newSocketQueueForConnectionFromAddress:(NSData *)address onSocket:(GCDAsyncSocket *)sock; 1042 1043/** 1044 * Called when a socket accepts a connection. 1045 * Another socket is automatically spawned to handle it. 1046 * 1047 * You must retain the newSocket if you wish to handle the connection. 1048 * Otherwise the newSocket instance will be released and the spawned connection will be closed. 1049 * 1050 * By default the new socket will have the same delegate and delegateQueue. 1051 * You may, of course, change this at any time. 1052**/ 1053- (void)socket:(GCDAsyncSocket *)sock didAcceptNewSocket:(GCDAsyncSocket *)newSocket; 1054 1055/** 1056 * Called when a socket connects and is ready for reading and writing. 1057 * The host parameter will be an IP address, not a DNS name. 1058**/ 1059- (void)socket:(GCDAsyncSocket *)sock didConnectToHost:(NSString *)host port:(uint16_t)port; 1060 1061/** 1062 * Called when a socket has completed reading the requested data into memory. 1063 * Not called if there is an error. 1064**/ 1065- (void)socket:(GCDAsyncSocket *)sock didReadData:(NSData *)data withTag:(long)tag; 1066 1067/** 1068 * Called when a socket has read in data, but has not yet completed the read. 1069 * This would occur if using readToData: or readToLength: methods. 1070 * It may be used to for things such as updating progress bars. 1071**/ 1072- (void)socket:(GCDAsyncSocket *)sock didReadPartialDataOfLength:(NSUInteger)partialLength tag:(long)tag; 1073 1074/** 1075 * Called when a socket has completed writing the requested data. Not called if there is an error. 1076**/ 1077- (void)socket:(GCDAsyncSocket *)sock didWriteDataWithTag:(long)tag; 1078 1079/** 1080 * Called when a socket has written some data, but has not yet completed the entire write. 1081 * It may be used to for things such as updating progress bars. 1082**/ 1083- (void)socket:(GCDAsyncSocket *)sock didWritePartialDataOfLength:(NSUInteger)partialLength tag:(long)tag; 1084 1085/** 1086 * Called if a read operation has reached its timeout without completing. 1087 * This method allows you to optionally extend the timeout. 1088 * If you return a positive time interval (> 0) the read's timeout will be extended by the given amount. 1089 * If you don't implement this method, or return a non-positive time interval (<= 0) the read will timeout as usual. 1090 * 1091 * The elapsed parameter is the sum of the original timeout, plus any additions previously added via this method. 1092 * The length parameter is the number of bytes that have been read so far for the read operation. 1093 * 1094 * Note that this method may be called multiple times for a single read if you return positive numbers. 1095**/ 1096- (NSTimeInterval)socket:(GCDAsyncSocket *)sock shouldTimeoutReadWithTag:(long)tag 1097 elapsed:(NSTimeInterval)elapsed 1098 bytesDone:(NSUInteger)length; 1099 1100/** 1101 * Called if a write operation has reached its timeout without completing. 1102 * This method allows you to optionally extend the timeout. 1103 * If you return a positive time interval (> 0) the write's timeout will be extended by the given amount. 1104 * If you don't implement this method, or return a non-positive time interval (<= 0) the write will timeout as usual. 1105 * 1106 * The elapsed parameter is the sum of the original timeout, plus any additions previously added via this method. 1107 * The length parameter is the number of bytes that have been written so far for the write operation. 1108 * 1109 * Note that this method may be called multiple times for a single write if you return positive numbers. 1110**/ 1111- (NSTimeInterval)socket:(GCDAsyncSocket *)sock shouldTimeoutWriteWithTag:(long)tag 1112 elapsed:(NSTimeInterval)elapsed 1113 bytesDone:(NSUInteger)length; 1114 1115/** 1116 * Conditionally called if the read stream closes, but the write stream may still be writeable. 1117 * 1118 * This delegate method is only called if autoDisconnectOnClosedReadStream has been set to NO. 1119 * See the discussion on the autoDisconnectOnClosedReadStream method for more information. 1120**/ 1121- (void)socketDidCloseReadStream:(GCDAsyncSocket *)sock; 1122 1123/** 1124 * Called when a socket disconnects with or without error. 1125 * 1126 * If you call the disconnect method, and the socket wasn't already disconnected, 1127 * then an invocation of this delegate method will be enqueued on the delegateQueue 1128 * before the disconnect method returns. 1129 * 1130 * Note: If the GCDAsyncSocket instance is deallocated while it is still connected, 1131 * and the delegate is not also deallocated, then this method will be invoked, 1132 * but the sock parameter will be nil. (It must necessarily be nil since it is no longer available.) 1133 * This is a generally rare, but is possible if one writes code like this: 1134 * 1135 * asyncSocket = nil; // I'm implicitly disconnecting the socket 1136 * 1137 * In this case it may preferrable to nil the delegate beforehand, like this: 1138 * 1139 * asyncSocket.delegate = nil; // Don't invoke my delegate method 1140 * asyncSocket = nil; // I'm implicitly disconnecting the socket 1141 * 1142 * Of course, this depends on how your state machine is configured. 1143**/ 1144- (void)socketDidDisconnect:(GCDAsyncSocket *)sock withError:(NSError *)err; 1145 1146/** 1147 * Called after the socket has successfully completed SSL/TLS negotiation. 1148 * This method is not called unless you use the provided startTLS method. 1149 * 1150 * If a SSL/TLS negotiation fails (invalid certificate, etc) then the socket will immediately close, 1151 * and the socketDidDisconnect:withError: delegate method will be called with the specific SSL error code. 1152**/ 1153- (void)socketDidSecure:(GCDAsyncSocket *)sock; 1154 1155/** 1156 * Allows a socket delegate to hook into the TLS handshake and manually validate the peer it's connecting to. 1157 * 1158 * This is only called if startTLS is invoked with options that include: 1159 * - GCDAsyncSocketManuallyEvaluateTrust == YES 1160 * 1161 * Typically the delegate will use SecTrustEvaluate (and related functions) to properly validate the peer. 1162 * 1163 * Note from Apple's documentation: 1164 * Because [SecTrustEvaluate] might look on the network for certificates in the certificate chain, 1165 * [it] might block while attempting network access. You should never call it from your main thread; 1166 * call it only from within a function running on a dispatch queue or on a separate thread. 1167 * 1168 * Thus this method uses a completionHandler block rather than a normal return value. 1169 * The completionHandler block is thread-safe, and may be invoked from a background queue/thread. 1170 * It is safe to invoke the completionHandler block even if the socket has been closed. 1171**/ 1172- (void)socket:(GCDAsyncSocket *)sock didReceiveTrust:(SecTrustRef)trust 1173 completionHandler:(void (^)(BOOL shouldTrustPeer))completionHandler; 1174 1175@end