Using native extensions for Adobe AIR

Native extension developers package a native extension into an ANE file. An ANE file is an archive file that contains the necessary libraries and resources for the native extension.

Note for some devices, the ANE file contains the native code library that the native extension uses. But for other devices, the native code library is installed on the device. In some cases, the native extension has no native code at all for a particular device; it is implemented with ActionScript only.

As an AIR application developer, you use the ANE file as follows:

ActionScript 3.0 provides a NativeProcess class. This class lets an AIR application execute native processes on the host operating system. This capability is similar to native extensions, which provide access to platform-specific features and libraries. When deciding on using the NativeProcess class versus using a native extension, consider the following:

• Only the extendedDesktop AIR profile supports the NativeProcess class. Therefore, for applications with the AIR profiles mobileDevice and extendedMobileDevice, native extensions are the only choice.

• Native extension developers often provide native implementations for various platforms, but the ActionScript API they provide is typically the same across platforms. When using the NativeProcess class, ActionScript code to start the native process can vary among the different platforms.

• The NativeProcess class starts a separate process, whereas a native extension runs in the same process as the AIR application. Therefore, if you are concerned about code crashing, using the NativeProcess class is safer. However, the separate process means that you possibly have interprocess communication handling to implement.

A SWC file is an ActionScript class library in an archive format. The SWC file contains a SWF file and other resource files. The SWC file is a convenient way to share ActionScript classes instead of sharing individual ActionScript code and resource files.

A native extension package is an ANE file. Like a SWC file, an ANE file is also an ActionScript class library, containing a SWF file and other resource files in an archive format. However, the most important difference between an ANE file and a SWC file is that only an ANE file can contain a native code library.

Starting in AIR 3, you can use native extensions in applications for the following devices:

Often, the same native extension targets multiple platforms. The extension’s ANE file contains ActionScript and native libraries for each supported platform. Usually, the ActionScript libraries have the same public interfaces for all the platforms. The native libraries are necessarily different.

Sometimes a native extension supports a default platform. The default platform’s implementation has only ActionScript code, but no native code. If you package an application for a platform that the extension does not specifically support, the application uses the default implementation when it executes. For example, consider an extension that provides a feature that applies only to mobile devices. The extension can also provide a default implementation that a desktop application can use to simulate the feature.

The following AIR profiles support native extensions:

To use a native extension in your application, do the following tasks:

1. Declare the extension in your application descriptor file.

2. Include the ANE file in your application’s library path.

3. Package the application.

All AIR applications have an application descriptor file. When an application uses a native extension, the application descriptor file includes an <extensions> element. For example:

<extensions> 
    <extensionID>com.example.Extension1</extensionID> 
    <extensionID>com.example.Extension2</extensionID> 
</extensions>

The extensionID element has the same value as the id element in the extension descriptor file. The extension descriptor file is an XML file called extension.xml. It is packaged in the ANE file. You can use an archive extractor tool to look at the extension.xml file.

To compile an application that uses a native extension, include the ANE file in your library path.

Use ADT to package an application that uses native extensions. You cannot package the application using Flash Professional CS5.5 or Flash Builder 4.5.1.

Details about using ADT are at AIR Developer Tool (ADT).

For example, the following ADT command creates a DMG file (a native installer file for Mac OS X) for an application that uses native extensions:

adt -package 
    -storetype pkcs12 
    -keystore myCert.pfx 
    -target native 
    myApp.dmg 
    application.xml 
    index.html resources 
    -extdir extensionsDir

adt -package 
    -target apk 
    -storetype pkcs12 -keystore ../codesign.p12 
    myApp.apk 
    myApp-app.xml 
    myApp.swf icons 
    -extdir extensionsDir

The following command creates an iOS package for an iPhone application:

adt -package 
    -target ipa-ad-hoc 
    -storetype pkcs12 -keystore ../AppleDistribution.p12 
    -provisioning-profile AppleDistribution.mobileprofile 
    myApp.ipa 
    myApp-app.xml 
    myApp.swf icons Default.png 
    -extdir extensionsDir

Note the following:

• Use a native installer package type.

• Specify the extension directory.

• Make sure that the ANE file supports the application’s target device.