Skip to content

Commit f062d36

Browse files
robbiehansonrobbiehanson
committed
Merge branch 'master' into ios-secure-transport
2 parents d6b8157 + 043ba8c commit f062d36

File tree

94 files changed

+6114
-6619
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

94 files changed

+6114
-6619
lines changed

‎GCD/Documentation.html

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,19 @@ <h1>Welcome to the CocoaAsyncSocket project!</h1>
55

66
<p>
77
A wealth of documentation can be found on the Google Code homepage:</br>
8-
<a href="http://code.google.com/p/cocoaasyncsocket/">http://code.google.com/p/cocoaasyncsocket/</a>
8+
<a href="https://github.com/robbiehanson/CocoaAsyncSocket">https://github.com/robbiehanson/CocoaAsyncSocket</a>
99
</p>
1010

1111
<p>
1212
If you are new to networking, it is recommended you start by reading the Intro page:<br/>
13-
<a href="http://code.google.com/p/cocoaasyncsocket/wiki/Intro">http://code.google.com/p/cocoaasyncsocket/wiki/Intro</a>
13+
<a href="https://github.com/robbiehanson/CocoaAsyncSocket/wiki/Intro">https://github.com/robbiehanson/CocoaAsyncSocket/wiki/Intro</a>
1414
</p>
1515

1616
<p>
1717
If you are a seasoned networking professional, with 10+ years of experience writing low-level socket code,
1818
and detailed knowledge of the underlying BSD networking stack, then you can skip the CommonPitfalls page.<br/>
1919
Otherwise, it should be considered mandatory reading:<br/>
20-
<a href="http://code.google.com/p/cocoaasyncsocket/wiki/CommonPitfalls">http://code.google.com/p/cocoaasyncsocket/wiki/CommonPitfalls</a>
20+
<a href="https://github.com/robbiehanson/CocoaAsyncSocket/wiki/CommonPitfalls">https://github.com/robbiehanson/CocoaAsyncSocket/wiki/CommonPitfalls</a>
2121
</p>
2222

2323
<h4>
@@ -26,12 +26,11 @@ <h4>
2626
</h4>
2727

2828
<p>
29-
The API reference page can be found here:</br/>
30-
<a href="http://code.google.com/p/cocoaasyncsocket/wiki/Reference_GCDAsyncSocket">http://code.google.com/p/cocoaasyncsocket/wiki/Reference_GCDAsyncSocket</a>
29+
Your first goto for reference should ALWAYS be the header files. They are extremely well documented. Please read them.
3130
</p>
3231

3332
<p>
34-
In addition to this, the headers are generally well documented.
33+
Did I mention you should read the headers? They're docemented very nicely, in plain english.
3534
</p>
3635

3736
<p>

‎GCD/GCDAsyncSocket.h

Lines changed: 79 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
9797
uint32_t flags;
9898
uint16_t config;
9999

100-
id delegate;
100+
__weak id delegate;
101101
dispatch_queue_t delegateQueue;
102102

103103
int socket4FD;
@@ -323,7 +323,7 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
323323

324324
/**
325325
* Connects to the given address, specified as a sockaddr structure wrapped in a NSData object.
326-
* For example, a NSData object returned from NSNetservice's addresses method.
326+
* For example, a NSData object returned from NSNetService's addresses method.
327327
*
328328
* If you have an existing struct sockaddr you can convert it to a NSData object like so:
329329
* struct sockaddr sa -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];
@@ -343,7 +343,7 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
343343
* Connects to the given address, using the specified interface and timeout.
344344
*
345345
* The address is specified as a sockaddr structure wrapped in a NSData object.
346-
* For example, a NSData object returned from NSNetservice's addresses method.
346+
* For example, a NSData object returned from NSNetService's addresses method.
347347
*
348348
* If you have an existing struct sockaddr you can convert it to a NSData object like so:
349349
* struct sockaddr sa -> NSData *dsa = [NSData dataWithBytes:&remoteAddr length:remoteAddr.sa_len];
@@ -501,9 +501,10 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
501501
* If the bufferOffset is greater than the length of the given buffer,
502502
* the method will do nothing, and the delegate will not be called.
503503
*
504-
* If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
504+
* If you pass a buffer, you must not alter it in any way while the socket is using it.
505505
* After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
506-
* That is, it will reference the bytes that were appended to the given buffer.
506+
* That is, it will reference the bytes that were appended to the given buffer via
507+
* the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
507508
**/
508509
- (void)readDataWithTimeout:(NSTimeInterval)timeout
509510
buffer:(NSMutableData *)buffer
@@ -523,9 +524,10 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
523524
* If the bufferOffset is greater than the length of the given buffer,
524525
* the method will do nothing, and the delegate will not be called.
525526
*
526-
* If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
527+
* If you pass a buffer, you must not alter it in any way while the socket is using it.
527528
* After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
528-
* That is, it will reference the bytes that were appended to the given buffer.
529+
* That is, it will reference the bytes that were appended to the given buffer via
530+
* the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
529531
**/
530532
- (void)readDataWithTimeout:(NSTimeInterval)timeout
531533
buffer:(NSMutableData *)buffer
@@ -556,7 +558,8 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
556558
*
557559
* If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
558560
* After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
559-
* That is, it will reference the bytes that were appended to the given buffer.
561+
* That is, it will reference the bytes that were appended to the given buffer via
562+
* the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
560563
**/
561564
- (void)readDataToLength:(NSUInteger)length
562565
withTimeout:(NSTimeInterval)timeout
@@ -570,11 +573,20 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
570573
* If the timeout value is negative, the read operation will not use a timeout.
571574
*
572575
* If you pass nil or zero-length data as the "data" parameter,
573-
* the method will do nothing, and the delegate will not be called.
576+
* the method will do nothing (except maybe print a warning), and the delegate will not be called.
574577
*
575578
* To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
576-
* Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
577-
* a character, the read will prematurely end.
579+
* If you're developing your own custom protocol, be sure your separator can not occur naturally as
580+
* part of the data between separators.
581+
* For example, imagine you want to send several small documents over a socket.
582+
* Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
583+
* In this particular example, it would be better to use a protocol similar to HTTP with
584+
* a header that includes the length of the document.
585+
* Also be careful that your separator cannot occur naturally as part of the encoding for a character.
586+
*
587+
* The given data (separator) parameter should be immutable.
588+
* For performance reasons, the socket will retain it, not copy it.
589+
* So if it is immutable, don't modify it while the socket is using it.
578590
**/
579591
- (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;
580592

@@ -587,15 +599,25 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
587599
* If the buffer if nil, a buffer will automatically be created for you.
588600
*
589601
* If the bufferOffset is greater than the length of the given buffer,
590-
* the method will do nothing, and the delegate will not be called.
602+
* the method will do nothing (except maybe print a warning), and the delegate will not be called.
591603
*
592-
* If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
604+
* If you pass a buffer, you must not alter it in any way while the socket is using it.
593605
* After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
594-
* That is, it will reference the bytes that were appended to the given buffer.
606+
* That is, it will reference the bytes that were appended to the given buffer via
607+
* the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
595608
*
596609
* To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
597-
* Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
598-
* a character, the read will prematurely end.
610+
* If you're developing your own custom protocol, be sure your separator can not occur naturally as
611+
* part of the data between separators.
612+
* For example, imagine you want to send several small documents over a socket.
613+
* Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
614+
* In this particular example, it would be better to use a protocol similar to HTTP with
615+
* a header that includes the length of the document.
616+
* Also be careful that your separator cannot occur naturally as part of the encoding for a character.
617+
*
618+
* The given data (separator) parameter should be immutable.
619+
* For performance reasons, the socket will retain it, not copy it.
620+
* So if it is immutable, don't modify it while the socket is using it.
599621
**/
600622
- (void)readDataToData:(NSData *)data
601623
withTimeout:(NSTimeInterval)timeout
@@ -614,13 +636,22 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
614636
* The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
615637
*
616638
* If you pass nil or zero-length data as the "data" parameter,
617-
* the method will do nothing, and the delegate will not be called.
639+
* the method will do nothing (except maybe print a warning), and the delegate will not be called.
618640
* If you pass a maxLength parameter that is less than the length of the data parameter,
619-
* the method will do nothing, and the delegate will not be called.
641+
* the method will do nothing (except maybe print a warning), and the delegate will not be called.
620642
*
621643
* To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
622-
* Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
623-
* a character, the read will prematurely end.
644+
* If you're developing your own custom protocol, be sure your separator can not occur naturally as
645+
* part of the data between separators.
646+
* For example, imagine you want to send several small documents over a socket.
647+
* Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
648+
* In this particular example, it would be better to use a protocol similar to HTTP with
649+
* a header that includes the length of the document.
650+
* Also be careful that your separator cannot occur naturally as part of the encoding for a character.
651+
*
652+
* The given data (separator) parameter should be immutable.
653+
* For performance reasons, the socket will retain it, not copy it.
654+
* So if it is immutable, don't modify it while the socket is using it.
624655
**/
625656
- (void)readDataToData:(NSData *)data withTimeout:(NSTimeInterval)timeout maxLength:(NSUInteger)length tag:(long)tag;
626657

@@ -637,18 +668,28 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
637668
* it is treated similarly to a timeout - the socket is closed with a GCDAsyncSocketReadMaxedOutError.
638669
* The read will complete successfully if exactly maxLength bytes are read and the given data is found at the end.
639670
*
640-
* If you pass a maxLength parameter that is less than the length of the data parameter,
641-
* the method will do nothing, and the delegate will not be called.
671+
* If you pass a maxLength parameter that is less than the length of the data (separator) parameter,
672+
* the method will do nothing (except maybe print a warning), and the delegate will not be called.
642673
* If the bufferOffset is greater than the length of the given buffer,
643-
* the method will do nothing, and the delegate will not be called.
674+
* the method will do nothing (except maybe print a warning), and the delegate will not be called.
644675
*
645-
* If you pass a buffer, you must not alter it in any way while AsyncSocket is using it.
676+
* If you pass a buffer, you must not alter it in any way while the socket is using it.
646677
* After completion, the data returned in socket:didReadData:withTag: will be a subset of the given buffer.
647-
* That is, it will reference the bytes that were appended to the given buffer.
678+
* That is, it will reference the bytes that were appended to the given buffer via
679+
* the method [NSData dataWithBytesNoCopy:length:freeWhenDone:NO].
648680
*
649681
* To read a line from the socket, use the line separator (e.g. CRLF for HTTP, see below) as the "data" parameter.
650-
* Note that this method is not character-set aware, so if a separator can occur naturally as part of the encoding for
651-
* a character, the read will prematurely end.
682+
* If you're developing your own custom protocol, be sure your separator can not occur naturally as
683+
* part of the data between separators.
684+
* For example, imagine you want to send several small documents over a socket.
685+
* Using CRLF as a separator is likely unwise, as a CRLF could easily exist within the documents.
686+
* In this particular example, it would be better to use a protocol similar to HTTP with
687+
* a header that includes the length of the document.
688+
* Also be careful that your separator cannot occur naturally as part of the encoding for a character.
689+
*
690+
* The given data (separator) parameter should be immutable.
691+
* For performance reasons, the socket will retain it, not copy it.
692+
* So if it is immutable, don't modify it while the socket is using it.
652693
**/
653694
- (void)readDataToData:(NSData *)data
654695
withTimeout:(NSTimeInterval)timeout
@@ -664,6 +705,17 @@ typedef enum GCDAsyncSocketError GCDAsyncSocketError;
664705
*
665706
* If you pass in nil or zero-length data, this method does nothing and the delegate will not be called.
666707
* If the timeout value is negative, the write operation will not use a timeout.
708+
*
709+
* Thread-Safety Note:
710+
* If the given data parameter is mutable (NSMutableData) then you MUST NOT alter the data while
711+
* the socket is writing it. In other words, it's not safe to alter the data until after the delegate method
712+
* socket:didWriteDataWithTag: is invoked signifying that this particular write operation has completed.
713+
* This is due to the fact that GCDAsyncSocket does NOT copy the data. It simply retains it.
714+
* This is for performance reasons. Often times, if NSMutableData is passed, it is because
715+
* a request/response was built up in memory. Copying this data adds an unwanted/unneeded overhead.
716+
* If you need to write data from an immutable buffer, and you need to alter the buffer before the socket
717+
* completes writing the bytes (which is NOT immediately after this method returns, but rather at a later time
718+
* when the delegate method notifies you), then you should first copy the bytes, and pass the copy to this method.
667719
**/
668720
- (void)writeData:(NSData *)data withTimeout:(NSTimeInterval)timeout tag:(long)tag;
669721

0 commit comments

Comments
 (0)