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.
8 // https://github.com/robbiehanson/CocoaAsyncSocket
11 #import <Foundation/Foundation.h>
12 #import <Security/Security.h>
13 #import <Security/SecureTransport.h>
14 #import <dispatch/dispatch.h>
16 @class GCDAsyncReadPacket;
17 @class GCDAsyncWritePacket;
18 @class GCDAsyncSocketPreBuffer;
24 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 50000 // iOS 5.0 supported
26 #if __IPHONE_OS_VERSION_MIN_REQUIRED >= 50000 // iOS 5.0 supported and required
28 #define IS_SECURE_TRANSPORT_AVAILABLE YES
29 #define SECURE_TRANSPORT_MAYBE_AVAILABLE 1
30 #define SECURE_TRANSPORT_MAYBE_UNAVAILABLE 0
32 #else // iOS 5.0 supported but not required
34 #ifndef NSFoundationVersionNumber_iPhoneOS_5_0
35 #define NSFoundationVersionNumber_iPhoneOS_5_0 881.00
38 #define IS_SECURE_TRANSPORT_AVAILABLE (NSFoundationVersionNumber >= NSFoundationVersionNumber_iPhoneOS_5_0)
39 #define SECURE_TRANSPORT_MAYBE_AVAILABLE 1
40 #define SECURE_TRANSPORT_MAYBE_UNAVAILABLE 1
44 #else // iOS 5.0 not supported
46 #define IS_SECURE_TRANSPORT_AVAILABLE NO
47 #define SECURE_TRANSPORT_MAYBE_AVAILABLE 0
48 #define SECURE_TRANSPORT_MAYBE_UNAVAILABLE 1
54 // Compiling for Mac OS X
56 #define IS_SECURE_TRANSPORT_AVAILABLE YES
57 #define SECURE_TRANSPORT_MAYBE_AVAILABLE 1
58 #define SECURE_TRANSPORT_MAYBE_UNAVAILABLE 0
62 extern NSString *const GCDAsyncSocketException;
63 extern NSString *const GCDAsyncSocketErrorDomain;
65 extern NSString *const GCDAsyncSocketQueueName;
66 extern NSString *const GCDAsyncSocketThreadName;
68 #if SECURE_TRANSPORT_MAYBE_AVAILABLE
69 extern NSString *const GCDAsyncSocketSSLCipherSuites;
71 extern NSString *const GCDAsyncSocketSSLProtocolVersionMin;
72 extern NSString *const GCDAsyncSocketSSLProtocolVersionMax;
74 extern NSString *const GCDAsyncSocketSSLDiffieHellmanParameters;
78 enum GCDAsyncSocketError
80 GCDAsyncSocketNoError = 0, // Never used
81 GCDAsyncSocketBadConfigError, // Invalid configuration
82 GCDAsyncSocketBadParamError, // Invalid parameter was passed
83 GCDAsyncSocketConnectTimeoutError, // A connect operation timed out
84 GCDAsyncSocketReadTimeoutError, // A read operation timed out
85 GCDAsyncSocketWriteTimeoutError, // A write operation timed out
86 GCDAsyncSocketReadMaxedOutError, // Reached set maxLength without completing
87 GCDAsyncSocketClosedError, // The remote peer closed the connection
88 GCDAsyncSocketOtherError, // Description provided in userInfo
90 typedef enum GCDAsyncSocketError GCDAsyncSocketError;
92 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
94 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
96 @interface GCDAsyncSocket : NSObject
99 * GCDAsyncSocket uses the standard delegate paradigm,
100 * but executes all delegate callbacks on a given delegate dispatch queue.
101 * This allows for maximum concurrency, while at the same time providing easy thread safety.
103 * You MUST set a delegate AND delegate dispatch queue before attempting to
104 * use the socket, or you will get an error.
106 * The socket queue is optional.
107 * If you pass NULL, GCDAsyncSocket will automatically create it's own socket queue.
108 * If you choose to provide a socket queue, the socket queue must not be a concurrent queue.
109 * If you choose to provide a socket queue, and the socket queue has a configured target queue,
110 * then please see the discussion for the method markSocketQueueTargetQueue.
112 * The delegate queue and socket queue can optionally be the same.
115 - (id)initWithSocketQueue:(dispatch_queue_t)sq;
116 - (id)initWithDelegate:(id)aDelegate delegateQueue:(dispatch_queue_t)dq;
117 - (id)initWithDelegate:(id)aDelegate delegateQueue:(dispatch_queue_t)dq socketQueue:(dispatch_queue_t)sq;
119 #pragma mark Configuration
122 - (void)setDelegate:(id)delegate;
123 - (void)synchronouslySetDelegate:(id)delegate;
125 - (dispatch_queue_t)delegateQueue;
126 - (void)setDelegateQueue:(dispatch_queue_t)delegateQueue;
127 - (void)synchronouslySetDelegateQueue:(dispatch_queue_t)delegateQueue;
129 - (void)getDelegate:(id *)delegatePtr delegateQueue:(dispatch_queue_t *)delegateQueuePtr;
130 - (void)setDelegate:(id)delegate delegateQueue:(dispatch_queue_t)delegateQueue;
131 - (void)synchronouslySetDelegate:(id)delegate delegateQueue:(dispatch_queue_t)delegateQueue;
134 * By default, both IPv4 and IPv6 are enabled.
136 * For accepting incoming connections, this means GCDAsyncSocket automatically supports both protocols,
137 * and can simulataneously accept incoming connections on either protocol.
139 * For outgoing connections, this means GCDAsyncSocket can connect to remote hosts running either protocol.
140 * If a DNS lookup returns only IPv4 results, GCDAsyncSocket will automatically use IPv4.
141 * If a DNS lookup returns only IPv6 results, GCDAsyncSocket will automatically use IPv6.
142 * If a DNS lookup returns both IPv4 and IPv6 results, the preferred protocol will be chosen.
143 * By default, the preferred protocol is IPv4, but may be configured as desired.
145 - (BOOL)isIPv4Enabled;
146 - (void)setIPv4Enabled:(BOOL)flag;
148 - (BOOL)isIPv6Enabled;
149 - (void)setIPv6Enabled:(BOOL)flag;
151 - (BOOL)isIPv4PreferredOverIPv6;
152 - (void)setPreferIPv4OverIPv6:(BOOL)flag;
155 * User data allows you to associate arbitrary information with the socket.
156 * This data is not used internally by socket in any way.
159 - (void)setUserData:(id)arbitraryUserData;
161 #pragma mark Accepting
164 * Tells the socket to begin listening and accepting connections on the given port.
165 * When a connection is accepted, a new instance of GCDAsyncSocket will be spawned to handle it,
166 * and the socket:didAcceptNewSocket: delegate method will be invoked.
168 * The socket will listen on all available interfaces (e.g. wifi, ethernet, etc)
170 - (BOOL)acceptOnPort:(uint16_t)port error:(NSError **)errPtr;
173 * This method is the same as acceptOnPort:error: with the
174 * additional option of specifying which interface to listen on.
176 * For example, you could specify that the socket should only accept connections over ethernet,
177 * and not other interfaces such as wifi.
179 * The interface may be specified by name (e.g. "en1" or "lo0") or by IP address (e.g. "192.168.4.34").
180 * You may also use the special strings "localhost" or "loopback" to specify that
181 * the socket only accept connections from the local machine.
183 * You can see the list of interfaces via the command line utility "ifconfig",
184 * or programmatically via the getifaddrs() function.
186 * To accept connections on any interface pass nil, or simply use the acceptOnPort:error: method.
188 - (BOOL)acceptOnInterface:(NSString *)interface port:(uint16_t)port error:(NSError **)errPtr;
190 #pragma mark Connecting
193 * Connects to the given host and port.
195 * This method invokes connectToHost:onPort:viaInterface:withTimeout:error:
196 * and uses the default interface, and no timeout.
198 - (BOOL)connectToHost:(NSString *)host onPort:(uint16_t)port error:(NSError **)errPtr;
201 * Connects to the given host and port with an optional timeout.
203 * This method invokes connectToHost:onPort:viaInterface:withTimeout:error: and uses the default interface.
205 - (BOOL)connectToHost:(NSString *)host
206 onPort:(uint16_t)port
207 withTimeout:(NSTimeInterval)timeout
208 error:(NSError **)errPtr;
211 * Connects to the given host & port, via the optional interface, with an optional timeout.
213 * The host may be a domain name (e.g. "deusty.com") or an IP address string (e.g. "192.168.0.2").
214 * The host may also be the special strings "localhost" or "loopback" to specify connecting
215 * to a service on the local machine.
217 * The interface may be a name (e.g. "en1" or "lo0") or the corresponding IP address (e.g. "192.168.4.35").
218 * The interface may also be used to specify the local port (see below).
220 * To not time out use a negative time interval.
222 * This method will return NO if an error is detected, and set the error pointer (if one was given).
223 * Possible errors would be a nil host, invalid interface, or socket is already connected.
225 * If no errors are detected, this method will start a background connect operation and immediately return YES.
226 * The delegate callbacks are used to notify you when the socket connects, or if the host was unreachable.
228 * Since this class supports queued reads and writes, you can immediately start reading and/or writing.
229 * All read/write operations will be queued, and upon socket connection,
230 * the operations will be dequeued and processed in order.
232 * The interface may optionally contain a port number at the end of the string, separated by a colon.
233 * This allows you to specify the local port that should be used for the outgoing connection. (read paragraph to end)
234 * To specify both interface and local port: "en1:8082" or "192.168.4.35:2424".
235 * To specify only local port: ":8082".
236 * Please note this is an advanced feature, and is somewhat hidden on purpose.
237 * You should understand that 99.999% of the time you should NOT specify the local port for an outgoing connection.
238 * If you think you need to, there is a very good chance you have a fundamental misunderstanding somewhere.
239 * Local ports do NOT need to match remote ports. In fact, they almost never do.
240 * This feature is here for networking professionals using very advanced techniques.
242 - (BOOL)connectToHost:(NSString *)host
243 onPort:(uint16_t)port
244 viaInterface:(NSString *)interface
245 withTimeout:(NSTimeInterval)timeout
246 error:(NSError **)errPtr;
249 * Connects to the given address, specified as a sockaddr structure wrapped in a NSData object.
250 * For example, a NSData object returned from NSNetService's addresses method.
252 * If you have an existing struct sockaddr you can convert it to a NSData object like so:
253 * struct sockaddr sa -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];
254 * struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];
256 * This method invokes connectToAdd
258 - (BOOL)connectToAddress:(NSData *)remoteAddr error:(NSError **)errPtr;
261 * This method is the same as connectToAddress:error: with an additional timeout option.
262 * To not time out use a negative time interval, or simply use the connectToAddress:error: method.
264 - (BOOL)connectToAddress:(NSData *)remoteAddr withTimeout:(NSTimeInterval)timeout error:(NSError **)errPtr;
267 * Connects to the given address, using the specified interface and timeout.
269 * The address is specified as a sockaddr structure wrapped in a NSData object.
270 * For example, a NSData object returned from NSNetService's addresses method.
272 * If you have an existing struct sockaddr you can convert it to a NSData object like so:
273 * struct sockaddr sa -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];
274 * struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];
276 * The interface may be a name (e.g. "en1" or "lo0") or the corresponding IP address (e.g. "192.168.4.35").
277 * The interface may also be used to specify the local port (see below).
279 * The timeout is optional. To not time out use a negative time interval.
281 * This method will return NO if an error is detected, and set the error pointer (if one was given).
282 * Possible errors would be a nil host, invalid interface, or socket is already connected.
284 * If no errors are detected, this method will start a background connect operation and immediately return YES.
285 * The delegate callbacks are used to notify you when the socket connects, or if the host was unreachable.
287 * Since this class supports queued reads and writes, you can immediately start reading and/or writing.
288 * All read/write operations will be queued, and upon socket connection,
289 * the operations will be dequeued and processed in order.
291 * The interface may optionally contain a port number at the end of the string, separated by a colon.
292 * This allows you to specify the local port that should be used for the outgoing connection. (read paragraph to end)
293 * To specify both interface and local port: "en1:8082" or "192.168.4.35:2424".
294 * To specify only local port: ":8082".
295 * Please note this is an advanced feature, and is somewhat hidden on purpose.
296 * You should understand that 99.999% of the time you should NOT specify the local port for an outgoing connection.
297 * If you think you need to, there is a very good chance you have a fundamental misunderstanding somewhere.
298 * Local ports do NOT need to match remote ports. In fact, they almost never do.
299 * This feature is here for networking professionals using very advanced techniques.
301 - (BOOL)connectToAddress:(NSData *)remoteAddr
302 viaInterface:(NSString *)interface
303 withTimeout:(NSTimeInterval)timeout
304 error:(NSError **)errPtr;
306 #pragma mark Disconnecting
309 * Disconnects immediately (synchronously). Any pending reads or writes are dropped.
311 * If the socket is not already disconnected, an invocation to the socketDidDisconnect:withError: delegate method
312 * will be queued onto the delegateQueue asynchronously (behind any previously queued delegate methods).
313 * In other words, the disconnected delegate method will be invoked sometime shortly after this method returns.
315 * Please note the recommended way of releasing a GCDAsyncSocket instance (e.g. in a dealloc method)
316 * [asyncSocket setDelegate:nil];
317 * [asyncSocket disconnect];
318 * [asyncSocket release];
320 * If you plan on disconnecting the socket, and then immediately asking it to connect again,
321 * you'll likely want to do so like this:
322 * [asyncSocket setDelegate:nil];
323 * [asyncSocket disconnect];
324 * [asyncSocket setDelegate:self];
325 * [asyncSocket connect...];
330 * Disconnects after all pending reads have completed.
331 * After calling this, the read and write methods will do nothing.
332 * The socket will disconnect even if there are still pending writes.
334 - (void)disconnectAfterReading;
337 * Disconnects after all pending writes have completed.
338 * After calling this, the read and write methods will do nothing.
339 * The socket will disconnect even if there are still pending reads.
341 - (void)disconnectAfterWriting;
344 * Disconnects after all pending reads and writes have completed.
345 * After calling this, the read and write methods will do nothing.
347 - (void)disconnectAfterReadingAndWriting;
349 #pragma mark Diagnostics
352 * Returns whether the socket is disconnected or connected.
354 * A disconnected socket may be recycled.
355 * That is, it can used again for connecting or listening.
357 * If a socket is in the process of connecting, it may be neither disconnected nor connected.
359 - (BOOL)isDisconnected;
363 * Returns the local or remote host and port to which this socket is connected, or nil and 0 if not connected.
364 * The host will be an IP address.
366 - (NSString *)connectedHost;
367 - (uint16_t)connectedPort;
369 - (NSString *)localHost;
370 - (uint16_t)localPort;
373 * Returns the local or remote address to which this socket is connected,
374 * specified as a sockaddr structure wrapped in a NSData object.
376 * See also the connectedHost, connectedPort, localHost and localPort methods.
378 - (NSData *)connectedAddress;
379 - (NSData *)localAddress;
382 * Returns whether the socket is IPv4 or IPv6.
383 * An accepting socket may be both.
389 * Returns whether or not the socket has been secured via SSL/TLS.
391 * See also the startTLS method.
397 // The readData and writeData methods won't block (they are asynchronous).
399 // When a read is complete the socket:didReadData:withTag: delegate method is dispatched on the delegateQueue.
400 // When a write is complete the socket:didWriteDataWithTag: delegate method is dispatched on the delegateQueue.
402 // You may optionally set a timeout for any read/write operation. (To not timeout, use a negative time interval.)
403 // If a read/write opertion times out, the corresponding "socket:shouldTimeout..." delegate method
404 // is called to optionally allow you to extend the timeout.
405 // Upon a timeout, the "socket:didDisconnectWithError:" method is called
407 // The tag is for your convenience.
408 // You can use it as an array index, step number, state id, pointer, etc.
411 * Reads the first available bytes that become available on the socket.
413 * If the timeout value is negative, the read operation will not use a timeout.
415 - (void)readDataWithTimeout:(NSTimeInterval)timeout tag:(long)tag;
418 * Reads the first available bytes that become available on the socket.
419 * The bytes will be appended to the given byte buffer starting at the given offset.
420 * The given buffer will automatically be increased in size if needed.
422 * If the timeout value is negative, the read operation will not use a timeout.
423 * If the buffer if nil, the socket will create a buffer for you.
425 * If the bufferOffset is greater than the length of the given buffer,
426 * the method will do nothing, and the delegate will not be called.
428 * If you pass a buffer, you must not alter it in any way while the socket is using it.
429 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
430 * That is, it will reference the bytes that were appended to the given buffer via
431 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
433 - (void)readDataWithTimeout:(NSTimeInterval)timeout
434 buffer:(NSMutableData *)buffer
435 bufferOffset:(NSUInteger)offset
439 * Reads the first available bytes that become available on the socket.
440 * The bytes will be appended to the given byte buffer starting at the given offset.
441 * The given buffer will automatically be increased in size if needed.
442 * A maximum of length bytes will be read.
444 * If the timeout value is negative, the read operation will not use a timeout.
445 * If the buffer if nil, a buffer will automatically be created for you.
446 * If maxLength is zero, no length restriction is enforced.
448 * If the bufferOffset is greater than the length of the given buffer,
449 * the method will do nothing, and the delegate will not be called.
451 * If you pass a buffer, you must not alter it in any way while the socket is using it.
452 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
453 * That is, it will reference the bytes that were appended to the given buffer via
454 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
456 - (void)readDataWithTimeout:(NSTimeInterval)timeout
457 buffer:(NSMutableData *)buffer
458 bufferOffset:(NSUInteger)offset
459 maxLength:(NSUInteger)length
463 * Reads the given number of bytes.
465 * If the timeout value is negative, the read operation will not use a timeout.
467 * If the length is 0, this method does nothing and the delegate is not called.
469 - (void)readDataToLength:(NSUInteger)length withTimeout:(NSTimeInterval)timeout tag:(long)tag;
472 * Reads the given number of bytes.
473 * The bytes will be appended to the given byte buffer starting at the given offset.
474 * The given buffer will automatically be increased in size if needed.
476 * If the timeout value is negative, the read operation will not use a timeout.
477 * If the buffer if nil, a buffer will automatically be created for you.
479 * If the length is 0, this method does nothing and the delegate is not called.
480 * If the bufferOffset is greater than the length of the given buffer,
481 * the method will do nothing, and the delegate will not be called.
483 * If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
484 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
485 * That is, it will reference the bytes that were appended to the given buffer via
486 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
488 - (void)readDataToLength:(NSUInteger)length
489 withTimeout:(NSTimeInterval)timeout
490 buffer:(NSMutableData *)buffer
491 bufferOffset:(NSUInteger)offset
495 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
497 * If the timeout value is negative, the read operation will not use a timeout.
499 * If you pass nil or zero-length data as the "data" parameter,
500 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
502 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
503 * If you're developing your own custom protocol, be sure your separator can not occur naturally as
504 * part of the data between separators.
505 * For example, imagine you want to send several small documents over a socket.
506 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
507 * In this particular example, it would be better to use a protocol similar to HTTP with
508 * a header that includes the length of the document.
509 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.
511 * The given data (separator) parameter should be immutable.
512 * For performance reasons, the socket will retain it, not copy it.
513 * So if it is immutable, don't modify it while the socket is using it.
515 - (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;
518 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
519 * The bytes will be appended to the given byte buffer starting at the given offset.
520 * The given buffer will automatically be increased in size if needed.
522 * If the timeout value is negative, the read operation will not use a timeout.
523 * If the buffer if nil, a buffer will automatically be created for you.
525 * If the bufferOffset is greater than the length of the given buffer,
526 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
528 * If you pass a buffer, you must not alter it in any way while the socket is using it.
529 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
530 * That is, it will reference the bytes that were appended to the given buffer via
531 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
533 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
534 * If you're developing your own custom protocol, be sure your separator can not occur naturally as
535 * part of the data between separators.
536 * For example, imagine you want to send several small documents over a socket.
537 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
538 * In this particular example, it would be better to use a protocol similar to HTTP with
539 * a header that includes the length of the document.
540 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.
542 * The given data (separator) parameter should be immutable.
543 * For performance reasons, the socket will retain it, not copy it.
544 * So if it is immutable, don't modify it while the socket is using it.
546 - (void)readDataToData:(NSData *)data
547 withTimeout:(NSTimeInterval)timeout
548 buffer:(NSMutableData *)buffer
549 bufferOffset:(NSUInteger)offset
553 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
555 * If the timeout value is negative, the read operation will not use a timeout.
557 * If maxLength is zero, no length restriction is enforced.
558 * Otherwise if maxLength bytes are read without completing the read,
559 * it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.
560 * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
562 * If you pass nil or zero-length data as the "data" parameter,
563 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
564 * If you pass a maxLength parameter that is less than the length of the data parameter,
565 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
567 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
568 * If you're developing your own custom protocol, be sure your separator can not occur naturally as
569 * part of the data between separators.
570 * For example, imagine you want to send several small documents over a socket.
571 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
572 * In this particular example, it would be better to use a protocol similar to HTTP with
573 * a header that includes the length of the document.
574 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.
576 * The given data (separator) parameter should be immutable.
577 * For performance reasons, the socket will retain it, not copy it.
578 * So if it is immutable, don't modify it while the socket is using it.
580 - (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout maxLength:(NSUInteger)length tag:(long)tag;
583 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.
584 * The bytes will be appended to the given byte buffer starting at the given offset.
585 * The given buffer will automatically be increased in size if needed.
587 * If the timeout value is negative, the read operation will not use a timeout.
588 * If the buffer if nil, a buffer will automatically be created for you.
590 * If maxLength is zero, no length restriction is enforced.
591 * Otherwise if maxLength bytes are read without completing the read,
592 * it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.
593 * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
595 * If you pass a maxLength parameter that is less than the length of the data (separator) parameter,
596 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
597 * If the bufferOffset is greater than the length of the given buffer,
598 * the method will do nothing (except maybe print a warning), and the delegate will not be called.
600 * If you pass a buffer, you must not alter it in any way while the socket is using it.
601 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
602 * That is, it will reference the bytes that were appended to the given buffer via
603 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
605 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
606 * If you're developing your own custom protocol, be sure your separator can not occur naturally as
607 * part of the data between separators.
608 * For example, imagine you want to send several small documents over a socket.
609 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
610 * In this particular example, it would be better to use a protocol similar to HTTP with
611 * a header that includes the length of the document.
612 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.
614 * The given data (separator) parameter should be immutable.
615 * For performance reasons, the socket will retain it, not copy it.
616 * So if it is immutable, don't modify it while the socket is using it.
618 - (void)readDataToData:(NSData *)data
619 withTimeout:(NSTimeInterval)timeout
620 buffer:(NSMutableData *)buffer
621 bufferOffset:(NSUInteger)offset
622 maxLength:(NSUInteger)length
626 * Returns progress of the current read, from 0.0 to 1.0, or NaN if no current read (use isnan() to check).
627 * The parameters "tag", "done" and "total" will be filled in if they aren't NULL.
629 - (float)progressOfReadReturningTag:(long *)tagPtr bytesDone:(NSUInteger *)donePtr total:(NSUInteger *)totalPtr;
634 * Writes data to the socket, and calls the delegate when finished.
636 * If you pass in nil or zero-length data, this method does nothing and the delegate will not be called.
637 * If the timeout value is negative, the write operation will not use a timeout.
639 * Thread-Safety Note:
640 * If the given data parameter is mutable (NSMutableData) then you MUST NOT alter the data while
641 * the socket is writing it. In other words, it's not safe to alter the data until after the delegate method
642 * socket:didWriteDataWithTag: is invoked signifying that this particular write operation has completed.
643 * This is due to the fact that GCDAsyncSocket does NOT copy the data. It simply retains it.
644 * This is for performance reasons. Often times, if NSMutableData is passed, it is because
645 * a request/response was built up in memory. Copying this data adds an unwanted/unneeded overhead.
646 * If you need to write data from an immutable buffer, and you need to alter the buffer before the socket
647 * completes writing the bytes (which is NOT immediately after this method returns, but rather at a later time
648 * when the delegate method notifies you), then you should first copy the bytes, and pass the copy to this method.
650 - (void)writeData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;
653 * Returns progress of the current write, from 0.0 to 1.0, or NaN if no current write (use isnan() to check).
654 * The parameters "tag", "done" and "total" will be filled in if they aren't NULL.
656 - (float)progressOfWriteReturningTag:(long *)tagPtr bytesDone:(NSUInteger *)donePtr total:(NSUInteger *)totalPtr;
658 #pragma mark Security
661 * Secures the connection using SSL/TLS.
663 * This method may be called at any time, and the TLS handshake will occur after all pending reads and writes
664 * are finished. This allows one the option of sending a protocol dependent StartTLS message, and queuing
665 * the upgrade to TLS at the same time, without having to wait for the write to finish.
666 * Any reads or writes scheduled after this method is called will occur over the secured connection.
668 * The possible keys and values for the TLS settings are well documented.
671 * - kCFStreamSSLLevel
672 * - kCFStreamSSLAllowsExpiredCertificates
673 * - kCFStreamSSLAllowsExpiredRoots
674 * - kCFStreamSSLAllowsAnyRoot
675 * - kCFStreamSSLValidatesCertificateChain
676 * - kCFStreamSSLPeerName
677 * - kCFStreamSSLCertificates
678 * - kCFStreamSSLIsServer
680 * If SecureTransport is available on iOS:
682 * - GCDAsyncSocketSSLCipherSuites
683 * - GCDAsyncSocketSSLProtocolVersionMin
684 * - GCDAsyncSocketSSLProtocolVersionMax
686 * If SecureTransport is available on Mac OS X:
688 * - GCDAsyncSocketSSLCipherSuites
689 * - GCDAsyncSocketSSLDiffieHellmanParameters;
692 * Please refer to Apple's documentation for associated values, as well as other possible keys.
694 * If you pass in nil or an empty dictionary, the default settings will be used.
696 * The default settings will check to make sure the remote party's certificate is signed by a
697 * trusted 3rd party certificate agency (e.g. verisign) and that the certificate is not expired.
698 * However it will not verify the name on the certificate unless you
699 * give it a name to verify against via the kCFStreamSSLPeerName key.
700 * The security implications of this are important to understand.
701 * Imagine you are attempting to create a secure connection to MySecureServer.com,
702 * but your socket gets directed to MaliciousServer.com because of a hacked DNS server.
703 * If you simply use the default settings, and MaliciousServer.com has a valid certificate,
704 * the default settings will not detect any problems since the certificate is valid.
705 * To properly secure your connection in this particular scenario you
706 * should set the kCFStreamSSLPeerName property to "MySecureServer.com".
707 * If you do not know the peer name of the remote host in advance (for example, you're not sure
708 * if it will be "domain.com" or "www.domain.com"), then you can use the default settings to validate the
709 * certificate, and then use the X509Certificate class to verify the issuer after the socket has been secured.
710 * The X509Certificate class is part of the CocoaAsyncSocket open source project.
712 - (void)startTLS:(NSDictionary *)tlsSettings;
714 #pragma mark Advanced
717 * Traditionally sockets are not closed until the conversation is over.
718 * However, it is technically possible for the remote enpoint to close its write stream.
719 * Our socket would then be notified that there is no more data to be read,
720 * but our socket would still be writeable and the remote endpoint could continue to receive our data.
722 * The argument for this confusing functionality stems from the idea that a client could shut down its
723 * write stream after sending a request to the server, thus notifying the server there are to be no further requests.
724 * In practice, however, this technique did little to help server developers.
726 * To make matters worse, from a TCP perspective there is no way to tell the difference from a read stream close
727 * and a full socket close. They both result in the TCP stack receiving a FIN packet. The only way to tell
728 * is by continuing to write to the socket. If it was only a read stream close, then writes will continue to work.
729 * Otherwise an error will be occur shortly (when the remote end sends us a RST packet).
731 * In addition to the technical challenges and confusion, many high level socket/stream API's provide
732 * no support for dealing with the problem. If the read stream is closed, the API immediately declares the
733 * socket to be closed, and shuts down the write stream as well. In fact, this is what Apple's CFStream API does.
734 * It might sound like poor design at first, but in fact it simplifies development.
736 * The vast majority of the time if the read stream is closed it's because the remote endpoint closed its socket.
737 * Thus it actually makes sense to close the socket at this point.
738 * And in fact this is what most networking developers want and expect to happen.
739 * However, if you are writing a server that interacts with a plethora of clients,
740 * you might encounter a client that uses the discouraged technique of shutting down its write stream.
741 * If this is the case, you can set this property to NO,
742 * and make use of the socketDidCloseReadStream delegate method.
744 * The default value is YES.
746 - (BOOL)autoDisconnectOnClosedReadStream;
747 - (void)setAutoDisconnectOnClosedReadStream:(BOOL)flag;
750 * GCDAsyncSocket maintains thread safety by using an internal serial dispatch_queue.
751 * In most cases, the instance creates this queue itself.
752 * However, to allow for maximum flexibility, the internal queue may be passed in the init method.
753 * This allows for some advanced options such as controlling socket priority via target queues.
754 * However, when one begins to use target queues like this, they open the door to some specific deadlock issues.
756 * For example, imagine there are 2 queues:
757 * dispatch_queue_t socketQueue;
758 * dispatch_queue_t socketTargetQueue;
760 * If you do this (pseudo-code):
761 * socketQueue.targetQueue = socketTargetQueue;
763 * Then all socketQueue operations will actually get run on the given socketTargetQueue.
764 * This is fine and works great in most situations.
765 * But if you run code directly from within the socketTargetQueue that accesses the socket,
766 * you could potentially get deadlock. Imagine the following code:
768 * - (BOOL)socketHasSomething
770 * __block BOOL result = NO;
771 * dispatch_block_t block = ^{
772 * result = [self someInternalMethodToBeRunOnlyOnSocketQueue];
774 * if (is_executing_on_queue(socketQueue))
777 * dispatch_sync(socketQueue, block);
782 * What happens if you call this method from the socketTargetQueue? The result is deadlock.
783 * This is because the GCD API offers no mechanism to discover a queue's targetQueue.
784 * Thus we have no idea if our socketQueue is configured with a targetQueue.
785 * If we had this information, we could easily avoid deadlock.
786 * But, since these API's are missing or unfeasible, you'll have to explicitly set it.
788 * IF you pass a socketQueue via the init method,
789 * AND you've configured the passed socketQueue with a targetQueue,
790 * THEN you should pass the end queue in the target hierarchy.
792 * For example, consider the following queue hierarchy:
793 * socketQueue -> ipQueue -> moduleQueue
795 * This example demonstrates priority shaping within some server.
796 * All incoming client connections from the same IP address are executed on the same target queue.
797 * And all connections for a particular module are executed on the same target queue.
798 * Thus, the priority of all networking for the entire module can be changed on the fly.
799 * Additionally, networking traffic from a single IP cannot monopolize the module.
801 * Here's how you would accomplish something like that:
802 * - (dispatch_queue_t)newSocketQueueForConnectionFromAddress:(NSData *)address onSocket:(GCDAsyncSocket *)sock
804 * dispatch_queue_t socketQueue = dispatch_queue_create("", NULL);
805 * dispatch_queue_t ipQueue = [self ipQueueForAddress:address];
807 * dispatch_set_target_queue(socketQueue, ipQueue);
808 * dispatch_set_target_queue(iqQueue, moduleQueue);
810 * return socketQueue;
812 * - (void)socket:(GCDAsyncSocket *)sock didAcceptNewSocket:(GCDAsyncSocket *)newSocket
814 * [clientConnections addObject:newSocket];
815 * [newSocket markSocketQueueTargetQueue:moduleQueue];
818 * Note: This workaround is ONLY needed if you intend to execute code directly on the ipQueue or moduleQueue.
819 * This is often NOT the case, as such queues are used solely for execution shaping.
821 - (void)markSocketQueueTargetQueue:(dispatch_queue_t)socketQueuesPreConfiguredTargetQueue;
822 - (void)unmarkSocketQueueTargetQueue:(dispatch_queue_t)socketQueuesPreviouslyConfiguredTargetQueue;
825 * It's not thread-safe to access certain variables from outside the socket's internal queue.
827 * For example, the socket file descriptor.
828 * File descriptors are simply integers which reference an index in the per-process file table.
829 * However, when one requests a new file descriptor (by opening a file or socket),
830 * the file descriptor returned is guaranteed to be the lowest numbered unused descriptor.
831 * So if we're not careful, the following could be possible:
833 * - Thread A invokes a method which returns the socket's file descriptor.
834 * - The socket is closed via the socket's internal queue on thread B.
835 * - Thread C opens a file, and subsequently receives the file descriptor that was previously the socket's FD.
836 * - Thread A is now accessing/altering the file instead of the socket.
838 * In addition to this, other variables are not actually objects,
839 * and thus cannot be retained/released or even autoreleased.
840 * An example is the sslContext, of type SSLContextRef, which is actually a malloc'd struct.
842 * Although there are internal variables that make it difficult to maintain thread-safety,
843 * it is important to provide access to these variables
844 * to ensure this class can be used in a wide array of environments.
845 * This method helps to accomplish this by invoking the current block on the socket's internal queue.
846 * The methods below can be invoked from within the block to access
847 * those generally thread-unsafe internal variables in a thread-safe manner.
848 * The given block will be invoked synchronously on the socket's internal queue.
850 * If you save references to any protected variables and use them outside the block, you do so at your own peril.
852 - (void)performBlock:(dispatch_block_t)block;
855 * These methods are only available from within the context of a performBlock: invocation.
856 * See the documentation for the performBlock: method above.
858 * Provides access to the socket's file descriptor(s).
859 * If the socket is a server socket (is accepting incoming connections),
860 * it might actually have multiple internal socket file descriptors - one for IPv4 and one for IPv6.
869 * These methods are only available from within the context of a performBlock: invocation.
870 * See the documentation for the performBlock: method above.
872 * Provides access to the socket's internal CFReadStream/CFWriteStream.
874 * These streams are only used as workarounds for specific iOS shortcomings:
876 * - Apple has decided to keep the SecureTransport framework private is iOS.
877 * This means the only supplied way to do SSL/TLS is via CFStream or some other API layered on top of it.
878 * Thus, in order to provide SSL/TLS support on iOS we are forced to rely on CFStream,
879 * instead of the preferred and faster and more powerful SecureTransport.
881 * - If a socket doesn't have backgrounding enabled, and that socket is closed while the app is backgrounded,
882 * Apple only bothers to notify us via the CFStream API.
883 * The faster and more powerful GCD API isn't notified properly in this case.
885 * See also: (BOOL)enableBackgroundingOnSocket
887 - (CFReadStreamRef)readStream;
888 - (CFWriteStreamRef)writeStream;
891 * This method is only available from within the context of a performBlock: invocation.
892 * See the documentation for the performBlock: method above.
894 * Configures the socket to allow it to operate when the iOS application has been backgrounded.
895 * In other words, this method creates a read & write stream, and invokes:
897 * CFReadStreamSetProperty(readStream, kCFStreamNetworkServiceType, kCFStreamNetworkServiceTypeVoIP);
898 * CFWriteStreamSetProperty(writeStream, kCFStreamNetworkServiceType, kCFStreamNetworkServiceTypeVoIP);
900 * Returns YES if successful, NO otherwise.
902 * Note: Apple does not officially support backgrounding server sockets.
903 * That is, if your socket is accepting incoming connections, Apple does not officially support
904 * allowing iOS applications to accept incoming connections while an app is backgrounded.
908 * - (void)socket:(GCDAsyncSocket *)sock didConnectToHost:(NSString *)host port:(uint16_t)port
910 * [asyncSocket performBlock:^{
911 * [asyncSocket enableBackgroundingOnSocket];
915 - (BOOL)enableBackgroundingOnSocket;
919 #if SECURE_TRANSPORT_MAYBE_AVAILABLE
922 * This method is only available from within the context of a performBlock: invocation.
923 * See the documentation for the performBlock: method above.
925 * Provides access to the socket's SSLContext, if SSL/TLS has been started on the socket.
927 - (SSLContextRef)sslContext;
931 #pragma mark Utilities
934 * Extracting host and port information from raw address data.
936 + (NSString *)hostFromAddress:(NSData *)address;
937 + (uint16_t)portFromAddress:(NSData *)address;
938 + (BOOL)getHost:(NSString **)hostPtr port:(uint16_t *)portPtr fromAddress:(NSData *)address;
941 * A few common line separators, for use with the readDataToData:... methods.
943 + (NSData *)CRLFData; // 0x0D0A
944 + (NSData *)CRData; // 0x0D
945 + (NSData *)LFData; // 0x0A
946 + (NSData *)ZeroData; // 0x00
950 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
952 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
954 @protocol GCDAsyncSocketDelegate
958 * This method is called immediately prior to socket:didAcceptNewSocket:.
959 * It optionally allows a listening socket to specify the socketQueue for a new accepted socket.
960 * If this method is not implemented, or returns NULL, the new accepted socket will create its own default queue.
962 * Since you cannot autorelease a dispatch_queue,
963 * this method uses the "new" prefix in its name to specify that the returned queue has been retained.
965 * Thus you could do something like this in the implementation:
966 * return dispatch_queue_create("MyQueue", NULL);
968 * If you are placing multiple sockets on the same queue,
969 * then care should be taken to increment the retain count each time this method is invoked.
971 * For example, your implementation might look something like this:
972 * dispatch_retain(myExistingQueue);
973 * return myExistingQueue;
975 - (dispatch_queue_t)newSocketQueueForConnectionFromAddress:(NSData *)address onSocket:(GCDAsyncSocket *)sock;
978 * Called when a socket accepts a connection.
979 * Another socket is automatically spawned to handle it.
981 * You must retain the newSocket if you wish to handle the connection.
982 * Otherwise the newSocket instance will be released and the spawned connection will be closed.
984 * By default the new socket will have the same delegate and delegateQueue.
985 * You may, of course, change this at any time.
987 - (void)socket:(GCDAsyncSocket *)sock didAcceptNewSocket:(GCDAsyncSocket *)newSocket;
990 * Called when a socket connects and is ready for reading and writing.
991 * The host parameter will be an IP address, not a DNS name.
993 - (void)socket:(GCDAsyncSocket *)sock didConnectToHost:(NSString *)host port:(uint16_t)port;
996 * Called when a socket has completed reading the requested data into memory.
997 * Not called if there is an error.
999 - (void)socket:(GCDAsyncSocket *)sock didReadData:(NSData *)data withTag:(long)tag;
1002 * Called when a socket has read in data, but has not yet completed the read.
1003 * This would occur if using readToData: or readToLength: methods.
1004 * It may be used to for things such as updating progress bars.
1006 - (void)socket:(GCDAsyncSocket *)sock didReadPartialDataOfLength:(NSUInteger)partialLength tag:(long)tag;
1009 * Called when a socket has completed writing the requested data. Not called if there is an error.
1011 - (void)socket:(GCDAsyncSocket *)sock didWriteDataWithTag:(long)tag;
1014 * Called when a socket has written some data, but has not yet completed the entire write.
1015 * It may be used to for things such as updating progress bars.
1017 - (void)socket:(GCDAsyncSocket *)sock didWritePartialDataOfLength:(NSUInteger)partialLength tag:(long)tag;
1020 * Called if a read operation has reached its timeout without completing.
1021 * This method allows you to optionally extend the timeout.
1022 * If you return a positive time interval (> 0) the read's timeout will be extended by the given amount.
1023 * If you don't implement this method, or return a non-positive time interval (<= 0) the read will timeout as usual.
1025 * The elapsed parameter is the sum of the original timeout, plus any additions previously added via this method.
1026 * The length parameter is the number of bytes that have been read so far for the read operation.
1028 * Note that this method may be called multiple times for a single read if you return positive numbers.
1030 - (NSTimeInterval)socket:(GCDAsyncSocket *)sock shouldTimeoutReadWithTag:(long)tag
1031 elapsed:(NSTimeInterval)elapsed
1032 bytesDone:(NSUInteger)length;
1035 * Called if a write operation has reached its timeout without completing.
1036 * This method allows you to optionally extend the timeout.
1037 * If you return a positive time interval (> 0) the write's timeout will be extended by the given amount.
1038 * If you don't implement this method, or return a non-positive time interval (<= 0) the write will timeout as usual.
1040 * The elapsed parameter is the sum of the original timeout, plus any additions previously added via this method.
1041 * The length parameter is the number of bytes that have been written so far for the write operation.
1043 * Note that this method may be called multiple times for a single write if you return positive numbers.
1045 - (NSTimeInterval)socket:(GCDAsyncSocket *)sock shouldTimeoutWriteWithTag:(long)tag
1046 elapsed:(NSTimeInterval)elapsed
1047 bytesDone:(NSUInteger)length;
1050 * Conditionally called if the read stream closes, but the write stream may still be writeable.
1052 * This delegate method is only called if autoDisconnectOnClosedReadStream has been set to NO.
1053 * See the discussion on the autoDisconnectOnClosedReadStream method for more information.
1055 - (void)socketDidCloseReadStream:(GCDAsyncSocket *)sock;
1058 * Called when a socket disconnects with or without error.
1060 * If you call the disconnect method, and the socket wasn't already disconnected,
1061 * this delegate method will be called before the disconnect method returns.
1063 - (void)socketDidDisconnect:(GCDAsyncSocket *)sock withError:(NSError *)err;
1066 * Called after the socket has successfully completed SSL/TLS negotiation.
1067 * This method is not called unless you use the provided startTLS method.
1069 * If a SSL/TLS negotiation fails (invalid certificate, etc) then the socket will immediately close,
1070 * and the socketDidDisconnect:withError: delegate method will be called with the specific SSL error code.
1072 - (void)socketDidSecure:(GCDAsyncSocket *)sock;