AsyncSocket&Document
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.
The library is public domain, originally written by Dustin
Voss, and now maintained by Deusty and the Cocoa community.
For support, visit the CocoaAsyncSocket Google code page at
/p/cocoaasyncsocket/
Introduction&
About AsyncSocket
About This Document
Socket Basics&
Socket Limitations
Packet Structure
Using AsyncSocket&
Socket Ownership
Delegate Methods
Accepting, Connecting, and Disconnecting
Reading and Writing
Parsing Packets
Error Handling
Threading and Run-Loops
Customizing AsyncSocket
AsyncSocket Reference&
Initialization and Deallocation Messages
User Data Messages
Delegation Messages
Connection Messages
Read and Write Messages
Delimiter Messages
Debugging and Customization Messages
AsyncSocketDelegate Methods
API Changes
About AsyncSocket
&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 NSFileHandle, NSInputStream,
and NSOutputStream. These functions and classes are not optimized
for TCP/IP networking in a real Cocoa application, and can be
difficult to integrate.&
&AsyncSocket provides easy-to-integrate “fire
and forget” networking that makes it easy for your application to
support networking. Features include:
&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
&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.&
&Delegate support. Errors, connections,
accepts, read completions, write completions, and disconnections
all result in a message to your delegate.&
&Run-loop based, not thread based. Although
you can use AsyncSocket on main or worker threads, you are not
forced to do so. AsyncSocket will sent messages to the delegate
asynchronously via the run-loop. The messages include a socket
argument, allowing you to distinguish between many instances of
AsyncSocket.&
&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.&
&Support for TCP streams. AsyncSocket does
not support UDP or multicast sockets.&
&Based on Apple’s own CFSocket and CFStream
Carbon APIs.&
About This Document
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.
Socket Basics
In networking parlance, a computer is a host for a number of
sockets. A socket is one end of a communication channel called a
the other end is another socket. From its own
point of view, any socket is the local socket, and the socket at
the other end of the connection is the remote socket.
To establish the connection, one of the two sockets, the
connect socket, must contact the other socket, the listen socket,
and the listen socket must accept the connection. To contact the
listen socket, the connect socket must know its socket address.
Every socket has a socket address. The address consists of two
parts: the host address and the port number. The host address is
the IP address of the computer, and the port number uniquely
identifies each socket hosted on the computer.
A computer can have multiple host addresses. It will have a
pair of addresses for each possible connection method (e.g., 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.”
An address such as “” corresponds to a host
address, but it is not a host address itself. It is a DNS address
or DNS name, which is converted to a host address by a DNS look-up
operation. A URL such as “:80” is likewise not
a host address. URLs can include a DNS name, host address, port
number, and other information.
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
client application. 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 packets and sent and
received in accordance with a protocol followed by both
applications.
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 client-server architecture,
some applications (the servers) provide a service used by other
applications (the clients). In a peer-to-peer architecture, some
applications (the peers) act as clients and servers at the same
Socket Limitations
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
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.
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.
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.
The AsyncSocket library was designed to make these protocol
considerations easy to deal with.
Packet Structure
Network communication protocols employ certain basic elements
common to all protocols. These are:
A field. 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.
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.
A field may be fixed-length or variable-length. The length of
a fixed-length field is specified by the protocol. The length of a
variable-length field is specified either explicitly or implicitly.
In the former case, the variable-length field (the data field) will
be preceded by a fixed-length numeric field (the length field) that
specifies the length of the data field. In the latter case, a byte
sequence (the delimiter) will mark the end of the field.
A line of text. This is character data, typically encoded as
ASCII. A line-ending 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.
A packet, consisting of a packet header and a payload. 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.
A data stream, 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.
A data stream may be preceded by a data stream header, a
series of variable-length and fixed-length fields that describe the
data stream.
“Parsing Packets” describes how to use AsyncSocket methods to
read these different elements.
Using AsyncSocket
The AsyncSocket library is composed of one class, also called
AsyncSocket. An instance of AsyncSocket 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 AsyncSocket” are used almost
interchangeably.
To use the AsyncSocket class in your project, add
AsyncSocket.m and /System/Library/Frameworks/CoreServices.framework
to the project, and import AsyncSocket.h into each file that needs
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
Socket Ownership
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
Each socket should be managed by a connection controller
class. This class should be responsible for:
Owning the local socket of the network connection.
Constructing and writing outgoing packets.
Reading and parsing incoming packets.
Detecting and handling error conditions.
A collection of connected sockets should be managed by a
connection array controller. 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.
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.
Delegate Methods
An instance of AsyncSocket sends messages to the its delegate
object upon completing certain operations or encountering certain
errors. All instances of AsyncSocket should have a delegate that
responds to these messages appropriately. The delegate object
should be the socket’s connection controller or connection array
controller.
The delegate object should implement the following delegate
methods according to the socket’s purpose (see “AsyncSocket
Reference” below for detailed descriptions):
All delegates should implement -onSocketDidDisconnect: for
All delegates should implement
-onSocket:willDisconnectWithError: for error recovery and
Delegates controlling listen sockets should implement
-onSocket:didAcceptNewSocket:. Delegates should also implement
-onSocket:wantsRunLoopForNewSocket: if connections should be
directed to individual threads.
Delegates controlling connect sockets or accepted connections
should implement -onSocket:didConnectToHost:port:,
-onSocket:didReadData:withTag:, and -onSocket:didWriteDataWithTag:.
Delegates should also implement -onSocketWillConnect: if the
socket’s underlying Cocoa objects need to be customized.
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 -canSafelySetDelegate: to the
socket. See “Reading and Writing” below for a discussion of pending
read or write operations.
Several instances of AsyncSocket 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 AsyncSocket instances.
Accepting, Connecting, and Disconnecting
To initiate a connection to a remote socket at a given socket
address, send -connectToHost:onPort:error: 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.
To set up a listen socket for a given port, send
-acceptOnPort:error: to the socket. The socket will listen on all
available host addresses. To set up a socket that listens on only
one address, send -acceptOnAddress:port:error:. To optionally
direct an incoming connection to a particular thread, implement
-onSocket:wantsRunLoopForNewSocket: in the socket’s delegate.
To alter the properties of the socket’s underlying
CFReadStream or CFWriteStream objects (for example, to support SSL
connections) implement -onSocketWillConnect: in the socket’s
To disconnect the socket cleanly, send -disconnectAfterWriting
to the socket. This method will complete all write operations
before disconnecting. To disconnect immediately, send -disconnect.
In either case, the socket will send -onSocketDidDisconnect: to the
delegate after it finishes disconnecting.
If the remote socket cleanly disconnects from the local
socket, the local socket will send
-onSocket:willDisconnectWithError: to the delegate. The message’s
error argument will be nil (see “Error Handling” below). The local
socket will then send -onSocketDidDisconnect: to the
Reading and Writing
AsyncSocket handles reading and writing operations itself. You
specify the operation you desire, and AsyncSocket carries it out as
soon as possible and sends a message to the delegate when the
operation is complete.
AsyncSocket supports three reading operations
(“read-to-length,” “read-to-data,” and “read-any”) and one write
operation (“write-data”).
The “read-to-length” operation reads a certain number of bytes
from the remote socket. To perform this operation, send
-readDataToLength:withTimeout:tag: to the socket.
The “read-to-data” operation reads all bytes up to (and
including) a delimiter sequence. To perform this operation, send
-readDataToData:withTimeout:tag: to the socket.
The “read-any” operation reads the first available bytes. To
perform this operation, send -readDataWithTimeout:tag: to the
The “write-data” operation writes a data object to the remote
socket. To perform this operation, send -writeData:withTimeout:tag:
to the socket.
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.
AsyncSocket will continue to execute the queued operations in
sequential order in the background.
To check the progress of the currently-executing
“read-to-length” or “write-data” operation, you may send
-progressOfReadReturningTag:bytesDone:total: or
-progressOfWriteReturningTag:bytesDone:total: 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
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. AsyncSocket will use the system-defined
time-out value if you send a negative time-out argument.
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 NSTimer objects instead of or in addition
to AsyncSocket’s own time-out system.
When an operation has completed within the allotted time, the
socket will send a message to its delegate (either
-onSocket:didReadData:withTag: or -onSocket:didWriteDataWithTag:).
The delegate object should respond appropriately, sending another
read or write message to the socket as necessary.
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.
Parsing Packets
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.
Here are some techniques you can use to read and parse the
elements of a protocol:
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:
UInt32 field1, field2;
struct fields { UInt32 field1; UInt32 field2; };
struct fields *fieldSeries = (struct fields *)[receivedData
field1 = fieldSeries-&field1;
field2 = fieldSeries-&field2;
If only fixed-length fields comprise a packet, you can use
this technique to read an entire packet at once.
Any delimited variable-length field can be read in its
entirety by a single “read-to-data” operation.
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
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.
A line of text can be treated as a variable-length field
delimited by a line ending. AsyncSocket 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
NSString and NSScanner classes to break the line into individual
Data stream headers vary in format, but can be treated as
fixed- or variable-length fields and parsed using the above
techniques.
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
Send -readDataWithTimeout:tag: to the socket.
When data arrives, the socket will send send
-onSocket:didReadData:withTag: to the delegate. Process or store
Send -readDataWithTimeout:tag: to the socket before returning
from the delegate method.
Repeat until the connection closes. In the delegate object’s
-onSocket:willDisconnectWithError: method, send
-readDataWithTimeout:tag: to the socket one last time.
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:
Send -readDataToLength:withTimeout:tag: to the socket.
Wait for the delegate object’s -onSocket:didReadData:withTag:
method to be called.
Error Handling
&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.&
&Before disconnecting the local socket, an
AsyncSocket instance will send -onSocket:willDisconnectWithError:
to its delegate object. The second argument of this message is an
NSError object. This object may contain a POSIX, Mac OS, or
CFStream error code, as indicated by the object’s -domain method.
It may also contain an AsyncSocket-specific error code. See
“Errors” below for details.&
&During the execution of its
-onSocket:willDisconnectWithError: method, the delegate object may
retrieve all unreceived data (including data from any
partially-completed read operations) by sending -unreadData to the
&After the delegate object’s
-onSocket:willDisconnectWithError: method returns, the socket will
be disconnected. It will then send -onSocketDidDisconnect: to the
delegate.&
Threading and Run-Loops
An AsyncSocket instance must be used in conjunction with a
run-loop. Its run-loop activity occurs in the NSDefaultRunLoopMode
An AsyncSocket 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.
To create a connect or listen socket in a particular thread,
simply create the socket in the context of that thread.
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
-onSocket:wantsRunLoopForNewSocket: delegate method.
Customizing AsyncSocket
AsyncSocket is not intended to be sub-classed. However, since
AsyncSocket 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.
AsyncSocket uses CFSocket, CFReadStream, and CFWriteStream
internally. You may access these directly and set whatever
properties or behaviors you may need. The -onSocketWillConnect:
delegate method is designed to facilitate this.
AsyncSocket Reference
See “API Index” below for an alphabetical list of messages,
methods, types, and constants.
Initialization and Deallocation Messages
AsyncSocket does not provide an auto-released convenience
initializer.
-init -initWithDelegate: -initWithDelegate:userData:
This message initializes the receiver, without setting a
Return Value
An instance of AsyncSocket.
-initWithDelegate:
This message initializes the receiver, setting the delegate at
the same time.
-(id)initWithDelegate:(id)delegate
An object that will act as the delegate for the receiver. The
delegate should implement the necessary AsyncSocketDelegate
May be nil.
Return Value
An instance of AsyncSocket.
-initWithDelegate:userData:
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.
-(id)initWithDelegate:(id)delegate
userData:(long)userData
An object that will act as the delegate for the receiver. The
delegate should implement the necessary AsyncSocketDelegate
May be nil.
A value that will be associated with the receiver. It may be
retrieved later through a -userData: message.
Return Value
An instance of AsyncSocket.
This message will deallocate the receiver, disconnecting if
necessary.
Syntax -(void)dealloc
Return Value
User Data Messages
-userData -setUserData:
This message returns the receiver’s current user data, an
arbitary value associated with the receiver.
-(long)userData
Return Value
The current user data.
-setUserData:
This message sets the receiver’s user data, an arbitary value
associated with the receiver.
-(void)setUserData:(long)userData
A value that will be associated with the receiver.
Return Value
Delegation Messages
-delegate -setDelegate: -canSafelySetDelegate
This message returns the receiver’s current delegate
-(id)delegate
Return Value
The current delegate object, or nil.
-setDelegate:
This message sets the receiver’s delegate object. The delegate
object is not retained.
-(void)setDelegate:(id)delegate
An instance of a class that will act as the delegate for the
receiver. Should implement the necessary AsyncSocketDelegate
May be nil.
Return Value
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 -canSafelySetDelegate:.
-canSafelySetDelegate
This message can be sent to determine whether a new delegate
object needs to be made aware of pending read or write
operations.
-(BOOL)canSafelySetDelegate
Return Value
YES, if the receiver has any pending read or write
operations.
NO, if the receiver has no pending read or write
operations.
Connection Messages
-connectToHost:onPort:error: -acceptOnPort:error:
-acceptOnAddress:port:error: -isConnected -disconnect
-disconnectAfterWriting -connectedHost -connectedPort -localHost
-localPort
-connectToHost:onPort:error:
This message establishes an outgoing connection from the
-(BOOL)connectToHost:(NSString *)hostname onPort:(UInt16)port
error:(NSError **)err
A DNS name or IP address to which the receiver should connect.
Both IPv4 and IPv6 addresses are supported.
A port number to which the receiver should connect.
The address of an NSError object pointer. In the event of an
error, the pointer will be set to the NSError object describing the
The sender may pass nil if it does not wish to retrieve any
NSError object.
Return Value
Returns YES if the connection is successful.
This does not indicate that the socket is ready for use. The
socket is only ready when the -onSocket:didConnectToHost:port:
delegate method is called.
Returns NO and an NSError object under the following
conditions:
hostname is not a valid address, or there is no such
The socket cannot be created, or cannot connect to the
Returns YES and calls -onSocket:willDisconnectWithError: under
the following conditions:
The read and write streams could not be attached or
Raises an AsyncSocketException if the socket is already
connected or accepting connections, or if no delegate has been
If the receiver returns YES, 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.
Read and write operations may be queued before the connection
is successfully established. They will be executed after the
connection is complete.
-acceptOnPort:error:
This message establishes the receiver as a listen socket that
will accept incoming connections.
-(BOOL)acceptOnPort:(UInt16)port error:(NSError **)err
A port number at which the receiver should accept
connections.
The address of an NSError object pointer. In the event of an
error, the pointer will be set to the NSError object describing the
The sender may pass nil if it does not wish to retrieve any
NSError object.
Return Value
Returns YES if the receiver is successfully accepting
connections at the specified port.
Returns NO and an NSError object if the socket cannot be
created, or cannot accept connections on the specified port.
Raises an AsyncSocketException if the socket is already
connected or accepting connections, or if no delegate has been
The receiver establishes a listen socket with the SO_REUSEADDR
option set.
In the event of a connection from a remote socket, the
receiver will create a new AsyncSocket instance. The new instance
will have the same delegate object as the receiver, and will
attempt to complete the connection to the remote socket.
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.
If successful, the receiver will send
-onSocket:didAcceptNewSocket: and
-onSocket:wantsRunLoopForNewSocket: 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 -onSocket:didConnectToHost:port: to its
delegate object.
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.
If unsuccessful for some other reason, the receiver will send
-onSocket:didAcceptNewSocket: and
-onSocket:wantsRunLoopForNewSocket: to its delegate object. After
the delegate method returns, the new instance will send
-onSocket:willDisconnectWithError: to its delegate with details
about the failure condition.
-acceptOnAddress:port:error:
This message establishes the receiver as a listen socket that
will accept incoming connections on a particular host address and
-(BOOL)acceptOnAddress:(NSString *)hostaddr port:(UInt16)port
error:(NSError **)err
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.”
If nil or an empty string, the effect is the same as
-acceptOnPort:error: message.&
A port number at which the receiver should accept
connections.
The address of an NSError object pointer. In the event of an
error, the pointer will be set to the NSError object describing the
The sender may pass nil if it does not wish to retrieve any
NSError object.
Return Value
Returns YES if the receiver is successfully accepting
connections at the specified port.
Returns NO and an NSError object if the socket cannot be
created, or cannot accept connections on the specified address or
Raises an AsyncSocketException if the socket is already
connected or accepting connections, or if no delegate has been
See -acceptOnPort:error: for more information.
-isConnected
This message may be sent to determine whether the receiver is
connected and capable of reading and writing.
-(BOOL)isConnected
Return Value
YES, if the receiver is connected and able to send and receive
NO, if the receiver is not connected, accepting connections,
or not able to send and receive data.
If the input or output streams have reached EOF, the receiver
returns NO. If the input or output streams are open, but in some
other error state, the receiver returns YES.
If the receiver is accepting incoming connections, it always
returns NO.
-disconnect
This message immediately disconnects the receiver.
-(void)disconnect
Return Value
If the receiver was accepting incoming connections, it will no
stop doing so. Any pending read or write operations are
After this method returns, the client application may send a
-connectToHost:onPort:error:, -acceptOnPort:error:, or
-acceptOnAddress:port:error: messages again.
-disconnectAfterWriting
This message will disconnect the receiver after all pending
write operations are completed. Pending read operations will not
prevent the receiver from disconnecting.
-(void)disconnectAfterWriting
Return Value
While the pending write operations are completing, the
receiver will ignore any further read or write messages. Other
messages may be sent as usual.
-connectedHost
This message returns the IP address of the connected remote
socket as a string.
-(NSString *)connectedHost
Return Value
If the receiver is connected, an IP address.
If the receiver is not connected, nil.
-connectedPort
This message returns the port number of the connected remote
-(UInt16)connectedPort
Return Value
If the receiver is connected, a port number.
If the receiver is not connected, 0.
-localHost
This method returns the local IP address of the receiver as a
-(NSString *)localHost
Return Value
If the receiver is connected, an IP address.
If the receiver is not connected, nil.
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
-localPort
This method returns the port number of the receiver.
-(UInt16)localPort
Return Value
If the receiver is connected, a port number.
If the receiver is not connected, 0.
If the computer is behind a NAT, the returned port number will
be a LAN address, not accurate outside the LAN.
Read and Write Messages
-readDataToLength:withTimeout:tag:
-readDataToData:withTimeout:tag: -readDataWithTimeout:tag:
-writeData:withTimeout:tag:
-progressOfReadReturningTag:bytesDone:total:
-progressOfWriteReturningTag:bytesDone:total:
-readDataToLength:withTimeout:tag:
This message queues a read operation. The receiver will read a
certain number of bytes from the socket.
-(void)readDataToLength:(CFIndex)length
withTimeout:(NSTimeInterval)timeout tag:(long)tag
Number of bytes that the receiver should read.
If 0, the receiver does nothing, and does not send
-onSocket:didReadData:withTag: to its delegate.
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.
If negative, the read operation will not time out.
An application-defined integer or pointer that will be sent as
an argument to the -onSocket:didReadData:withTag: message sent to
the delegate.
Return Value
The receiver will send -onSocket:didReadData:withTag: to the
delegate object when the read operation has completed. The received
data will be passed as an argument of that message.
The receiver will send -onSocket:willDisconnectWithError: to
the delegate object under the following conditions:
The read operation times out.
The receiver is disconnected from the remote socket.
Some other i/o error occurs.
The -onSocket:willDisconnectWithError: method may retrieve
partially received data by sending -readDataWithTimeout:tag: to the
When the bytes have been successfully received, the receiver
will send -onSocket:didReadData:withTag: to its delegate
The read operation will be performed immediately if possible.
If so, the receiver will send the message before returning from
this method.
-readDataToData:withTimeout:tag:
This message queues a read operation. The receiver will read
bytes until (and including) a sequence of bytes passed in the data
argument. That sequence acts as a separator or delimiter.
-(void)readDataToData:(NSData *)data
withTimeout:(NSTimeInterval)timeout tag:(long)tag
A sequence of bytes that mark the end of the read
operation.
If nil or empty, the receiver does nothing, and does not send
-onSocket:didReadData:withTag: to its delegate.
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.
If negative, the read operation will not time out.
An application-defined integer or pointer that will be sent as
an argument to the -onSocket:didReadData:withTag: message sent to
the delegate.
Return Value
The receiver will send -onSocket:didReadData:withTag: to the
delegate object when the read operation has completed. The received
data will be passed as an argument of that message. It will include
the delimiter.
The receiver will send -onSocket:willDisconnectWithError: to
the delegate object under the following conditions:
The read operation times out.
The receiver is disconnected from the remote socket.
Some other i/o error occurs.
The -onSocket:willDisconnectWithError: method may retrieve
partially received data by sending -readDataWithTimeout:tag: to the
When the bytes have been successfully received, the receiver
will send -onSocket:didReadData:withTag: to its delegate object,
passing all the received bytes as a parameter, including the
delimiting sequence.
The read operation will be performed immediately if possible.
If so, the receiver will send the message before returning from
this method.
Note that this method is not character-set aware. If a
character should happen to be encoded to a sequence of bytes that
matches the delimiting sequence, the read operation can prematurely
-readDataWithTimeout:tag:
This message queues a read operation. The receiver will
retrieve the first available bytes.
-(void)readDataWithTimeout:(NSTimeInterval)timeout
tag:(long)tag
&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
If negative, the read operation will not time out.
An application-defined integer or pointer that will be sent as
an argument to the -onSocket:didReadData:withTag: message sent to
the delegate.
Return Value
&The receiver will send
-onSocket:didReadData:withTag: to its delegate object when the read
operation has completed. The received data, if any, will be passed
as an argument.&
An error will occur under these conditions:
The read operation times out.
The receiver is disconnected from the remote socket.
Some other i/o error occurs.
&When the bytes have been successfully
retrieved, the receiver will then send
-onSocket:didReadData:withTag: to its delegate object, passing all
the received bytes as an argument.&
-writeData:withTimeout:tag:
This message queues a write operation. The receiver will write
an NSData object to the socket.
-(void)writeData:(NSData *)data
withTimeout:(NSTimeInterval)timeout tag:(long)tag
The data that should be written to the remote socket.
If nil, the receiver does nothing, and does not send
-onSocket:didWriteDataWithTag: to its delegate.
The number of seconds from the start of the write operation in
which the operation must complete. If the operation takes longer
than this interval, the operation times out.
If negative, the write operation will not time out.
An application-defined integer or pointer that will be sent as
an argument to the -onSocket:didWriteDataWithTag: message sent to
the delegate.
Return Value
None. The receiver will send -onSocket:didWriteDataWithTag: to
the delegate object when the write operation has
completed.&
The receiver will send -onSocket:willDisconnectWithError: to
the delegate object under the following conditions:
The write operation times out.
The receiver is disconnected from the remote socket.
Some other i/o error occurs.
When the bytes have been successfully sent, the receiver will
send -onSocket:didWriteData:withTag: to its delegate object.
The write operation will be performed immediately if possible.
If so, the receiver will send the message before returning from
this method.
-progressOfReadReturningTag:bytesDone:total:
This message can be sent to determine the progress of the
current read operation.
-(float)progressOfReadReturningTag:(long *)tag
bytesDone:(CFIndex *)done total:(CFIndex *)total
The address of a variable. When this method returns, the
variable will contain the tag of the current read operation. If
there is no current read operation, the variable will not be
The sender may pass NULL if it does not wish to retrieve the
The address of a variable. When this method returns, the
variable will contain the number of bytes that the current read
operation has read. If there is no current read operation, the
variable will not be changed.
The sender may pass NULL if it does not wish to retrieve the
number of bytes read.
The address of a variable. When this method returns, the
variable will contain the total number of bytes that the current
read operation expects to read. This value is only meaningful if
the current read operation is a “read-to-length” operation. If
there is no current read operation, the variable will not be
The sender may pass NULL if it does not wish to retrieve the
total number of bytes being read.
Return Value
A decimal value.
NaN indicates that there is no read operation currently being
executed. Use the isnan() function to test for this return
0.0 indicates that no bytes have been read of the total.
1.0 indicates that all bytes have been read of the total, or
the total number of bytes that must be read is not known.
-progressOfWriteReturningTag:bytesDone:total:
This message can be sent to determine the progress of the
current write operation.
-(float)progressOfWriteReturningTag(long *)tag
bytesDone:(CFIndex *)done total:(CFIndex *)total
The address of a variable. When this method returns, the
variable will contain the tag of the current read operation. If
there is no current read operation, the variable will not be
The sender may pass NULL if it does not wish to retrieve the
The address of a variable. When this method returns, the
variable will contain the number of bytes that have been sent. If
there is no current read operation, the variable will not be
The sender may pass NULL if it does not wish to retrieve the
number of bytes sent.
The address of a variable. When this method returns, the
variable will contain the total number of bytes that the current
write operation is sending. If there is no current read operation,
the variable will not be changed.
The sender may pass NULL if it does not wish to retrieve the
total number of bytes being sent.
Return Value
A decimal value.
NaN indicates that there is no write operation currently being
executed. Use the isnan() function to test for this return
0.0 indicates that no bytes have been sent of the total.
1.0 indicates that all bytes have been sent of the
Delimiter Messages
The results of these messages are commonly-used delimiters
that can be passed as the data argument of a
-readDataToData:withTimeout:tag: message.
+CRLFData +CRData +LFData +ZeroData
This method returns the CRLF byte sequence, the line separator
for DOS and Windows.
+(NSData *)CRLFData
Return Value
An instance of NSData containing the bytes 0D0A.
This method returns the CR byte sequence, the line separator
for Macintosh operating systems before Mac OS X.
+(NSData *)CRData
Return Value
An instance of NSData containing the byte 0D.
This method returns the LF byte sequence, the line separator
for most Unix operating systems and Mac OS X.
+(NSData *)LFData
Return Value
An instance of NSData containing the byte 0A.
This method returns a zero byte, the delimiter for C
+(NSData *)ZeroData
Return Value
An instance of NSData containing the byte 00.
Debugging and Customization Messages
-description -getCFSocket -getCFReadStream
-getCFWriteStream
-description
This message returns a description of the receiver suitable
for debugging purposes.
-(NSString *)description
Return Value
An string describing the receiver and its status.
The returned description does not have any newline characters
and includes:
the receiver’s id/address and hash values.
a CFSocket reference number.
the local and remote socket addresses.
the number of queued read and write operations.
progress of current read and write operations.
CFReadStream and CFWriteStream reference numbers.
the status of the read and write streams.
the connection status.
-getCFSocket
This message returns the internal CFSocket instance being
using by the receiver, enabling access to the underlying Unix
-(CFSocketRef)getCFSocket
Return Value
The receiver’s CFSocket reference number, or NULL if not
connected or accepting connections.
Do not close, read from, or write to the underlying
-getCFReadStream
This method returns the internal CFReadStream instance being
using by the receiver, enabling access to the underlying Carbon
-(CFReadStreamRef)getCFReadStream
Return Value
The receiver’s CFReadStream reference number, or NULL if not
connected or accepting connections.
Do not close, read from, or write to the underlying
-getCFWriteStream
This method returns the internal CFWriteStream instance being
used by the receiver, enabling access to the underlying Carbon
-(CFWriteStreamRef)getCFWriteStream
Return Value
The receiver’s CFWriteStream reference number, or NULL if not
connected or accepting connections.
Do not close, read from, or write to the underlying
AsyncSocketDelegate Methods
Delegate objects may implement these methods to respond to
AsyncSocket messages.
-onSocket:willDisconnectWithError: -onSocketDidDisconnect:
-onSocket:didAcceptNewSocket: -onSocket:wantsRunLoopForNewSocket:
-onSocketWillConnect: -onSocket:didConnectToHost:port:
-onSocket:didReadData:withTag: -onSocket:didWriteDataWithTag:
-onSocket:willDisconnectWithError:
In the event of an error, the socket is disconnected. The
socket sends this message before disconnection.
-(void)onSocket:(AsyncSocket *)sock
willDisconnectWithError:(NSError *)err
The sending AsyncSocket instance.
The error causing the socket to disconnect.
If nil, then there is no error. This typically means the
socket was cleanly closed by the remote client application.
This message is sent:
if there is an connection, time out, or other i/o error.
if the remote socket cleanly disconnects.
before the local socket is disconnected.
This message is primarily intended to give the receiver a
chance to retrieve any remaining buffered data from the connection.
The receiver may do this by sending -readDataWithTimeout:tag: to
the sender.
-onSocketDidDisconnect:
The socket sends this message is called after it has
disconnected.
-(void)onSocketDidDisconnect:(AsyncSocket *)sock
The sending AsyncSocket instance.
This message is sent after the sender disconnects for any
The receiver may safely release the sender in this
-onSocket:didAcceptNewSocket:
The socket sends this message to provide the receiver with a
chance to save a new socket in an appropriate place.
-(void)onSocket:(AsyncSocket *)sock
didAcceptNewSocket:(AsyncSocket *)newSocket
The sending AsyncSocket instance. This instance will be
accepting connections.
A new instance of AsyncSocket.
This method is sent after the sender accepts an incoming
connection and creates a new instance of AsyncSocket to handle
When this message is sent, newSocket is not fully connected to
the remote socket.
The receiver should assign and retain newSocket, and may also
set a more appropriate delegate.
-onSocket:wantsRunLoopForNewSocket:
The socket sends this message to determine which thread and
run-loop the new socket and its delegate’s methods should operate
on. Defaults to the current run-loop.
-(NSRunLoop *)onSocket:(AsyncSocket *)sock
wantsRunLoopForNewSocket:(AsyncSocket *)newSocket
The sending AsyncSocket instance. This instance will be
accepting connections.
An instance of AsyncSocket.
Return Value
The instance of NSRunLoop associated with a target
This method is sent after the sender accepts an incoming
connection and sends the -onSocket:didAcceptNewSocket:
When this message is sent, newSocket is not fully connected to
the remote socket.
The receiver should return the instance of NSRunLoop
associated with a target thread. All delegate messages from
newSocket will be sent in the context of that thread to that
run-loop, all timers will run on that run-loop, and all processing
will occur on that thread.
If the receiver does not implement this method, the sender
will use the current thread and run-loop.
-onSocketWillConnect:
The socket sends this message when it is about to connect to a
remote socket.
-(BOOL)onSocketWillConnect:(AsyncSocket *)sock
The sender.
Return Value
YES if the socket should continue to connect to the remote
socket. This is the default if this method is not implemented by
the receiver.
NO to cancel the connection.
This message is sent before the sender attempts to connect
the remote socket specified by a -connectToHost:onPort:error:
the remote socket that initiated a connection to the port
specified by an -acceptOnPort:error:
the remote socket that initiated a connection to the address
and port specified by an -acceptOnAddress:port:error:
This message is primarily intended to give the receiver a
chance to configure properties of the internal CFReadStream or
CFWriteStream instances. The receiver should return YES or NO,
indicating whether the sender should continue connecting.
If the receiver returns NO and the connection attempt was
initiated by -connectToHost:onPort:error:, that method will return
NO to its sender, along with an AsyncSocketCanceledError error
If the receiver returns NO and the connection attempt was
initiated by a remote socket, no error will be reported.
-onSocket:didConnectToHost:port:
The socket sends this message when it is connected and ready
for reading or writing.
-(void)onSocket:(AsyncSocket *)sock didConnectToHost:(NSString
*)host port:(UInt16)port
The sender.
The remote socket’s IPv4 or IPv6 address.
This may differ from the IP address or DNS name sent to the
sender as the hostname argument of
-connectToHost:onPort:error:.
The remote socket’s port.
This message is sent after the sender has successfully
connected to:
the remote socket specified by a -connectToHost:onPort:error:
the remote socket that initiated a connection to the port
specified by an -acceptOnPort:error:
the remote socket that initiated a connection to the address
and port specified by an -acceptOnAddress:port:error:
The receiver may choose to disconnect the sender, or to queue
a read or write operation.
The socket will perform any previously-queued read or write
operations after the receiver returns from this method.
-onSocket:didReadData:withTag:
The sender sends this message when it successfully completes a
read operation. It may send this message before the invoked read
method returns, or later.
-(void)onSocket:(AsyncSocket *)sock didReadData:(NSData*)data
withTag:(long)tag
The sender.
The received data.
The tag argument passed in the read message.
This message is sent after the sender has successfully
received the requested data.
If a read operation is unsuccessful, the sender will send a
-onSocket:willDisconnectWithError: message instead.
The receiver should process the data and queue a read or write
operation or disconnect as needed.
-onSocket:didWriteDataWithTag:
The sender sends this message when a write operation has
successfully completed. It may send this message before the invoked
write method returns, or later.
-(void)onSocket:(AsyncSocket *)sock
didWriteDataWithTag:(long)tag
The sender.
The tag argument passed in the write message.
This message is sent after the sender has successfully sent
the provided data.
If a write operation is unsuccessful, the sender will send a
-onSocket:willDisconnectWithError: message instead.
The receiver should queue a read or write operation or
disconnect as needed.
AsyncSocketException
An instance of AsyncSocket raises this exception when it
receives an -acceptOnPort:error:, -acceptOnAddress:port:error:, or
-connectToHost:onPort:error: message, and:
it is already connected or accepting connections.
it has not been assigned a delegate.
AsyncSocketErrorDomain
This NSError domain includes the following AsyncSocketError
AsyncSocketCanceledError indicates that a socket’s
-onSocketWillConnect: delegate method has returned NO. It is
returned from a -connectToHost:onPort:error: message.
AsyncSocketCFSocketError indicates an error in a CFSocket
operation. Such an error can occur while accepting incoming
connections or establishing outgoing connections, and can be caused
by an illegal port number or an internal error. It is generally
returned from a -acceptOnPort:error:, -acceptOnAddress:port:error:,
or -connectToHost:onPort:error: messages.
AsyncSocketReadTimeoutError indicates that a read operation
has timed out. It is passed to a socket’s delegate in a
-onSocket:willDisconnectWithError: message.
AsyncSocketWriteTimeoutError indicates that a write operation
has timed out. It is passed to a socket’s delegate in a
-onSocket:willDisconnectWithError: message.
AsyncSocketNoError, indicating no error, is never used. It is
defined for completeness’ sake.
You may provide localized error messages for these codes in an
AsyncSocket.strings strings file in the main bundle, using as keys
“AsyncSocketNoError,” etc. Default English strings are
API Changes
Changes since AsyncSocket 4.2:
Per-socket user data has been added.
-readDataWithTag: has been replaced by
-readDataWithTimeout:tag:. This method will not return empty data
via the -onSocket:didReadData:withTag: delegate method, but will
instead hold off until data arrives. The new method can still be
used to recover unread data from within
-onSocket:willDisconnectWithError:.
Changes since AsyncSocket 4.0:
Two methods have been added to allow you to monitor the
current read and write operation.
A new method allows the socket to only accept connections on
one address.
A new delegate method has been added to allow the underlying
streams and CFSocket to be customized.
An error code has been added to support that method.
Changes since AsyncSocket 3.13:
AsyncSocket now requires Mac OS X 10.4 or later.
-acceptOnPort: and -connectToHost:onPort: now take an extra
error parameter. This may be set to nil if you are not interested
in this feature.
-acceptOnPort: and -connectToHost:onPort: also raise an
exception if used while the socket is already connected or
accepting connections, instead of returning NO.
The error argument of -onSocket:willDisconnectWithError: is
now an NSError object instead of a CFStreamError object.
A new delegate method has been added to handle the threading
of incoming connections.
+addressFromString: has been removed. Use CFHost or NSHost
It is now possible to distinguish disconnections caused by a
read timeout from those caused by a write timeout.
You must add /System/Library/Frameworks/CoreServices.framework
this is necessary to convert certain CFStreamError
domains to NSError domains.
-acceptOnAddress:port:error:
-acceptOnPort:error:
AsyncSocketCanceledError
AsyncSocketCFSocketError
AsyncSocketError
AsyncSocketErrorDomain
AsyncSocketException
AsyncSocketNoError
AsyncSocketReadTimeoutError
AsyncSocketWriteTimeoutError
-canSafelySetDelegate
-connectedHost
-connectedPort
-connectToHost:onPort:error:
-description
-disconnect
-disconnectAfterWriting
-getCFReadStream
-getCFSocket
-getCFWriteStream
-initWithDelegate:
-initWithDelegate:userData:
-isConnected
-localHost
-localPort
-onSocket:didAcceptNewSocket:
-onSocket:didConnectToHost:port:
-onSocketDidDisconnect:
-onSocket:didReadData:withTag:
-onSocket:didWriteDataWithTag:
-onSocket:wantsRunLoopForNewSocket:
-onSocketWillConnect:
-onSocket:willDisconnectWithError:
-progressOfReadReturningTag:bytesDone:total:
-progressOfWriteReturningTag:bytesDone:total:
-readDataToData:withTimeout:tag:
-readDataToLength:withTimeout:tag:
-readDataWithTimeout:tag:
-setDelegate:
-setUserData:
-writeData:withTimeout:tag:
已投稿到：
以上网友发言只代表其个人观点，不代表新浪网的观点或立场。