Communicate Using a Socket with JavaScript

When communicating using protocols other than those directly supported by Adobe AIR, you may need to use the Socket API. The Socket API is an asynchronous API that lets you send data to a persistent socket endpoint and receive data from it in real time. You do not need to create a new Socket instance for each set of data sent to the same endpoint. The connection can be kept alive for the entire conversation between your client and the service to which you're connecting. This is the typical flow when using the Socket API:

1. Create a connection to the endpoint.
2. Listen for notification of connection success or failure.
3. Queue data that will be sent to the endpoint.
4. Send the data to the endpoint.
5. Listen for data incoming from the endpoint.
6. Repeat steps 3 through 5.
7. Close the connection.

The first step is to create a connection to the socket endpoint that consists of a host and a port number. For example, to connect to an endpoint the host might be foo.com (http://foo.com) and the port number might be 5555. Create the instance of the Socket class and connect to the endpoint using that information. At this time, we will also set up our listeners to listen for the different events that the Socket can dispatch:

var socket = new air.Socket();
socket.addEventListener( air.Event.CONNECT, onSocketOpen ); 
socket.addEventListener( air.ProgressEvent.SOCKET_DATA, onSocketData ); 
socket.connect( 'foo.com', 5555 );

We will also need to create the functions to handle the events for which we subscribed. The first event is the air.Event.CONNECT event. This event will tell us when the socket has been initiated and when communication with the service behind the endpoint is possible. In this example, we are sending the bytes of a UTF-8 encoded string to the service:

function onSocketOpen( event )
{
    // This queues up the binary representation of the
    // string 'Bob' in UTF-8 format to be sent to the
    // endpoint. socket.writeUTFBytes( "Bob" );
    
    // Send the actual bytes to the server and clear
    // the stream. We then wait for data to be sent
    // back to us.
    
    socket.flush();
}

The air.ProgressEvent.SOCKET_DATA event is dispatched whenever data is received. The service we are connecting to uses a simple protocol: we send a UTF8 encoded string and it returns a UTF8 encoded string. This makes accessing the data sent back to us very simple. To access this data, we measure the total number of bytes of data available on the Socket and read that many bytes as a UTF-8 encoded string using the readUTFBytes() method of the Socket class.

function onSocketData( event )
{
    var data = socket.readUTFBytes(socket.bytesAvailable);
    air.trace( data ); // Hello Bob
}

In our example, the protocol of communication was just a single string. In some cases, depending on the service with which you're communicating, you may need to send and receive other data types. The Socket class provides methods for reading and writing many data types, such as ints, Booleans, floats, and more. For example, if we were talking with a fictional service that required us to send a Boolean followed by an int, our onSocketOpen function in the preceding example could look like this:

function onSocketOpen( event )
{
    // First send the boolean
    socket.writeBoolean( true );

    // Now send an int
    socket.writeInt( 10 );

    // Now we send the bytes to the service and
    // clear the buffer.
    socket.flush();
}

This example provides a baseline of functionality that can be expanded upon to speak to many different protocols. The only current limitation is that there is not currently an SSL Socket implementation in AIR. For secure communication with a server you will be limited to HTTPS using the URLRequest API.

This cookbook example was originally posted in the Adobe AIR for JavaScript Developers Pocketguide, which can currently be found at toString.org.