APE DOM Extensions Overview

1. Introduction

Before CS5, the communication between an ActionScript program running in a Flash Player instance embedded in an application and the application itself was limited to ActionScript's ExternalInterface class. This class offered a XML-based communications protocol to exchange data between the ActionScript world and the application it was embedded in. The application had to write C++ code to use the interface on its side.

This way, an ActionScript program and its embedding host could exchange simple data, such as strings and numbers. But the only realistic way to exchange Live Objects, like a Document object, is through heavy administration and maintenance of several layers of code. Bernd Paradies' PatchPanel technology provided such a layer.

These limitations kept integrators from embedding a Flash Player in an application that was able to efficiently talk to the application's scripting object model.

The APE DOM Extensions are implemented in the APE library. The API is not present in the Flash Player library, or browser plug-in. SWF files that work with DOM Extensions cannot be loaded into a browser environment; they can only load and run in the APE environment.

2. The APIs

Most of the APIs are symmetric. The host has a set of APIs to access the ActionScript object model in an embedded Flash Player instance. Typical calls include the reading and writing of object properties, or the invocation of an object method.

The host application registers a set of function pointers. Again, there are functions to read or write object properties, or to invoke an object method, this time for a host object.

Before working with host or ActionScript objects, there must be a way to get such an object. In a scripting environment, there are several ways.

Access a DOM tree: Often, a host's object model is organized as a tree of objects, starting from a root object that contains elements that themselves contain other objects:

Class objects: Another way to organize a DOM may be to provide several distinct class objects, each of them encapsulating unique functionality.

Creatable objects: Many objects are only present when needed, like colors, files, and more.

The DOM Extensions offers all of these mechanisms to access a host's object model. A host can decide freely which of these object structures to offer. A JavaScript-based host would, for example, offer all three combinations, while a plug-in that offers a restricted set of services might only offer class objects, and neither a root object (because there is no tree-like object structure) nor creatable objects (because there are no objects that are creatable).

The APE environment takes care of object lifetime issues and maintains the connection between host objects and the ActionScript object that they are wrapped into. The ActionScript programmer does not need to worry about issues like garbage collection, asynchronous state changes and the like.

Exceptions are a vital part of ActionScript. The APIs help with generating exceptions and forwarding them between the host and ActionScript. This way, a JavaScript based host could throw JavaScript exceptions into ActionScript, and vice versa.

Mush as the PatchPanel product today, there will be a set of wrapper libraries available that define a host's object model in ActionScript. These wrapper libraries can be used to speed up performance, and to provide safe type checking, code hints, help information and much more.

3. Flow Chart

The host loads a SWF file containing code that uses the HostObject APIs to access the host's DOM. 

Immediately after the SWF has been loaded, the SWF is not yet operational, because it has to execute its startup code (a.k.a frame #1) first. 

This gives the host time to register one or more DOM extensions, and to wait for the SWF to initialize. This wait is necessary if the host wishes to access the objects inside the SWF itself, since most of these objects will be created during the SWF's startup phase. If the host does not want to access the SWF's objects, it does not need to wait either.

The startup code inside the SWF already has full access to the host's object model, because the host registered its DOM extensions before allowing the startup code to execute.

For the interested: The SWF executes its startup code by sending out timer events.

4. Flash events

An ActionScript program often relies on Flash events. A typical Flash event is the click of a button. The ActionScript program can forward these events to the host, who in turn can choose to process these events. This makes it possible for a host environment to e.g. process Flash dialog events.

A Flash event is an ActionScript Event object, so it can be passed on, or created, just like any other ActionScript object. If a host application wants to process Flash events, it registers a function thatreceives these handlers. 

On the ActionScript side, there is a static HostObject.eventListener() method that can be registered as the event processing function. That method directs the event to the host application.

The host, on the other hand, can, of course, create Flash Event objects, and send them off to ActionScript to process. Thus, a host environment can e.g. choose to generate a Button Click event and send it off to a Flash dialog.