PageRenderTime 31ms CodeModel.GetById 3ms app.highlight 20ms RepoModel.GetById 1ms app.codeStats 0ms

/external_dependencies/cocoalumberjack/Xcode/WebServerIPhone/Vendor/CocoaAsyncSocket/GCDAsyncSocket.h

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