With the release of AIR 2, developers were given the option in desktop AIR to interface with native processes on the host operating system. This was great, as it meant that an AIR application could be somewhat extended by passing messages back and forth between the application and a running process. It wasn’t ideal though, and wasn’t available for mobile AIR projects.

Now, with AIR 3 we have something much more powerful at our disposal: ActionScript Native Extensions (ANE). This new functionality allows a developer to write the bulk of an application in ActionScript but also provide a portion of it in the language of the native operating system in order to extend the AIR runtime itself, providing hooks into hitherto untouchable possibilities.

For example, while the AIR runtime has native support for sensors like the accelerometer on iOS or Android…it does not provide any way of tapping into a gyroscope, barometer, or vibration component of the device, which may be present. Likewise, core OS data and functionality such as the device contact list or the ability to transmit notifications remain completely hidden from AIR. With ANEs, a developer can write the code to extend the capabilities of AIR in order to access such things within the application.

In this example, we will use a Vibrator ANE developed for use on Android. An ANE is similar to a SWC and is included in our project through a very familiar method. In this example, we’ll use Flash Builder 4.6 to include the Vibrator ANE into an AIR for Android project. Choose the project you are working on and click File > Properties. This will open up the Properties dialog in which you will choose ActionScript Build Path (alternatively: Flex Build Path) on the left and choose the Native Extensions tab. Here you may click the button labeled Add ANE…and simply browse to the ANE file you wish to build into your project.

Figure 8-1. Vibrator ANE added to mobile project

Next, we will need to be sure and package the ANE into our build settings. With the Properties window still open, click ActionScript Build Packaging (alternatively: Flex Build Packaging) on the left and choose the Native Extensions tab. Here, we simply select which ANE files we want to include with our build for each platform. This is a major difference between ANE and SWC in that ANE must be packaged separately in this manner.

Figure 8-2. Including an ANE into the build package

When using an ANE on Android, we may also need to include various permissions within the <android> node of our application descriptor file. Here, we add permissions for vibrate.

<android>
    <manifestAdditions><![CDATA[
        <manifest android:installLocation="auto">
            <uses-permission android:name="android.permission.INTERNET"/>
            <uses-permission android:name="android.permission.VIBRATE"/>
        </manifest>
    ]]></manifestAdditions>
</android>

For any extensions we add to a project, we must declare them within the application descriptor file root as demonstrated here. Flash Builder 4.6 will actually perform this action for us, if desired.

<extensions>
    <extensionID>com.adobe.Vibrator</extensionID>
</extensions>

To effectively use this Vibrator ANE within our project, we must first import the Vibrator class. We can then instantiate a new Vibrator object and invoke Vibrator.vibrate() whenever we wish to cause our device to vibrate. Passing in a certain number of milliseconds as an argument will instruct the device to vibrate for that specific length of time. In the example below, we cause the device to vibrate based upon the user touching the Stage, and display a message along with the current reading from the flash.utils.getTimer class.

package {
    import com.adobe.nativeExtensions.Vibrator.Vibrator;

    import flash.display.Sprite;
    import flash.display.StageAlign;
    import flash.display.StageScaleMode;
    import flash.events.MouseEvent;
    import flash.text.TextField;
    import flash.text.TextFormat;
    import flash.utils.getTimer;

    [SWF(backgroundColor="#000000")]

    public class MobileVibrate extends Sprite {

        private var traceField:TextField;
        private var vibrator:Vibrator;

        public function MobileVibrate() {
            super();
            stage.scaleMode = StageScaleMode.NO_SCALE;
            stage.align = StageAlign.TOP_LEFT;

            generateDisplayObjects();
            performOperations();
        }

        protected function generateDisplayObjects():void {
            var defaultFormat:TextFormat = new TextFormat();
            defaultFormat.font = "Arial";
            defaultFormat.size = 36;
            defaultFormat.color = 0xFFFFFF;

            traceField = new TextField();
            traceField.backgroundColor = 0x000000;
            traceField.alpha = 0.7;
            traceField.width = stage.stageWidth;
            traceField.height = stage.stageHeight;
            traceField.wordWrap = true;
            traceField.multiline = true;
            traceField.background = true;
            traceField.defaultTextFormat = defaultFormat;
            addChild(traceField);
        }

        protected function performOperations():void {
            if(Vibrator.isSupported){
                vibrator = new Vibrator();
                stage.addEventListener(MouseEvent.CLICK, performVibration);
                traceField.appendText("Click anywhere to vibrate device...

");
            }else{
                traceField.appendText("Vibrator not supported!!!");
            }
        }

        protected function performVibration(e:MouseEvent):void {
            vibrator.vibrate(1000);
            traceField.appendText("VIBRATE! [" + getTimer() + "]
");
        }

    }
}

When this code is compiled to APK and run on Android, it will appear similar to Figure 8-3.

Figure 8-3. Vibration ANE on Android