Pre-requisites

In order to create an ANE you will need to download and install the following tooling.

PlayBook NDK 1.0 – https://bdsc.webapps.blackberry.com/native/
Once installed, this is what you will use to develop the native portion of our ANE.

Flash Builder 4.6 public pre-release – http://adobe.ly/qGRD3d
The current release version of Flash Builder, 4.5.1, does not contain support for ANE development. It is possible to use it with lots of work arounds, but it is better to simply sign up for the pre-release of 4.6.

Currently Flash Builder 4.6 only comes with the Flex 4.6 SDK, which requires you to have AIR 3.1, even if you are only creating an ActionScript project. So to get around this, I would recommend copying the 4.5.1 SDK from your Flash Builder 4.5/sdks folder before un-installing it and installing Flash Builder 4.6. This will allow you to develop ANE’s and target AIR 2.7.

Or you can download the latest Flex 4.5.1 SDK from the Flex open source site here. http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4.5 You will then need to download the AIR SDK and overlay it on top of the Flex SDK.
AIR SDK download – http://www.adobe.com/special/products/air/sdk/
Overlay instructions – http://kb2.adobe.com/cps/495/cpsid_49532.html

Hopefully that wasn’t too painful to get up and running and as more of these tools get officially released it will become easier.

Source code for the native and ActionScript implementations as well as a sample application can be downloaded here.

Developing the native library

Before you can start coding the native side there are a couple of things that are required in order to set up your project correctly.

First create a new project.
File > New > BlackBerry Tablet OS C/C++ Project

After you create name for you project you will be asked to select what type of project to create. Make sure to select Shared Library > Empty Project.

When you press Finish your project will be created. Once created select Project > Properties.

The Project Properties dialog is presented and we need to add the AirStub library to your build configuration.
1. Select C/C++ Build > Settings from the left menu.
2. Select QCC Linker > Libraries
3. Click the “+” Button in the Libraries Section.
4. Enter “AirStub” into the prompt.

You will need to do this to every Build Configuration you plan on using. To add the AirStub library to another configuration, select it from the Configuration drop down at the top of the dialog.

With that your project is ready to start coding. Create a new Source File and name it main.c, or something similar.

Throughout this article I will explain some of the native code, as we show some simple examples of how to interact with native code. For more information on all of the C methods read through the documentation on Adobe’s web site. http://help.adobe.com/en_US/air/extensions/index.html

You can also look through the FlashRuntimeExtensions.h header file to find all of the methods and properties.

I have attached a sample project that with this article and in the next section will explain the pieces of it.

Initializing the extension

void ExtInitializer(void** extDataToSet, FREContextInitializer* ctxInitializerToSet,
FREContextFinalizer* ctxFinalizerToSet) {
*extDataToSet = NULL;
*ctxInitializerToSet = &ContextInitializer;
*ctxFinalizerToSet = &ContextFinalizer;
}

The ExtInitializer method is called when your extension is initialized by your application. The method can be called whatever you want and is defined later on. However, the method signature must match the FREInitializer(). For more info check out the documentation here http://help.adobe.com/en_US/air/extensions/WSb464b1207c184b141a93a0d1129383bfc42-8000.html

This method sets pointers to the ContextInitializer and ContextFinalizer methods. Next let’s have a look at the ContextInitializer.

void ContextInitializer(void* extData, const uint8_t* ctxType,
FREContext ctx, uint32_t* numFunctionsToSet,
const FRENamedFunction** functionsToSet)
{
static FRENamedFunction s_classMethods[] =
{
{(const uint8_t *)"helloNative", NULL, helloNative},
{(const uint8_t *)"getElementAt", NULL, getElementAt},
{(const uint8_t *)"updateBitmap", NULL, updateBitmap},
};
const int c_methodCount = sizeof(s_classMethods) / sizeof(FRENamedFunction);
 
// Update caller with the required data
*functionsToSet = s_classMethods;
*numFunctionsToSet = c_methodCount;
}

Your context initializer method can be called anything as long as it matches the FREContextInitializer(). For more information have a look at the documentation here.
http://help.adobe.com/en_US/air/extensions/WSb464b1207c184b14-62b8e11f12937b86be4-7ffd.html

The purpose of this method is to set up a mapping to all of your methods that will be called from ActionScript. In our example we have 3 methods, helloNative, getElementAt, and updateBitmap. The first argument in the s_classMethods elements is the string that will be used to call the method from ActionScript. You will see how this works later on when we look at developing the ActionScript side.

The third argument is a reference to the native method. Although these 2 names can be different, it is best practice to keep them the same.

Once your methods are defined, update the pointers that where passed in to the function with the methods and the method count.

Before we look at the implementation of the native methods lets quickly take a look at the finalizer methods.

void ContextFinalizer(FREContext ctx) {
return;
}

When your extension context is unloaded the above method will be called. This is the opportunity to do any cleanup and dispose of any objects in your extension.

Creating native methods

Now that our methods are defined in our context initializer let’s create the native methods. All of the methods need to have the same method signature – FREFunction() – http://help.adobe.com/en_US/air/extensions/WSb464b1207c184b14-62b8e11f12937b86be4-7ffa.html

Here is what our helloNative method looks like.

FREObject helloNative(FREContext ctx, void* functionData, uint32_t argc, FREObject argv[]);

The first argument, FREContext ctx, is the context of the extension.
The second argument, void* functionData, is native data passed to the method. When setting up a mapping of the methods in the context initializer, the second parameter of the object was NULL. You could have created some data and had it passed in as this argument to our function.
The third argument, uint32_t argc, is the number of arguments passed from ActionScript.
The fourth argument, FREObject argv[], is an array of all the arguments passed from ActionScript.

The FREObject represents any ActionScript object of any data type. Every object passed from ActionScript will be of this type and every object returned from native to ActionScript must be of this type. You can see that the method signature for the method returns an FREObject. It is up to the native code to convert an FREObject into a native data type so it can work with it. Fortunately there are a number of methods to help with this. Here is a list of them and based on the name it should be fairly straightforward what does what.

FREGetObjectAsInt32 ( FREObject object, int32_t  *value );
FREGetObjectAsUInt32( FREObject object, uint32_t *value );
FREGetObjectAsDouble( FREObject object, double   *value );
FREGetObjectAsBool  ( FREObject object, uint32_t *value );
FREGetObjectAsUTF8( FREObject object, uint32_t* length,const uint8_t** value );

Suppose the first argument passed into your method was an int. You would do the following to convert the value.

int32_t index;
FREGetObjectAsInt32( argv[ 0 ], &index );

Setting a native data type to an FREObject to return to ActionScript is pretty much the same, but the reverse. You can see an example of this in the implementation of the helloNative method.

const char *out = "Hello Native\n";
FREObject result;
FRENewObjectFromUTF8((uint32_t)(strlen(out) + 1), (uint8_t*) out, &result);

These few simple concepts are the basics for creating native methods for ActionScript to call. The getElementAt() method shows how to easily access elements in an Array using native methods. The updateBitmap() method shows how to modify a BitmapData object from ActionScript and have it re-drawn with the new values. These examples should get you started on creating the native code for your ANE.

Coding the ActionScript implementation

Included in the sample there is a Flash Builder 4.6 Flex Library project called firstane. This project includes the ActionScript implementation of our ANE. The FirstANE class has 3 methods that mimic our native methods. It is good practice to do this whenever possible so methods are easy to map across the 2 code bases.

Creating the extension context

In the constructor of the class we create a reference in ActionScript to our extension context.

ext = ExtensionContext.createExtensionContext( "qnx.extensions.FirstANE", null );

The first argument is the ID of the extension. This can be anything you like, but should be something that is unique to you. Reverse domain is always a great standard. Later in this article we’ll show where to define this.

The second argument is an optional context type. This is passed to the context initialization method so that the native code can initialize different implementation based on a context. Most extensions will not require this, but more complicate extensions it may be useful.

Once we have a reference to the extension, native methods are now available to be called. Calling native methods are really simple. If we have a look at the getElementAt() method it shows how to call a native method with arguments and return the result from the native code.

public function getElementAt( items:Array, index:int ):String
{
return( ext.call( "getElementAt", items, index ) as String );
}

To call any native method the ExtensionContext.call() method is used – http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/external/ExtensionContext.html#call()

The first parameter is the string that you used in the context initializer. This is the method that we are going to call.

The second and third parameters are arguments that are passed to the native method.

The returned value of the call() method is the value returned from the native method. Because this could be any data type, it is necessary to cast it to the type that the method is expecting.

Defining the extension

In the bin folder of the firstane project there is an extension.xml file. This is the file that is used to define the extension. Here is what it looks like.

<extension xmlns="http://ns.adobe.com/air/extension/2.5">
    <id>qnx.extensions.FirstANE</id>
    <versionNumber>1</versionNumber>
    <platforms>
        <platform name="QNX-ARM">
           <applicationDeployment> 
		<nativeLibrary>libfirstane.so</nativeLibrary> 
		<initializer>ExtInitializer</initializer>
	          	<finalizer>ExtFinalizer</finalizer>
	</applicationDeployment>
        </platform>
    </platforms>
</extension>

The node is the root node and the version at the end must be 2.5. This value is not the same as the AIR Runtime version you are targeting. Even if your application is targeting AIR 3.0, the extension namespace must be http://ns.adobe.com/air/extension/2.5.

The node is extension id is defined. This is the same value that is passed into the ExtensionContext.createExtensionContext() method in ActionScript.

The is the version number of your extension.

The node is a list of nodes that define all of the platforms the extension supports.

The BlackBerry PlayBook supports 2 platforms, QNX-ARM for the PlayBook hardware, and QNX-x86 for the PlayBook Simulator.

One thing that is a really good idea is to implement a default platform for when application runs on a platform that is not supported. For, example you may create native libraries for both the PlayBook device and simulator, but what happens when you want to test your application locally on your development machine. If the API’s only exist on the PlayBook platforms your application will not run locally on Windows or OSX. To accomplish this you can create a “default” platform that is ActionScript only. This allows you to implement default behavior for your API and allow you to fail gracefully or provide alternate implementations.

For more details on the extension descriptor file check out the Adobe documentation here. http://help.adobe.com/en_US/air/extensions/WS901d38e593cd1bac-3004221412afa24c001-8000.html

Compiling the extension

In order to compile the extension you must use the adt command line tool that comes with the AIR SDK.

First you must un-zip the firstane.swc. SWC files are simply zip files that contain a library.swf and a catalog.xml. You will need the library.swf to be compiled with each platform, and it must be named library.swf. You can dispose the catalog.xml file, as it is not needed.

To make life easier I have placed the firstane.so, firstane.swc, library.swf, and extension.xml all in the same directory. Here is the command to compile your ane.

adt –package –target ane firstane.ane extension.xml –swc firstane.swc –platform QNX-ARM –C . firstane.so library.swf

For BlackBerry PlayBook ANE files it is not necessary to sign them and is optional.

Using a ANE

In order to use an ANE, it is best to simply follow the instructions in the Flash Builder 4.6 pre-release site. The only difference for the BlackBerry platform is an additional permission is needed in the apps blackberry-tablet.xml file.

run_air_native

Included in the source is a Flash Builder project called firstaneapp that shows how to use the application. You will most likely have to fix the path to the .ane in the project file, but it should give you an idea on how to use it.

Conclusion

Hopefully this gets you started in creating ActionScript Native Extensions for the BlackBerry PlayBook. All of the C API documentation from Adobe on ANE’s applies to the PlayBook. With all of the documentation out there, this article and the sample projects, hopefully it gets you well under way.

That all being said I just made a fairly big commit today to the google code repository. It isn’t fully featured yet and only supports the svn:// protocol. Once I get some more of that protocol completed I plan on doing the http:// protocol. In the wiki there is an example AIR app that allows you to display directories in a tree, export files and folders, as well as trace out the log for any item in the repository.

This is still a work in progress and lots to do before it gets to a really stable state. For instance the Error handling is almost non-existent but I have placed a lot of //TODO where the errors need to be thrown. I also only have 1 svn server to test on so I am not sure how running it in other environments will work out.

I have created the library to a point where I can create our internal app, so I am not entirely sure what features I will tackle next. I may try doing commit and add, but those are fairly big. So if you have any requests I am all ears.

1. Copy and paste the code below into a blank fla in CS4.
2. Compile the swf and save a file.
3. Close the swf
4. repeat step 2
5. Open the test.txt file.

I am on OSX and haven’t tested on a PC.

var str:String = "12345";
var ba:ByteArray = new ByteArray();
ba.writeUTFBytes( str );
 
var fr:FileReference = new FileReference();
fr.save(ba, "test.txt");

I did a quick search on the Adobe bug base and found some related issues from 2008 but they where for downloading files from the net.