Creating AIR Native Extensions for BB10

Before Starting

You will have to have installed and configured both the BlackBerry® Native SDK 2.0 for BlackBerry® Tablet OS and the BlackBerry Tablet OS SDK 2.0 for Adobe® Air®. We’re also going to use Adobe® Flash Builder® to create the Adobe® ActionScript® side and the sample application. However, you are able to accomplish the same tasks using the command line only.

If you’re planning to test the application shown here in an actual device, make sure you have requested code signing keys and created debug tokens. The simulator doesn’t require debug token for testing. For more information on code signing, refer to this link: https://bdsc.webapps.blackberry.com/CodeSigningHelp/

Tools you are going to need

Adobe® Flash Builder® 4.6 (optional – command line tools can also be used)

Adobe® Air® SDK 2.7

BlackBerry Tablet OS SDK for Adobe Air 2.0 or later.

What is Air Native Extension (ANE)?

An ANE is a combination of ActionScript and Native code, allowing developers to extend Air runtime capabilities in areas where the core runtime doesn’t cover, normally related to device-specific capabilities.

As probably you already know, Air applications run in a protected environment (sandbox), and because of that such application doesn’t have full access to the system resources. The native extension interface allows native code to run still keeping the Air security model.

As you can see, the code above implements the ActionScript side of the method sayHello(), which will actually be calling the shared object functions with the same name.

Note: The string "com.example.NativeCode" matches the name used on the native extension project created using the NDK.

Next, we will be creating the native code itself, and using the new NDK tooling to create the ANE file.

Creating the Native side

Setup

A native extension is no more thsn a C/C++ shared object, which contains certain functions that act as entry-points to setup the interface used by the ActionScript code. Again, for details about the ANE structure, check the document mentioned above.

For this tutorial, I am using the Blackberry Native SDK 2.0, available at Blackberry Developer Zone, and I am assuming you have basic familiarity with the IDE, and you read the Getting Started Guide. The version 2.0 brought new tools that help the native extension creation, from project templates to creating the final product.

That said, let’s get started creating our shared object:

Open the NDK for BlackBerry Tablet OS.

Select File -> New -> BlackBerry Tablet OS C/C++ Project.

Give this project the name NativeCode, and click Next.

On the next step you will be presented to several project types. Select under the new AIR Native Extension the Hello AIR Native Extension option.

Click Finish.

At this point, your project will be created. Note that if this is the first time you are using the NDK, the Deployment Setup Wizard will be displayed, allowing you to configure your environment. Check the BlackBerry Native SDK Getting Started Guide and User Guide for more information about it.

This project template contais the barebones of a native extension, and a function called sayHello, which will be used to demonstrate the whole process.

In this tutorial, I’m going to create the shared object to be used on the device and also on the simulator. Remember that the simulator uses x86 binaries whereas the Playbook uses arm7.

It is not the scope of this tutorial explaining details of the code above, but there few highlights that worth mentioning:

FlashRuntimeExtensions.h is provided by Adobe, but it is already available in the NDK.

The function sayHello() is the one you will be able to call directly from your ActionScript code.

The initializer/finalizer functions are mandatory and part of the ANE interface between the ActionScript and the native code.

Building the Project

In this tutorial, I’m going to create the shared object to be used on the device and also on the simulator. Remember that the simulator uses x86 binaries whereas the Playbook uses arm7.

To build the only Device-Debug and Simulator-Debug targets at once, the best way is:

Right-click the project name on your Project Explorer view

Select Build Configurations… -> Build Selected…. The following dialog will be displayed:

3. Select Device-Debug and Simulator-Debug, and click OK.

4. After the build is done, you will see both binaries created: libNativeCode-arm.so and libNativeCode-x86.so

Creating the ANE file

The NDK 2.0 does an excellent job helping you to create the native extension file (ANE) with few steps. For that, you just have to:

Open the NDK IDE, and select the NativeCode project.

Right-click and select Export.

On the Export dialog, select BlackBerry Tablet OS -> AIR Native Extension. The following dialog box will be displayed:

4. Change the Base filename to com.example. This is not mandatory, but only to keep the steps clearer in this tutorial

5. The AIR SDK field has to point to the Flash Builder sdks folder (as illustrated above), or the place where the standalone Air SDK was installed.

6. Library SWC should be filled in with the NativeAS3.swc file you created before using Flash Builder.

7. Click Finish to start the build process.

Note: If during the build process, you see an error message like "Invalid swc file. The extension NameSpace requires the SWF verison to be 13 or lower", you will have to go back to the Flash Builder project and add the compiler parameter "-swf-version 13" (Project Properties -> Flex Library Compiler) to force the right swf version for the library.

If everything is fine, you will see a com.example.ane file created in the NDK Project Explorer. This file will be used in the next section, to create the sample application that uses the native extension.

Creating the Sample Air Application

The sample Air application is a simple application that will use the ANE. For this tutorial it will consist in a simple screen with the button Hello. To create the project, and assigning the ANE file you should:

1. Create a new ActionScript Mobile project, and call it UsingANE.

2. Unselect iOS and Android support (optional)

3. The last step on the New Project wizard has three tabs: Source Path, Library Path and Native Extensions. Select the latter.

8. On the same dialog, click the Native Extensions tab. You'll see the com.example.ane file is listed there, but you also have to select to add it to the Package. If you don't see the checkbox after the com.example.ane item, you have to enlarge the dialog in order to see it.

9. To add the ANE to the BAR file, check to option Package. At this point, Flash Builder will ask for confirmation. Just confirm and click OK to close the project Properties.

Your sample application should also be informed that the native extension called com.example.NativeAS3 is present and available to be used. Since you've added the native extension using Flash Builder tools, this is already done, but if you are using command line instead, you must add the highlighted tag <extensions> in your *-app.xml file (in our case UningANE-app.xml):

Deploying to the Playbook

To be able to run native code from an Air application, you must add to the bar file descriptor (blackberry-tablet.xml or bar-descriptor.xml) the appropriated <action> tag:

<action system="true">run_air_native</action>

As you probably know, when deploying to an actual device, not the simulator, you have to use a debug token or sign the .bar file.

Only the Air application that will use and call native methods, has to be sign, so in our tutorial, only the UsingANE must be signed. It is not necessary to sign the shared object created with NDK 1.0 or the ActionScript library (.swc file).