ActionScript® 3.0 Reference for the Adobe® Flash® Platform
Home  |  Show Packages and Classes List |  Packages  |  Classes  |  What's New  |  Index  |  Appendixes
flash.external 

ExtensionContext  - AS3

Packageflash.external
Classpublic final class ExtensionContext
InheritanceExtensionContext Inheritance EventDispatcher Inheritance Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

The ExtensionContext class also provides a static method getExtensionDirectory() for accessing the directory in which the extension is installed on the device. It also provides a property, actionScriptData, for sharing data with the native implementation of the extension.

Note: AIR applications using the extendedDesktop profile can use the NativeProcess class to execute native processes.

More examples

Related API Elements



Public Properties
 PropertyDefined By
      actionScriptData : Object
The ActionScript object, if any, associated with this context.
ExtensionContext
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
Public Methods
 MethodDefined By
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
  
    call(functionName:String, ... args):Object
Calls the native function specified by functionName.
ExtensionContext
  
    createExtensionContext(extensionID:String, contextType:String):ExtensionContext
[static] Creates an ExtensionContext instance for the given extension identifier and context type.
ExtensionContext
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
    dispose():void
Disposes of this ExtensionContext instance.
ExtensionContext
  
    getExtensionDirectory(extensionID:String):File
[static] Returns the directory in which the extension is installed on the device.
ExtensionContext
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
  
    status
The ExtensionContext class provides an interface for calling functions in the native implementation of a native extension for Adobe AIR.ExtensionContext
Property Detail
    

actionScriptData

property
actionScriptData:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

The ActionScript object, if any, associated with this context.

You can associate any ActionScript object with an ExtensionContext instance. The native implementation can also get and set this ActionScript object. Therefore, you can use actionScriptData to share data between the ActionScript side and the native side of an extension.

You can also set the value of actionScriptData to null.



Implementation
    public function get actionScriptData():Object
    public function set actionScriptData(value:Object):void

Throws
IllegalOperationError — The method dispose() was already called on this ExtensionContext instance.
Method Detail

    call

()method
public function call(functionName:String, ... args):Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Calls the native function specified by functionName. Any additional arguments are passed to the native function.

Parameters

functionName:String — A name that represents a function in the native implementation. This name is not necessarily the actual name of the native function, but any name agreed to between the ActionScript side and native side of the extension.
 
... args — A list of arguments for the native function. These arguments can be any ActionScript objects: primitive types or ActionScript class objects. The types and order of the arguments are agreed to between the ActionScript side and native side of the extension.

Returns
Object — The value returned by the native function. The return value is null if the native function has no return value or returns an invalid object reference.

Throws
ArgumentError — No function corresponds to the name given by functionName.
 
IllegalOperationError — The method dispose() was already called on this ExtensionContext instance. This error is also thrown if the native function returns an invalid object reference.

    createExtensionContext

()method 
public static function createExtensionContext(extensionID:String, contextType:String):ExtensionContext

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Creates an ExtensionContext instance for the given extension identifier and context type.

Parameters

extensionID:String — The extension identifier of the extension. This identifier has the same value as the id element in the extension descriptor file. Application developers also use this value in the extensionID element in the application descriptor file. All extensions share a single, global namespace. Therefore, to avoid name conflicts, use reverse DNS notation for the extension identifier.
 
contextType:String — The context type of the extension. Depending on the context type, the native implementation can perform different initializations. These differences can include the native implementation specifying a different set of available native functions that the ActionScript side can call. The value of the context type is any string agreed to between the ActionScript side and the native side of the extension. Simple extensions often have no use for different context types. In those cases, pass an empty string "" or null for the contextType value.

Returns
ExtensionContext — The new ExtensionContext instance. Returns null if no extension with the given extensionID value is available or if the context initializer function specified in the extension.xml document for the given extensionID cannot be found or run.

Throws
ArgumentError — The extensionID parameter is null or is not a valid extension ID.

    dispose

()method 
public function dispose():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Disposes of this ExtensionContext instance.

The runtime notifies the native implementation, which can release any associated native resources. After calling dispose(), the code cannot call the call() method and cannot get or set the actionScriptData property.

    getExtensionDirectory

()method 
public static function getExtensionDirectory(extensionID:String):File

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Returns the directory in which the extension is installed on the device.

Sometimes an extension includes resources such as images that you want to access from the extension's ActionScript code. Sometimes the code also requires information that is available in the extension descriptor file, such as the extension version number. You can use this method to access the base directory of the extension.

Regardless where the extension is on the device, the extension's files are always in the same location relative to this base directory of the extension. Using the File instance that this method returns, you can navigate to and manipulate specific files included with the extension.

The extension directory has the following structure:

			 extension base directory/
			      platform independent files
			      META-INF/
			           ANE/
			                extension.xml
			                platform name/
			                     platform-dependent files and directories
			 

The extension directory location depends on whether the extension is available through application-bundling or device-bundling as follows:

  • With application-bundling, the extension directory is located within the application directory.
  • With device-bundling, the extension directory location depends on the device.

An exception to using getExtensionDirectory() exists for native extensions for iOS devices. The resources for these extensions are not located in the extension directory. Instead, they are located in the top-level application directory.

Parameters

extensionID:String — The extension identifier of the extension. This identifier has the same value as the extensionID parameter in createExtensionContext().

Returns
File — A File instance for the directory in which the extension is installed.

Throws
TypeError — Parameter extensionID must not be null.
 
ArgumentError — The value specified for argument extensionID is invalid. The directory does not exist.
Event Detail
    

status

Event
Event Object Type: flash.events.StatusEvent
property StatusEvent.type = flash.events.StatusEvent.STATUS

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

The ExtensionContext class provides an interface for calling functions in the native implementation of a native extension for Adobe AIR. You can use this class only in ActionScript classes that are part of the extension.

AIR profile support: This feature is supported on mobile devices starting in AIR 3. It is also supported starting in AIR 3 on desktop devices in applications that use the extendedDesktop device profile. It is supported on AIR for TV devices starting in AIR 2.5 in applications that use the extendedTV device profile.

A native extension is a combination of:

  • ActionScript classes.
  • Native code. Native code is code that executes on a device outside the runtime. For example, code that you write in C is native code.

You can create a native extension to:

  • Give an AIR application access to device-specific features.
  • Reuse existing native code.
  • Provide more efficient processing using native code than you can provide with ActionScript code.

Use the ExtensionContext class in the ActionScript side of an extension to access the native side of the extension. First, create an instance of the ExtensionContext class. To do so, call the static method ExtensionContext.createExtensionContext().

After creating the ExtensionContext instance, use the instance's call() method to call a native function.

When you are done with an ExtensionContext instance, call dispose() to release any associated native resources. Without an explicit call to dispose(), the runtime garbage collector calls dispose() when it disposes of the instance. An explicit call to dispose() typically occurs much sooner than waiting for the garbage collector.

An ExtensionContext instance can listen for StatusEvent events that the native code dispatches when some asynchronous event occurs in the extension's native implementation. Since the ExtensionContext class derives from EventDispatcher, it can in turn dispatch events.

Defines the value of the type property of a status event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
codeA description of the object's status.
currentTargetThe object that is actively processing the Event object with an event listener.
levelThe category of the message, such as "status", "warning" or "error".
targetThe object reporting its status.