The external API's XML format

Communication between ActionScript and an application hosting the Shockwave Flash ActiveX control uses a specific XML format to encode function calls and values. There are two parts to the XML format used by the external API. One format is used to represent function calls. Another format is used to represent individual values; this format is used for parameters in functions as well as function return values. The XML format for function calls is used for calls to and from ActionScript. For a function call from ActionScript, Flash Player passes the XML to the container; for a call from the container, Flash Player expects the container application to pass it an XML string in this format. The following XML fragment shows an example XML-formatted function call:

<invoke name="functionName" returntype="xml">
    <arguments>
        ... (individual argument values)
    </arguments>
</invoke>

The root node is the invoke node. It has two attributes: name indicates the name of the function to call, and returntype is always xml. If the function call includes parameters, the invoke node has a child arguments node, whose child nodes will be the parameter values formatted using the individual value format explained next.

Individual values, including function parameters and function return values, use a formatting scheme that includes data type information in addition to the actual values. The following table lists ActionScript classes and the XML format used to encode values of that data type:

ActionScript class/value	C# class/value	Format	Comments
null	null	<null/>
Boolean `true`	bool true	<true/>
Boolean `false`	bool false	<false/>
String	string	<string>string value</string>
Number, int, uint	single, double, int, uint	`<number>27.5</number>` `<number>-12</number>`
Array (elements can be mixed types)	A collection that allows mixed-type elements, such as ArrayList or object[]	`<array> <property id="0"> <number>27.5</number> </property> <property id="1"> <string>Hello there!</string> </property> ...` `</array>`	The `property` node defines individual elements, and the `id` attribute is the numeric, zero-based index.
Object	A dictionary with string keys and object values, such as a HashTable with string keys	`<object> <property id="name"> <string>John Doe</string> </property> <property id="age"> <string>33</string> </property> ...` `</object>`	The `property` node defines individual properties, and the `id` attribute is the property name (a string).
Other built-in or custom classes		`<null/> or` `<object></object>`	ActionScript encodes other objects as null or as an empty object. In either case any property values are lost.

NOTE

By way of example, this table shows equivalent C# classes in addition to ActionScript classes; however, the external API can be used to communicate with any programming language or run time that supports ActiveX controls, and is not limited to C# applications.

When you are building your own applications using the external API with an ActiveX container application, you'll probably find it convenient to write a proxy that will perform the task of converting native function calls to the serialized XML format. For an example of a proxy class written in C#, see Inside the ExternalInterfaceProxy class.

Flash CS3

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/9.0/main/00000344.html