Adobe ActionScript® 3 (AS3 ) API Reference (original) (raw)

The Socket class enables code to establish Transport Control Protocol (TCP) socket connections for sending and receiving binary data.

The Socket class is useful for working with servers that use binary protocols.

To use the methods of the Socket class, first use the constructor, new Socket, to create a Socket object.

A socket transmits and receives data asynchronously.

On some operating systems, flush() is called automatically between execution frames, but on other operating systems, such as Windows, the data is never sent unless you call flush() explicitly. To ensure your application behaves reliably across all operating systems, it is a good practice to call the flush() method after writing each message (or related group of data) to the socket.

In Adobe AIR, Socket objects are also created when a listening ServerSocket receives a connection from an external process. The Socket representing the connection is dispatched in a ServerSocketConnectEvent. Your application is responsible for maintaining a reference to this Socket object. If you don't, the Socket object is eligible for garbage collection and may be destroyed by the runtime without warning.

SWF content running in the local-with-filesystem security sandbox cannot use sockets.

Socket policy files on the target host specify the hosts from which SWF files can make socket connections, and the ports to which those connections can be made. The security requirements with regard to socket policy files have become more stringent in the last several releases of Flash Player. In all versions of Flash Player, Adobe recommends the use of a socket policy file; in some circumstances, a socket policy file is required. Therefore, if you are using Socket objects, make sure that the target host provides a socket policy file if necessary.

The following list summarizes the requirements for socket policy files in different versions of Flash Player:

• In Flash Player 9.0.124.0 and later, a socket policy file is required for any socket connection. That is, a socket policy file on the target host is required no matter what port you are connecting to, and is required even if you are connecting to a port on the same host that is serving the SWF file.
• In Flash Player versions 9.0.115.0 and earlier, if you want to connect to a port number below 1024, or if you want to connect to a host other than the one serving the SWF file, a socket policy file on the target host is required.
• In Flash Player 9.0.115.0, even if a socket policy file isn't required, a warning is displayed when using the Flash Debug Player if the target host doesn't serve a socket policy file.
• In AIR, a socket policy file is not required for content running in the application security sandbox. Socket policy files are required for any socket connection established by content running outside the AIR application security sandbox.

For more information related to security, see the Flash Player Developer Center Topic:Security

View the examples

bytesAvailable:[uint](../../uint.html) [read-only]

The number of bytes of data available for reading in the input buffer.

Your code must access bytesAvailable to ensure that sufficient data is available before trying to read it with one of the read methods.

Implementation
public function get bytesAvailable():[uint](../../uint.html)

bytesPending:[uint](../../uint.html) [read-only]

Indicates the number of bytes remaining in the write buffer.

Use this property in combination with with the OutputProgressEvent. An OutputProgressEvent is thrown whenever data is written from the write buffer to the network. In the event handler, you can check bytesPending to see how much data is still left in the buffer waiting to be written. When bytesPending returns 0, it means that all the data has been transferred from the write buffer to the network, and it is safe to do things like remove event handlers, null out socket references,start the next upload in a queue, etc.

Implementation
public function get bytesPending():[uint](../../uint.html)

Related API Elements

connected:[Boolean](../../Boolean.html) [read-only]

Indicates whether this Socket object is currently connected. A call to this property returns a value of true if the socket is currently connected, or false otherwise.

Implementation
public function get connected():[Boolean](../../Boolean.html)

endian:[String](../../String.html)

Indicates the byte order for the data. Possible values are constants from the flash.utils.Endian class,Endian.BIG_ENDIAN or Endian.LITTLE_ENDIAN.

The default value is Endian.BIG_ENDIAN.

Implementation
public function get endian():[String](../../String.html)
public function set endian(value:[String](../../String.html)):[void](../../specialTypes.html#void)

Related API Elements

localAddress:[String](../../String.html) [read-only]

The IP address this socket is bound to on the local machine.

Implementation
public function get localAddress():[String](../../String.html)

Related API Elements

localPort:[int](../../int.html) [read-only]

The port this socket is bound to on the local machine.

Implementation
public function get localPort():[int](../../int.html)

Related API Elements

objectEncoding:[uint](../../uint.html)

Controls the version of AMF used when writing or reading an object.

Implementation
public function get objectEncoding():[uint](../../uint.html)
public function set objectEncoding(value:[uint](../../uint.html)):[void](../../specialTypes.html#void)

Related API Elements

remoteAddress:[String](../../String.html) [read-only]

The IP address of the remote machine to which this socket is connected.

You can use this property to determine the IP address of a client socket dispatched in a ServerSocketConnectEvent by a ServerSocket object. Use the DNSResolver class to convert an IP address to a domain name, if desired.

Implementation
public function get remoteAddress():[String](../../String.html)

Related API Elements

remotePort:[int](../../int.html) [read-only]

The port on the remote machine to which this socket is connected.

You can use this property to determine the port number of a client socket dispatched in a ServerSocketConnectEvent by a ServerSocket object.

Implementation
public function get remotePort():[int](../../int.html)

Related API Elements

timeout:[uint](../../uint.html)

Indicates the number of milliseconds to wait for a connection.

If the connection doesn't succeed within the specified time, the connection fails. The default value is 20,000 (twenty seconds).

Implementation
public function get timeout():[uint](../../uint.html)
public function set timeout(value:[uint](../../uint.html)):[void](../../specialTypes.html#void)

public function Socket(host:[String](../../String.html) = null, port:[int](../../int.html) = 0)

Creates a new Socket object. If no parameters are specified, an initially disconnected socket is created. If parameters are specified, a connection is attempted to the specified host and port.

Note: It is strongly advised to use the constructor form without parameters, then add any event listeners, then call the connect method with host and port parameters. This sequence guarantees that all event listeners will work properly.

Parameters

Events

Throws

public function close():[void](../../specialTypes.html#void)

Closes the socket. You cannot read or write any data after the close() method has been called.

The close event is dispatched only when the server closes the connection; it is not dispatched when you call the close() method.

You can reuse the Socket object by calling the connect() method on it again.

Throws

public function connect(host:[String](../../String.html), port:[int](../../int.html)):[void](../../specialTypes.html#void)

Connects the socket to the specified host and port.

If the connection fails immediately, either an event is dispatched or an exception is thrown: an error event is dispatched if a host was specified, and an exception is thrown if no host was specified. Otherwise, the status of the connection is reported by an event. If the socket is already connected, the existing connection is closed first.

Parameters

Events

Throws

More examples

public function flush():[void](../../specialTypes.html#void)

Flushes any accumulated data in the socket's output buffer.

On some operating systems, flush() is called automatically between execution frames, but on other operating systems, such as Windows, the data is never sent unless you call flush() explicitly. To ensure your application behaves reliably across all operating systems, it is a good practice to call the flush() method after writing each message (or related group of data) to the socket.

Throws

public function readBoolean():[Boolean](../../Boolean.html)

Reads a Boolean value from the socket. After reading a single byte, the method returns true if the byte is nonzero, andfalse otherwise.

Returns

Throws

public function readByte():[int](../../int.html)

Reads a signed byte from the socket.

Returns

Throws

public function readBytes(bytes:[ByteArray](../../flash/utils/ByteArray.html), offset:[uint](../../uint.html) = 0, length:[uint](../../uint.html) = 0):[void](../../specialTypes.html#void)

Reads the number of data bytes specified by the length parameter from the socket. The bytes are read into the specified byte array, starting at the position indicated by offset.

Parameters

Throws

public function readDouble():[Number](../../Number.html)

Reads an IEEE 754 double-precision floating-point number from the socket.

Returns

Throws

public function readFloat():[Number](../../Number.html)

Reads an IEEE 754 single-precision floating-point number from the socket.

Returns

Throws

public function readInt():[int](../../int.html)

Reads a signed 32-bit integer from the socket.

Returns

Throws

public function readMultiByte(length:[uint](../../uint.html), charSet:[String](../../String.html)):[String](../../String.html)

Reads a multibyte string from the byte stream, using the specified character set.

Parameters

Returns

Throws

public function readObject():[*](../../specialTypes.html#%2A)

Reads an object from the socket, encoded in AMF serialized format.

Returns

Throws

Related API Elements

public function readShort():[int](../../int.html)

Reads a signed 16-bit integer from the socket.

Returns

Throws

public function readUnsignedByte():[uint](../../uint.html)

Reads an unsigned byte from the socket.

Returns

Throws

public function readUnsignedInt():[uint](../../uint.html)

Reads an unsigned 32-bit integer from the socket.

Returns

Throws

public function readUnsignedShort():[uint](../../uint.html)

Reads an unsigned 16-bit integer from the socket.

Returns

Throws

public function readUTF():[String](../../String.html)

Reads a UTF-8 string from the socket. The string is assumed to be prefixed with an unsigned short integer that indicates the length in bytes.

Returns

Throws

public function readUTFBytes(length:[uint](../../uint.html)):[String](../../String.html)

Reads the number of UTF-8 data bytes specified by the length parameter from the socket, and returns a string.

Parameters

Returns

Throws

public function writeBoolean(value:[Boolean](../../Boolean.html)):[void](../../specialTypes.html#void)

Writes a Boolean value to the socket. This method writes a single byte, with either a value of 1 (true) or 0 (false).

Parameters

Throws

Related API Elements

public function writeByte(value:[int](../../int.html)):[void](../../specialTypes.html#void)

Writes a byte to the socket.

Parameters

Throws

Related API Elements

public function writeBytes(bytes:[ByteArray](../../flash/utils/ByteArray.html), offset:[uint](../../uint.html) = 0, length:[uint](../../uint.html) = 0):[void](../../specialTypes.html#void)

Writes a sequence of bytes from the specified byte array. The write operation starts at the position specified by offset.

If you omit the length parameter the default length of 0 causes the method to write the entire buffer starting atoffset.

If you also omit the offset parameter, the entire buffer is written.

Parameters

Throws

Related API Elements

public function writeDouble(value:[Number](../../Number.html)):[void](../../specialTypes.html#void)

Writes an IEEE 754 double-precision floating-point number to the socket.

Parameters

Throws

Related API Elements

public function writeFloat(value:[Number](../../Number.html)):[void](../../specialTypes.html#void)

Writes an IEEE 754 single-precision floating-point number to the socket.

Parameters

Throws

Related API Elements

public function writeInt(value:[int](../../int.html)):[void](../../specialTypes.html#void)

Writes a 32-bit signed integer to the socket.

Parameters

Throws

Related API Elements

public function writeMultiByte(value:[String](../../String.html), charSet:[String](../../String.html)):[void](../../specialTypes.html#void)

Writes a multibyte string from the byte stream, using the specified character set.

Parameters

Related API Elements

public function writeObject(object:[*](../../specialTypes.html#%2A)):[void](../../specialTypes.html#void)

Write an object to the socket in AMF serialized format.

Parameters

Throws

Related API Elements

public function writeShort(value:[int](../../int.html)):[void](../../specialTypes.html#void)

Writes a 16-bit integer to the socket. The bytes written are as follows:

(v >> 8) & 0xff v & 0xff

The low 16 bits of the parameter are used; the high 16 bits are ignored.

Parameters

Throws

Related API Elements

public function writeUnsignedInt(value:[uint](../../uint.html)):[void](../../specialTypes.html#void)

Writes a 32-bit unsigned integer to the socket.

Parameters

Throws

Related API Elements

public function writeUTF(value:[String](../../String.html)):[void](../../specialTypes.html#void)

Writes the following data to the socket: a 16-bit unsigned integer, which indicates the length of the specified UTF-8 string in bytes, followed by the string itself.

Before writing the string, the method calculates the number of bytes that are needed to represent all characters of the string.

Parameters

Throws

Related API Elements

public function writeUTFBytes(value:[String](../../String.html)):[void](../../specialTypes.html#void)

Writes a UTF-8 string to the socket.

Parameters

Throws

Related API Elements

Event Object Type: flash.events.Event
property Event.type = flash.events.Event.CLOSE

Dispatched when the server closes the socket connection.

The close event is dispatched only when the server closes the connection; it is not dispatched when you call the Socket.close() method.

The Event.CLOSE constant defines the value of the type property of a close event object.

This event has the following properties:

Event Object Type: flash.events.Event
property Event.type = flash.events.Event.CONNECT

Dispatched when a network connection has been established.

The Event.CONNECT constant defines the value of the type property of a connect event object.

This event has the following properties:

Event Object Type: flash.events.IOErrorEvent
property IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR

Dispatched when an input/output error occurs that causes a send or load operation to fail.

Defines the value of the type property of an ioError event object.

This event has the following properties:

Event Object Type: flash.events.OutputProgressEvent

Dispatched when a socket moves data from its write buffer to the networking transport layer

Event Object Type: flash.events.SecurityErrorEvent
property SecurityErrorEvent.type = flash.events.SecurityErrorEvent.SECURITY_ERROR

Dispatched if a call to Socket.connect() attempts to connect to a server prohibited by the caller's security sandbox or to a port lower than 1024 and no socket policy file exists to permit such a connection.

Note: In an AIR application, content running in the application security sandbox is permitted to connect to any server and port number without a socket policy file.

The SecurityErrorEvent.SECURITY_ERROR constant defines the value of the type property of a securityError event object.

This event has the following properties:

Related API Elements

Event Object Type: flash.events.ProgressEvent
property ProgressEvent.type = flash.events.ProgressEvent.SOCKET_DATA

Dispatched when a socket has received data.

The data received by the socket remains in the socket until it is read. You do not have to read all the available data during the handler for this event.

Events of type socketData do not use the ProgressEvent.bytesTotal property.

Defines the value of the type property of a socketData event object.

This event has the following properties:

The following example reads from and writes to a socket and outputs information transmitted during socket events. Highlights of the example follow:

1. The constructor creates a CustomSocket instance named socket and passes the host name localhost and port 80 as arguments. Since CustomSocket extends Socket, a call to super() calls Socket's constructor.
2. The example then calls the configureListeners() method, which adds listeners for Socket events.
3. Finally, the socket connect() method is called with localhost as the host name and 80 as the port number.

Note: To run the example, you need a server running on the same domain where the SWF resides (in the example, localhost) and listening on port 80.

package { import flash.display.Sprite;

public class SocketExample extends Sprite {
    private var socket:CustomSocket;
    
    public function SocketExample() {
        socket = new CustomSocket("localhost", 80);
    }
}

}

import flash.errors.; import flash.events.; import flash.net.Socket;

class CustomSocket extends Socket { private var response:String;

public function CustomSocket(host:String = null, port:uint = 0) {
    super();
    configureListeners();
    if (host && port)  {
        super.connect(host, port);
    }
}

private function configureListeners():void {
    addEventListener(Event.CLOSE, closeHandler);
    addEventListener(Event.CONNECT, connectHandler);
    addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
    addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
    addEventListener(ProgressEvent.SOCKET_DATA, socketDataHandler);
}

private function writeln(str:String):void {
    str += "\n";
    try {
        writeUTFBytes(str);
    }
    catch(e:IOError) {
        trace(e);
    }
}

private function sendRequest():void {
    trace("sendRequest");
    response = "";
    writeln("GET /");
    flush();
}

private function readResponse():void {
    var str:String = readUTFBytes(bytesAvailable);
    response += str;
}

private function closeHandler(event:Event):void {
    trace("closeHandler: " + event);
    trace(response.toString());
}

private function connectHandler(event:Event):void {
    trace("connectHandler: " + event);
    sendRequest();
}

private function ioErrorHandler(event:IOErrorEvent):void {
    trace("ioErrorHandler: " + event);
}

private function securityErrorHandler(event:SecurityErrorEvent):void {
    trace("securityErrorHandler: " + event);
}

private function socketDataHandler(event:ProgressEvent):void {
    trace("socketDataHandler: " + event);
    readResponse();
}

}