Subversion Repositories Mobile Apps.GyroMouse

//  

//  GCDAsyncSocket.h

//  

//  This class is in the public domain.

//  Originally created by Robbie Hanson in Q3 2010.

//  Updated and maintained by Deusty LLC and the Apple development community.

//  

//  https://github.com/robbiehanson/CocoaAsyncSocket

//

#import <Foundation/Foundation.h>

#import <Security/Security.h>

#import <Security/SecureTransport.h>

#import <dispatch/dispatch.h>

#import <Availability.h>

#include <sys/socket.h> // AF_INET, AF_INET6

@class GCDAsyncReadPacket;

@class GCDAsyncWritePacket;

@class GCDAsyncSocketPreBuffer;

@protocol GCDAsyncSocketDelegate;

NS_ASSUME_NONNULL_BEGIN

extern NSString *const GCDAsyncSocketException;

extern NSString *const GCDAsyncSocketErrorDomain;

extern NSString *const GCDAsyncSocketQueueName;

extern NSString *const GCDAsyncSocketThreadName;

extern NSString *const GCDAsyncSocketManuallyEvaluateTrust;

#if TARGET_OS_IPHONE

extern NSString *const GCDAsyncSocketUseCFStreamForTLS;

#endif

#define GCDAsyncSocketSSLPeerName     (NSString *)kCFStreamSSLPeerName

#define GCDAsyncSocketSSLCertificates (NSString *)kCFStreamSSLCertificates

#define GCDAsyncSocketSSLIsServer     (NSString *)kCFStreamSSLIsServer

extern NSString *const GCDAsyncSocketSSLPeerID;

extern NSString *const GCDAsyncSocketSSLProtocolVersionMin;

extern NSString *const GCDAsyncSocketSSLProtocolVersionMax;

extern NSString *const GCDAsyncSocketSSLSessionOptionFalseStart;

extern NSString *const GCDAsyncSocketSSLSessionOptionSendOneByteRecord;

extern NSString *const GCDAsyncSocketSSLCipherSuites;

extern NSString *const GCDAsyncSocketSSLALPN;

#if !TARGET_OS_IPHONE

extern NSString *const GCDAsyncSocketSSLDiffieHellmanParameters;

#endif

#define GCDAsyncSocketLoggingContext 65535

typedef NS_ERROR_ENUM(GCDAsyncSocketErrorDomain, GCDAsyncSocketError) {

        GCDAsyncSocketNoError = 0,           // Never used

        GCDAsyncSocketBadConfigError,        // Invalid configuration

        GCDAsyncSocketBadParamError,         // Invalid parameter was passed

        GCDAsyncSocketConnectTimeoutError,   // A connect operation timed out

        GCDAsyncSocketReadTimeoutError,      // A read operation timed out

        GCDAsyncSocketWriteTimeoutError,     // A write operation timed out

        GCDAsyncSocketReadMaxedOutError,     // Reached set maxLength without completing

        GCDAsyncSocketClosedError,           // The remote peer closed the connection

        GCDAsyncSocketOtherError,            // Description provided in userInfo

};

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

#pragma mark -

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

@interface GCDAsyncSocket : NSObject

/**

 * GCDAsyncSocket uses the standard delegate paradigm,

 * but executes all delegate callbacks on a given delegate dispatch queue.

 * This allows for maximum concurrency, while at the same time providing easy thread safety.

 *

 * You MUST set a delegate AND delegate dispatch queue before attempting to

 * use the socket, or you will get an error.

 *

 * The socket queue is optional.

 * If you pass NULL, GCDAsyncSocket will automatically create it's own socket queue.

 * If you choose to provide a socket queue, the socket queue must not be a concurrent queue.

 * If you choose to provide a socket queue, and the socket queue has a configured target queue,

 * then please see the discussion for the method markSocketQueueTargetQueue.

 *

 * The delegate queue and socket queue can optionally be the same.

**/

- (instancetype)init;

- (instancetype)initWithSocketQueue:(nullable dispatch_queue_t)sq;

- (instancetype)initWithDelegate:(nullable id<GCDAsyncSocketDelegate>)aDelegate delegateQueue:(nullable dispatch_queue_t)dq;

- (instancetype)initWithDelegate:(nullable id<GCDAsyncSocketDelegate>)aDelegate delegateQueue:(nullable dispatch_queue_t)dq socketQueue:(nullable dispatch_queue_t)sq NS_DESIGNATED_INITIALIZER;

/**

 * Create GCDAsyncSocket from already connect BSD socket file descriptor

**/

+ (nullable instancetype)socketFromConnectedSocketFD:(int)socketFD socketQueue:(nullable dispatch_queue_t)sq error:(NSError**)error;

+ (nullable instancetype)socketFromConnectedSocketFD:(int)socketFD delegate:(nullable id<GCDAsyncSocketDelegate>)aDelegate delegateQueue:(nullable dispatch_queue_t)dq error:(NSError**)error;

+ (nullable instancetype)socketFromConnectedSocketFD:(int)socketFD delegate:(nullable id<GCDAsyncSocketDelegate>)aDelegate delegateQueue:(nullable dispatch_queue_t)dq socketQueue:(nullable dispatch_queue_t)sq error:(NSError **)error;

#pragma mark Configuration

@property (atomic, weak, readwrite, nullable) id<GCDAsyncSocketDelegate> delegate;

#if OS_OBJECT_USE_OBJC

@property (atomic, strong, readwrite, nullable) dispatch_queue_t delegateQueue;

#else

@property (atomic, assign, readwrite, nullable) dispatch_queue_t delegateQueue;

#endif

- (void)getDelegate:(id<GCDAsyncSocketDelegate> __nullable * __nullable)delegatePtr delegateQueue:(dispatch_queue_t __nullable * __nullable)delegateQueuePtr;

- (void)setDelegate:(nullable id<GCDAsyncSocketDelegate>)delegate delegateQueue:(nullable dispatch_queue_t)delegateQueue;

/**

 * If you are setting the delegate to nil within the delegate's dealloc method,

 * you may need to use the synchronous versions below.

**/

- (void)synchronouslySetDelegate:(nullable id<GCDAsyncSocketDelegate>)delegate;

- (void)synchronouslySetDelegateQueue:(nullable dispatch_queue_t)delegateQueue;

- (void)synchronouslySetDelegate:(nullable id<GCDAsyncSocketDelegate>)delegate delegateQueue:(nullable dispatch_queue_t)delegateQueue;

/**

 * By default, both IPv4 and IPv6 are enabled.

 *

 * For accepting incoming connections, this means GCDAsyncSocket automatically supports both protocols,

 * and can simulataneously accept incoming connections on either protocol.

 *

 * For outgoing connections, this means GCDAsyncSocket can connect to remote hosts running either protocol.

 * If a DNS lookup returns only IPv4 results, GCDAsyncSocket will automatically use IPv4.

 * If a DNS lookup returns only IPv6 results, GCDAsyncSocket will automatically use IPv6.

 * If a DNS lookup returns both IPv4 and IPv6 results, the preferred protocol will be chosen.

 * By default, the preferred protocol is IPv4, but may be configured as desired.

**/

@property (atomic, assign, readwrite, getter=isIPv4Enabled) BOOL IPv4Enabled;

@property (atomic, assign, readwrite, getter=isIPv6Enabled) BOOL IPv6Enabled;

@property (atomic, assign, readwrite, getter=isIPv4PreferredOverIPv6) BOOL IPv4PreferredOverIPv6;

/**

 * When connecting to both IPv4 and IPv6 using Happy Eyeballs (RFC 6555) https://tools.ietf.org/html/rfc6555

 * this is the delay between connecting to the preferred protocol and the fallback protocol.

 *

 * Defaults to 300ms.

**/

@property (atomic, assign, readwrite) NSTimeInterval alternateAddressDelay;

/**

 * User data allows you to associate arbitrary information with the socket.

 * This data is not used internally by socket in any way.

**/

@property (atomic, strong, readwrite, nullable) id userData;

#pragma mark Accepting

/**

 * Tells the socket to begin listening and accepting connections on the given port.

 * When a connection is accepted, a new instance of GCDAsyncSocket will be spawned to handle it,

 * and the socket:didAcceptNewSocket: delegate method will be invoked.

 *

 * The socket will listen on all available interfaces (e.g. wifi, ethernet, etc)

**/

- (BOOL)acceptOnPort:(uint16_t)port error:(NSError **)errPtr;

/**

 * This method is the same as acceptOnPort:error: with the

 * additional option of specifying which interface to listen on.

 *

 * For example, you could specify that the socket should only accept connections over ethernet,

 * and not other interfaces such as wifi.

 *

 * The interface may be specified by name (e.g. "en1" or "lo0") or by IP address (e.g. "192.168.4.34").

 * You may also use the special strings "localhost" or "loopback" to specify that

 * the socket only accept connections from the local machine.

 *

 * You can see the list of interfaces via the command line utility "ifconfig",

 * or programmatically via the getifaddrs() function.

 *

 * To accept connections on any interface pass nil, or simply use the acceptOnPort:error: method.

**/

- (BOOL)acceptOnInterface:(nullable NSString *)interface port:(uint16_t)port error:(NSError **)errPtr;

/**

 * Tells the socket to begin listening and accepting connections on the unix domain at the given url.

 * When a connection is accepted, a new instance of GCDAsyncSocket will be spawned to handle it,

 * and the socket:didAcceptNewSocket: delegate method will be invoked.

 *

 * The socket will listen on all available interfaces (e.g. wifi, ethernet, etc)

 **/

- (BOOL)acceptOnUrl:(NSURL *)url error:(NSError **)errPtr;

#pragma mark Connecting

/**

 * Connects to the given host and port.

 *

 * This method invokes connectToHost:onPort:viaInterface:withTimeout:error:

 * and uses the default interface, and no timeout.

**/

- (BOOL)connectToHost:(NSString *)host onPort:(uint16_t)port error:(NSError **)errPtr;

/**

 * Connects to the given host and port with an optional timeout.

 *

 * This method invokes connectToHost:onPort:viaInterface:withTimeout:error: and uses the default interface.

**/

- (BOOL)connectToHost:(NSString *)host

               onPort:(uint16_t)port

          withTimeout:(NSTimeInterval)timeout

                error:(NSError **)errPtr;

/**

 * Connects to the given host & port, via the optional interface, with an optional timeout.

 *

 * The host may be a domain name (e.g. "deusty.com") or an IP address string (e.g. "192.168.0.2").

 * The host may also be the special strings "localhost" or "loopback" to specify connecting

 * to a service on the local machine.

 *

 * The interface may be a name (e.g. "en1" or "lo0") or the corresponding IP address (e.g. "192.168.4.35").

 * The interface may also be used to specify the local port (see below).

 *

 * To not time out use a negative time interval.

 *

 * This method will return NO if an error is detected, and set the error pointer (if one was given).

 * Possible errors would be a nil host, invalid interface, or socket is already connected.

 *

 * If no errors are detected, this method will start a background connect operation and immediately return YES.

 * The delegate callbacks are used to notify you when the socket connects, or if the host was unreachable.

 *

 * Since this class supports queued reads and writes, you can immediately start reading and/or writing.

 * All read/write operations will be queued, and upon socket connection,

 * the operations will be dequeued and processed in order.

 *

 * The interface may optionally contain a port number at the end of the string, separated by a colon.

 * This allows you to specify the local port that should be used for the outgoing connection. (read paragraph to end)

 * To specify both interface and local port: "en1:8082" or "192.168.4.35:2424".

 * To specify only local port: ":8082".

 * Please note this is an advanced feature, and is somewhat hidden on purpose.

 * You should understand that 99.999% of the time you should NOT specify the local port for an outgoing connection.

 * If you think you need to, there is a very good chance you have a fundamental misunderstanding somewhere.

 * Local ports do NOT need to match remote ports. In fact, they almost never do.

 * This feature is here for networking professionals using very advanced techniques.

**/

- (BOOL)connectToHost:(NSString *)host

               onPort:(uint16_t)port

         viaInterface:(nullable NSString *)interface

          withTimeout:(NSTimeInterval)timeout

                error:(NSError **)errPtr;

/**

 * Connects to the given address, specified as a sockaddr structure wrapped in a NSData object.

 * For example, a NSData object returned from NSNetService's addresses method.

 *

 * If you have an existing struct sockaddr you can convert it to a NSData object like so:

 * struct sockaddr sa  -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];

 * struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];

 *

 * This method invokes connectToAddress:remoteAddr viaInterface:nil withTimeout:-1 error:errPtr.

**/

- (BOOL)connectToAddress:(NSData *)remoteAddr error:(NSError **)errPtr;

/**

 * This method is the same as connectToAddress:error: with an additional timeout option.

 * To not time out use a negative time interval, or simply use the connectToAddress:error: method.

**/

- (BOOL)connectToAddress:(NSData *)remoteAddr withTimeout:(NSTimeInterval)timeout error:(NSError **)errPtr;

/**

 * Connects to the given address, using the specified interface and timeout.

 *

 * The address is specified as a sockaddr structure wrapped in a NSData object.

 * For example, a NSData object returned from NSNetService's addresses method.

 *

 * If you have an existing struct sockaddr you can convert it to a NSData object like so:

 * struct sockaddr sa  -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];

 * struct sockaddr *sa -> NSData *dsa = [NSData dataWithBytes:remoteAddr length:remoteAddr->sa_len];

 *

 * The interface may be a name (e.g. "en1" or "lo0") or the corresponding IP address (e.g. "192.168.4.35").

 * The interface may also be used to specify the local port (see below).

 *

 * The timeout is optional. To not time out use a negative time interval.

 *

 * This method will return NO if an error is detected, and set the error pointer (if one was given).

 * Possible errors would be a nil host, invalid interface, or socket is already connected.

 *

 * If no errors are detected, this method will start a background connect operation and immediately return YES.

 * The delegate callbacks are used to notify you when the socket connects, or if the host was unreachable.

 *

 * Since this class supports queued reads and writes, you can immediately start reading and/or writing.

 * All read/write operations will be queued, and upon socket connection,

 * the operations will be dequeued and processed in order.

 *

 * The interface may optionally contain a port number at the end of the string, separated by a colon.

 * This allows you to specify the local port that should be used for the outgoing connection. (read paragraph to end)

 * To specify both interface and local port: "en1:8082" or "192.168.4.35:2424".

 * To specify only local port: ":8082".

 * Please note this is an advanced feature, and is somewhat hidden on purpose.

 * You should understand that 99.999% of the time you should NOT specify the local port for an outgoing connection.

 * If you think you need to, there is a very good chance you have a fundamental misunderstanding somewhere.

 * Local ports do NOT need to match remote ports. In fact, they almost never do.

 * This feature is here for networking professionals using very advanced techniques.

**/

- (BOOL)connectToAddress:(NSData *)remoteAddr

            viaInterface:(nullable NSString *)interface

             withTimeout:(NSTimeInterval)timeout

                   error:(NSError **)errPtr;

/**

 * Connects to the unix domain socket at the given url, using the specified timeout.

 */

- (BOOL)connectToUrl:(NSURL *)url withTimeout:(NSTimeInterval)timeout error:(NSError **)errPtr;

/**

 * Iterates over the given NetService's addresses in order, and invokes connectToAddress:error:. Stops at the

 * first invocation that succeeds and returns YES; otherwise returns NO.

 */

- (BOOL)connectToNetService:(NSNetService *)netService error:(NSError **)errPtr;

#pragma mark Disconnecting

/**

 * Disconnects immediately (synchronously). Any pending reads or writes are dropped.

 *

 * If the socket is not already disconnected, an invocation to the socketDidDisconnect:withError: delegate method

 * will be queued onto the delegateQueue asynchronously (behind any previously queued delegate methods).

 * In other words, the disconnected delegate method will be invoked sometime shortly after this method returns.

 *

 * Please note the recommended way of releasing a GCDAsyncSocket instance (e.g. in a dealloc method)

 * [asyncSocket setDelegate:nil];

 * [asyncSocket disconnect];

 * [asyncSocket release];

 *

 * If you plan on disconnecting the socket, and then immediately asking it to connect again,

 * you'll likely want to do so like this:

 * [asyncSocket setDelegate:nil];

 * [asyncSocket disconnect];

 * [asyncSocket setDelegate:self];

 * [asyncSocket connect...];

**/

- (void)disconnect;

/**

 * Disconnects after all pending reads have completed.

 * After calling this, the read and write methods will do nothing.

 * The socket will disconnect even if there are still pending writes.

**/

- (void)disconnectAfterReading;

/**

 * Disconnects after all pending writes have completed.

 * After calling this, the read and write methods will do nothing.

 * The socket will disconnect even if there are still pending reads.

**/

- (void)disconnectAfterWriting;

/**

 * Disconnects after all pending reads and writes have completed.

 * After calling this, the read and write methods will do nothing.

**/

- (void)disconnectAfterReadingAndWriting;

#pragma mark Diagnostics

/**

 * Returns whether the socket is disconnected or connected.

 *

 * A disconnected socket may be recycled.

 * That is, it can be used again for connecting or listening.

 *

 * If a socket is in the process of connecting, it may be neither disconnected nor connected.

**/

@property (atomic, readonly) BOOL isDisconnected;

@property (atomic, readonly) BOOL isConnected;

/**

 * Returns the local or remote host and port to which this socket is connected, or nil and 0 if not connected.

 * The host will be an IP address.

**/

@property (atomic, readonly, nullable) NSString *connectedHost;

@property (atomic, readonly) uint16_t  connectedPort;

@property (atomic, readonly, nullable) NSURL    *connectedUrl;

@property (atomic, readonly, nullable) NSString *localHost;

@property (atomic, readonly) uint16_t  localPort;

/**

 * Returns the local or remote address to which this socket is connected,

 * specified as a sockaddr structure wrapped in a NSData object.

 *

 * @seealso connectedHost

 * @seealso connectedPort

 * @seealso localHost

 * @seealso localPort

**/

@property (atomic, readonly, nullable) NSData *connectedAddress;

@property (atomic, readonly, nullable) NSData *localAddress;

/**

 * Returns whether the socket is IPv4 or IPv6.

 * An accepting socket may be both.

**/

@property (atomic, readonly) BOOL isIPv4;

@property (atomic, readonly) BOOL isIPv6;

/**

 * Returns whether or not the socket has been secured via SSL/TLS.

 *

 * See also the startTLS method.

**/

@property (atomic, readonly) BOOL isSecure;

#pragma mark Reading

// The readData and writeData methods won't block (they are asynchronous).

// 

// When a read is complete the socket:didReadData:withTag: delegate method is dispatched on the delegateQueue.

// When a write is complete the socket:didWriteDataWithTag: delegate method is dispatched on the delegateQueue.

// 

// You may optionally set a timeout for any read/write operation. (To not timeout, use a negative time interval.)

// If a read/write opertion times out, the corresponding "socket:shouldTimeout..." delegate method

// is called to optionally allow you to extend the timeout.

// Upon a timeout, the "socket:didDisconnectWithError:" method is called

// 

// The tag is for your convenience.

// You can use it as an array index, step number, state id, pointer, etc.

/**

 * Reads the first available bytes that become available on the socket.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

**/

- (void)readDataWithTimeout:(NSTimeInterval)timeout tag:(long)tag;

/**

 * Reads the first available bytes that become available on the socket.

 * The bytes will be appended to the given byte buffer starting at the given offset.

 * The given buffer will automatically be increased in size if needed.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

 * If the buffer is nil, the socket will create a buffer for you.

 *

 * If the bufferOffset is greater than the length of the given buffer,

 * the method will do nothing, and the delegate will not be called.

 *

 * If you pass a buffer, you must not alter it in any way while the socket is using it.

 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.

 * That is, it will reference the bytes that were appended to the given buffer via

 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].

**/

- (void)readDataWithTimeout:(NSTimeInterval)timeout

                                         buffer:(nullable NSMutableData *)buffer

                           bufferOffset:(NSUInteger)offset

                                                tag:(long)tag;

/**

 * Reads the first available bytes that become available on the socket.

 * The bytes will be appended to the given byte buffer starting at the given offset.

 * The given buffer will automatically be increased in size if needed.

 * A maximum of length bytes will be read.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

 * If the buffer is nil, a buffer will automatically be created for you.

 * If maxLength is zero, no length restriction is enforced.

 *

 * If the bufferOffset is greater than the length of the given buffer,

 * the method will do nothing, and the delegate will not be called.

 *

 * If you pass a buffer, you must not alter it in any way while the socket is using it.

 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.

 * That is, it will reference the bytes that were appended to the given buffer  via

 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].

**/

- (void)readDataWithTimeout:(NSTimeInterval)timeout

                     buffer:(nullable NSMutableData *)buffer

               bufferOffset:(NSUInteger)offset

                  maxLength:(NSUInteger)length

                        tag:(long)tag;

/**

 * Reads the given number of bytes.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

 *

 * If the length is 0, this method does nothing and the delegate is not called.

**/

- (void)readDataToLength:(NSUInteger)length withTimeout:(NSTimeInterval)timeout tag:(long)tag;

/**

 * Reads the given number of bytes.

 * The bytes will be appended to the given byte buffer starting at the given offset.

 * The given buffer will automatically be increased in size if needed.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

 * If the buffer is nil, a buffer will automatically be created for you.

 *

 * If the length is 0, this method does nothing and the delegate is not called.

 * If the bufferOffset is greater than the length of the given buffer,

 * the method will do nothing, and the delegate will not be called.

 *

 * If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.

 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.

 * That is, it will reference the bytes that were appended to the given buffer via

 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].

**/

- (void)readDataToLength:(NSUInteger)length

             withTimeout:(NSTimeInterval)timeout

                  buffer:(nullable NSMutableData *)buffer

            bufferOffset:(NSUInteger)offset

                     tag:(long)tag;

/**

 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

 *

 * If you pass nil or zero-length data as the "data" parameter,

 * the method will do nothing (except maybe print a warning), and the delegate will not be called.

 *

 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.

 * If you're developing your own custom protocol, be sure your separator can not occur naturally as

 * part of the data between separators.

 * For example, imagine you want to send several small documents over a socket.

 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.

 * In this particular example, it would be better to use a protocol similar to HTTP with

 * a header that includes the length of the document.

 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.

 *

 * The given data (separator) parameter should be immutable.

 * For performance reasons, the socket will retain it, not copy it.

 * So if it is immutable, don't modify it while the socket is using it.

**/

- (void)readDataToData:(nullable NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;

/**

 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.

 * The bytes will be appended to the given byte buffer starting at the given offset.

 * The given buffer will automatically be increased in size if needed.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

 * If the buffer is nil, a buffer will automatically be created for you.

 *

 * If the bufferOffset is greater than the length of the given buffer,

 * the method will do nothing (except maybe print a warning), and the delegate will not be called.

 *

 * If you pass a buffer, you must not alter it in any way while the socket is using it.

 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.

 * That is, it will reference the bytes that were appended to the given buffer via

 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].

 *

 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.

 * If you're developing your own custom protocol, be sure your separator can not occur naturally as

 * part of the data between separators.

 * For example, imagine you want to send several small documents over a socket.

 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.

 * In this particular example, it would be better to use a protocol similar to HTTP with

 * a header that includes the length of the document.

 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.

 *

 * The given data (separator) parameter should be immutable.

 * For performance reasons, the socket will retain it, not copy it.

 * So if it is immutable, don't modify it while the socket is using it.

**/

- (void)readDataToData:(NSData *)data

           withTimeout:(NSTimeInterval)timeout

                buffer:(nullable NSMutableData *)buffer

          bufferOffset:(NSUInteger)offset

                   tag:(long)tag;

/**

 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

 *

 * If maxLength is zero, no length restriction is enforced.

 * Otherwise if maxLength bytes are read without completing the read,

 * it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.

 * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.

 *

 * If you pass nil or zero-length data as the "data" parameter,

 * the method will do nothing (except maybe print a warning), and the delegate will not be called.

 * If you pass a maxLength parameter that is less than the length of the data parameter,

 * the method will do nothing (except maybe print a warning), and the delegate will not be called.

 *

 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.

 * If you're developing your own custom protocol, be sure your separator can not occur naturally as

 * part of the data between separators.

 * For example, imagine you want to send several small documents over a socket.

 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.

 * In this particular example, it would be better to use a protocol similar to HTTP with

 * a header that includes the length of the document.

 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.

 *

 * The given data (separator) parameter should be immutable.

 * For performance reasons, the socket will retain it, not copy it.

 * So if it is immutable, don't modify it while the socket is using it.

**/

- (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout maxLength:(NSUInteger)length tag:(long)tag;

/**

 * Reads bytes until (and including) the passed "data" parameter, which acts as a separator.

 * The bytes will be appended to the given byte buffer starting at the given offset.

 * The given buffer will automatically be increased in size if needed.

 *

 * If the timeout value is negative, the read operation will not use a timeout.

 * If the buffer is nil, a buffer will automatically be created for you.

 *

 * If maxLength is zero, no length restriction is enforced.

 * Otherwise if maxLength bytes are read without completing the read,

 * it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.

 * The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.

 *

 * If you pass a maxLength parameter that is less than the length of the data (separator) parameter,

 * the method will do nothing (except maybe print a warning), and the delegate will not be called.

 * If the bufferOffset is greater than the length of the given buffer,

 * the method will do nothing (except maybe print a warning), and the delegate will not be called.

 *

 * If you pass a buffer, you must not alter it in any way while the socket is using it.

 * After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.

 * That is, it will reference the bytes that were appended to the given buffer via

 * the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].

 *

 * To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.

 * If you're developing your own custom protocol, be sure your separator can not occur naturally as

 * part of the data between separators.

 * For example, imagine you want to send several small documents over a socket.

 * Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.

 * In this particular example, it would be better to use a protocol similar to HTTP with

 * a header that includes the length of the document.

 * Also be careful that your separator cannot occur naturally as part of the encoding for a character.

 *

 * The given data (separator) parameter should be immutable.

 * For performance reasons, the socket will retain it, not copy it.

 * So if it is immutable, don't modify it while the socket is using it.

**/

- (void)readDataToData:(NSData *)data

           withTimeout:(NSTimeInterval)timeout

                buffer:(nullable NSMutableData *)buffer

          bufferOffset:(NSUInteger)offset

             maxLength:(NSUInteger)length

                   tag:(long)tag;

/**

 * Returns progress of the current read, from 0.0 to 1.0, or NaN if no current read (use isnan() to check).

 * The parameters "tag", "done" and "total" will be filled in if they aren't NULL.

**/

- (float)progressOfReadReturningTag:(nullable long *)tagPtr bytesDone:(nullable NSUInteger *)donePtr total:(nullable NSUInteger *)totalPtr;

#pragma mark Writing

/**

 * Writes data to the socket, and calls the delegate when finished.

 *

 * If you pass in nil or zero-length data, this method does nothing and the delegate will not be called.

 * If the timeout value is negative, the write operation will not use a timeout.

 *

 * Thread-Safety Note:

 * If the given data parameter is mutable (NSMutableData) then you MUST NOT alter the data while

 * the socket is writing it. In other words, it's not safe to alter the data until after the delegate method

 * socket:didWriteDataWithTag: is invoked signifying that this particular write operation has completed.

 * This is due to the fact that GCDAsyncSocket does NOT copy the data. It simply retains it.

 * This is for performance reasons. Often times, if NSMutableData is passed, it is because

 * a request/response was built up in memory. Copying this data adds an unwanted/unneeded overhead.

 * If you need to write data from an immutable buffer, and you need to alter the buffer before the socket

 * completes writing the bytes (which is NOT immediately after this method returns, but rather at a later time

 * when the delegate method notifies you), then you should first copy the bytes, and pass the copy to this method.

**/

- (void)writeData:(nullable NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;

/**

 * Returns progress of the current write, from 0.0 to 1.0, or NaN if no current write (use isnan() to check).

 * The parameters "tag", "done" and "total" will be filled in if they aren't NULL.

**/

- (float)progressOfWriteReturningTag:(nullable long *)tagPtr bytesDone:(nullable NSUInteger *)donePtr total:(nullable NSUInteger *)totalPtr;

#pragma mark Security

/**

 * Secures the connection using SSL/TLS.

 *

 * This method may be called at any time, and the TLS handshake will occur after all pending reads and writes

 * are finished. This allows one the option of sending a protocol dependent StartTLS message, and queuing

 * the upgrade to TLS at the same time, without having to wait for the write to finish.

 * Any reads or writes scheduled after this method is called will occur over the secured connection.

 *

 * ==== The available TOP-LEVEL KEYS are:

 *

 * - GCDAsyncSocketManuallyEvaluateTrust

 *     The value must be of type NSNumber, encapsulating a BOOL value.

 *     If you set this to YES, then the underlying SecureTransport system will not evaluate the SecTrustRef of the peer.

 *     Instead it will pause at the moment evaulation would typically occur,

 *     and allow us to handle the security evaluation however we see fit.

 *     So GCDAsyncSocket will invoke the delegate method socket:shouldTrustPeer: passing the SecTrustRef.

 *

 *     Note that if you set this option, then all other configuration keys are ignored.

 *     Evaluation will be completely up to you during the socket:didReceiveTrust:completionHandler: delegate method.

 *

 *     For more information on trust evaluation see:

 *     Apple's Technical Note TN2232 - HTTPS Server Trust Evaluation

 *     https://developer.apple.com/library/ios/technotes/tn2232/_index.html

 *    

 *     If unspecified, the default value is NO.

 *

 * - GCDAsyncSocketUseCFStreamForTLS (iOS only)

 *     The value must be of type NSNumber, encapsulating a BOOL value.

 *     By default GCDAsyncSocket will use the SecureTransport layer to perform encryption.

 *     This gives us more control over the security protocol (many more configuration options),

 *     plus it allows us to optimize things like sys calls and buffer allocation.

 *    

 *     However, if you absolutely must, you can instruct GCDAsyncSocket to use the old-fashioned encryption

 *     technique by going through the CFStream instead. So instead of using SecureTransport, GCDAsyncSocket

 *     will instead setup a CFRead/CFWriteStream. And then set the kCFStreamPropertySSLSettings property

 *     (via CFReadStreamSetProperty / CFWriteStreamSetProperty) and will pass the given options to this method.

 *    

 *     Thus all the other keys in the given dictionary will be ignored by GCDAsyncSocket,

 *     and will passed directly CFReadStreamSetProperty / CFWriteStreamSetProperty.

 *     For more infomation on these keys, please see the documentation for kCFStreamPropertySSLSettings.

 *

 *     If unspecified, the default value is NO.

 *

 * ==== The available CONFIGURATION KEYS are:

 *

 * - kCFStreamSSLPeerName

 *     The value must be of type NSString.

 *     It should match the name in the X.509 certificate given by the remote party.

 *     See Apple's documentation for SSLSetPeerDomainName.

 *

 * - kCFStreamSSLCertificates

 *     The value must be of type NSArray.

 *     See Apple's documentation for SSLSetCertificate.

 *

 * - kCFStreamSSLIsServer

 *     The value must be of type NSNumber, encapsulationg a BOOL value.

 *     See Apple's documentation for SSLCreateContext for iOS.

 *     This is optional for iOS. If not supplied, a NO value is the default.

 *     This is not needed for Mac OS X, and the value is ignored.

 *

 * - GCDAsyncSocketSSLPeerID

 *     The value must be of type NSData.

 *     You must set this value if you want to use TLS session resumption.

 *     See Apple's documentation for SSLSetPeerID.

 *

 * - GCDAsyncSocketSSLProtocolVersionMin

 * - GCDAsyncSocketSSLProtocolVersionMax

 *     The value(s) must be of type NSNumber, encapsulting a SSLProtocol value.

 *     See Apple's documentation for SSLSetProtocolVersionMin & SSLSetProtocolVersionMax.

 *     See also the SSLProtocol typedef.

 *

 * - GCDAsyncSocketSSLSessionOptionFalseStart

 *     The value must be of type NSNumber, encapsulating a BOOL value.

 *     See Apple's documentation for kSSLSessionOptionFalseStart.

 *

 * - GCDAsyncSocketSSLSessionOptionSendOneByteRecord

 *     The value must be of type NSNumber, encapsulating a BOOL value.

 *     See Apple's documentation for kSSLSessionOptionSendOneByteRecord.

 *

 * - GCDAsyncSocketSSLCipherSuites

 *     The values must be of type NSArray.

 *     Each item within the array must be a NSNumber, encapsulating an SSLCipherSuite.

 *     See Apple's documentation for SSLSetEnabledCiphers.

 *     See also the SSLCipherSuite typedef.

 *

 * - GCDAsyncSocketSSLDiffieHellmanParameters (Mac OS X only)

 *     The value must be of type NSData.

 *     See Apple's documentation for SSLSetDiffieHellmanParams.

 *

 * ==== The following UNAVAILABLE KEYS are: (with throw an exception)

 *

 * - kCFStreamSSLAllowsAnyRoot (UNAVAILABLE)

 *     You MUST use manual trust evaluation instead (see GCDAsyncSocketManuallyEvaluateTrust).

 *     Corresponding deprecated method: SSLSetAllowsAnyRoot

 *

 * - kCFStreamSSLAllowsExpiredRoots (UNAVAILABLE)

 *     You MUST use manual trust evaluation instead (see GCDAsyncSocketManuallyEvaluateTrust).

 *     Corresponding deprecated method: SSLSetAllowsExpiredRoots

 *

 * - kCFStreamSSLAllowsExpiredCertificates (UNAVAILABLE)

 *     You MUST use manual trust evaluation instead (see GCDAsyncSocketManuallyEvaluateTrust).

 *     Corresponding deprecated method: SSLSetAllowsExpiredCerts

 *

 * - kCFStreamSSLValidatesCertificateChain (UNAVAILABLE)

 *     You MUST use manual trust evaluation instead (see GCDAsyncSocketManuallyEvaluateTrust).

 *     Corresponding deprecated method: SSLSetEnableCertVerify

 *

 * - kCFStreamSSLLevel (UNAVAILABLE)

 *     You MUST use GCDAsyncSocketSSLProtocolVersionMin & GCDAsyncSocketSSLProtocolVersionMin instead.

 *     Corresponding deprecated method: SSLSetProtocolVersionEnabled

 *

 *

 * Please refer to Apple's documentation for corresponding SSLFunctions.

 *

 * If you pass in nil or an empty dictionary, the default settings will be used.

 *

 * IMPORTANT SECURITY NOTE:

 * The default settings will check to make sure the remote party's certificate is signed by a

 * trusted 3rd party certificate agency (e.g. verisign) and that the certificate is not expired.

 * However it will not verify the name on the certificate unless you

 * give it a name to verify against via the kCFStreamSSLPeerName key.

 * The security implications of this are important to understand.

 * Imagine you are attempting to create a secure connection to MySecureServer.com,

 * but your socket gets directed to MaliciousServer.com because of a hacked DNS server.

 * If you simply use the default settings, and MaliciousServer.com has a valid certificate,

 * the default settings will not detect any problems since the certificate is valid.

 * To properly secure your connection in this particular scenario you

 * should set the kCFStreamSSLPeerName property to "MySecureServer.com".

 *

 * You can also perform additional validation in socketDidSecure.

**/

- (void)startTLS:(nullable NSDictionary <NSString*,NSObject*>*)tlsSettings;

#pragma mark Advanced

/**

 * Traditionally sockets are not closed until the conversation is over.

 * However, it is technically possible for the remote enpoint to close its write stream.

 * Our socket would then be notified that there is no more data to be read,

 * but our socket would still be writeable and the remote endpoint could continue to receive our data.

 *

 * The argument for this confusing functionality stems from the idea that a client could shut down its

 * write stream after sending a request to the server, thus notifying the server there are to be no further requests.

 * In practice, however, this technique did little to help server developers.

 *

 * To make matters worse, from a TCP perspective there is no way to tell the difference from a read stream close

 * and a full socket close. They both result in the TCP stack receiving a FIN packet. The only way to tell

 * is by continuing to write to the socket. If it was only a read stream close, then writes will continue to work.

 * Otherwise an error will be occur shortly (when the remote end sends us a RST packet).

 *

 * In addition to the technical challenges and confusion, many high level socket/stream API's provide

 * no support for dealing with the problem. If the read stream is closed, the API immediately declares the

 * socket to be closed, and shuts down the write stream as well. In fact, this is what Apple's CFStream API does.

 * It might sound like poor design at first, but in fact it simplifies development.

 *

 * The vast majority of the time if the read stream is closed it's because the remote endpoint closed its socket.

 * Thus it actually makes sense to close the socket at this point.

 * And in fact this is what most networking developers want and expect to happen.

 * However, if you are writing a server that interacts with a plethora of clients,

 * you might encounter a client that uses the discouraged technique of shutting down its write stream.

 * If this is the case, you can set this property to NO,

 * and make use of the socketDidCloseReadStream delegate method.

 *

 * The default value is YES.

**/

@property (atomic, assign, readwrite) BOOL autoDisconnectOnClosedReadStream;

/**

 * GCDAsyncSocket maintains thread safety by using an internal serial dispatch_queue.

 * In most cases, the instance creates this queue itself.

 * However, to allow for maximum flexibility, the internal queue may be passed in the init method.

 * This allows for some advanced options such as controlling socket priority via target queues.

 * However, when one begins to use target queues like this, they open the door to some specific deadlock issues.

 *

 * For example, imagine there are 2 queues:

 * dispatch_queue_t socketQueue;

 * dispatch_queue_t socketTargetQueue;

 *

 * If you do this (pseudo-code):

 * socketQueue.targetQueue = socketTargetQueue;

 *

 * Then all socketQueue operations will actually get run on the given socketTargetQueue.

 * This is fine and works great in most situations.

 * But if you run code directly from within the socketTargetQueue that accesses the socket,

 * you could potentially get deadlock. Imagine the following code:

 *

 * - (BOOL)socketHasSomething

 * {

 *     __block BOOL result = NO;

 *     dispatch_block_t block = ^{

 *         result = [self someInternalMethodToBeRunOnlyOnSocketQueue];

 *     }

 *     if (is_executing_on_queue(socketQueue))

 *         block();

 *     else

 *         dispatch_sync(socketQueue, block);

 *    

 *     return result;

 * }

 *

 * What happens if you call this method from the socketTargetQueue? The result is deadlock.

 * This is because the GCD API offers no mechanism to discover a queue's targetQueue.

 * Thus we have no idea if our socketQueue is configured with a targetQueue.

 * If we had this information, we could easily avoid deadlock.

 * But, since these API's are missing or unfeasible, you'll have to explicitly set it.

 *

 * IF you pass a socketQueue via the init method,

 * AND you've configured the passed socketQueue with a targetQueue,

 * THEN you should pass the end queue in the target hierarchy.

 *

 * For example, consider the following queue hierarchy:

 * socketQueue -> ipQueue -> moduleQueue

 *

 * This example demonstrates priority shaping within some server.

 * All incoming client connections from the same IP address are executed on the same target queue.

 * And all connections for a particular module are executed on the same target queue.

 * Thus, the priority of all networking for the entire module can be changed on the fly.

 * Additionally, networking traffic from a single IP cannot monopolize the module.

 *

 * Here's how you would accomplish something like that:

 * - (dispatch_queue_t)newSocketQueueForConnectionFromAddress:(NSData *)address onSocket:(GCDAsyncSocket *)sock

 * {

 *     dispatch_queue_t socketQueue = dispatch_queue_create("", NULL);

 *     dispatch_queue_t ipQueue = [self ipQueueForAddress:address];

 *    

 *     dispatch_set_target_queue(socketQueue, ipQueue);

 *     dispatch_set_target_queue(iqQueue, moduleQueue);

 *    

 *     return socketQueue;

 * }

 * - (void)socket:(GCDAsyncSocket *)sock didAcceptNewSocket:(GCDAsyncSocket *)newSocket

 * {

 *     [clientConnections addObject:newSocket];

 *     [newSocket markSocketQueueTargetQueue:moduleQueue];

 * }

 *

 * Note: This workaround is ONLY needed if you intend to execute code directly on the ipQueue or moduleQueue.

 * This is often NOT the case, as such queues are used solely for execution shaping.

**/

- (void)markSocketQueueTargetQueue:(dispatch_queue_t)socketQueuesPreConfiguredTargetQueue;

- (void)unmarkSocketQueueTargetQueue:(dispatch_queue_t)socketQueuesPreviouslyConfiguredTargetQueue;

/**

 * It's not thread-safe to access certain variables from outside the socket's internal queue.

 *