flash.externalExtensionContext The ExtensionContext class provides an interface for calling functions in the native implementation of an ActionScript extension.flash.events:EventDispatcher The ExtensionContext class provides an interface for calling functions in the native implementation of an ActionScript extension. You can use this class only in ActionScript classes that are part of the extension.

AIR profile support: This feature is supported only on AIR for TV devices in applications that use the extendedTV device profile.

An ActionScript 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 an ActionScript extension to give an AIR application access to device-specific features. Other reasons to create an ActionScript extension are to reuse existing native code, or to provide more efficient processing using native code than you can provide with ActionScript code. For more information about writing, building, and packaging ActionScript extensions, see the PDF Developing ActionScript Extensions for Adobe AIR.

Use the ExtensionContext class in the ActionScript side of an ActionScript 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.

call Calls the native function specified by functionName.No function corresponds to the name given by functionName. ArgumentErrorArgumentErrorThe method dispose() was already called on this ExtensionContext instance. This error is also thrown if the native function returns an invalid object reference. IllegalOperationErrorflash.errors:IllegalOperationErrorThe 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. ObjectfunctionNameStringA 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. argsA 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. Calls the native function specified by functionName. Any additional arguments are passed to the native function. createExtensionContext Creates an ExtensionContext instance for the given extension identifier and context type.The extensionID parameter is null or is not a valid extension ID. ArgumentErrorArgumentErrorThe new ExtensionContext instance. Returns null if no extension with the given extensionID value is available. flash.external:ExtensionContextextensionIDStringThe 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. contextTypeStringThe 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. Creates an ExtensionContext instance for the given extension identifier and context type. dispose Disposes of this ExtensionContext instance. 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 Returns the directory in which the extension is installed on the device.The directory does not exist. The most likely reason is that the specified extensionID is not valid. IOErrorflash.errors:IOErrorA File instance for the directory in which the extension is installed. flash.filesystem:FileextensionIDStringThe extension identifier of the extension. This identifier has the same value as the extensionID parameter in createExtensionContext(). 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 located 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.

actionScriptData The ActionScript object, if any, associated with this context.ObjectThe method dispose() was already called on this ExtensionContext instance. IllegalOperationErrorflash.errors:IllegalOperationError 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.

ExternalInterface The ExternalInterface class is an application programming interface that enables straightforward communication between ActionScript and the SWF container– for example, an HTML page with JavaScript or a desktop application that uses Flash Player to display a SWF file.Verify table is still correct and paragraph below the table still applies. Enables communications between ActionScript and the container. Object The ExternalInterface class is an application programming interface that enables straightforward communication between ActionScript and the SWF container– for example, an HTML page with JavaScript or a desktop application that uses Flash Player to display a SWF file.

Using the ExternalInterface class, you can call an ActionScript function in the Flash runtime, using JavaScript in the HTML page. The ActionScript function can return a value, and JavaScript receives it immediately as the return value of the call.

This functionality replaces the fscommand() method.

Use the ExternalInterface class in the following combinations of browser and operating system:

BrowserOperating SystemOperating SystemInternet Explorer 5.0 and later Windows Netscape 8.0 and later Windows MacOS Mozilla 1.7.5 and later Windows MacOS Firefox 1.0 and later Windows MacOS Safari 1.3 and later MacOS

Flash Player for Linux version 9.0.31.0 and later supports the ExternalInterface class in the following browsers:

BrowserMozilla 1.7.x and laterFirefox 1.5.0.7 and laterSeaMonkey 1.0.5 and later

The ExternalInterface class requires the user's web browser to support either ActiveX^® or the NPRuntime API that is exposed by some browsers for plug-in scripting. Even if a browser and operating system combination are not listed above, they should support the ExternalInterface class if they support the NPRuntime API. See http://www.mozilla.org/projects/plugins/npruntime.html.

Note: When embedding SWF files within an HTML page, make sure that the id attribute is set and the id and name attributes of the object and embed tags do not include the following characters:

 . - + ~~ / \

Note for Flash Player applications: Flash Player version 9.0.115.0 and later allows the . (period) character within the id and name attributes.

Note for Flash Player applications: In Flash Player 10 and later running in a browser, using this class programmatically to open a pop-up window may not be successful. Various browsers (and browser configurations) may block pop-up windows at any time; it is not possible to guarantee any pop-up window will appear. However, for the best chance of success, use this class to open a pop-up window only in code that executes as a direct result of a user action (for example, in an event handler for a mouse click or key-press event.)

From ActionScript, you can do the following on the HTML page:

Call any JavaScript function.
Pass any number of arguments, with any names.
Pass various data types (Boolean, Number, String, and so on).
Receive a return value from the JavaScript function.

From JavaScript on the HTML page, you can:

Call an ActionScript function.
Pass arguments using standard function call notation.
Return a value to the JavaScript function.

Note for Flash Player applications: Flash Player does not currently support SWF files embedded within HTML forms.

Note for AIR applications: In Adobe AIR, the ExternalInterface class can be used to communicate between JavaScript in an HTML page loaded in the HTMLLoader control and ActionScript in SWF content embedded in that HTML page.

The following example demonstrates sending data between Flash Player and an HTML container. package { import flash.display.Sprite; import flash.events.*; import flash.external.ExternalInterface; import flash.text.TextField; import flash.utils.Timer; import flash.text.TextFieldType; import flash.text.TextFieldAutoSize; public class ExternalInterfaceExample extends Sprite { private var input:TextField; private var output:TextField; private var sendBtn:Sprite; public function ExternalInterfaceExample() { input = new TextField(); input.type = TextFieldType.INPUT; input.background = true; input.border = true; input.width = 350; input.height = 18; addChild(input); sendBtn = new Sprite(); sendBtn.mouseEnabled = true; sendBtn.x = input.width + 10; sendBtn.graphics.beginFill(0xCCCCCC); sendBtn.graphics.drawRoundRect(0, 0, 80, 18, 10, 10); sendBtn.graphics.endFill(); sendBtn.addEventListener(MouseEvent.CLICK, clickHandler); addChild(sendBtn); output = new TextField(); output.y = 25; output.width = 450; output.height = 325; output.multiline = true; output.wordWrap = true; output.border = true; output.text = "Initializing...\n"; addChild(output); if (ExternalInterface.available) { try { output.appendText("Adding callback...\n"); ExternalInterface.addCallback("sendToActionScript", receivedFromJavaScript); if (checkJavaScriptReady()) { output.appendText("JavaScript is ready.\n"); } else { output.appendText("JavaScript is not ready, creating timer.\n"); var readyTimer:Timer = new Timer(100, 0); readyTimer.addEventListener(TimerEvent.TIMER, timerHandler); readyTimer.start(); } } catch (error:SecurityError) { output.appendText("A SecurityError occurred: " + error.message + "\n"); } catch (error:Error) { output.appendText("An Error occurred: " + error.message + "\n"); } } else { output.appendText("External interface is not available for this container."); } } private function receivedFromJavaScript(value:String):void { output.appendText("JavaScript says: " + value + "\n"); } private function checkJavaScriptReady():Boolean { var isReady:Boolean = ExternalInterface.call("isReady"); return isReady; } private function timerHandler(event:TimerEvent):void { output.appendText("Checking JavaScript status...\n"); var isReady:Boolean = checkJavaScriptReady(); if (isReady) { output.appendText("JavaScript is ready.\n"); Timer(event.target).stop(); } } private function clickHandler(event:MouseEvent):void { if (ExternalInterface.available) { ExternalInterface.call("sendToJavaScript", input.text); } } } } In order to test the previous ActionScript code, embed the generated SWF file using the following HTML template:  <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>ExternalInterfaceExample</title> <script language="JavaScript"> var jsReady = false; function isReady() { return jsReady; } function pageInit() { jsReady = true; document.forms["form1"].output.value += "\n" + "JavaScript is ready.\n"; } function thisMovie(movieName) { if (navigator.appName.indexOf("Microsoft") != -1) { return window[movieName]; } else { return document[movieName]; } } function sendToActionScript(value) { thisMovie("ExternalInterfaceExample").sendToActionScript(value); } function sendToJavaScript(value) { document.forms["form1"].output.value += "ActionScript says: " + value + "\n"; } </script> </head> <body onload="pageInit();"> <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" id="ExternalInterfaceExample" width="500" height="375" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab"> <param name="movie" value="ExternalInterfaceExample.swf" /> <param name="quality" value="high" /> <param name="bgcolor" value="#869ca7" /> <param name="allowScriptAccess" value="sameDomain" /> <embed src="ExternalInterfaceExample.swf" quality="high" bgcolor="#869ca7" width="500" height="375" name="ExternalInterfaceExample" align="middle" play="true" loop="false" quality="high" allowScriptAccess="sameDomain" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer"> </embed> </object> <form name="form1" onsubmit="return false;"> <input type="text" name="input" value="" /> <input type="button" value="Send" onclick="sendToActionScript(this.form.input.value);" /><br /> <textarea cols="60" rows="20" name="output" readonly="true">Initializing...</textarea> </form> </body> </html> addCallback Registers an ActionScript method as callable from the container.The container does not support incoming calls. Incoming calls are supported only in Internet Explorer for Windows and browsers that use the NPRuntime API such as Mozilla 1.7.5 and later or Firefox 1.0 and later. ErrorErrorA callback with the specified name has already been added by ActionScript in a sandbox to which you do not have access; you cannot overwrite that callback. To work around this problem, rewrite the ActionScript that originally called the addCallback() method so that it also calls the Security.allowDomain() method. SecurityErrorSecurityErrorThe containing environment belongs to a security sandbox to which the calling code does not have access. To fix this problem, follow these steps:

In the object tag for the SWF file in the containing HTML page, set the following parameter:
<param name="allowScriptAccess" value="always" />
In the SWF file, add the following ActionScript:
flash.system.Security.allowDomain(sourceDomain)

SecurityErrorSecurityErrorfunctionNameStringThe name by which the container can invoke the function. closureFunctionThe function closure to invoke. This could be a free-standing function, or it could be a method closure referencing a method of an object instance. By passing a method closure, you can direct the callback at a method of a particular object instance.

Note: Repeating addCallback() on an existing callback function with a null closure value removes the callback.

Registers an ActionScript method as callable from the container. After a successful invocation of addCallBack(), the registered function in the player can be called by JavaScript or ActiveX code in the container.

Note: For local content running in a browser, calls to the ExternalInterface.addCallback() method work only if the SWF file and the containing web page are in the local-trusted security sandbox. For more information, see the Flash Player Developer Center Topic: Security.

call Calls a function exposed by the SWF container, passing zero or more arguments.Should probably provide a link for the 4th paragraph above for info on Netscape. The container does not support outgoing calls. Outgoing calls are supported only in Internet Explorer for Windows and browsers that use the NPRuntime API such as Mozilla 1.7.5 and later or Firefox 1.0 and later. ErrorErrorThe containing environment belongs to a security sandbox to which the calling code does not have access. To fix this problem, follow these steps:

In the object tag for the SWF file in the containing HTML page, set the following parameter:
<param name="allowScriptAccess" value="always" />
In the SWF file, add the following ActionScript:
flash.system.Security.allowDomain(sourceDomain)

SecurityErrorSecurityErrorThe response received from the container. If the call failed– for example, if there is no such function in the container, the interface is not available, a recursion occurred (with a Netscape or Opera browser), or there is a security issue– null is returned and an error is thrown. functionNameStringThe alphanumeric name of the function to call in the container. Using a non-alphanumeric function name causes a runtime error (error 2155). You can use a try..catch block to handle the error. argumentsThe arguments to pass to the function in the container. You can specify zero or more parameters, separating them with commas. They can be of any ActionScript data type. When the call is to a JavaScript function, the ActionScript types are automatically converted into JavaScript types; when the call is to some other ActiveX container, the parameters are encoded in the request message. Calls a function in the container. Calls a function exposed by the SWF container, passing zero or more arguments. If the function is not available, the call returns null; otherwise it returns the value provided by the function. Recursion is not permitted on Opera or Netscape browsers; on these browsers a recursive call produces a null response. (Recursion is supported on Internet Explorer and Firefox browsers.)

If the container is an HTML page, this method invokes a JavaScript function in a script element.

If the container is another ActiveX container, this method dispatches the FlashCall ActiveX event with the specified name, and the container processes the event.

If the container is hosting the Netscape plug-in, you can either write custom support for the new NPRuntime interface or embed an HTML control and embed the player within the HTML control. If you embed an HTML control, you can communicate with the player through a JavaScript interface to the native container application.

Note: For local content running in a browser, calls to the ExternalInterface.call() method are permitted only if the SWF file and the containing web page (if there is one) are in the local-trusted security sandbox. Also, you can prevent a SWF file from using this method by setting the allowNetworking parameter of the object and embed tags in the HTML page that contains the SWF content. For more information, see the Flash Player Developer Center Topic: Security.

Note for Flash Player applications: In Flash Player 10 and Flash Player 9 Update 5, some web browsers restrict this method if a pop-up blocker is enabled. In this scenario, you can only call this method successfully in response to a user event (for example, in an event handler for a mouse click or keypress event).

The following example shows how you can use the ExternalInterface class (flash.external.ExternalInterface) to send a string from Flash Player to the HTML container where it is displayed using the JavaScript alert() function. Example provided by ActionScriptExamples.com. // // Requires: // - A Flash Professional Label component on the Stage with an instance name of "lbl". // - A Flash Professional Button component on the Stage with an instance name of "button". // var xmlResponse:String = "<invoke name=\"isReady\" returntype=\"xml\"><arguments><number>1</number><number>" + stage.stageWidth + "</number><number>" + stage.stageHeight + "</number></arguments></invoke>"; lbl.text = "ExternalInterface.available: " + ExternalInterface.available; lbl.width = 200; button.enabled = ExternalInterface.available; button.addEventListener(MouseEvent.CLICK, button_click); function button_click(evt:MouseEvent):void { ExternalInterface.call("alert", xmlResponse); } marshallExceptions Indicates whether the external interface should attempt to pass ActionScript exceptions to the current browser and JavaScript exceptions to the player.falseBooleanPasses exceptions between AS and JS. Indicates whether the external interface should attempt to pass ActionScript exceptions to the current browser and JavaScript exceptions to the player. You must explicitly set this property to true to catch JavaScript exceptions in ActionScript and to catch ActionScript exceptions in JavaScript. The following example creates an ActionScript function and registers it with the containing browser by using the addCallback() method. The new function throws an exception so that JavaScript code running in the browser can catch it. This example also contains a try..catch statement to catch any exceptions thrown by the browser when the throwit() function is called. package { import flash.external.* import flash.net.*; import flash.display.*; import flash.system.System; public class ext_test extends Sprite { function ext_test():void { ExternalInterface.marshallExceptions = true; ExternalInterface.addCallback("g", g); try { ExternalInterface.call("throwit"); } catch(e:Error) { trace(e) } } function g() { throw new Error("exception from actionscript!!!!") } } } available Indicates whether this player is in a container that offers an external interface.BooleanIndicates if the player is in a container that offers an external interface. Indicates whether this player is in a container that offers an external interface. If the external interface is available, this property is true; otherwise, it is false.

Note: When using the External API with HTML, always check that the HTML has finished loading before you attempt to call any JavaScript methods.

The following example uses the available property to determine whether the player is in a container that offers an external interface. package { import flash.text.TextField; import flash.display.MovieClip; import flash.external.ExternalInterface; public class extint_test extends MovieClip { public function extint_test() { var isAvailable:Boolean = ExternalInterface.available; var availTxt:TextField = new TextField(); availTxt.text = isAvailable.toString(); addChild(availTxt); } } } objectID Returns the id attribute of the object tag in Internet Explorer, or the name attribute of the embed tag in Netscape.String Returns the id attribute of the object tag in Internet Explorer, or the name attribute of the embed tag in Netscape.