flash.net.Socket

	Property	Defined By
		bytesAvailable : uint [read-only] The number of bytes of data available for reading in the input buffer.	Socket
		connected : Boolean [read-only] Indicates whether this Socket object is currently connected.	Socket
		endian : String Indicates the byte order for the data; possible values are constants from the flash.utils.Endian class, Endian.BIG_ENDIAN or Endian.LITTLE_ENDIAN.	Socket
		objectEncoding : uint Controls the version of AMF used when writing or reading an object.	Socket
		timeout : uint Indicates the number of milliseconds to wait for a connection.	Socket

	Method	Defined By
		Socket(host:String = null, port:int = 0) Creates a new Socket object.	Socket
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.	EventDispatcher
		close():void Closes the socket.	Socket
		connect(host:String, port:int):void Connects the socket to the specified host and port.	Socket
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	EventDispatcher
		flush():void Flushes any accumulated data in the socket's output buffer.	Socket
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		readBoolean():Boolean Reads a Boolean value from the socket.	Socket
		readByte():int Reads a signed byte from the socket.	Socket
		readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void Reads the number of data bytes specified by the length parameter from the socket.	Socket
		readDouble():Number Reads an IEEE 754 double-precision floating-point number from the socket.	Socket
		readFloat():Number Reads an IEEE 754 single-precision floating-point number from the socket.	Socket
		readInt():int Reads a signed 32-bit integer from the socket.	Socket
		readMultiByte(length:uint, charSet:String):String Reads a multibyte string from the byte stream, using the specified character set.	Socket
		readObject():* Reads an object from the socket, encoded in AMF serialized format.	Socket
		readShort():int Reads a signed 16-bit integer from the socket.	Socket
		readUnsignedByte():uint Reads an unsigned byte from the socket.	Socket
		readUnsignedInt():uint Reads an unsigned 32-bit integer from the socket.	Socket
		readUnsignedShort():uint Reads an unsigned 16-bit integer from the socket.	Socket
		readUTF():String Reads a UTF-8 string from the socket.	Socket
		readUTFBytes(length:uint):String Reads the number of UTF-8 data bytes specified by the length parameter from the socket, and returns a string.	Socket
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.	EventDispatcher
		writeBoolean(value:Boolean):void Writes a Boolean value to the socket.	Socket
		writeByte(value:int):void Writes a byte to the socket.	Socket
		writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void Writes a sequence of bytes from the specified byte array.	Socket
		writeDouble(value:Number):void Writes an IEEE 754 double-precision floating-point number to the socket.	Socket
		writeFloat(value:Number):void Writes an IEEE 754 single-precision floating-point number to the socket.	Socket
		writeInt(value:int):void Writes a 32-bit signed integer to the socket.	Socket
		writeMultiByte(value:String, charSet:String):void Writes a multibyte string from the byte stream, using the specified character set.	Socket
		writeObject(object:*):void Write an object to the socket in AMF serialized format.	Socket
		writeShort(value:int):void Writes a 16-bit integer to the socket.	Socket
		writeUnsignedInt(value:uint):void Writes a 32-bit unsigned integer to the socket.	Socket
		writeUTF(value:String):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.	Socket
		writeUTFBytes(value:String):void Writes a UTF-8 string to the socket.	Socket

Summary	Defined By
activate	[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.	EventDispatcher
close	Dispatched when the server closes the socket connection.	Socket
connect	Dispatched when a network connection has been established.	Socket
deactivate	[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.	EventDispatcher
ioError	Dispatched when an input/output error occurs that causes a send or load operation to fail.	Socket
securityError	Dispatched if a call to Socket.connect() attempts to connect either to a server outside the caller's security sandbox or to a port lower than 1024.	Socket
socketData	Dispatched when a socket has received data.	Socket

Property Detail

bytesAvailable

property

bytesAvailable:uint [read-only]

Runtime Versions:

1.0

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.

connected

property

connected:Boolean [read-only]

Runtime Versions:

1.0

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.

endian

property

endian:String

Runtime Versions:

1.0

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.

See also

Endian

objectEncoding

property

objectEncoding:uint

Runtime Versions:

1.0

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

timeout

property

timeout:uint

Runtime Versions:

1.5

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

Constructor Detail

Socket

()

Constructor

function Socket(host:String = null, port:int = 0)

Runtime Versions:

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

	`host:String` (default = `null`) — A fully qualified DNS domain name or an IP address in the form 111.222.333.444. In Flash Player 9.0.115.0 and AIR 1.0 and later, you can specify IPv6 addresses, such as rtmp://[2001:db8:ccc3:ffff:0:444d:555e:666f]. You can also specify `null` to connect to the host server on which the SWF file resides. If the SWF file issuing this call is running in a web browser, `host` must be in the same domain as the SWF file.

	`port:int` (default = `0`) — The TCP port number on the target host used to establish a connection. In Flash Player 9.0.124.0 and later, the target host must serve a socket policy file specifying that socket connections are permitted from the host serving the SWF file to the specified port. In earlier versions of Flash Player, a socket policy file is required only 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.

Events

	`connect:Event` — Dispatched when a network connection has been established.

	`ioError:IOErrorEvent` — Dispatched when an input/output error occurs that causes the connection to fail.

	`securityError:SecurityErrorEvent` — This error occurs in SWF content. Dispatched if a call to `Socket.connect()` attempts to connect either to a server that doesn't serve a socket policy file, or to a server whose policy file doesn't grant the calling host access to the specified port. For more information about socket policy files, see the "Flash Player Security" chapter in Programming ActionScript 3.0.

Throws

— This error occurs in SWF content.

Method Detail

()

method

function close():void

Runtime Versions:

1.0

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

IOError — The socket could not be closed, or the socket was not open.

connect

()

method

function connect(host:String, port:int):void

Runtime Versions:

1.0

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

	`host:String` — The name or IP address of the host to connect to. If no host is specified, the host that is contacted is the host where the calling file resides. If you do not specify a host, use an event listener to determine whether the connection was successful.

	`port:int` — The port number to connect to.

Events

	`connect:Event` — Dispatched when a network connection has been established.

	`ioError:IOErrorEvent` — Dispatched if a host is specified and an input/output error occurs that causes the connection to fail.

	`securityError:SecurityErrorEvent` — Dispatched if a call to `Socket.connect()` attempts to connect either to a server that doesn't serve a socket policy file, or to a server whose policy file doesn't grant the calling host access to the specified port. For more information, see the "Flash Player Security" chapter in Programming ActionScript 3.0.

Throws

	`IOError` — No host was specified and the connection failed.

	— This error occurs in SWF content.

flush

()

method

function flush():void

Runtime Versions:

1.0

Flushes any accumulated data in the socket's output buffer. Data written by the write methods is not immediately transmitted; it is queued until the flush() method is called.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

readBoolean

()

method

function readBoolean():Boolean

Runtime Versions:

1.0

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

Returns

Boolean — A value of true if the byte read is nonzero, otherwise false.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readByte

()

method

function readByte():int

Runtime Versions:

1.0

Reads a signed byte from the socket.

Returns

int — A value from -128 to 127.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readBytes

()

method

function readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void

Runtime Versions:

1.0

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

	`bytes:ByteArray` — The ByteArray object to read data into.

	`offset:uint` (default = `0`) — The offset at which data reading should begin in the byte array.

	`length:uint` (default = `0`) — The number of bytes to read. The default value of 0 causes all available data to be read.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readDouble

()

method

function readDouble():Number

Runtime Versions:

1.0

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

Returns

Number — An IEEE 754 double-precision floating-point number.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readFloat

()

method

function readFloat():Number

Runtime Versions:

1.0

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

Returns

Number — An IEEE 754 single-precision floating-point number.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readInt

()

method

function readInt():int

Runtime Versions:

1.0

Reads a signed 32-bit integer from the socket.

Returns

int — A value from -2147483648 to 2147483647.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readMultiByte

()

method

function readMultiByte(length:uint, charSet:String):String

Runtime Versions:

1.0

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

Parameters

	`length:uint` — The number of bytes from the byte stream to read.

	`charSet:String` — The string denoting the character set to use to interpret the bytes. Possible character set strings include `"shift_jis"`, `"CN-GB"`, and `"iso-8859-1"`. For a complete list, see Supported Character Sets. Note: If the value for the `charSet` parameter is not recognized by the current system, then the application uses the system's default code page as the character set. For example, a value for the `charSet` parameter, as in `myTest.readMultiByte(22, "iso-8859-01")` that uses `01` instead of `1` might work on your development machine, but not on another machine. On the other machine, the application will use the system's default code page.

Returns

String — A UTF-8 encoded string.

Throws

EOFError — There is insufficient data available to read.

readObject

()

method

function readObject():*

Runtime Versions:

1.0

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

Returns

* — The deserialized object

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

See also

ObjectEncoding

readShort

()

method

function readShort():int

Runtime Versions:

1.0

Reads a signed 16-bit integer from the socket.

Returns

int — A value from -32768 to 32767.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readUnsignedByte

()

method

function readUnsignedByte():uint

Runtime Versions:

1.0

Reads an unsigned byte from the socket.

Returns

uint — A value from 0 to 255.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readUnsignedInt

()

method

function readUnsignedInt():uint

Runtime Versions:

1.0

Reads an unsigned 32-bit integer from the socket.

Returns

uint — A value from 0 to 4294967295.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readUnsignedShort

()

method

function readUnsignedShort():uint

Runtime Versions:

1.0

Reads an unsigned 16-bit integer from the socket.

Returns

uint — A value from 0 to 65535.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readUTF

()

method

function readUTF():String

Runtime Versions:

1.0

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

String — A UTF-8 string.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

readUTFBytes

()

method

function readUTFBytes(length:uint):String

Runtime Versions:

1.0

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

Parameters

length:uint — The number of bytes to read.

Returns

String — A UTF-8 string.

Throws

	`EOFError` — There is insufficient data available to read.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

writeBoolean

()

method

function writeBoolean(value:Boolean):void

Runtime Versions:

1.0

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

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:Boolean — The value to write to the socket: 1 (true) or 0 (false).

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeByte

()

method

function writeByte(value:int):void

Runtime Versions:

1.0

Writes a byte to the socket.

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:int — The value to write to the socket. The low 8 bits of the value are used; the high 24 bits are ignored.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeBytes

()

method

function writeBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void

Runtime Versions:

1.0

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

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

If offset or length is out of range, they are adjusted to match the beginning and end of the bytes array.

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

	`bytes:ByteArray` — The ByteArray object to write data from.

	`offset:uint` (default = `0`) — The zero-based offset into the `bytes` ByteArray object at which data writing should begin.

	`length:uint` (default = `0`) — The number of bytes to write. The default value of 0 causes the entire buffer to be written, starting at the value specified by the `offset` parameter.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeDouble

()

method

function writeDouble(value:Number):void

Runtime Versions:

1.0

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

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:Number — The value to write to the socket.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeFloat

()

method

function writeFloat(value:Number):void

Runtime Versions:

1.0

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

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:Number — The value to write to the socket.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeInt

()

method

function writeInt(value:int):void

Runtime Versions:

1.0

Writes a 32-bit signed integer to the socket.

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:int — The value to write to the socket.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeMultiByte

()

method

function writeMultiByte(value:String, charSet:String):void

Runtime Versions:

1.0

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

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

	`value:String` — The string value to be written.

	`charSet:String` — The string denoting the character set to use to interpret the bytes. Possible character set strings include `"shift_jis"`, `"CN-GB"`, and `"iso-8859-1"`. For a complete list, see Supported Character Sets.

See also

flush()

writeObject

()

method

function writeObject(object:*):void

Runtime Versions:

1.0

Write an object to the socket in AMF serialized format.

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

object:* — The object to be serialized.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()
ObjectEncoding

writeShort

()

method

function writeShort(value:int):void

Runtime Versions:

1.0

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.

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:int — The value to write to the socket.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeUnsignedInt

()

method

function writeUnsignedInt(value:uint):void

Runtime Versions:

1.0

Writes a 32-bit unsigned integer to the socket.

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:uint — The value to write to the socket.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeUTF

()

method

function writeUTF(value:String):void

Runtime Versions:

1.0

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.

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:String — The string to write to the socket.

Throws

	— The length is larger than 65535.

	`IOError` — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

writeUTFBytes

()

method

function writeUTFBytes(value:String):void

Runtime Versions:

1.0

Writes a UTF-8 string to the socket.

Note: Data written by this method is not immediately transmitted; it is queued until the flush() method is called.

Parameters

value:String — The string to write to the socket.

Throws

IOError — An I/O error occurred on the socket, or the socket is not open.

See also

flush()

Event Detail

Event

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

Runtime Versions:

1.0

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:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The object whose connection has been closed.

connect

Event

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

Runtime Versions:

1.0

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:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The Socket or XMLSocket object that has established a network connection.

ioError

Event

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

Runtime Versions:

1.0

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:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`errorID`	A reference number associated with the specific error (AIR only).
`target`	The network object experiencing the input/output error.
`text`	Text to be displayed as an error message.

securityError

Event

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

Runtime Versions:

1.0

Dispatched if a call to Socket.connect() attempts to connect either to a server outside the caller's security sandbox or to a port lower than 1024.

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

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The network object reporting the security error.
`text`	Text to be displayed as an error message.

See also

Socket.connect()

socketData

Event

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

Runtime Versions:

1.0

Dispatched when a socket has received data. 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:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event.
`bytesLoaded`	The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal`	0; this property is not used by `socketData` event objects.
`target`	The Socket object reporting progress.

window.runtime property	window.runtime.flash.net.Socket

Inheritance	Socket EventDispatcher

Adobe AIR Language Reference for HTML Developers This Help system only	Index \| Frames No Frames
Socket