Recipe 24.2. Sending Data

Problem

You want to send data to a socket server.

Solution

For Socket objects, use the write methods (writeByte( ), writeUTFBytes( ), etc.) to write the data to the buffer and call flush( ) to send the data. For XMLSocket objects, use the send( ) method.

Discussion

The Socket and XMLSocket classes define different APIs for sending data to the socket server. Let's look at the Socket API first.

When you want to send data to a socket server using a Socket object, you first must write the data to the buffer. The Socket class defines a slew of methods for writing data. Each of the methods writes a different type of data (or writes the data differently). The methods are writeBoolean( ), writeByte( ), writeBytes( ), writeDouble( ), writeFloat( ), writeInt( ), writeMultiByte( ), writeObject( ), writeShort( ), write- UnsignedInt( ), writeUTF( ), and writeUTFBytes( ). Most of the methods accept one parameter of the type implied by the name of the method. For example, writeBoolean( ) accepts a Boolean parameter and writeByte( ), writeDouble( ), writeFloat( ), writeInt( ), writeShort( ), and writeUnsignedInt( ) accept numeric parameters. The writeObject( ) method accepts an object parameter that must be serializable to AMF format. The writeBytes( ) method allows you to pass it a ByteArray parameter along with offset and length parameters. For example, the following calls writeBytes( ) passing, it a reference to a ByteArray object and specifying that it should write all the bytes (starting at offset 0 with length equal to the length of the ByteArray):

socket.writeBytes(byteArray, 0, byteArray.length);

The writeUTF( ) and writeUTFBytes( ) methods allow you to write strings. Each method accepts a string parameter. The writeUTFBytes( ) method simply writes the string as bytes. The writeUTF( ) method first writes the number of bytes before writing the actual byte data.

The writeMultiByte( ) method also writes string data, but using a nondefault character set. The method requires two parameters: the string to write and the name of the character set to use. The help documentation for Flash and Flex list the supported character sets along with the labels and aliases for each. Use the label value as a string when specifying the character set for writeMultiByte( ). The following example writes a string example using Unicode:

socket.writeMultiByte("example", "unicode");

Which method or methods you use to write data to a Socket object is entirely dependent on what sort of data you want to write and what sort of data the server expects. Using a Socket object, you can write a Telnet or POP mail client entirely by using ActionScript. Both protocols expect ASCII text commands. For example, after connecting to a POP server, you can specify a user with the USER command. The following writes such a command to a Socket object:

// POP servers expect a newline (\n) to execute the preceding command.
socket.writeUTFBytes("USER exampleUsername\n");

Writing the data to the Socket object does not actually send the data to the socket server. Each call to a write method appends the data to the Socket object. For example, the following writes four bytes to a Socket object, but none of them are sent:

socket.writeByte(1);
socket.writeByte(5);
socket.writeByte(4);
socket.writeByte(8);

When you want to send the accumulated data to the socket server, use the flush( ) method. The flush( ) method simply sends all the written data and clears the buffer:

socket.flush(  );

The XMLSocket class has a much simpler API for sending data. Writing and sending data occur with one method aptly named send( ). The send( ) method accepts parameter of any datatype. It converts the parameter to a string and sends it to the server. Traditionally the parameter is an XML object or a string containing data structured as XML:

xmlSocket.send(xml);

However, the exact format of the data is entirely dependent on the format the server expects. If the server expects XML-formatted data, then you'll need to send XML-formatted data. If the server expects URL-encoded data, then you'll need to send URL-encoded data.