XMLSocket

Object   |   +-XMLSocket public class XMLSocket extends Object

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:

• XML messages are sent over a full-duplex TCP/IP stream socket connection.

• Each XML message is a complete XML document, terminated by a zero (0) byte.

• An unlimited number of XML messages can be sent and received over a single XMLSocket connection.

The following restrictions apply to how and where an XMLSocket object can connect to the server:

• The XMLSocket.connect() method can connect only to TCP port numbers greater than or equal to 1024. One consequence of this restriction is that the server daemons that communicate with the XMLSocket object must also be assigned to port numbers greater than or equal to 1024. Port numbers below 1024 are often used by system services such as FTP, Telnet, and HTTP, so XMLSocket objects are barred from these ports for security reasons. The port number restriction limits the possibility that these resources will be inappropriately accessed and abused.

• The XMLSocket.connect() method can connect only to computers in the same domain where the SWF file resides. This restriction does not apply to SWF files running off a local disk. (This restriction is identical to the security rules for loadVariables(), XML.sendAndLoad(), and XML.load().) To connect to a server daemon running in a domain other than the one where the SWF resides, you can create a security policy file on the server that allows access from specific domains.

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.

Availability: ActionScript 1.0; Flash Player 5

Property summary

Properties inherited from class Object

constructor (Object.constructor property) ,__proto__ (Object.__proto__ property),prototype (Object.prototype property) ,__resolve (Object.__resolve property)

Event summary

Event	Description
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

Signature	Description
XMLSocket ()	Creates a new XMLSocket object.

Method summary

Modifiers	Signature	Description
	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 (Object.addProperty method),hasOwnProperty (Object.hasOwnProperty method),isPropertyEnumerable (Object.isPropertyEnumerable method),isPrototypeOf  (Object.isPrototypeOf method),registerClass (Object.registerClass  method),toString (Object.toString method),unwatch (Object.unwatch  method),valueOf (Object.valueOf method),watch (Object.watch method)

close (XMLSocket.close method)

public close() : Void

Closes the connection specified by XMLSocket object.

Availability: ActionScript 1.0; Flash Player 5

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

connect (XMLSocket.connect method)

connect (XMLSocket.connect method)

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

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 Flash Player 8, the XMLSocket.connect() method is not allowed if the calling SWF file is in the local-with-file-system sandbox.

• For Flash Player 7 and later, websites can permit access to a resource from requesters in different domains by deploying a cross-domain policy file.

For more information, see the following:

• Chapter 17, "Understanding Security," in Learning ActionScript 2.0 in Flash

• The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security

• The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

Availability: ActionScript 1.0; Flash Player 5 - Behavior changed in Flash Player 7.

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

Boolean - true 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

onConnect (XMLSocket.onConnect handler),function statement

onClose (XMLSocket.onClose handler)

onClose = function() {}

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.

Availability: ActionScript 1.0; Flash Player 5

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

onConnect (XMLSocket.onConnect handler),function statement

onConnect (XMLSocket.onConnect handler)

onConnect = function(success:Boolean) {}

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.

Availability: ActionScript 1.0; Flash Player 5

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

connect (XMLSocket.connect method),function statement

onData (XMLSocket.onData handler)

onData = function(src:String) {}

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.

Availability: ActionScript 1.0; Flash Player 5

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 (XMLSocket.onXML handler)

onXML = function(src:XML) {}

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.

Availability: ActionScript 1.0; Flash Player 5

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

send (XMLSocket.send method)

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

Availability: ActionScript 1.0; Flash Player 5

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

connect (XMLSocket.connect method)

XMLSocket constructor

public XMLSocket()

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.

Availability: ActionScript 1.0; Flash Player 5

Example

The following example creates an XMLSocket object:

var socket:XMLSocket = new XMLSocket();