AsyncSocket 4.3

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, written and maintained by Dustin Voss. For support, e-mail d.j.v.@mac.com.

Contents

  1. Introduction
  2. Socket Basics
  3. Using AsyncSocket
  4. AsyncSocket Reference
  5. API Changes
  6. API Index

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:

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 network connection; 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 “www.google.com” 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 “http://www.google.com: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 time.

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 protocol.

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:

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 it.

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.

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 server.

Each socket should be managed by a connection controller class. This class should be responsible for:

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):

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 delegate.

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 delegate.

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”).

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 total.

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:

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 -readDataWithTimeout:tag: to the socket. The socket will invoke the delegate object’s -onSocket:didReadData:withTag: method before returning from -readDataWithTimeout:tag:.

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 mode.

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: -dealloc

-init

This message initializes the receiver, without setting a delegate.

Syntax

-(id)init

Arguments

None.

Return Value

An instance of AsyncSocket.

Errors

None.

-initWithDelegate:

This message initializes the receiver, setting the delegate at the same time.

Syntax

-(id)initWithDelegate:(id)delegate

Arguments

delegate

An object that will act as the delegate for the receiver. The delegate should implement the necessary AsyncSocketDelegate methods.

May be nil.

Return Value

An instance of AsyncSocket.

Errors

None.

-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.

Syntax

-(id)initWithDelegate:(id)delegate userData:(long)userData

Arguments

delegate

An object that will act as the delegate for the receiver. The delegate should implement the necessary AsyncSocketDelegate methods.

May be nil.

userData

A value that will be associated with the receiver. It may be retrieved later through a -userData: message.

Return Value

An instance of AsyncSocket.

Errors

None.

-dealloc

This message will deallocate the receiver, disconnecting if necessary.

Syntax

-(void)dealloc

Arguments

None.

Return Value

None.

Errors

None.

User Data Messages

-userData -setUserData:

-userData

This message returns the receiver’s current user data, an arbitary value associated with the receiver.

Syntax

-(long)userData

Arguments

None.

Return Value

The current user data.

Errors

None.

-setUserData:

This message sets the receiver’s user data, an arbitary value associated with the receiver.

Syntax

-(void)setUserData:(long)userData

Arguments

userData

A value that will be associated with the receiver.

Return Value

None.

Errors

None.

Delegation Messages

-delegate -setDelegate: -canSafelySetDelegate

-delegate

This message returns the receiver’s current delegate object.

Syntax

-(id)delegate

Arguments

None.

Return Value

The current delegate object, or nil.

Errors

None.

-setDelegate:

This message sets the receiver’s delegate object. The delegate object is not retained.

Syntax

-(void)setDelegate:(id)delegate

Arguments

delegate

An instance of a class that will act as the delegate for the receiver. Should implement the necessary AsyncSocketDelegate methods.

May be nil.

Return Value

None.

Errors

None.

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.

Syntax

-(BOOL)canSafelySetDelegate

Arguments

None.

Return Value

YES, if the receiver has any pending read or write operations.

NO, if the receiver has no pending read or write operations.

Errors

None.

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 receiver.

Syntax

-(BOOL)connectToHost:(NSString *)hostname onPort:(UInt16)port error:(NSError **)err

Arguments

hostname

A DNS name or IP address to which the receiver should connect. Both IPv4 and IPv6 addresses are supported.

port

A port number to which the receiver should connect.

err

The address of an NSError object pointer. In the event of an error, the pointer will be set to the NSError object describing the error.

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.

Errors

Returns NO and an NSError object under the following conditions:

  • hostname is not a valid address, or there is no such address.
  • The socket cannot be created, or cannot connect to the address.

Returns YES and calls -onSocket:willDisconnectWithError: under the following conditions:

  • The read and write streams could not be attached or opened.

Raises an AsyncSocketException if the socket is already connected or accepting connections, or if no delegate has been set.

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.

Syntax

-(BOOL)acceptOnPort:(UInt16)port error:(NSError **)err

Arguments

port

A port number at which the receiver should accept connections.

err

The address of an NSError object pointer. In the event of an error, the pointer will be set to the NSError object describing the error.

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.

Errors

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 set.

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 port.

Syntax

-(BOOL)acceptOnAddress:(NSString *)hostaddr port:(UInt16)port error:(NSError **)err

Arguments

hostaddr

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.

port

A port number at which the receiver should accept connections.

err

The address of an NSError object pointer. In the event of an error, the pointer will be set to the NSError object describing the error.

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.

Errors

Returns NO and an NSError object if the socket cannot be created, or cannot accept connections on the specified address or port.

Raises an AsyncSocketException if the socket is already connected or accepting connections, or if no delegate has been set.

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.

Syntax

-(BOOL)isConnected

Arguments

None.

Return Value

YES, if the receiver is connected and able to send and receive data.

NO, if the receiver is not connected, accepting connections, or not able to send and receive data.

Errors

None.

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.

Syntax

-(void)disconnect

Arguments

None.

Return Value

None.

Errors

None.

If the receiver was accepting incoming connections, it will no stop doing so. Any pending read or write operations are dropped.

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.

Syntax

-(void)disconnectAfterWriting

Arguments

None.

Return Value

None.

Errors

None.

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.

Syntax

-(NSString *)connectedHost

Arguments

None.

Return Value

If the receiver is connected, an IP address.

If the receiver is not connected, nil.

Errors

None.

-connectedPort

This message returns the port number of the connected remote socket.

Syntax

-(UInt16)connectedPort

Arguments

None.

Return Value

If the receiver is connected, a port number.

If the receiver is not connected, 0.

Errors

None.

-localHost

This method returns the local IP address of the receiver as a string.

Syntax

-(NSString *)localHost

Arguments

None.

Return Value

If the receiver is connected, an IP address.

If the receiver is not connected, nil.

Errors

None.

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.

-localPort

This method returns the port number of the receiver.

Syntax

-(UInt16)localPort

Arguments

None.

Return Value

If the receiver is connected, a port number.

If the receiver is not connected, 0.

Errors

None.

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.

Syntax

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

Arguments

length

Number of bytes that the receiver should read.

If 0, the receiver does nothing, and does not send -onSocket:didReadData:withTag: to its delegate.

timeout

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.

tag

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.

Errors

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 socket.

When the bytes have been successfully received, the receiver will send -onSocket:didReadData:withTag: to its delegate object.

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.

Syntax

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

Arguments

data

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.

timeout

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.

tag

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.

Errors

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 socket.

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 end.

-readDataWithTimeout:tag:

This message queues a read operation. The receiver will retrieve the first available bytes.

Syntax

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

Arguments

timeout

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.

If this message is being sent from within the delegate’s -onSocket:willDisconnectWithError: method to recover unread data, this argument is irrelevant.

tag

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.

Errors

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.

The read operation will be performed immediately if possible. If so, the receiver will send the message before returning from this method.

The delegate object may send this message while responding to a -onSocket:willDisconnectWithError: message. This allows the delegate to retrieve partially-received and unreceived bytes.

-writeData:withTimeout:tag:

This message queues a write operation. The receiver will write an NSData object to the socket.

Syntax

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

Arguments

data

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.

timeout

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.

tag

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.

Errors

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.

Syntax

-(float)progressOfReadReturningTag:(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total

Arguments

tag

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 changed.

The sender may pass NULL if it does not wish to retrieve the tag.

done

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.

total

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 changed.

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 value.
  • 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.

Errors

None.

-progressOfWriteReturningTag:bytesDone:total:

This message can be sent to determine the progress of the current write operation.

Syntax

-(float)progressOfWriteReturningTag(long *)tag bytesDone:(CFIndex *)done total:(CFIndex *)total

Arguments

tag

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 changed.

The sender may pass NULL if it does not wish to retrieve the tag.

done

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 changed.

The sender may pass NULL if it does not wish to retrieve the number of bytes sent.

total

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 value.
  • 0.0 indicates that no bytes have been sent of the total.
  • 1.0 indicates that all bytes have been sent of the total.

Errors

None.

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

+CRLFData

This method returns the CRLF byte sequence, the line separator for DOS and Windows.

Syntax

+(NSData *)CRLFData

Arguments

None.

Return Value

An instance of NSData containing the bytes 0D0A.

Errors

None.

+CRData

This method returns the CR byte sequence, the line separator for Macintosh operating systems before Mac OS X.

Syntax

+(NSData *)CRData

Arguments

None.

Return Value

An instance of NSData containing the byte 0D.

Errors

None.

+LFData

This method returns the LF byte sequence, the line separator for most Unix operating systems and Mac OS X.

Syntax

+(NSData *)LFData

Arguments

None.

Return Value

An instance of NSData containing the byte 0A.

Errors

None.

+ZeroData

This method returns a zero byte, the delimiter for C strings.

Syntax

+(NSData *)ZeroData

Arguments

None.

Return Value

An instance of NSData containing the byte 00.

Errors

None.

Debugging and Customization Messages

-description -getCFSocket -getCFReadStream -getCFWriteStream

-description

This message returns a description of the receiver suitable for debugging purposes.

Syntax

-(NSString *)description

Arguments

None.

Return Value

An string describing the receiver and its status.

Errors

None.

The returned description does not have any newline characters and includes:

-getCFSocket

This message returns the internal CFSocket instance being using by the receiver, enabling access to the underlying Unix socket.

Syntax

-(CFSocketRef)getCFSocket

Arguments

None.

Return Value

The receiver’s CFSocket reference number, or NULL if not connected or accepting connections.

Errors

None.

Do not close, read from, or write to the underlying socket.

-getCFReadStream

This method returns the internal CFReadStream instance being using by the receiver, enabling access to the underlying Carbon stream.

Syntax

-(CFReadStreamRef)getCFReadStream

Arguments

None.

Return Value

The receiver’s CFReadStream reference number, or NULL if not connected or accepting connections.

Errors

None.

Do not close, read from, or write to the underlying stream.

-getCFWriteStream

This method returns the internal CFWriteStream instance being used by the receiver, enabling access to the underlying Carbon stream.

Syntax

-(CFWriteStreamRef)getCFWriteStream

Arguments

None.

Return Value

The receiver’s CFWriteStream reference number, or NULL if not connected or accepting connections.

Errors

None.

Do not close, read from, or write to the underlying stream.

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.

Prototype

-(void)onSocket:(AsyncSocket *)sock willDisconnectWithError:(NSError *)err

Arguments

sock

The sending AsyncSocket instance.

err

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.

Condition

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.

Prototype

-(void)onSocketDidDisconnect:(AsyncSocket *)sock

Arguments

sock

The sending AsyncSocket instance.

Condition

This message is sent after the sender disconnects for any reason.

The receiver may safely release the sender in this method.

-onSocket:didAcceptNewSocket:

The socket sends this message to provide the receiver with a chance to save a new socket in an appropriate place.

Prototype

-(void)onSocket:(AsyncSocket *)sock didAcceptNewSocket:(AsyncSocket *)newSocket

Arguments

sock

The sending AsyncSocket instance. This instance will be accepting connections.

newSocket

A new instance of AsyncSocket.

Condition

This method is sent after the sender accepts an incoming connection and creates a new instance of AsyncSocket to handle it.

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.

Prototype

-(NSRunLoop *)onSocket:(AsyncSocket *)sock wantsRunLoopForNewSocket:(AsyncSocket *)newSocket

Arguments

sock

The sending AsyncSocket instance. This instance will be accepting connections.

newSocket

An instance of AsyncSocket.

Return Value

The instance of NSRunLoop associated with a target thread.

Condition

This method is sent after the sender accepts an incoming connection and sends the -onSocket:didAcceptNewSocket: message.

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.

Prototype

-(BOOL)onSocketWillConnect:(AsyncSocket *)sock

Argument

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.

Condition

This message is sent before the sender attempts to connect to:

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 object.

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.

Prototype

-(void)onSocket:(AsyncSocket *)sock didConnectToHost:(NSString *)host port:(UInt16)port

Arguments

sock

The sender.

host

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:.

port

The remote socket’s port.

Condition

This message is sent after the sender has successfully connected to:

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.

Prototype

-(void)onSocket:(AsyncSocket *)sock didReadData:(NSData*)data withTag:(long)tag

Arguments

sock

The sender.

data

The received data.

tag

The tag argument passed in the read message.

Condition

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.

Prototype

-(void)onSocket:(AsyncSocket *)sock didWriteDataWithTag:(long)tag

Arguments

sock

The sender.

tag

The tag argument passed in the write message.

Condition

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.

Errors

AsyncSocketException

An instance of AsyncSocket raises this exception when it receives an -acceptOnPort:error:, -acceptOnAddress:port:error:, or -connectToHost:onPort:error: message, and:

AsyncSocketErrorDomain

This NSError domain includes the following AsyncSocketError codes:

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 provided.

API Changes

Changes since AsyncSocket 4.2:

Changes since AsyncSocket 4.0:

Changes since AsyncSocket 3.13:

API Index


Author: Dustin Voss