Windows ANE tutorial: The AIR library

At the end of this part you will have:

An AIR library, ready to be packaged in an AIR Native Extension for Windows.

Time

10-15 minutes

You’ll like this: You can download the packaged Windows ANE and the complete source code for this tutorial here.

Wait, have you done this first?

Part 1: The native DLL project, 8-10 minutes
Part 2: The Native DLL code, 10-15 minutes

The first two parts of this tutorial walk you through building the native Windows library that your ANE will use. If you haven’t done that yet, you can do it after this part, but make sure you have a DLL built before you move on to packaging the ANE.

Step 1: Create a Flex Library Project

Note: You don’t need to read this step in detail if you already know how to set up a Flex Library.

In Flash Builder select File > New > Flex Library Project:

In the dialog that appears, tick Include Adobe AIR libraries. Name your project and save it. I have named mine DiaDrawWindowsANETutorialAIRLib:

Leave the next step of the New Flex Library dialog set as default and click Finish to create your AIR library project.

Step 2: Create the AIR wrapper for your ANE

In this step you’ll add an ActionScript class to your AIR library, whose purpose will be to talk to Windows.

Add a new ActionScript class to the src/ folder of your project, name it WindowsExtensionWrapper, set its superclass to flash.events.EventDispatcher and put it in a package of your choice: mine is com.diadraw.extensions.

Why subclass EventDispatcher?

A lot of the work that happens in an Adobe AIR Native Extension is asynchronous. Getting asynchronous events from your Windows DLL is also one of the few ways that the code in the DLL can communicate with your AIR library. Making your extension wrapper inherit EventDispatcher allows you to pass these events back to an app that uses your ANE.

I won’t cover passing messages on Windows in this tutorial. Unless you scream loud and clear in the comments below, of course.

Do you remember the slightly lopsided way in which ActionScript and native code talk to one another? Click here for a quick reminder with cartoons.

Flash Builder will automatically create this for you:

package com.diadraw.extensions
{
	import flash.events.EventDispatcher;
	import flash.events.IEventDispatcher;

	public class WindowsExtensionWrapper extends EventDispatcher
	{
		public function WindowsExtensionWrapper(target:IEventDispatcher=null)
		{
			super(target);
		}
	}
}

package com.diadraw.extensions

{

import flash.events.EventDispatcher;

import flash.events.IEventDispatcher;

public class WindowsExtensionWrapper extends EventDispatcher

{

public function WindowsExtensionWrapper(target:IEventDispatcher=null)

{

super(target);

}

Step 3: Add the Extension Context

Let’s start adding functionality to your newly created class by having it create an extension context in its constructor. You will need the context instance to make calls to native code later on, so make it a private class member:

private var m_extContext : ExtensionContext = null;

1	private var m_extContext : ExtensionContext = null;

To instantiate an ExtensionContext you’ll need a unique string – an Extension ID. You will also need to listen to events that may come from your native code.

Below is the modified code for the WindowsExtensionWrapper class:

package com.diadraw.extensions
{
	import flash.events.EventDispatcher;
	import flash.events.IEventDispatcher;
	import flash.events.StatusEvent;
	import flash.external.ExtensionContext;

	public class WindowsExtensionWrapper extends EventDispatcher
	{
		public function WindowsExtensionWrapper( _target : IEventDispatcher = null )
		{
			super( _target );

			// Create a new extension context and listen for status events from it:
			m_extContext = ExtensionContext.createExtensionContext( EXTENSION_ID, null );
			m_extContext.addEventListener( StatusEvent.STATUS, onStatusEvent );				
		}

		private function onStatusEvent( _event : StatusEvent ) : void
		{
			// Here you can add functionality to deal with the various events
			// that you may need to dispatch from native code.
			// For the moment let's just log what comes in for now:
			trace( "Event code: " + _event.code + ", event level: " + _event.level );
		}

		// For this tutorial we'll need one ExtensionContext instance
		// and we'll need to keep it while our ANE is in use:
		private var m_extContext : ExtensionContext = null;

		// The extension ID needs to be a unique string:
		private static const EXTENSION_ID : String = "com.diadraw.extensions.tutorial.WindowsExtension";
	}
}

package com.diadraw.extensions

{

import flash.events.EventDispatcher;

import flash.events.IEventDispatcher;

import flash.events.StatusEvent;

import flash.external.ExtensionContext;

public class WindowsExtensionWrapper extends EventDispatcher

{

public function WindowsExtensionWrapper( _target : IEventDispatcher = null )

{

super( _target );

// Create a new extension context and listen for status events from it:

m_extContext = ExtensionContext.createExtensionContext( EXTENSION_ID, null );

m_extContext.addEventListener( StatusEvent.STATUS, onStatusEvent );

}

private function onStatusEvent( _event : StatusEvent ) : void

{

// Here you can add functionality to deal with the various events

// that you may need to dispatch from native code.

// For the moment let's just log what comes in for now:

trace( "Event code: " + _event.code + ", event level: " + _event.level );

}

// For this tutorial we'll need one ExtensionContext instance

// and we'll need to keep it while our ANE is in use:

private var m_extContext : ExtensionContext = null;

// The extension ID needs to be a unique string:

private static const EXTENSION_ID : String = "com.diadraw.extensions.tutorial.WindowsExtension";

}

Step 4: Add the AIR API of your extension

As pompous as this sounds, that’s actually the meat of your AIR library: the functions that will serve as the interface between an app and the native code you wrote in the previous step of this tutorial.

Well, one function in this case. Add the following public method to your WindowsExtensionWrapper class:

public function passString ( _message : String ) : String
{
	// Calls the ASPassAString function (exposed as "as_passAString" to ActionScript)
	// that we defined in dllMain.cpp:
	// passes a string to it and expects a strnig back.
	return m_extContext.call( "as_passAString", _message ) as String; 
}

public function passString ( _message : String ) : String

{

// Calls the ASPassAString function (exposed as "as_passAString" to ActionScript)

// that we defined in dllMain.cpp:

// passes a string to it and expects a strnig back.

return m_extContext.call( "as_passAString", _message ) as String;

}

Step 5: Add the extension descriptor

The extension descriptor tells AIR about the native library. Click here for a reminder of how that works.

Add a new XML file to your AIR library’s src folder and name it DiaDrawWindowsANETutorialAIRLib-extension.xml (you can give it any name, really).

Your project should now look like this:

And this is what your extension file should contain:

<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="http://ns.adobe.com/air/extension/3.1">

  <!-- This is the extension ID: the same unique string
  	   you defined in WindowsExtensionWrapper.as -->
  <id>com.diadraw.extensions.tutorial.WindowsExtension</id>

  <versionNumber>1.0.0</versionNumber>

  <platforms>

  		<platform name="Windows-x86">
			<applicationDeployment>
				<!-- The name of the DLL file: -->
				<nativeLibrary>DiaDrawWindowsANETutorialDLL.dll</nativeLibrary>

				<!-- The names of the extension initializer
				     and finalizer functions you defined
				     in dllMain.cpp: -->
				<initializer>ExtensionInitializer</initializer>
				<finalizer>ExtensionFinalizer</finalizer>
			</applicationDeployment>
		</platform>

  </platforms>
</extension>

<?xml version="1.0" encoding="UTF-8"?>

<!-- This is the extension ID: the same unique string

you defined in WindowsExtensionWrapper.as -->

<id>com.diadraw.extensions.tutorial.WindowsExtension</id>

<nativeLibrary>DiaDrawWindowsANETutorialDLL.dll</nativeLibrary>

<!-- The names of the extension initializer

and finalizer functions you defined

in dllMain.cpp: -->

<initializer>ExtensionInitializer</initializer>

<finalizer>ExtensionFinalizer</finalizer>

</applicationDeployment>

</platform>

</platforms>

</extension>

Build your project to make sure you don’t get any compiler errors and you are now ready to package your ANE.

What’s next?

Part 4: Packaging the ANE – 10-12 minutes
See the table of contents for the tutorial, in case you want to jump back or ahead.

Early bird offer on the ANE eBooks

Buy any Easy Native Extensions 2nd Edition package and get our $99 iOS + Android ANE Template completely free before the end of June 2015.

I want it!

step-by-step guide to making your iOS extension in under an hour
library for data conversion between ActionScript and native code
tutorials
infographics
code included

At the end of this part you will have:

Time

Wait, have you done this first?

Step 1: Create a Flex Library Project

Step 2: Create the AIR wrapper for your ANE

Why subclass EventDispatcher?

Step 3: Add the Extension Context

Step 4: Add the AIR API of your extension

Step 5: Add the extension descriptor

What’s next?

Leave a Reply Cancel reply

Read the latest:

Protected: DiaDraw Tutorial Template, Part 1: Typography

Protected: DiaDraw Tutorial Template

Swift resources for Flash and ActionScript developers

7 surprising lessons from writing a book on maternity leave