Recent Posts

Recent Comments

Archives

Blackberry

Creating AIR Native Extensions for BlackBerry PlayBook

The PlayBook NDK 1.0 was released at BlackBerry DevCon Americas 2011 this week and with it comes the ability to create AIR Native Extensions. AIR Native Extensions is one of the big features available in AIR 3.0 on all other platforms. However, Native Extensions have been available in the AIR Runtime on the PlayBook since it launched. So when developing your application and your ANE, it is not necessary to target AIR 3.0. You can target AIR 2.7 and the BlackBerry Tablet OS 1.0.7 if you like.

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 > Libraries3. 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.

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 herehttp://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.

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

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.

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.

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.

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.

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.

Continue reading » · Rating: · Written on: 10-25-11 · 7 Comments »

AS3 SVN Library

A few months ago I started writing a svn protocol library in as3. It started with an idea for a internal tool that would allow us to select files from our svn code repository and export it and all of it’s code dependencies. And because I haven’t done a lot of work with ByteArray, or Sockets before I was pretty excited about giving this a shot. My first attempts where really rough and basic and worked for the most part, but were in no shape to be in the form of a nice library. I let it sit for a while as I was busy getting ready for FOTB and Flashpitt. Then one night I started doing some more research about the protocol and found that SVNKit, a Java SVN library, was open source. So I started going through all the source and spent a great deal of time going through how the code was structured. I couldn’t just do a straight port because of the differences that data gets returned between Java and AS3. Long story short the way they have it set up is you can make the call to the server and on the next line read the input. In AS3 you need to wait for your event to come back, and there is no guarantees that all of it is going to come back in one event either. But I was able to port some important parts like reading and writing the data. I’ve tried to keep the API’s similar, but there are instances where they just couldn’t be or didn’t make sense to. One of my goals for this project to is to make it as platform independent as possible. And by that I mean I want you to be able to use the library in the web, air, and any other Flash Player 10 player. I’ve tried to abstract out the parts that deal with writing files to disk so that this could be accomplished. But there may come a point where a feature may need AIR for whatever reason. But I’ll cross that bridge when I get to it. If that feature isn’t a super high priority chances are I will leave it out just for that reason.

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.

Continue reading » · Rating: · Written on: 11-13-09 · 5 Comments »

AS3 FP10 FileReference.save bug

While playing with FileReference.save today in Flash Player 10 I found a REALLY REALLY BIG BUG. It seems that if you go to overwrite a file it appends it’s contents instead of replacing.

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 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.

Continue reading » · Rating: · Written on: 08-04-09 · 4 Comments »

gotoAndStop in AS3

I have been busy re-writing our AS2 libraries to AS3 this week and encountered something that will easily trip up most people. And of course I didn’t see it in any documentation anywhere. Basically the issue is that in AS2 when you navigated to a frame using mc.gotoAndStop() you would have access to all the elements on that frame. But now in AS3 they aren’t available right away. I found a great post by Senocular that explains this and shows the solution. Check out the post here.