deleteaso

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

Currently with the PlayBook 1.0.1 AIR SDK the error reporting for signing and debug token issues can be far too generic. The biggest culprit of this is the BarSigner 500 unsigned error. The team is actively working on returning more specific error messages for all the various use cases. In the meantime here is a list of the reasons why this error would occur. Hopefully this will help you debug the issue faster when you see this error.

• There is no debug token on the device.
• The debug token on the device has expired.
• The debug token author does not match the author of the application being deployed.
• The debug token author id does not match the author id of the application being deployed.

The process for developing and deploying applications to the PlayBook simulator is a little different then that of the device. For the simulator you simply place it into development mode and you can deploy your un-signed applications. There are 2 additional steps that you need to do in order to deploy and debug your applications on the device.

The first step is to create and upload a debug token to the device. This entire step can be done with the command line, but is much easier to do with the Flash Builder plugin. Before you can create your debug token you must sign up for signing keys. This can be done from the BlackBerry Developer Zone form found here. You should get your keys the following day so may sure to sign up for your keys early so you aren’t waiting a day to develop for the device. What the debug token does is associates your application with you and your device. Watch the video below for a complete list of steps on how to create and upload.

The second thing you need to do is add the author and authorId tags to your blackberry-tablet.xml file. This associates your application with your debug token and allows it to run on any device with that debug token installed on it. With this you should be able to deploy your application to your device as many times as you need.

The alternative to using debug tokens is to sign your application every time you want to load it on to the device. This would mean that for every little code change it would need to be re-signed. There are 2 things to keep in mind when signing your application. The first is that the version number has to be incremented every single time you sign your application. If you try to sign an application with the same version number it will throw an error. You can read this page for more information about assigning a version number to your application. The second thing to keep in mind is you need to be connected to the internet in order to sign your application. Having to do these 2 things every time you wanted to test your application on the device is unreasonable, which is why debug tokens were created in order to provide greater flexibility in developing and deploying to the actual device.

If you have gone through and followed all the steps in the video below for creating debug tokens, your applications is all ready to be signed. It is as simple as right clicking on the project and selecting Export. I hope the video below helps you get your application on deployed to the device.

PlayBook Debug Tokens and Signing from Julian Dolce on Vimeo.

The most recent release of the Adobe AIR SDK is version 2.6. With this version of the SDK you can target the AIR 2.6 runtime on multiple platforms. However, one platform that you cannot yet target yet is the BlackBerry PlayBook. At launch the PlayBook, device and simulator, only support the AIR 2.5 runtime. This means that any application which targets anything higher then AIR 2.5 will not work on the PlayBook. There are a couple of things to consider when developing for PlayBook using the AIR 2.6 SDK.

The first and biggest issue is that the newer versions of the Flex 4.5 Hero Framework only support AIR 2.6. This means that you will only be able to create ActionScript only projects, which do not use any of the Flex Hero components. The public preview of Flash Builder 4.5, which is available on Adobe Labs, contains a very early version of the Flex Hero Framework and targets AIR 2.5, which is why this works today. However, when Flash Builder 4.5 ships and anyone using the pre-release version will not be able to create Flex Hero applications for the PlayBook until the runtime is updated.

When using Flash Builder and the AIR 2.6 SDK for developing your applications, Flash Builder will auto generate a application descriptor file, which targets the AIR 2.6 runtime. If you try to run this in the Simulator or on the PlayBook device the application will instantly crash without any real reason. There are 2 small items that you can do in order to workaround this issue. These steps are meant to be done with the BlackBerry Tablet OS AIR SDK 1.0.1

First, you need to make sure you compile your swf to Flash Player 10. This can easily be done with the following command if you are using the command line. -swf-version=10. If you are using Flash Builder you can go to Project > Properties > ActionScript Compiler and place it into the Additional Compiler Arguments field.

The second thing you need to do is force your application to target the AIR 2.5 runtime. Because you may be targeting AIR 2.6 for other platforms you do not want to change it directly in the -app.xml file. To get around this the PlayBook has an option to force the air version to a specific value when packaging your application. To set this you can use the following command on the command line -forceAirVersion 2.5. Or if you are using Flash Builder you can go to Project > Properties > ActionScript Build Packaging > BlackBerry Tablet OS > Advanced and place the command in the extra packaging options field.

With these 2 workarounds you should be able to now target AIR 2.6 for iOS and Android and 2.5 for the PlayBook. I hope that helps solve some of the confusion people are having

With the new release of the BlackBerry Tablet SDK 1.0.1 and the release of the PlayBook device, there is a new application capability that is required to access the PIN and serial number of the device. To access these properties in the SDK you can use the Device.pin and Device.serialNumber properties. However, if accessing these you must make sure you take into consideration that these values may be null. This will happen if the user does not grant your application permission to read those values. And we all know what happens when you try to access a null object in ActionScript. Crashy Crashy. Here is the documentation for the Device class as well as more information on add permissions to your application.

You will also need to re-compile your application with the 1.0.1 SDK in order to make this work correctly.

With the release of the PlayBook Tablet OS AIR SDK 1.0.1 we have improved the installation process greatly. With previous beta releases we realize, and heard clearly from the community, that it was difficult to get everything set up just right as there were a lot of steps and different options. We have done a great job at removing as many of the steps from the process as possible.

First, the SDK and the Simulator are 1 download and there is no longer 2 separate installers. When installing the SDK into Flash Builder it now supports 3 different versions, Flash Builder 4.0.1, Flash Builder “Burrito” Preview, which is available on Adobe Labs, and later pre-release versions of Flash Builder 4.5, which are available to Adobe pre-release members. This should save you from having multiple installs of Flash Builder on your machine. Also, the installer will now accept an AIR SDK which is 2.5 or higher. This means that you can use the AIR 2.6 SDK and any other future releases. The catch with this is that the Simulator and actual hardware only support the AIR 2.5 runtime and if your application targets anything higher it will crash.

Once you have the SDK installed you are ready to get the Simulator set up. Instead of installing an .iso for the Simulator we now ship an actual VMWare image, which you can simply open in VMWare. This image has the Simulator already set up with a default password, “playbook”, and already has Development Mode turned on by default. This removes a lot of the steps in previous beta releases to get the iso installed with the right settings. Also, the EULA has been removed and you no longer have to scroll through it entirely to accept it.

With these changes we have greatly reduced the number of clicks and documentation reading required to get developers up and running. We still have other things we want to improve and will be working on for upcoming releases. I can honestly say that these changes are a direct result of community feedback. Hopefully this is the first step into showing the community that we are truly listening to your feedback and want to make the process for developing application for the PlayBook, no matter which runtime on the device you are targeting, the best development experience out there.

Here is a video of the entire installation process.

BlackBerry Tablet OS AIR SDK 1.0.1 Installation from Julian Dolce on Vimeo.

If you didn’t get a chance to go to Adobe MAX in person this year you missed out on a great conference. I had only been to one previous to this year, but from what everyone was saying it was one of the best MAX conferences. The biggest announcements came from other companies working with Adobe who are bring the AIR runtime to other platforms. Last years big announcements where focused on AIR on mobile device platforms, and this year they have moved to the TV. As an AIR developer you have to be excited on how many different screens you can easily put your content on.

The newest platform to adopt the AIR runtime is the BlackBerry Tablet OS and the BlackBerry PlayBook. I have been working hard on the AIR SDK for this platform, which we released publicly at MAX. Mike Lazaridis, RIM co-CEO, gave the first live public demo of the PlayBook. Here is the video from the day one keynote showing the PlayBook.

I also had the pleasure of giving 2 session on developing AIR Applications for the BlackBerry Tablet OS. Both sessions where completely booked and I had great response from everybody. It was great to see and talk to so many people who are interested in getting started with the SDK. The recording of the session is live on the Adobe MAX website.

http://2010.max.adobe.com/online/2010/MAX260_1288217641375UQJD

This week my first book will be released, Android Development with Flash. I am pretty excited to see it in print and on the shelf in store. This book has a very interesting story behind it. Back in January of 2010 I had started writing a book for the CS5 iPhone Packager. Literally 2 days after I had sent the final edits back, Apple had mad the announcement that they where not going to allow the use of third party tools to develop applications. I was pretty disappointed for about a week, but then the AIR Android pre-release was made available, and I began rewriting the book for Android. I spent the next 2 months feverishly tweaking and adding features to the book. Fast forward to September and a few weeks before it is set to be released, Apple removes the restriction on third party applications, and it looks like the original iPhone version will be released as well hopefully by the end of the year. I have to say that working with everyone at Wiley was amazing to work with. I was really nervous about writing my first book and everyone there helped me a great deal getting through it. It was a really great experience and I would recommend working with Wiley to anyone.

Here are some links to where you can buy it.
Wiley
Amazon US – Amazon Canada
Chapters

I started a new blog today in conjunction with the launch of CS5, www.flashiphonedevelopment.com. It is strictly going to focus on iPhone development from a Flash developers perspective. There will be a lot of Flash CS5 iPhone Packager content, as well as a resource for learning Objective-C and the iPhone SDK from a Flash development perspective. I have lots of great stuff planned for it and with a little faith this whole Adobe vs. Apple fiasco will fade away.

It has been a long time since my last post and have been fairly quiet over the last 4-5 months. 2010 so far has been a year of first and big changes.

Since January I have been working on writing my first book. It has been on my list of things to do ever since I started my career, but never really thought it would happen. So when I was approached to write one on the new Flash iPhone Packager last November I could not pass up the opportunity. It has been a really intense process and has kept me quite busy over the last 3 months. This week I will be finishing up the last few chapter edits, and it should be available sometime in June.

April 1st, 2003 was my first day at Fuel Industries, and 7 years and a week later, yesterday was my last day. The last 7 years has been an amazing journey and have learned and seen so much.  Working at Fuel has provided me with so many opportunities that I would not have had working elsewhere. The wide variety of types of projects has exposed me to so many new and different technologies, which has helped me become a better programmer. I was also fortunate enough to travel and see many parts of the world that I would not have seen on my own. The friends that I have made there will last forever, and it was hard to say goodbye to them.

So what’s next? In a couple of weeks I am going to start work at QNX here in Ottawa. QNX is a pretty cool company and you may have seen their QNX car on display at Adobe Max last year. QNX develops an operating system for embedded devices, which has a Flash layer which can be used to create interfaces and applications which run on their OS. I can’t talk about what I will be doing too much yet, but will once I get settled there.

2010 is turning out to be a pretty monumental year, and has been a great way to start a new decade. I am really looking forward to what the rest of the year and decade has in store for me. I’ll be at FiTC for Saturday and Sunday only. So if you ar0und let’s grab a drink.