This post shows you through a couple of infographics what happens when an AIR Native Extension is loaded and unloaded by the AIR Runtime.

First, a couple of useful resources

Functions that your native code needs to implement

The Adobe AIR SDK defines a C interface, which your native code needs to implement, so that it can be called by the AIR Runtime. The function signatures you’ll need to implement are defined in FlashRuntimeExtensions.h, which is usually found in the include folder of the Adobe AIR SDK.

These are the functions that you will need to implement:

  • The first pair is called by the AIR Runtime when your native extension is loaded or unloaded:
  • These two are called when your ActionScript code instantiates flash.external.ExtensionContext:
  • And this is the signature that your custom functions will need to have – these are the functions that you will call from ActionScript:

Loading a native extension – initialization phase

Here is what happens at runtime when you use a native extension:

1. Your app makes a call into your ANE’s AIR library code – typically by creating an instance of the class that you have provided as an interface between ActionScript and native code. Let us call that YourNativeExtension.as

2. YourNativeExtension creates an instance of flash.external.ExtensionContext. For what is ExtensionContext have a look at the bottom of the post.

3. This causes AIR Runtime to call your Extension Initializer function, let us call it YourExtensionInitializer(), which implements FREInitializer(). FREInitializer() takes three arguments:

  • extDataToSet – a pointer to a pointer to data you may want to set for your extension.
  • ctxInitializerToSet – a function pointer; set it to point to your implementation of
    FREContextInitializer().
  • ctxFinalizerToSet – a function pointer; set it to point to your implementation of
    FREContextFinalizer() function

Note that all of these are output arguments, which YourExtensionInitializer() sets.

4. Now that the AIR Runtime has a pointer to your implementation of FREContextInitializer (named YourContextInitializer() on the diagram below), it calls it to finish the initialization of flash.external.ExtensionContext.

YourContextInitializer, in turn, sets the pointers to the functions you have implemented as your native code API. I’ve named them NativeFunctionA and NativeFunctionB on the diagram. Your AIR library now has an extension context that knows all about your native functions and you can use it to make calls to them.

Initialization Sequence Diagram

Unloading a native extension – finalization phase

In your native extension you can create one or more instances of ExtensionContext, each with its own type. You can respectively have data that you allocate for each instance – ‘context-specific data’. YourContextFinalizer is the function where you can clean this data up. This function gets called when one of the following happens:

1a. you explicitly call dispose in your ActionScript code and dispose of your extension context:

myContext.dispose();

1b. the AIR Runtime garbage collector detects no references to your extension context and disposes of it;

1c. the AIR Runtime shuts down, normally when your application quits.

Finalization Sequence Diagram

About the Author

Radoslava is co-founder of DiaDraw. Prefers to communicate with images. Verbal communication always caused trouble with her parents. Started speaking Basic early on, followed by four years of Delphi, six years of C++, four years of ActionScript, lately converses in Objective-C. Her mum and dad hope she'll start speaking human at some point.