Protocol

Introduction

All messages passed back and forth between the Flash virtual machine and the external language are in XML. There are 5 different commands documented below.

All the commands work with object references and values. Values passed back and forth are contained within a single XML element. Values can be represented in two ways:

1. Primitives (String, int, float, boolean & null) are copied and sent in a message. These values have a value attribute equal to their literal representation and a dataType attribute equal signifying their type.

2. Objects are sent by reference. These XML element elements are represented with a value attribute set to the object's proxy identifier and the dataType attribute is set to "object".

Proxy identifiers are used by the external language to reference objects that have already been accessed. These identifiers are also used in some commands (Get Property, Set Property, & Invoke Method) to reference the object which has the property or method being used.

Create Object Command

This command creates an object given a fully qualified class name. The format for this command is:

<create class="flash.geom.Point"/>

This will create a Point object and return a reference to the object. The Create Object command is limited in that it can only instantiate objects from zero-argument constructors.

When throwable, an error is thrown when instantiating a class that doesn't exist. When non-throwable, null is returned when instantiating a class that doesn't exist.

Get Class Command

This command returns a reference to a class given a fully qualified class name. The format for this command is:

<get-class name="flash.display.Stage"/>

This command is useful when a reference is needed to a class in order to read static methods or properties.

When throwable, an error is thrown when retrieving a class that doesn't exist. When non-throwable, null is returned when retrieving a class that doesn't exist.

Get Property Command

This command returns the value of a property on an object. Because classes are objects in ActionScript, this works on classes as well. The format for this command is:

<get object="123" property="name"/>

This command can return a primitive value or a reference to an object.

When throwable, an error is thrown when retrieving a property that doesn't exist on a class or sealed object. When non-throwable, null is returned when retrieving a property that doesn't exist on a class or sealed object. Dynamic objects are not affected by the throwable status.

Set Property Command

This command sets a property on an object to a given value. The format for this command is:

<set object="123" property="name">
  <arg value="bar" dataType="string"/>
</set>

This command will return the value of the property that is being set so that it can be chained in the external language.

When throwable, an error is thrown when setting a property that doesn't exist on a class or sealed object. When non-throwable, nothing occurs when setting a property that doesn't exist on a class or sealed object. Dynamic objects are not affected by the throwable status.

Invoke Method Command

This command invokes a method on an object and passes zero or more arguments. The format for this command is:

<invoke object="123" property="concatenate">
  <args>
    <arg value="foo" dataType="string"/>
    <arg value="bar" dataType="string"/>
  </args>
</set>

This example method invocation would return this message:

<return value="foobar" dataType="string"/>

When throwable, an error is thrown when invoking a method that doesn't exist on a class or object. When non-throwable, nothing is invoked and a null is returned when invoking a method that doesn't exist on a class or object.

Invoke Function

This command invokes a package level function and passes zero or more arguments. The format of this command is:

<invoke-function name="flash.utils.getQualifiedClassName">
  <args>
    <arg value="foo" dataType="string"/>
  </args>
</set>

This example method invocation would return this message:

<return value="String" dataType="string"/>

When throwable, an error is thrown when invoking a global function that doesn't exist. When non-throwable, nothing is invoked and a null is returned when invoking a global function that doesn't exist.

Return Values

All return values are represented with a value element in the following format:

<return value="foo" dataType="string"/>

Errors

All errors are represented with an error element in the following format:

<error proxyId="" errorId="" name="" message="">
  <stack-trace>
  </stack-trace>
</error>

The proxyId is a reference to an object proxy for the original Flash error object. This is useful when you need to look at properties on the original error object. The errorId, name, and message attributes are copied directly from the original Flash Error object.

The <stack-trace/> element contains the entire Flash stack trace within the element. This element is only available when running the Flash SWF within the Flash debug player or the AIR Debug Launcher (ADL).

Throwable Attribute

The throwable attribute can be added to any command to toggle whether certain errors are raised. By default, all commands have throwable set to true. This means that all errors are sent back to Melomel.

Throwable does not affect errors thrown within a method or inside property accessors or mutators.