-
Notifications
You must be signed in to change notification settings - Fork 83
/
AsyncSocket Documentation.html
1848 lines (1777 loc) · 99.9 KB
/
AsyncSocket Documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>AsyncSocket Documentation</title>
<style type="text/css">
body {
line-height: 120%
}
h1 {
text-align: center;
font-family: sans-serif;
font-weight: bold;
font-size: 2em;
margin-bottom: 1.25em;
}
h2 {
font-family: sans-serif;
font-weight: bold;
font-style: normal;
font-size: 1.5em;
margin: 1.75em 0px 1em 0px;
}
h3 {
font-family: sans-serif;
font-weight: bold;
font-style: italic;
margin: 1.75em 0px 0.75em 0px;
}
p {
margin: 0px 0px 0.5em 0px;
}
ul {
margin: 0px 0px 0.5em 0px;
}
table {
border-collapse: collapse;
}
th {
font-family: sans-serif;
font-style: italic;
font-weight: normal;
vertical-align: top;
text-align: left;
border: 0px;
width: 7em;
}
td {
vertical-align: top;
border: 0px;
}
td.Argument {
width: 5em;
}
.Sample_Code {
white-space: pre;
background: #cccccc;
font-family: monospace;
margin: 0.75em 0px 0.75em 2em;
}
.Method_Heading {
font-family: sans-serif;
background: #cccccc;
margin: 1.5em 0px 0.75em 0px;
}
.Function {
white-space: nowrap;
}
.Class {
}
.Code {
font-family: monospace;
}
.Constant {
font-family: monospace;
}
.Filename {
font-style: italic;
}
.Vocabulary_Word {
font-style: italic;
}
.Argument {
font-style: italic;
}
</style>
</head>
<body style="margin: 1em 1em 1em 1em;">
<h1 style="text-align: center;">AsyncSocket Documentation</h1>
<a name="intro"></a>
<p>AsyncSocket is a TCP/IP socket networking library, designed to efficiently handle packet data. The library is in two files and one public Cocoa class.</p>
<p>The library is public domain, originally written by Dustin Voss, and now maintained by Deusty and the Cocoa community.</p>
<p>For support, visit the CocoaAsyncSocket Google code page at <a href="http://code.google.com/p/cocoaasyncsocket/">http://code.google.com/p/cocoaasyncsocket/</a></p>
<a name="cont"></a>
<h3>Contents</h3>
<ol>
<li><a href="#intro">Introduction</a>
<ul>
<li><a href="#cont">Contents</a></li>
<li><a href="#about">About AsyncSocket</a></li>
<li><a href="#doc">About This Document</a></li>
</ul>
</li>
<li><a href="#basics">Socket Basics</a>
<ul>
<li><a href="#limit">Socket Limitations</a></li>
<li><a href="#struct">Packet Structure</a></li>
</ul>
</li>
<li><a href="#using">Using AsyncSocket</a>
<ul>
<li><a href="#owner">Socket Ownership</a></li>
<li><a href="#deleg">Delegate Methods</a></li>
<li><a href="#conn">Accepting, Connecting, and Disconnecting</a></li>
<li><a href="#rw">Reading and Writing</a></li>
<li><a href="#parse">Parsing Packets</a></li>
<li><a href="#err">Error Handling</a></li>
<li><a href="#thread">Threading and Run-Loops</a></li>
<li><a href="#sub">Customizing AsyncSocket</a></li>
</ul>
</li>
<li><a href="#ref">AsyncSocket Reference</a>
<ul>
<li><a href="#api_alloc">Initialization and Deallocation Messages</a></li>
<li><a href="#api_ud">User Data Messages</a></li>
<li><a href="#api_deleg">Delegation Messages</a></li>
<li><a href="#api_conn">Connection Messages</a></li>
<li><a href="#api_rw">Read and Write Messages</a></li>
<li><a href="#api_delim">Delimiter Messages</a></li>
<li><a href="#api_debug">Debugging and Customization Messages</a></li>
<li><a href="#api_delegmeth">AsyncSocketDelegate Methods</a></li>
<li><a href="#api_err">Errors</a></li>
</ul>
</li>
<li><a href="#new">API Changes</a></li>
<li><a href="#idx">API Index</li>
</ol>
<a name="about"></a>
<h3>About AsyncSocket</h3>
<p>
The Cocoa API provides a handful of networking classes, suitable for downloading and uploading images and files.
These classes support HTML, FTP, and other protocols, but cannot be used with application-specific protocols.
Without low-level socket classes supporting application-specific protocols,
developers must custom-code networking solutions using BSD or Carbon functions in conjunction with
<span class="Class">NSFileHandle</span>,
<span class="Class">NSInputStream</span>, and
<span class="Class">NSOutputStream</span>.
These functions and classes are not optimized for TCP/IP networking in a real Cocoa application, and can be difficult to integrate.
</p>
<p>
AsyncSocket provides easy-to-integrate “fire and forget” networking that makes it easy for your application to support networking.
Features include:</p>
<ul>
<li>
Queued non-blocking reads and writes, with optional timeouts.
You tell AsyncSocket what to read or write and get out of the way.
It will call you when it's done.
</li>
<li>
Automatic socket acceptance. If you tell AsyncSocket to accept connections, it will call you with new instances of itself for each connection.
You can, of course, disconnect them immediately.
</li>
<li>
Delegate support. Errors, connections, accepts, read completions, write completions, and disconnections all result in a message to your delegate.
</li>
<li>
Run-loop based, not thread based. Although you can use AsyncSocket on main or worker threads, you are not forced to do so.
<span class="Class">AsyncSocket</span> will sent messages to the delegate asynchronously via the run-loop.
The messages include a <span class="Argument">socket</span> argument, allowing you to distinguish between many instances of <span class="Class">AsyncSocket</span>.
</li>
<li>
Self-contained in one class. You do not need to muck around with a collection of stream or socket instances. The class handles all of that.
</li>
<li>
Support for TCP streams. <span class="Class">AsyncSocket</span> does not support UDP or multicast sockets.
</li>
<li>
Based on Apple’s own <span class="Class">CFSocket</span> and <span class="Class">CFStream</span> Carbon APIs.
</li>
</ul>
<a name="doc"></a>
<h3>About This Document</h3>
<p>This document assumes the reader already has the general public’s understanding of networking, and a developer’s understanding of Cocoa and Objective-C programming.</p>
<a name="basics"></a>
<h2>Socket Basics</h2>
<p>In networking parlance, a computer is a <span class="Vocabulary_Word ">host</span> for a number of sockets. A <span class="Vocabulary_Word ">socket</span> is one end of a communication channel called a <span class="Vocabulary_Word ">network connection</span>; the other end is another socket. From its own point of view, any socket is the <span class="Vocabulary_Word ">local socket</span>, and the socket at the other end of the connection is the <span class="Vocabulary_Word ">remote socket.</p>
<p>To establish the connection, one of the two sockets, the <span class="Vocabulary_Word ">connect socket</span>, must contact the other socket, the <span class="Vocabulary_Word ">listen socket</span>, and the listen socket must <span class="Vocabulary_Word ">accept</span> the connection. To contact the listen socket, the connect socket must know its <span class="Vocabulary_Word ">socket address</span>. Every socket has a socket address. The address consists of two parts: the <span class="Vocabulary_Word ">host address</span> and the <span class="Vocabulary_Word ">port number</span>. The host address is the IP address of the computer, and the port number uniquely identifies each socket hosted on the computer.</p>
<p>A computer can have multiple host addresses. It will have a pair of addresses for each possible connection method (<i>e.g.</i>, an Ethernet card, a modem, an AirPort card, a VPN connection) and a pair for connecting to itself (called “localhost”). One address of each pair is an IPv4 address such as “192.168.3.1,” and the other is an IPv6 address such as “fe80::230:65ff:fe29:aa9d.”</p>
<p>An address such as “www.google.com” corresponds to a host address, but it is not a host address itself. It is a <span class="Vocabulary_Word ">DNS address</span> or <span class="Vocabulary_Word ">DNS name</span>, which is converted to a host address by a <span class="Vocabulary_Word ">DNS look-up</span> operation. A <span class="Vocabulary_Word ">URL</span> such as “http://www.google.com:80” is likewise not a host address. URLs can include a DNS name, host address, port number, and other information.</p>
<p>Applications running on different hosts, or even on the same host, can use sockets to communicate with each other. Looking at it another way, each socket provides a communication service to its <span class="Vocabulary_Word ">client application</span>. The applications send and receive data to and from each other, which they can interpret and act upon. The data is composed of bytes, arranged into groups called <span class="Vocabulary_Word ">packets</span> and sent and received in accordance with a <span class="Vocabulary_Word ">protocol</span> followed by both applications.</p>
<p>A protocol establishes the structure of each packet, the circumstances under which any particular packet should be sent, and rules to handle exceptional circumstances. It also establishes roles for each client application. In a <span class="Vocabulary_Word ">client-server architecture</span>, some applications (the <span class="Vocabulary_Word ">servers</span>) provide a service used by other applications (the <span class="Vocabulary_Word ">clients</span>). In a <span class="Vocabulary_Word ">peer-to-peer architecture</span>, some applications (the <span class="Vocabulary_Word ">peers</span>) act as clients and servers at the same time.</p>
<a name="limit"></a>
<h3>Socket Limitations</h3>
<p>In some ways, a socket is like a file. Both contain data with a beginning and an end. Both can be written to or read from. But in other ways they differ, and these differences drive the design of a protocol.</p>
<p>First, while a file is typically for either reading or writing, a socket is interactive. Applications must be able to interrupt and alert each other, changing each others’ behavior. For this reason, data is divided up into packets, and this division leaves an opening for interruptions.</p>
<p>Second, while a file has a known size, a socket does not have a size. An application cannot know how much data is left in the current packet, unless the protocol itself specifies this. Thus, all packets include implicit or explicit size information or markers to indicate when the packet is finished.</p>
<p>Third, while a file is reliable, a socket is not reliable. When you read from a socket, the data arrives in chunks, with possibly large delays between each chunk, and there is no way to know whether a particular delay is because of high traffic or because of an unexpected disconnection. So applications are forced to treat a long delay as if it was a disconnection, and protocols define time-outs and retry messages to regulate this.</p>
<p>The AsyncSocket library was designed to make these protocol considerations easy to deal with.</p>
<a name="struct"></a>
<h3>Packet Structure</h3>
<p>Network communication protocols employ certain basic elements common to all protocols. These are:</p>
<ul>
<li>
<p>A <span class="Vocabulary_Word ">field</span>. This is the fundamental component of a packet. A field is a sequence of bytes, usually short, that are interpreted as a unit. A field may be represent a number, a character or sequence of characters, binary data, an enumeration, or a series of bit flags.</p>
<p>If field is numeric and more than one byte long, the protocol must specify whether the bytes of the number should be arranged in “little-endian,” “big-endian,” or “network” byte order. Carbon and Cocoa both provide byte-order functions that can handle different byte orders.</p>
<p>A field may be fixed-length or variable-length. The length of a <span class="Vocabulary_Word ">fixed-length field</span> is specified by the protocol. The length of a <span class="Vocabulary_Word ">variable-length field</span> is specified either explicitly or implicitly. In the former case, the variable-length field (the <span class="Vocabulary_Word ">data field</span>) will be preceded by a fixed-length numeric field (the <span class="Vocabulary_Word ">length field</span>) that specifies the length of the data field. In the latter case, a byte sequence (the <span class="Vocabulary_Word ">delimiter</span>) will mark the end of the field.</p>
</li>
<li>
<p>A <span class="Vocabulary_Word ">line of text</span>. This is character data, typically encoded as ASCII. A <span class="Vocabulary_Word ">line-ending</span> marks the end of the line. There are three commonly-used line endings: CR, LF, and CRLF. The protocol must specify which is to be used. Many text-based protocols sub-divide a line of text into variable-length fields delimited by spaces and other characters.</p>
</li>
<li>
<p>A <span class="Vocabulary_Word ">packet</span>, consisting of a <span class="Vocabulary_Word ">packet header</span> and a <span class="Vocabulary_Word ">payload</span>. The packet header contains fixed-length fields describing the type (and possibly length) of the payload. The payload contains a series of variable-length and fixed-length fields, which vary according to the payload type.</p>
</li>
<li>
<p>A <span class="Vocabulary_Word ">data stream</span>, a continuous sequence of bytes. The end of the data stream is marked by the closing of the connection. A data stream can be considered one enormous unstructured packet. When an application is transmitting a data stream, protocols typically do not allow the receiving application to interrupt the transmitting application.</p>
<p>A data stream may be preceded by a <span class="Vocabulary_Word ">data stream header</span>, a series of variable-length and fixed-length fields that describe the data stream.</p>
</li>
</ul>
<p>“<a href="#parse">Parsing Packets</a>” describes how to use <span class="Class">AsyncSocket</span> methods to read these different elements.</p>
<a name="using"></a>
<h2>Using AsyncSocket</h2>
<p>The AsyncSocket library is composed of one class, also called <span class="Class">AsyncSocket</span>. An instance of <span class="Class">AsyncSocket</span> represents one socket, which may be a listen socket or a connect socket. An instance may also be disconnected, in which case it does not represent a functioning socket. Throughout this document, the terms “socket” and “instance of <span class="Class">AsyncSocket</span>” are used almost interchangeably.</p>
<p>To use the <span class="Class">AsyncSocket</span> class in your project, add <span class="Filename ">AsyncSocket.m</span> and <span class="Filename ">/System/Library/Frameworks/CoreServices.framework</span> to the project, and import <span class="Filename ">AsyncSocket.h</span> into each file that needs it.</p>
<p>This version of AsyncSocket requires Mac OS X 10.4 or later. If you must support Mac OS X 10.3, you may use AsyncSocket version 3.13.</p>
<a name="owner"></a>
<h3>Socket Ownership</h3>
<p>In a client-server architecture, an application acting as a client usually employs one connect socket to communicate with a server, and an application acting as a server usually employs one listen socket to accept connections from clients and several connect sockets to communicate with the connected clients. In a peer-to-peer architecture, an application usually employs one listen socket and several connect sockets as if it were a server.</p>
<p>Each socket should be managed by a <span class="Vocabulary_Word ">connection controller</span> class. This class should be responsible for:</p>
<ul>
<li>Owning the local socket of the network connection.</li>
<li>Constructing and writing outgoing packets.</li>
<li>Reading and parsing incoming packets.</li>
<li>Detecting and handling error conditions.</li>
</ul>
<p>A collection of connected sockets should be managed by a <span class="Vocabulary_Word ">connection array controller</span>. This class should be responsible for creating and destroying individual connection controllers as needed. Each managed connection controller should keep the connection array controller apprised of its status.</p>
<p>If an application has a listen socket, it should be owned and managed by the connection array controller. When the listen socket accepts a connection, the connection array controller should construct a new connection controller responsible for managing the new connection.</p>
<a name="deleg"></a>
<h3>Delegate Methods</h3>
<p>An instance of <span class="Class">AsyncSocket</span> sends messages to the its delegate object upon completing certain operations or encountering certain errors. All instances of <span class="Class">AsyncSocket</span> should have a delegate that responds to these messages appropriately. The delegate object should be the socket’s connection controller or connection array controller.</p>
<p>The delegate object should implement the following delegate methods according to the socket’s purpose (see “<a href="#ref">AsyncSocket Reference</a>” below for detailed descriptions):</p>
<ul>
<li>
<p>All delegates should implement <a class="Function" href="#api_sockdiddisconnect">-onSocketDidDisconnect:</a> for clean-up.</p>
</li>
<li>
<p>All delegates should implement <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> for error recovery and logging.</p>
</li>
<li>
<p>Delegates controlling listen sockets should implement <a class="Function" href="#api_sockdidacceptnewsock">-onSocket:didAcceptNewSocket:</a>. Delegates should also implement <a class="Function" href="#api_sockwantsrunloopnewsock">-onSocket:wantsRunLoopForNewSocket:</a> if connections should be directed to individual threads.</p>
</li>
<li>
<p>Delegates controlling connect sockets or accepted connections should implement <a class="Function " href="#api_sockdidconnecthostport">-onSocket:didConnectToHost:port:</a>, <a class="Function" href="#api_sockdidreaddatatag">-onSocket:didReadData:withTag:</a>, and <a class="Function" href="#api_sockdidwritedatatag">-onSocket:didWriteDataWithTag:</a>. Delegates should also implement <a class="Function" href="#api_sockwillconnect">-onSocketWillConnect:</a> if the socket’s underlying Cocoa objects need to be customized.</p>
</li>
</ul>
<p>You will seldom need to change a socket’s delegate, but should the need arise, be careful. If a socket completes any read or write operations initiated under the old delegate, the new delegate will be notified, not the old delegate. You can check for pending read or write operations by sending <a class="Function" href="#api_cansafelysetdelegate">-canSafelySetDelegate:</a> to the socket. See “<a href="#rw">Reading and Writing</a>” below for a discussion of pending read or write operations.</p>
<p>Several instances of <span class="Class">AsyncSocket</span> can safely share one delegate object. Each instance passes itself as the first argument of any delegate message it sends. This allows the delegate object to distinguish between <span class="Class">AsyncSocket</span> instances.</p>
<a name="conn"></a>
<h3>Accepting, Connecting, and Disconnecting</h3>
<p>To initiate a connection to a remote socket at a given socket address, send <a class="Function" href="#api_connecthostporterror">-connectToHost:onPort:error:</a> to the socket, passing the host address and port as arguments. The host address can be an IP address or DNS name, including “localhost.” A DNS name does not include a port number.</p>
<p>To set up a listen socket for a given port, send <a class="Function" href="#api_acceptporterror">-acceptOnPort:error:</a> to the socket. The socket will listen on all available host addresses. To set up a socket that listens on only one address, send <a class="Function" href="#api_acceptaddressporterror">-acceptOnAddress:port:error:</a>. To optionally direct an incoming connection to a particular thread, implement <a class="Function" href="#api_sockwantsrunloopnewsock">-onSocket:wantsRunLoopForNewSocket:</a> in the socket’s delegate.</p>
<p>To alter the properties of the socket’s underlying <a class="Class">CFReadStream</a> or <a class="Class">CFWriteStream</a> objects (for example, to support SSL connections) implement <a class="Function" href="#api_sockwillconnect">-onSocketWillConnect:</a> in the socket’s delegate.</p>
<p>To disconnect the socket cleanly, send <a class="Function" href="#api_disconnectafterwriting">-disconnectAfterWriting</a> to the socket. This method will complete all write operations before disconnecting. To disconnect immediately, send <a class="Function" href="#api_disconnect">-disconnect</a>. In either case, the socket will send <a class="Function" href="#api_sockdiddisconnect">-onSocketDidDisconnect:</a> to the delegate after it finishes disconnecting.</p>
<p>If the remote socket cleanly disconnects from the local socket, the local socket will send <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> to the delegate. The message’s <span class="Argument">error</span> argument will be <span class="Constant">nil</span> (see “<a href="#err">Error Handling</a>” below). The local socket will then send <a class="Function" href="#api_sockdiddisconnect">-onSocketDidDisconnect:</a> to the delegate.</p>
<a name="rw"></a>
<h3>Reading and Writing</h3>
<p><span class="Class">AsyncSocket</span> handles reading and writing operations itself. You specify the operation you desire, and <span class="Class">AsyncSocket</span> carries it out as soon as possible and sends a message to the delegate when the operation is complete.</p>
<p><span class="Class">AsyncSocket</span> supports three reading operations (“read-to-length,” “read-to-data,” and “read-any”) and one write operation (“write-data”).</p>
<ul>
<li>
<p>The “read-to-length” operation reads a certain number of bytes from the remote socket. To perform this operation, send <a class="Function" href="#api_readdatalengthtimeouttag">-readDataToLength:withTimeout:tag:</a> to the socket.</p>
</li>
<li>
<p>The “read-to-data” operation reads all bytes up to (and including) a delimiter sequence. To perform this operation, send <a class="Function" href="#api_readdatadatatimeouttag">-readDataToData:withTimeout:tag:</a> to the socket.</p>
</li>
<li>
<p>The “read-any” operation reads the first available bytes. To perform this operation, send <a class="Function" href="#api_readdatatimeouttag">-readDataWithTimeout:tag:</a> to the socket.</p>
</li>
<li>
<p>The “write-data” operation writes a data object to the remote socket. To perform this operation, send <a class="Function" href="#api_writedatatimeouttag">-writeData:withTimeout:tag:</a> to the socket.</p>
</li>
</ul>
<p>Invoking a read or write method will perform the requested operation immediately, if possible. But if the operation cannot be completed immediately, it will be placed in a read or write queue. <span class="Class">AsyncSocket</span> will continue to execute the queued operations in sequential order in the background.</p>
<p>To check the progress of the currently-executing “read-to-length” or “write-data” operation, you may send <a class="Function" href="#api_progressreadtagbytesdonetotal">-progressOfReadReturningTag:bytesDone:total:</a> or <a class="Function" href="#api_progresswritetagbytesdonetotal">-progressOfWriteReturningTag:bytesDone:total:</a> to the socket. These methods return a decimal number between 0.0 and 1.0, and you may also get the number of bytes read or written of the total.
<p>The read and write operations support optional time-outs. The time-out value is a decimal number of seconds, for example, 1.5. The time-out value specifies how long the operation can take once begun. A queued operation does not start running out of time until it begins execution. <span class="Class">AsyncSocket</span> will use the system-defined time-out value if you send a negative time-out argument.</p>
<p>If an operation runs out of time before it is completed, the socket will disconnect. If your protocol supports a mechanism to recover from a long-delayed transmission, you can supply your own “soft” time-out by using <span class="Class">NSTimer</span> objects instead of or in addition to AsyncSocket’s own time-out system.</p>
<p>When an operation has completed within the allotted time, the socket will send a message to its delegate (either <a class="Function" href="#api_sockdidreaddatatag">-onSocket:didReadData:withTag:</a> or <a class="Function" href="#api_sockdidwritedatatag">-onSocket:didWriteDataWithTag:</a>). The delegate object should respond appropriately, sending another read or write message to the socket as necessary.</p>
<p>To help the delegate object respond appropriately, you can supply a tag value as an argument of a read or write message. A tag value can be an integer, pointer, or object id. Tag values are not transmitted to the remote socket, and the remote socket does not transmit tag values to the local socket. But the message sent by the local socket to its delegate upon completing the operation includes the tag value you initially supplied. The tag value can be used to “remember” the circumstances under which the operation was initiated. Tag values can mark a type of operation, or specify a step of a multi-operation process.</p>
<a name="parse"></a>
<h3>Parsing Packets</h3>
<p>To parse a packet, or to read a data stream, line of text, or data stream header, consider how to break it down into a series of simple read operations.</p>
<p>Here are some techniques you can use to read and parse the elements of a protocol:</p>
<ul>
<li>
<p>Any individual fixed-length field can be read by a “read-to-length” operation. But you can also read a series of fixed-length fields all at once. The fields will be collected in a single data object. You can easily recover individual fields by using a C struct, as in this sample code:</p>
<div class="Sample_Code ">
UInt32 field1, field2;
struct fields { UInt32 field1; UInt32 field2; };
struct fields *fieldSeries = (struct fields *)[receivedData bytes];
field1 = fieldSeries->field1;
field2 = fieldSeries->field2;</div>
<p>If only fixed-length fields comprise a packet, you can use this technique to read an entire packet at once.</p>
</li>
<li>
<p>Any delimited variable-length field can be read in its entirety by a single “read-to-data” operation.</p>
</li>
<li>
<p>A variable-length data field preceded by a fixed-length length field can be read in two parts. Use one “read-to-length” operation to read the length field. This will tell you how long the data field is. Use another “read-to-length” operation to read the data field.</p>
</li>
<li>
<p>A packet can also be read in two (or more) parts. Use one “read-to-length” operation to read the entire fixed-length packet header. Extract the length of the payload from the header, and use the above techniques to read the fields of the payload.</p>
</li>
<li>
<p>A line of text can be treated as a variable-length field delimited by a line ending. <span class="Class">AsyncSocket</span> provides delimiter messages that return the CR, LF, and CRLF line endings. Your client application will receive the line of text as a data object. You can then convert the data object to a string object, and use the <span class="Class">NSString</span> and <span class="Class">NSScanner</span> classes to break the line into individual fields.</p>
</li>
<li>
<p>Data stream headers vary in format, but can be treated as fixed- or variable-length fields and parsed using the above techniques.</p>
</li>
<li>
<p>A data stream can be read with one of two techniques. The first technique is appropriate when the data in the stream must be processed as it arrives, or if you do not know the size of the data:</p>
<ol>
<li>
<p>Send <a class="Function" href="#api_readdatatimeouttag">-readDataWithTimeout:tag:</a> to the socket.</p>
</li>
<li>
<p>When data arrives, the socket will send send <a class="Function" href="#api_sockdidreaddatatag">-onSocket:didReadData:withTag:</a> to the delegate. Process or store the data.</p>
</li>
<li>
<p>Send <a class="Function" href="#api_readdatatimeouttag">-readDataWithTimeout:tag:</a> to the socket before returning from the delegate method.</p>
</li>
<li>
<p>Repeat until the connection closes. In the delegate object’s <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> method, send <a class="Function" href="#api_readdatatimeouttag">-readDataWithTimeout:tag:</a> to the socket one last time.</p>
</li>
</ol>
<p>The second technique can only be used when you know the size of the data stream and want the entire stream returned in a single data object:</p>
<ol>
<li><p>Send <a class="Function" href="#api_readdatalengthtimeouttag">-readDataToLength:withTimeout:tag:</a> to the socket.</p></li>
<li><p>Wait for the delegate object’s <a class="Function" href="#api_sockdidreaddatatag">-onSocket:didReadData:withTag:</a> method to be called.</p></li>
</ol>
</li>
</ul>
<a name="err"></a>
<h3>Error Handling</h3>
<p>
If a socket encounters an input/output error, or if a read or write operation times out, AsyncSocket assumes the connection has been broken and must be re-established.
The socket will proceed to disconnect itself. The remote socket will typically be disconnected by its own client application.
</p>
<p>
Before disconnecting the local socket, an <span class="Class">AsyncSocket</span> instance will
send <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> to its delegate object.
The second argument of this message is an <span class="Class">NSError</span> object.
This object may contain a POSIX, Mac OS, or <span class="Class">CFStream</span> error code,
as indicated by the object’s <span class="Function ">-domain</span> method.
It may also contain an <span class="Class">AsyncSocket</span>-specific error code.
See “<a href="#api_sockdomain">Errors</a>” below for details.
</p>
<p>
During the execution of its <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> method,
the delegate object may retrieve all unreceived data (including data from any partially-completed read operations) by
sending <a class="Function" href="#api_unreaddatatag">-unreadData</a> to the socket.
</p>
<p>
After the delegate object’s <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> method returns,
the socket will be disconnected.
It will then send <a class="Function" href="#api_sockdiddisconnect">-onSocketDidDisconnect:</a> to the delegate.
</p>
<a name="thread"></a>
<h3>Threading and Run-Loops</h3>
<p>An <span class="Class">AsyncSocket</span> instance must be used in conjunction with a run-loop. Its run-loop activity occurs in the <span class="Constant">NSDefaultRunLoopMode</span> mode.</p>
<p>An <span class="Class">AsyncSocket</span> instance may be used from a worker thread or the main thread. However, each instance should only be used from one thread, so that the instance does not invoke delegate methods from within the wrong thread context.</p>
<p>To create a connect or listen socket in a particular thread, simply create the socket in the context of that thread.</p>
<p>A listen socket creates a new socket when it accepts a connection. To ensure this new socket is created in a particular thread, return the thread’s run-loop from the listen socket’s <a class="Function" href="#api_sockwantsrunloopnewsock">-onSocket:wantsRunLoopForNewSocket:</a> delegate method.</p>
<a name="sub"></a>
<h3>Customizing AsyncSocket</h3>
<p><span class="Class">AsyncSocket</span> is not intended to be sub-classed. However, since <span class="Class">AsyncSocket</span> is in the public domain, you may alter it as much as you like for your own projects. The source code was written to be understandable.</p>
<p><span class="Class">AsyncSocket</span> uses <span class="Class">CFSocket</span>, <span class="Class">CFReadStream</span>, and <span class="Class">CFWriteStream</span> internally. You may access these directly and set whatever properties or behaviors you may need. The <a class="Function" href="#api_sockwillconnect">-onSocketWillConnect:</a> delegate method is designed to facilitate this.</p>
<a name="ref"></a>
<h2>AsyncSocket Reference</h2>
<p>See “<a href="#idx">API Index</a>” below for an alphabetical list of messages, methods, types, and constants.</p>
<a name="api_alloc"></a>
<h3>Initialization and Deallocation Messages</h3>
<p><span class="Class">AsyncSocket</span> does not provide an auto-released convenience initializer.</p>
<p><a class="Function" href="#api_init">-init</a> <a class="Function" href="#api_initdelegate">-initWithDelegate:</a> <a class="Function" href="#api_initdelegateuserdata">-initWithDelegate:userData:</a> <a class="Function" href="#api_dealloc">-dealloc</a></p>
<a name="api_init"></a>
<p class="Method_Heading">-init</p>
<p>This message initializes the receiver, without setting a delegate.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(id)init</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td><p>An instance of <span class="Class">AsyncSocket</span>.</p></td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<a name="api_initdelegate"></a>
<p class="Method_Heading">-initWithDelegate:</p>
<p>This message initializes the receiver, setting the delegate at the same time.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(id)initWithDelegate:(id)delegate</p></td>
</tr>
<tr>
<th><p>Arguments<p></th>
<td class="Argument"><p>delegate</p></td>
<td>
<p>An object that will act as the delegate for the receiver. The delegate should implement the necessary <span class="Class">AsyncSocketDelegate</span> methods.</p>
<p>May be <span class="Constant">nil</span>.</p>
</td>
</tr>
<tr>
<th><p>Return Value</p>
<td colspan="2">
<p>An instance of <span class="Class">AsyncSocket</span>.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td colspan="2"><p>None.</p></td>
</tr>
</table>
<a name="api_initdelegateuserdata"></a>
<p class="Method_Heading">-initWithDelegate:userData:</p>
<p>This message initializes the receiver, setting the delegate and user data at the same time. This method is the designated initializer of an AsyncSocket instance.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(id)initWithDelegate:(id)delegate userData:(long)userData</p></td>
</tr>
<tr>
<th rowspan="2"><p>Arguments<p></th>
<td class="Argument"><p>delegate</p></td>
<td>
<p>An object that will act as the delegate for the receiver. The delegate should implement the necessary <span class="Class">AsyncSocketDelegate</span> methods.</p>
<p>May be <span class="Constant">nil</span>.</p>
</td>
</tr>
<tr>
<td class="Argument"><p>userData</p></td>
<td>
<p>A value that will be associated with the receiver. It may be retrieved later through a <a class="Function" href="#api_userdata">-userData:</a> message.</p>
</td>
</tr>
<tr>
<th><p>Return Value</p>
<td colspan="2">
<p>An instance of <span class="Class">AsyncSocket</span>.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td colspan="2"><p>None.</p></td>
</tr>
</table>
<a name="api_dealloc"></a>
<p class="Method_Heading">-dealloc</p>
<p>This message will deallocate the receiver, disconnecting if necessary.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td><span class="Body Code ">-(void)dealloc</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<a name="api_ud"></a>
<h3>User Data Messages</h3>
<p><a class="Function" href="#api_userdata">-userData</a> <a class="Function" href="#api_setuserdata">-setUserData:</a></p>
<a name="api_userdata"></a>
<p class="Method_Heading">-userData</p>
<p>This message returns the receiver’s current user data, an arbitary value associated with the receiver.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(long)userData</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td><p>The current user data.</p></td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<a name="api_setuserdata"></a>
<p class="Method_Heading">-setUserData:</p>
<p>This message sets the receiver’s user data, an arbitary value associated with the receiver.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(void)setUserData:(long)userData</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td class="Argument"><p>userData</p></td>
<td>
<p>A value that will be associated with the receiver.</p>
</td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td colspan="2"><p>None.</p></td>
</tr>
<tr>
<th><p>Errors</p></th>
<td colspan="2"><p>None.</p></td>
</tr>
</table>
<a name="api_deleg"></a>
<h3>Delegation Messages</h3>
<p><a class="Function" href="#api_delegate">-delegate</a> <a class="Function" href="#api_setdelegate">-setDelegate:</a> <a class="Function" href="#api_cansafelysetdelegate">-canSafelySetDelegate</a></p>
<a name="api_delegate"></a>
<p class="Method_Heading">-delegate</p>
<p>This message returns the receiver’s current delegate object.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(id)delegate</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td><p>The current delegate object, or <span class="Constant">nil</span>.</p></td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<a name="api_setdelegate"></a>
<p class="Method_Heading">-setDelegate:</p>
<p>This message sets the receiver’s delegate object. The delegate object is not retained.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(void)setDelegate:(id)delegate</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td class="Argument"><p>delegate</p></td>
<td>
<p>An instance of a class that will act as the delegate for the receiver. Should implement the necessary <span class="Class">AsyncSocketDelegate</span> methods.</p>
<p>May be <span class="Constant">nil</span>.</p>
</td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td colspan="2"><p>None.</p></td>
</tr>
<tr>
<th><p>Errors</p></th>
<td colspan="2"><p>None.</p></td>
</tr>
</table>
<p>If the delegate object is changed, the old delegate object will no longer receive any messages that it may be expecting as a result of pending read or write operations that it initiated. To ensure there are no pending read or write operations, the delegate object can invoke <a class="Function" href="#api_cansafelysetdelegate">-canSafelySetDelegate:</a>.</p>
<a name="api_cansafelysetdelegate"></a>
<p class="Method_Heading">-canSafelySetDelegate</p>
<p>This message can be sent to determine whether a new delegate object needs to be made aware of pending read or write operations.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(BOOL)canSafelySetDelegate</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td>
<p><span class="Constant">YES</span>, if the receiver has any pending read or write operations.</p>
<p><span class="Constant">NO</span>, if the receiver has no pending read or write operations.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<a name="api_conn"></a>
<h3>Connection Messages</h3>
<p><a class="Function" href="#api_connecthostporterror">-connectToHost:onPort:error:</a> <a class="Function" href="#api_acceptporterror">-acceptOnPort:error:</a> <a class="Function" href="#api_acceptaddressporterror">-acceptOnAddress:port:error:</a> <a class="Function" href="#api_isconnected">-isConnected</a> <a class="Function" href="#api_disconnect">-disconnect</a> <a class="Function" href="#api_disconnectafterwriting">-disconnectAfterWriting</a> <a class="Function" href="#api_connectedhost">-connectedHost</a> <a class="Function" href="#api_connectedport">-connectedPort</a> <a class="Function" href="#api_localhost">-localHost</a> <a class="Function" href="#api_localport">-localPort</a></p>
<a name="api_connecthostporterror"></a>
<p class="Method_Heading">-connectToHost:onPort:error:</p>
<p>This message establishes an outgoing connection from the receiver.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(BOOL)connectToHost:(NSString *)hostname onPort:(UInt16)port error:(NSError **)err</p></td>
</tr>
<tr>
<th rowspan="3"><p>Arguments</p></th>
<td class="Argument"><p>hostname</p></td>
<td>
<p>A DNS name or IP address to which the receiver should connect. Both IPv4 and IPv6 addresses are supported.</p>
</td>
</tr>
<tr>
<td class="Argument"><p>port</p></th>
<td>
<p>A port number to which the receiver should connect.</p>
</td>
</tr>
<tr>
<td class="Argument"><p>err</p></td>
<td>
<p>The address of an <span class="Class">NSError</span> object pointer. In the event of an error, the pointer will be set to the <span class="Class">NSError</span> object describing the error.</p>
<p>The sender may pass <span class="Constant">nil</span> if it does not wish to retrieve any <span class="Class">NSError</span> object.</p>
</td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td colspan="2">
<p>Returns <span class="Constant">YES</span> if the connection is successful.</p>
<p>This does not indicate that the socket is ready for use. The socket is only ready when the <a class="Function" href="#api_sockdidconnecthostport">-onSocket:didConnectToHost:port:</a> delegate method is called.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td colspan="2">
<p>Returns <span class="Constant">NO</span> and an <span class="Class">NSError</span> object under the following conditions:</p>
<ul>
<li><span class="Argument">hostname</span> is not a valid address, or there is no such address.</li>
<li>The socket cannot be created, or cannot connect to the address.</li>
</ul>
<p>Returns <span class="Constant">YES</span> and calls <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> under the following conditions:</p>
<ul>
<li>The read and write streams could not be attached or opened.</li>
</ul>
<p>Raises an <a class="Constant" href="#api_sockexception">AsyncSocketException</a> if the socket is already connected or accepting connections, or if no delegate has been set.</p>
</td>
</tr>
</table>
<p>If the receiver returns <span class="Constant">YES</span>, it will continue to establish a connection. When the connection is successfully established, or fails to be established, the receiver will send an appropriate message to its delegate object.</p>
<p>Read and write operations may be queued before the connection is successfully established. They will be executed after the connection is complete.</p>
<a name="api_acceptporterror"></a>
<p class="Method_Heading">-acceptOnPort:error:</p>
<p>This message establishes the receiver as a listen socket that will accept incoming connections.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(BOOL)acceptOnPort:(UInt16)port error:(NSError **)err</p></td>
</tr>
<tr>
<th rowspan="2"><p>Arguments</p></th>
<td class="Argument"><p>port</p></td>
<td>
<p>A port number at which the receiver should accept connections.</p>
</td>
</tr>
<tr>
<td class="Argument"><p>err</p></td>
<td>
<p>The address of an <span class="Class">NSError</span> object pointer. In the event of an error, the pointer will be set to the <span class="Class">NSError</span> object describing the error.</p>
<p>The sender may pass <span class="Constant">nil</span> if it does not wish to retrieve any <span class="Class">NSError</span> object.</p>
</td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td colspan="2">
<p>Returns <span class="Constant">YES</span> if the receiver is successfully accepting connections at the specified port.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td colspan="2">
<p>Returns <span class="Constant">NO</span> and an <span class="Class">NSError</span> object if the socket cannot be created, or cannot accept connections on the specified port.</p>
<p>Raises an <a class="Constant" href="#api_sockexception">AsyncSocketException</a> if the socket is already connected or accepting connections, or if no delegate has been set.</p>
</td>
</tr>
</table>
<p>The receiver establishes a listen socket with the <span class="Constant">SO_REUSEADDR</span> option set.</p>
<p>In the event of a connection from a remote socket, the receiver will create a new <span class="Class">AsyncSocket</span> instance. The new instance will have the same delegate object as the receiver, and will attempt to complete the connection to the remote socket.</p>
<p>There are three possible outcomes of the new instance’s attempt. First, the attempt could succeed. Second, the attempt could fail because a local socket could not be created. Third, the attempt could fail because of another issue.</p>
<p>If successful, the receiver will send <a class="Function" href="#api_sockdidacceptnewsock">-onSocket:didAcceptNewSocket:</a> and <a class="Function" href="#api_sockwantsrunloopnewsock">-onSocket:wantsRunLoopForNewSocket:</a> to its delegate object. At this point the delegate object can change the new instance’s delegate object or assign a run-loop. After the delegate methods return, the new instance will send <a class="Function" href="#api_sockdidconnecthostport">-onSocket:didConnectToHost:port:</a> to its delegate object.</p>
<p>If unsuccessful because a local socket could not be created, the new instance will be silently destroyed, and the receiver will continue to accept connections.</p>
<p>If unsuccessful for some other reason, the receiver will send <a class="Function" href="#api_sockdidacceptnewsock">-onSocket:didAcceptNewSocket:</a> and <a class="Function" href="#api_sockwantsrunloopnewsock">-onSocket:wantsRunLoopForNewSocket:</a> to its delegate object. After the delegate method returns, the new instance will send <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> to its delegate with details about the failure condition.</p>
<a name="api_acceptaddressporterror"></a>
<p class="Method_Heading">-acceptOnAddress:port:error:</p>
<p>This message establishes the receiver as a listen socket that will accept incoming connections on a particular host address and port.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(BOOL)acceptOnAddress:(NSString *)hostaddr port:(UInt16)port error:(NSError **)err</p></td>
</tr>
<tr>
<th rowspan="3"><p>Arguments</p></th>
<td class="Argument"><p>hostaddr</p></td>
<td>
<p>A host address at which the receiver should accept connections. The address should be an IPv4 or IPv6 address, such as “192.168.3.1” or “fe80::230:65ff:fe29:aa9d.”</p>
<p>If <span class="Constant">nil</span> or an empty string, the effect is the same as <a class="Function" href="#api_acceptporterror">-acceptOnPort:error:</a> message.
<tr>
<td class="Argument"><p>port</p></td>
<td>
<p>A port number at which the receiver should accept connections.</p>
</td>
</tr>
<tr>
<td class="Argument"><p>err</p></td>
<td>
<p>The address of an <span class="Class">NSError</span> object pointer. In the event of an error, the pointer will be set to the <span class="Class">NSError</span> object describing the error.</p>
<p>The sender may pass <span class="Constant">nil</span> if it does not wish to retrieve any <span class="Class">NSError</span> object.</p>
</td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td colspan="2">
<p>Returns <span class="Constant">YES</span> if the receiver is successfully accepting connections at the specified port.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td colspan="2">
<p>Returns <span class="Constant">NO</span> and an <span class="Class">NSError</span> object if the socket cannot be created, or cannot accept connections on the specified address or port.</p>
<p>Raises an <a class="Constant" href="#api_sockexception">AsyncSocketException</a> if the socket is already connected or accepting connections, or if no delegate has been set.</p>
</td>
</tr>
</table>
<p>See <a class="Function" href="#api_acceptporterror">-acceptOnPort:error:</a> for more information.</p>
<a name="api_isconnected"></a>
<p class="Method_Heading">-isConnected</p>
<p>This message may be sent to determine whether the receiver is connected and capable of reading and writing.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code"><p>-(BOOL)isConnected</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td>
<p><span class="Constant">YES</span>, if the receiver is connected and able to send and receive data.</p>
<p><span class="Constant">NO</span>, if the receiver is not connected, accepting connections, or not able to send and receive data.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<p>If the input or output streams have reached <span class="Constant">EOF</span>, the receiver returns <span class="Constant">NO</span>. If the input or output streams are open, but in some other error state, the receiver returns <span class="Constant">YES</span>.</p>
<p>If the receiver is accepting incoming connections, it always returns <span class="Constant">NO</span>.</p>
<a name="api_disconnect"></a>
<p class="Method_Heading">-disconnect</p>
<p>This message immediately disconnects the receiver.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code"><p>-(void)disconnect</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<p>If the receiver was accepting incoming connections, it will no stop doing so. Any pending read or write operations are dropped.</p>
<p>After this method returns, the client application may send a <a class="Function" href="#api_connecthostporterror">-connectToHost:onPort:error:</a>, <a class="Function" href="#api_acceptporterror">-acceptOnPort:error:</a>, or <a class="Function" href="#api_acceptaddressporterror">-acceptOnAddress:port:error:</a> messages again.</p>
<a name="api_disconnectafterwriting"></a>
<p class="Method_Heading">-disconnectAfterWriting</p>
<p>This message will disconnect the receiver after all pending write operations are completed. Pending read operations will not prevent the receiver from disconnecting.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code"><p>-(void)disconnectAfterWriting</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<p>While the pending write operations are completing, the receiver will ignore any further read or write messages. Other messages may be sent as usual.</p>
<a name="api_connectedhost"></a>
<p class="Method_Heading">-connectedHost</p>
<p>This message returns the IP address of the connected remote socket as a string.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(NSString *)connectedHost</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td>
<p>If the receiver is connected, an IP address.</p>
<p>If the receiver is not connected, <span class="Constant">nil</span>.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<a name="api_connectedport"></a>
<p class="Method_Heading">-connectedPort</p>
<p>This message returns the port number of the connected remote socket.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code"><p>-(UInt16)connectedPort</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td>
<p>If the receiver is connected, a port number.</p>
<p>If the receiver is not connected, <span class="Constant">0</span>.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<a name="api_localhost"></a>
<p class="Method_Heading">-localHost</p>
<p>This method returns the local IP address of the receiver as a string.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code"><p>-(NSString *)localHost</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td>
<p>If the receiver is connected, an IP address.</p>
<p>If the receiver is not connected, <span class="Constant">nil</span>.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<p>If the computer has more than one IP address, the one in use by the receiver will be returned. If the computer is behind a NAT, the returned IP address will be a LAN address, not useable outside the LAN.</p>
<a name="api_localport"></a>
<p class="Method_Heading">-localPort</p>
<p>This method returns the port number of the receiver.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code"><p>-(UInt16)localPort</p></td>
</tr>
<tr>
<th><p>Arguments</p></th>
<td><p>None.</p></td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td>
<p>If the receiver is connected, a port number.</p>
<p>If the receiver is not connected, <span class="Constant">0</span>.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td><p>None.</p></td>
</tr>
</table>
<p>If the computer is behind a NAT, the returned port number will be a LAN address, not accurate outside the LAN.</p>
<a name="api_rw"></a>
<h3>Read and Write Messages</h3>
<p><a class="Function" href="#api_readdatalengthtimeouttag">-readDataToLength:withTimeout:tag:</a> <a class="Function" href="#api_readdatadatatimeouttag">-readDataToData:withTimeout:tag:</a> <a class="Function" href="#api_readdatatimeouttag">-readDataWithTimeout:tag:</a> <a class="Function" href="#api_writedatatimeouttag">-writeData:withTimeout:tag:</a> <a class="Function" href="#api_progressreadtagbytesdonetotal">-progressOfReadReturningTag:bytesDone:total:</a> <a class="Function" href="#api_progresswritetagbytesdonetotal">-progressOfWriteReturningTag:bytesDone:total:</a></p>
<a name="api_readdatalengthtimeouttag"></a>
<p class="Method_Heading">-readDataToLength:withTimeout:tag:</p>
<p>This message queues a read operation. The receiver will read a certain number of bytes from the socket.</p>
<table>
<tr>
<th><p>Syntax</p></th>
<td class="Code" colspan="2"><p>-(void)readDataToLength:(CFIndex)length withTimeout:(NSTimeInterval)timeout tag:(long)tag</p></td>
</tr>
<tr>
<th rowspan="3"><p>Arguments</p></th>
<td class="Argument"><p>length</p></td>
<td>
<p>Number of bytes that the receiver should read.</p>
<p>If <span class="Constant">0</span>, the receiver does nothing, and does not send <a class="Function" href="#api_sockdidreaddatatag">-onSocket:didReadData:withTag:</a> to its delegate.</p>
</td>
</tr>
<tr>
<td class="Argument"><p>timeout</p></td>
<td>
<p>The number of seconds from the start of the read operation in which the operation must complete. If the operation takes longer than this interval, the operation times out.</p>
<p>If negative, the read operation will not time out.</p>
</td>
</tr>
<tr>
<td class="Argument"><p>tag</p></td>
<td>
<p>An application-defined integer or pointer that will be sent as an argument to the <a class="Function" href="#api_sockdidreaddatatag">-onSocket:didReadData:withTag:</a> message sent to the delegate.</p>
</td>
</tr>
<tr>
<th><p>Return Value</p></th>
<td colspan="2">
<p>The receiver will send <a class="Function" href="#api_sockdidreaddatatag">-onSocket:didReadData:withTag:</a> to the delegate object when the read operation has completed. The received data will be passed as an argument of that message.</p>
</td>
</tr>
<tr>
<th><p>Errors</p></th>
<td colspan="2">
<p>The receiver will send <a class="Function" href="#api_sockwilldisconnecterror">-onSocket:willDisconnectWithError:</a> to the delegate object under the following conditions:</p>
<ul>
<li>The read operation times out.</li>