flash.external

# ExtensionContext - AS3

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 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

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
|  | 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:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`code` | A description of the object's status.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`level` | The category of the message, such as `"status"`, `"warning"` or `"error"`.
`target` | The object reporting its status.

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00