| XMLSocket.onXML( ) Event Handler | Flash 5 |
| invoked when data is received by an XMLSocket object and has been parsed as XML |
The XML object that will house the incoming XML-formatted data.
The onXML( ) event handler executes when Flash receives, and has parsed, an incoming transmission. Whenever socket receives a complete block of data (i.e., a string followed by a null character) from the server, the callback function specified by socket.onXML is automatically invoked. A server can send data as often as it pleases, but the callback function is executed only when the trailing null character (i.e., a zero byte) is received by socket. In Java, a zero byte is specified as '\0'.
When the zero byte is received, it causes ActionScript to parse any data that has been received by socket since the last zero byte was sent (or since the initial connection, if this is the first zero byte). The parsed data is converted to an XML object hierarchy, which is passed as the xmlObject argument to the callback function.
If you are a Flash programmer who is responsible for only the client side of a client/server application, simply note that the callback function specified by onXML receives any new XML data when it arrives. The new XML data is accessible through xmlObject.
To access the raw data sent over a socket, override the default behavior of the socket's onData( ) handler (see XMLSocket.onData( )).
To respond to an onXML( ) event, we must assign our own callback function to the onXML property of an XMLSocket object. The following code assigns the function handleIncoming( ) to mySocket's onXML property. The handleIncoming( ) function accesses one of the nodes of the XML object hierarchy stored in messageObj and adds its value to the text field messages_txt:
mySocket = new XMLSocket();
mySocket.onXML = handleIncoming;
function handleIncoming (messageObj) {
trace("Got some new data!");
// messageObj will contain the fragment: <MESSAGE>text</MESSAGE>
var message = messageObj.firstChild.firstChild;
messages_txt.text += (message.nodeValue + "\n");
}
For code showing the onXML( ) handler used in a more complete system, see Example 18-11 under the XMLSocket class.
XMLSocket.send( ), XMLSocket.onData( ); Chapter 10
