Top Level

Class XMLSocket

Object


public class XMLSocket
extends Object

Player version: Flash Player 5

The XMLSocket class implements client sockets that let the computer running Flash Player communicate with a server computer identified by an IP address or domain name. The XMLSocket class is useful for client-server applications that require low latency, such as real-time chat systems. A traditional HTTP-based chat solution frequently polls the server and downloads new messages using an HTTP request. In contrast, an XMLSocket chat solution maintains an open connection to the server, which lets the server immediately send incoming messages without a request from the client. To use the XMLSocket class, the server computer must run a daemon that understands the protocol used by the XMLSocket class. The protocol is described in the following list: The following restrictions apply to how and where an XMLSocket object can connect to the server: Setting up a server to communicate with the XMLSocket object can be challenging. If your application does not require real-time interactivity, use the loadVariables() function, or Flash HTTP-based XML server connectivity (XML.load(), XML.sendAndLoad(), XML.send()), instead of the XMLSocket class. To use the methods of the XMLSocket class, you must first use the constructor, new XMLSocket, to create an XMLSocket object.




Property Summary

Properties inherited from class Object
__proto__, __resolve, constructor, prototype


Event Summary
onClose = function() {}
Invoked only when an open connection is closed by the server.
onConnect = function(success:Boolean) {}
Invoked by Flash Player when a connection request initiated through XMLSocket.connect() has succeeded or failed.
onData = function(src:String) {}
Invoked when a message has been downloaded from the server, terminated by a zero (0) byte.
onXML = function(src:XML) {}
Invoked by Flash Player when the specified XML object containing an XML document arrives over an open XMLSocket connection.


Constructor Summary
XMLSocket()
Creates a new XMLSocket object.


Method Summary
close() : Void
Closes the connection specified by XMLSocket object.
connect(url:String, port:Number) : Boolean
Establishes a connection to the specified Internet host using the specified TCP port (must be 1024 or higher), and returns true or false, depending on whether a connection is successfully established.
send(data:Object) : Void
Converts the XML object or data specified in the object parameter to a string and transmits it to the server, followed by a zero (0) byte.

Methods inherited from class Object
addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch


Event Detail

onClose Event Handler

public onClose = function() {}

Player version: Flash Player 5

Invoked only when an open connection is closed by the server. The default implementation of this method performs no actions. To override the default implementation, you must assign a function containing custom actions.

Example
The following example executes a trace statement if an open connection is closed by the server:
var socket:XMLSocket = new XMLSocket();
socket.connect(null, 2000);
socket.onClose = function () {
    trace("Connection to server lost.");
}

See also
XMLSocket.onConnect, function statement

onConnect Event Handler

public onConnect = function(success:Boolean) {}

Player version: Flash Player 5

Invoked by Flash Player when a connection request initiated through XMLSocket.connect() has succeeded or failed. If the connection succeeded, the success parameter is true; otherwise the success parameter is false.

The default implementation of this method performs no actions. To override the default implementation, you must assign a function containing custom actions.

Parameters
success:Boolean — A Boolean value indicating whether a socket connection is successfully established (true or false).

Example
The following example illustrates the process of specifying a replacement function for the onConnect method in a simple chat application.

After creating the XMLSocket object using the constructor method, the script defines the custom function to be executed when the onConnect event handler is invoked. The function controls the screen to which users are taken, depending on whether a connection is successfully established. If the connection is successfully made, users are taken to the main chat screen on the frame labeled startChat. If the connection is not successful, users go to a screen with troubleshooting information on the frame labeled connectionFailed.

var socket:XMLSocket = new XMLSocket();
socket.onConnect = function (success) {
    if (success) {
        gotoAndPlay("startChat");
    } else {
        gotoAndStop("connectionFailed");
    }
}

Finally, the connection is initiated. If connect() returns false, the SWF file is sent directly to the frame labeled connectionFailed, and onConnect is never invoked. If connect() returns true, the SWF file jumps to a frame labeled waitForConnection, which is the "Please wait" screen. The SWF file remains on the waitForConnection frame until the onConnect handler is invoked, which happens at some point in the future depending on network latency.

if (!socket.connect(null, 2000)) {
    gotoAndStop("connectionFailed");
} else {
    gotoAndStop("waitForConnection");
}

See also
XMLSocket.connect(), function statement

onData Event Handler

public onData = function(src:String) {}

Player version: Flash Player 5

Invoked when a message has been downloaded from the server, terminated by a zero (0) byte. You can override XMLSocket.onData to intercept the data sent by the server without parsing it as XML. This is a useful if you're transmitting arbitrarily formatted data packets, and you'd prefer to manipulate the data directly when it arrives, rather than have Flash Player parse the data as XML.

By default, the XMLSocket.onData method invokes the XMLSocket.onXML method. If you override XMLSocket.onData with custom behavior, XMLSocket.onXML is not called unless you call it in your implementation of XMLSocket.onData.

Parameters
src:String — A string containing the data sent by the server.

Example
In this example, the src parameter is a string containing XML text downloaded from the server. The zero (0) byte terminator is not included in the string.
XMLSocket.prototype.onData = function (src) {
    this.onXML(new XML(src));
}


onXML Event Handler

public onXML = function(src:XML) {}

Player version: Flash Player 5

Invoked by Flash Player when the specified XML object containing an XML document arrives over an open XMLSocket connection. An XMLSocket connection can be used to transfer an unlimited number of XML documents between the client and the server. Each document is terminated with a zero (0) byte. When Flash Player receives the zero byte, it parses all the XML received since the previous zero byte or since the connection was established if this is the first message received. Each batch of parsed XML is treated as a single XML document and passed to the onXML method.

The default implementation of this method performs no actions. To override the default implementation, you must assign a function containing actions that you define.

Parameters
src:XML — An XML object that contains a parsed XML document received from a server.

Example
The following function overrides the default implementation of the onXML method in a simple chat application. The function myOnXML instructs the chat application to recognize a single XML element, MESSAGE, in the following format.

      <MESSAGE USER="John" TEXT="Hello, my name is John!" />.
      

The following function displayMessage() is assumed to be a user-defined function that displays the message received by the user:

var socket:XMLSocket = new XMLSocket();
socket.onXML = function (doc) {
    var e = doc.firstChild;
    if (e != null && e.nodeName == "MESSAGE") {
        displayMessage(e.attributes.user, e.attributes.text);
    }
}

See also
function statement


Constructor Detail

XMLSocket Constructor

public XMLSocket()

Player version: Flash Player 5

Creates a new XMLSocket object. The XMLSocket object is not initially connected to any server. You must call XMLSocket.connect() to connect the object to a server.

Example
The following example creates an XMLSocket object:
var socket:XMLSocket = new XMLSocket();



Method Detail

close Method

public close() : Void

Player version: Flash Player 5

Closes the connection specified by XMLSocket object.

Example
The following simple example creates an XMLSocket object, attempts to connect to the server, and then closes the connection.
var socket:XMLSocket = new XMLSocket();
socket.connect(null, 2000);
socket.close();

See also
XMLSocket.connect()

connect Method

public connect(url:String, port:Number) : Boolean

Player version: Flash Player 5 — Behavior changed in Flash Player 7.

Establishes a connection to the specified Internet host using the specified TCP port (must be 1024 or higher), and returns true or false, depending on whether a connection is successfully established. If you do not know the port number of your Internet host computer, contact your network administrator.

If you specify null for the host parameter, the host contacted is the one where the SWF file calling XMLSocket.connect() resides. For example, if the SWF file was downloaded from www.yoursite.com, specifying null for the host parameter is the same as entering the IP address for www.yoursite.com.

In SWF files running in a version of the player earlier than Flash Player 7, host must be in the same superdomain as the SWF file that is issuing this call. For example, a SWF file at www.someDomain.com can load variables from a SWF file at store.someDomain.com because both files are in the same superdomain of someDomain.com.

In SWF files of any version running in Flash Player 7 or later, host must be in exactly the same domain. For example, a SWF file at www.someDomain.com that is published for Flash Player 5, but is running in Flash Player 7 or later can load variables only from SWF files that are also at www.someDomain.com. If you want to load variables from a different domain, you can place a cross-domain policy file on the server hosting the SWF file that is being accessed.

The value you pass for url must be in exactly the same domain. For example, a SWF file at www.someDomain.com can load variables only from SWF files that are also at www.someDomain.com. If you want to load variables from a different domain, you can place a cross-domain policy file on the server hosting the SWF file that is being accessed.

When load() is executed, the XML object property loaded is set to false. When the XML data finishes downloading, the loaded property is set to true, and the onLoad event handler is invoked. The XML data is not parsed until it is completely downloaded. If the XML object previously contained any XML trees, they are discarded.

If XMLSocket.connect() returns a value of true, the initial stage of the connection process is successful; later, the XMLSocket.onConnect method is invoked to determine whether the final connection succeeded or failed. If XMLSocket.connect() returns false, a connection could not be established.

When using this method, consider the Flash Player security model.

For more information, see the following:

Parameters
url:String — String; a fully qualified DNS domain name or an IP address in the form aaa.bbb.ccc.ddd. 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; for details, see the information about domain restrictions for SWF files in the main description of this method.
port:Number — A number; the TCP port number on the host used to establish a connection. The port number must be 1024 or greater.

Returns
Booleantrue if the connection is successful; false otherwise.

Example
The following example uses XMLSocket.connect() to connect to the host where the SWF file resides and uses trace to display the return value indicating the success or failure of the connection:
var socket:XMLSocket = new XMLSocket()
socket.onConnect = function (success:Boolean) {
    if (success) {
    trace ("Connection succeeded!")
    } else {
    trace ("Connection failed!")
    }
}
if (!socket.connect(null, 2000)) {
    trace ("Connection failed!")
}

See also
XMLSocket.onConnect, function statement

send Method

public send(data:Object) : Void

Player version: Flash Player 5

Converts the XML object or data specified in the object parameter to a string and transmits it to the server, followed by a zero (0) byte. If object is an XML object, the string is the XML textual representation of the XML object. The send operation is asynchronous; it returns immediately, but the data may be transmitted at a later time. The XMLSocket.send() method does not return a value indicating whether the data was successfully transmitted.

If the myXMLSocket object is not connected to the server (using XMLSocket.connect()), the XMLSocket.send() operation will fail.

Parameters
data:Object — An XML object or other data to transmit to the server.

Example
The following example shows how you could specify a user name and password to send the XML object my_xml to the server:
var myXMLSocket:XMLSocket = new XMLSocket();
var my_xml:XML = new XML();
var myLogin:XMLNode = my_xml.createElement("login");
myLogin.attributes.username = usernameTextField;
myLogin.attributes.password = passwordTextField;
my_xml.appendChild(myLogin);
myXMLSocket.send(my_xml);

See also
XMLSocket.connect()