flash.external.ExtensionContext - ActionScript® 3.0 Reference for the Adobe® Flash® Platform

Package	flash.external
Class	public final class ExtensionContext
Inheritance	ExtensionContext EventDispatcher Object

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.

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

Create an ExtensionContext instance

Related API Elements

flash.desktop.NativeProcess

Public Properties

Hide Inherited Public Properties

Show Inherited Public Properties

	Property		Defined By
		actionScriptData : Object The ActionScript object, if any, associated with this context.	ExtensionContext
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		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
		dispatchEvent(event:Event):Boolean 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
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.	Object
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions.	Object
		toString():String Returns the string representation of the specified object.	Object
		valueOf():Object Returns the primitive value of the specified object.	Object
		willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.	EventDispatcher

Events

Click for more information on events

Hide Inherited Events

Show Inherited Events

	Event		Summary	Defined By
		activate	[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.	EventDispatcher
		deactivate	[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.	EventDispatcher

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.

[an error occurred while processing this directive]

Legal Notices | Online Privacy Policy

Classes x

actionScriptData

call

createExtensionContext

dispose

getExtensionDirectory