Developing ActionScript Extensions - Adobe

3 downloads 181 Views 816KB Size Report
Dec 7, 2010 - Dispatch events from the native code to ActionScript. When you .... Typically, as with any software develo
Developing ACTIONSCRIPT® Extensions for ADOBE® AIR®

© 2010 Adobe Systems Incorporated and its licensors. All rights reserved. Copyright

Developing ActionScript® Extensions for Adobe® AIR® This user guide is protected under copyright law, furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. This user guide is licensed for use under the terms of the Creative Commons Attribution Non-Commercial 3.0 License. This License allows users to copy, distribute, and transmit the guide for noncommercial purposes only so long as (1) proper attribution to Adobe is given as the owner of the guide; and (2) any reuse or distribution of the guide contains a notice that use of the guide is governed by these terms. The best way to provide notice is to include the following link. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ Adobe, the Adobe logo, ActionScript, Adobe AIR, AIR, Flash, and Flex are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Java is a trademark or registered trademark of Oracle and/or its affiliates. All other trademarks are the property of their respective owners. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA

Last updated 12/7/2010

iii

Contents Chapter 1: Introducing ActionScript extensions for Adobe AIR About ActionScript extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Extensions architecture

................................................................................................ 2

Task overview to create an extension

.................................................................................. 4

Chapter 2: Coding the ActionScript side Declare the public interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Check for extension support

........................................................................................... 7

Create an ExtensionContext instance Call a native function Listen for events

.................................................................................. 7

.................................................................................................. 8

....................................................................................................... 9

Dispose of an ExtensionContext instance Access the extension’s directory

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Identify the calling application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12

Chapter 3: Coding the native side with C AIR for TV extension examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Extension initialization

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Extension context initialization Context-specfic > com.sample.ext.Feature 0.0.1

See “AIR extension descriptor files” on page 38 for more information.



FeatureExtension.swc — the ActionScript interface for the extension.



-platform default Library.swf — Specifies the files to include for the default ActionScript implementation

of the extension. The default implementation is optional, but if included, you must compile the implementation into a file named, “Library.swf”. Note that this is the default name assigned when you compile a library project as a SWC file, which is a zip-like archive. The SWC archive contains Library.swf and a meta> com.example.MyExtension 0.0.1

More Help topics “Building and installing extensions for AIR for TV” on page 29

The extension descriptor file structure The extension descriptor file is an XML document with the following structure:

Last updated 12/7/2010

39

DEVELOPING ACTIONSCRIPT EXTENSIONS AIR extension descriptor files

... ... ... ... ... ... ...

AIR extension descriptor elements The following dictionary of elements describes each of the legal elements of an AIR application descriptor file.

applicationDeployment Adobe AIR 2.5 and later, tv and extendedTV profile only Declares a native code library included in the extension package and, hence, deployed with the application. Application deployment is not supported by all platforms. Parent elements:“platform” on page 44. Child elements:

• “finalizer” on page 42 • “initializer” on page 43 • “nativeLibrary” on page 44 Content Identifies the native code library and the initialization and finalization functions.

Last updated 12/7/2010

40

DEVELOPING ACTIONSCRIPT EXTENSIONS AIR extension descriptor files

Example myExtension.so com.example.extension.Initializer com.example.extension.Finalizer

copyright Adobe AIR 2.5 and later, tv and extendedTV profile only — Optional A copyright declaration for the extension. Parent elements:“extension” on page 41 Child elements: none Content A string containing copyright information. Example © 2010, Examples, Inc. All rights reserved.

description Adobe AIR 2.5 and later, tv and extendedTV profile only — Optional The description of the extension. Parent elements:“extension” on page 41 Child elements:“text” on page 45 Content Use a simple text node or multiple text elements. Using multiple text elements, you can specify multiple languages in the description element. The xml:lang attribute for each text element specifies a language code, as defined in RFC4646 (http://www.ietf.org/rfc/rfc4646.txt). Example Description with simple text node: This is a sample AIR extension.

Description with localized text elements for English, French, and Spanish: This is a example. C'est un exemple. Esto es un ejemplo.

Last updated 12/7/2010

41

DEVELOPING ACTIONSCRIPT EXTENSIONS AIR extension descriptor files

deviceDeployment Adobe AIR 2.5 and later, tv and extendedTV profile only — Required Declares a native extension for which the code libraries are deployed separately on the device and are not included in this extension package. Device deployment is not supported by all platforms. Parent elements:“platform” on page 44 Child elements: None. Content None. The deviceDeployment element must be empty. Example

extension Adobe AIR 2.5 and later, tv and extendedTV profile only — Required The root element of the extension descriptor document. The namespace identifies the minimum version of the AIR runtime required to use this extension. Parent elements: None. Child elements:

• “copyright” on page 40 • “description” on page 40 • “id” on page 42 • “name” on page 43 • “platforms” on page 45 • “versionNumber” on page 46 Content Identifies the supported platforms and the code libraries for each platform. The XML namespace attribute determines the required AIR runtime version of the application. The extension namespace changes with each major release of AIR (but not with minor patches). The last segment of the namespace, such as “2.5,” indicates the runtime version required by the application. The xmlns value must be: xmlns="http://ns.adobe.com/air/extension/2.5"

Last updated 12/7/2010

42

DEVELOPING ACTIONSCRIPT EXTENSIONS AIR extension descriptor files

Example com.example.MyExtension 1.0.1

finalizer Adobe AIR 2.5 and later, tv and extendedTV profile only — Optional The finalization function defined in the native library. Parent elements:“applicationDeployment” on page 39 Child elements: None. Content The name of the finalization function. Example ...

id Adobe AIR 2.5 and later, tv and extendedTV profile only — Required The ID of the extension. Parent elements:“extension” on page 41 Child elements: None. Content Specifies the ID of the extension. Example com.example.MyExtension

Last updated 12/7/2010

43

DEVELOPING ACTIONSCRIPT EXTENSIONS AIR extension descriptor files

initializer Adobe AIR 2.5 and later, tv and extendedTV profile only — Optional The initialization function defined in the native library. An initializer element is required if the nativeLibrary element is used. Parent elements:“applicationDeployment” on page 39 Child elements: None. Content The name of the initialization function. Example ...

name Adobe AIR 2.5 and later, tv and extendedTV profile only — Optional The name of the extension. Parent elements:“extension” on page 41 Child elements:“text” on page 45 Content If you specify a single text node (instead of multiple elements), the AIR application installer uses this name, regardless of the system language. The xml:lang attribute for each text element specifies a language code, as defined in RFC4646 (http://www.ietf.org/rfc/rfc4646.txt). Example The following example defines a name with a simple text node: Test Extension

The following example, specifies the name in three languages (English, French, and Spanish) using element nodes: Hello AIR Bonjour AIR Hola AIR

Last updated 12/7/2010

44

DEVELOPING ACTIONSCRIPT EXTENSIONS AIR extension descriptor files

nativeLibrary Adobe AIR 2.5 and later, tv and extendedTV profile only — Optional The native library file included in the extension package for a platform. The nativeLibrary element is not required if the extension contains only ActionScript code. If the nativeLibrary element is not used, the initializer and finalizer elements cannot be used either. Parent elements:“applicationDeployment” on page 39 Child elements: None. Content The file name of the native library included in the extension package. Example extensioncode.so

platform Adobe AIR 2.5 and later, tv and extendedTV profile only — Required Specifies the native code library for the extension on a specific platform. Parent elements:“platforms” on page 45 Child elements: One, and only one, of the following elements:

• “applicationDeployment” on page 39 • “deviceDeployment” on page 41 Content The name attribute specifies the name of the platform. The special default platform name allows the extension developer to include an ActionScript library that simulates the behavior of the native code on unsupported platforms. Simulated behavior can be used to support debugging and to provide fall back behavior for multi-platform applications. The child elements specify how the native code library is deployed. Application deployment means that the code library is deployed with each AIR application that uses it. The code library must be included in the extension package. Device deployment means that the code library is deployed separately to the platform and is not included in the extension package. The two deployment types are mutually exclusive; include only one deployment element. Example

Last updated 12/7/2010

45

DEVELOPING ACTIONSCRIPT EXTENSIONS AIR extension descriptor files

platforms Adobe AIR 2.5 and later, tv and extendedTV profile only — Required Specifies the platforms supported by this extension. Parent elements:“extension” on page 41 Child elements:“platform” on page 44 Content A platform element for each supported platform. Optionally, a special default platform can be specified containing an ActionScript implementation for use on platforms not supported with a specific code library. Example

text Adobe AIR 2.5 and later, tv and extendedTV profile only — Optional Specifies a localized string. The xml:lang attribute of a text element specifies a language code, as defined in RFC4646 (http://www.ietf.org/rfc/rfc4646.txt). AIR uses the text element with the xml:lang attribute value that most closely matches the user interface language of the user’s operating system. For example, consider an installation in which a text element includes a value for the en (English) locale. AIR uses the en name if the operating system identifies en (English) as the user interface language. It also uses the en name if the system user interface language is en-US (U.S. English). However, if the user interface language is en-US and the application descriptor file defines both en-US and en-GB names, then the AIR application installer uses the en-US value. If the application defines no text element that matches the system user interface languages, AIR uses the first name value defined in the extension descriptor file. Parent elements:

• “name” on page 43 • “description” on page 40

Last updated 12/7/2010

46

DEVELOPING ACTIONSCRIPT EXTENSIONS AIR extension descriptor files

Child elements: none Content An xml:lang attribute specifying a locale and a string of localized text. Example Bonjour AIR

versionNumber Adobe AIR 2.5 and later, tv and extendedTV profile only — Required The application version number. Parent elements:“extension” on page 41 Child elements: none Content The version number can contain a sequence of up to three integers separated by periods. Each integer must be a number between 0 and 999 (inclusive). Examples 1.0.657 10 0.01

Last updated 12/7/2010

47

Chapter 6: Native C API Reference Typedefs FREContext typedef void* FREContext;

The ActionScript side creates an extension context by calling ExtensionContext.createExtensionContext(). For each extension context, the AIR runtime creates a corresponding FREContext variable. The runtime passes the FREContext variable to each of the following functions in the native implementation:

• The context initialization function, “FREContextInitializer()” on page 52. • The context finalizer function, “FREContextFinalizer()” on page 51. • Each extension function, “FREFunction()” on page 54. Use this FREContext variable when:

• You dispatch an event to the ActionScript ExtensionContext instance. See “FREDispatchStatusEventAsync()” on page 58.

• You get or set native context data. See “FREGetContextNativeData()” on page 62 and “FRESetContextNativeData()” on page 76.

• You get or set ActionScript context data. See “FREGetContextActionScriptData()” on page 61 and “FRESetContextActionScriptData()” on page 75.

FREObject typedef void* FREObject;

When you access an ActionScript class object or primitive data type variable from your native C implementation, you use an FREObject variable. The runtime associates an FREObject variable with the corresponding ActionScript object. FREObject variables are used in native extension functions you implement with the signature “FREFunction()” on page 54. The native extension functions:

• Receive FREObject variables as parameters. • Return an FREObject variable. FREObject variables are also used when you use native extensions C API functions to:

• Create an ActionScript class object or ActionScript primitive data type. • Get the value of an ActionScript class object or ActionScript primitive data type. • Create an ActionScript String object. • Get the value of an ActionScript String object. • Get or set a property of an ActionScript object. • Call a method of an ActionScript object. • Access the bits of an ActionScript BitmapData object.

Last updated 12/7/2010

48

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

• Access the bytes of an ActionScript ByteArray object. • Get or set the length of an ActionScript Array or Vector object. • Get or set an element of an ActionScript Array or Vector object. • Get an ActionScript Error object when the runtime throws an exception in a native extension C API function call. • Set or get an ActionScript object in the ActionScript context data.

Structure typedefs FREBitmapData Use the FREBitmapData structure when acquiring and manipulating the bits in an ActionScript BitmapData class object. The structure is defined as follows: typedef struct { uint32_t width; uint32_t height; bool hasAlpha; bool isPremultiplied; uint32_t lineStride32; uint32_t* bits32; } FREBitmapData;

The fields of FREBitmapData have the following meanings: width A uint32_t that specifies the width, in pixels, of the bitmap. This value corresponds to the width property of the ActionScript BitmapData class object. This field is read-only. height A uint32_t that specifies the height, in pixels, of the bitmap. This value corresponds to the height property of

the ActionScript BitmapData class object. This field is read-only. hasAlpha A bool that indicates whether the bitmap supports per-pixel transparency. This value corresponds to the transparent property of the ActionScript BitmapData class object. If the value is true, then the pixel format is ARGB32. If the value is false, the pixel format is _RGB32. Whether the value is big endian or little endian depends on the host device. This field is read-only.

isPremultiplied A bool that indicates whether the bitmap pixels are stored as premultiplied color values. This value is always true in AIR 2.5. This field is read-only. For more information about premultiplied color values, see BitmapData.getPixel() in the ActionScript 3.0 Reference for the Adobe Flash Platform. lineStride32 A uint32_t that specifies the number of uint32_t values per scanline. This value is typically the same as

the width parameter. This field is read-only. bits32 A pointer to a uint32_t. This value is an array of uint32_t values. Each value is one pixel of the bitmap.

Note: The only field of a FREBitmapData structure that you can change in the native implementation is the bits32 field. The bits32 field contains the actual bitmap values. Treat all the other fields in the FREBitmapData structure as readonly fields.

More Help topics “FREAcquireBitmapData()” on page 55 “FREInvalidateBitmapDataRect()” on page 67

Last updated 12/7/2010

49

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FREByteArray Use the FREByteArray structure when acquiring and manipulating the bytes in an ActionScript ByteArray class object. The structure is defined as follows: typedef struct { uint32_t length; uint8_t* bytes; } FREByteArray;

The fields of FREByteArray have the following meanings: length A uint32_t that is the number of bytes in the bytes array. bytes A uint8_t* that is a pointer to the bytes in the ActionScript ByteArray object.

More Help topics “FREAcquireByteArray()” on page 56

FRENamedFunction Use the FRENamedFunction to associate an FREFunction that you write with a name. Use that name in your ActionScript code when calling the native function with the ExtensionContext instance call() method. The structure is defined as follows: typedef struct FRENamedFunction_{ const uint8_t* name; void* functionData; FREFunction function; } FRENamedFunction;

The fields of FRENamedFunction have the following meanings: name A const uint8_t*. This pointer points to a string that the ActionScript side uses to call the associated C function.

That is, the string value is the name that the ActionScript ExtensionContext call() method uses in its functionName parameter. Use UTF-8 encoding for the string and terminate it with the null character. functionData A void*. This pointer points to any data you want to associate with this FREFunction function. When the runtime calls the FREFunction function, it passes the function this data pointer. function An FRENamedFunction. The function that the runtime associates with the string given by the name field. Define this function with the signature of an “FREFunction()” on page 54.

Enumerations FREObjectType An FREObject variable corresponds to an ActionScript class object or primitive type. The FREObjectType enumeration defines values for these ActionScript class types and primitive types. The C API function “FREGetObjectType()” on page 67 returns an FREObjectType enumeration value that best describes an FREObject variable’s corresponding ActionScript class object or primitive type.

Last updated 12/7/2010

50

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

enum FREObjectType { FRE_TYPE_OBJECT FRE_TYPE_NUMBER FRE_TYPE_STRING FRE_TYPE_BYTEARRAY FRE_TYPE_ARRAY FRE_TYPE_VECTOR FRE_TYPE_BITMAPDATA FRE_TYPE_BOOLEAN FRE_TYPE_NULL FREObjectType_ENUMPADDING };

= = = = = = = = = =

0, 1, 2,, 3, 4, 5, 6, 7, 8, 0xfffff

The enumeration values have the following meanings: FRE_TYPE_OBJECT The FREObject variable corresponds to an ActionScript class object that is not a String object,

ByteArray object, Array object, Vector object, or BitmapData object. FRE_TYPE_NUMBER The FREObject variable corresponds to an ActionScript Number variable. FRE_TYPE_STRING The FREObject variable corresponds to an ActionScript String object. FRE_TYPE_BYTEARRAY The FREObject variable corresponds to an ActionScript ByteArray object. FRE_TYPE_ARRAY The FREObject variable corresponds to an ActionScript Array object. FRE_TYPE_VECTOR The FREObject variable corresponds to an ActionScript Vector object. FRE_TYPE_BITMAPDATA The FREObject variable corresponds to an ActionScript BitmapData object. FRE_TYPE_BOOLEAN The FREObject variable corresponds to an ActionScript Boolean variable. FRE_TYPE_NULL The FREObject variable corresponds to the ActionScript value Null or undefined. FREObjectType_ENUMPADDING This final enumeration value is to guarantee that the size of an enumeration value is

always 4 bytes.

More Help topics “The FREObject type” on page 21

FREResult The FREResult enumeration defines return values for native extensions C API functions you call. enum FREResult { FRE_OK = 0, FRE_NO_SUCH_NAME, FRE_INVALID_OBJECT, FRE_TYPE_MISMATCH, FRE_ACTIONSCRIPT_ERROR, FRE_INVALID_ARGUMENT, FRE_READ_ONLY, FRE_WRONG_THREAD, FRE_ILLEGAL_STATE, FRE_INSUFFICIENT_MEMORY };

The enumeration values have the following meanings: FRE_OK The function succeeded.

Last updated 12/7/2010

51

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FRE_ACTIONSCRIPT_ERROR An ActionScript error occurred, and an exception was thrown. The C API functions that can result in this error allow you to specify an FREObject to receive information about the exception. FRE_ILLEGAL_STATE A call was made to a native extensions C API function when the extension context was in an illegal state for that call. This return value occurs in the following situation. The context has acquired access to an ActionScript BitmapData or ByteArray class object. With one exception, the context can call no other C API functions until it releases the BitmapData or ByteArray object. The one exception is that the context can call FREInvalidateBitmapDataRect() after calling FREAcquireBitmapData(). FRE_INSUFFICIENT_MEMORY The runtime could not allocate enough memory to change the size of an Array or Vector

object. FRE_INVALID_ARGUMENT A pointer parameter is NULL. FRE_INVALID_OBJECT An FREObject parameter is invalid. For examples of invalid FREObject variables, see

“FREObject validity” on page 22. FRE_NO_SUCH_NAME The name of a class, property, or method passed as a parameter does not match an ActionScript class name, property, or method. FRE_READ_ONLY The function attempted to modify a read-only property of an ActionScript object. FRE_TYPE_MISMATCH An FREObject parameter does not represent an object of the ActionScript class expected by the

called function. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Functions you implement The extensions C API provides signatures of functions that you implement in your extension’s native C implementation.

FREContextFinalizer() Signature typedef void (*FREContextFinalizer)( FREContext ctx, );

Parameters ctx The FREContext variable that represents this extension context. See “FREContext” on page 47. Returns Nothing. Description The runtime calls this function when it disposes of the ExtensionContext instance for this extension context. The following situations cause the runtime to dispose of the instance:

• The ActionScript side calls the dispose() method of the ExtensionContext instance. • The runtime’s garbage collector detects no references to the ExtensionContext instance.

Last updated 12/7/2010

52

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

• The AIR application is shutting down. Implement this function to clean up resources specific to this context of the extension. Use the ctx parameter to get and then clean up resources associated with native context data and ActionScript context data. See “Context-specfic data” on page 18. After the runtime calls this function, it calls no other functions of this extension context.

More Help topics “Extension context initialization” on page 17 “Extension context finalization” on page 19

FREContextInitializer() Signature typedef void (*FREContextInitializer)( void* extData, const uint8_t* ctxType, FREContext ctx, uint32_t* numFunctionsToSet, const FRENamedFunction** functionsToSet );

Parameters extData A pointer to the extension data of the ActionScript extension. The function “FREInitializer()” on page 55 created the extension data. ctxType A string identifying the type of the context. You define this string as required by your extension. The context

type can indicate any agreed-to meaning between the ActionScript side and native side of the extension. If your extension has no use for context types, this value can be Null. This value is a UTF-8 encoded string, terminated with the null character. ctx An FREContext variable. The runtime creates this value and passes it to FREContextInitializer(). See

“FREContext” on page 47. numFunctionsToSet A pointer to a unint32_t. Set numFunctionsToSet to a unint32_t variable containing the number of functions in the functionsToSet parameter. functionsToSet A pointer to an array of FRNamedFunction elements. Each element contains a pointer to a native function, and the string the ActionScript side uses in the ExtensionContext instance’s call() method. See “FRENamedFunction” on page 49.

Returns Nothing. Description The runtime calls this method when the ActionScript side calls ExtensionContext.createExtensionContext(). Implement this method to do the following:

• Initialize your extension context. The initializations can depend on the context type passed in the ctxType parameter.

Last updated 12/7/2010

53

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

• Save the value of the ctx parameter so it is available to calls the native implementation makes to FREDispatchStatusEventAsync().

• Use the ctx parameter to initialize context-specific data. This data includes context-specific native data and context-specific ActionScript data.

• Set up an array of FRENamedFunction objects. Return a pointer to the array in the functionsToSet parameter. Return a pointer to the number of array elements in the numFunctionsToSet parameter. The behavior your FREContextInitializer() method can depend on the ctxType parameter. The ActionScript side can pass a context type to ExtensionContext.createExtensionContext(). Then, the runtime passes the value to FREContextInitializer(). This function typically uses the context type to choose the set of methods in the native implementation that the ActionScript side can call. Each context type corresponds to a different set of methods.

More Help topics “The context type” on page 8 “Extension context initialization” on page 17

FREFinalizer() Signature typedef void (*FREFinalizer)( void* extData, );

Parameters extData A pointer to the extension data of the extension. Returns Nothing. Description The runtime calls this function when it unloads an extension. However, the runtime does not guarantee that it will unload the extension or call FREFinalizer(). Implement this function to clean up extension resources.

More Help topics “FREInitializer()” on page 55 “Extension finalization” on page 20

Last updated 12/7/2010

54

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FREFunction() Signature typedef FREObject (*FREFunction)( FREContext ctx, void* functionData, unint32_t argc, FREObject argv[] );

Parameters ctx The FREContext variable that represents this extension context. See “FREContext” on page 47. functionData A void*. This pointer points to the data you associated with this FREFunction function in its FRENamedFunction structure. Your implementation of FREContextInitializer() passed a set of FRENamedFunction structures to the runtime in an out parameter. When the runtime calls the FREFunction function, it passes the function this data pointer. See “FRENamedFunction” on page 49. argc The number of elements in the argv parameter. argv An array of FREObject variables. These pointers correspond to the parameters passed after the function name in

the ActionScript call to the ExtensionContext instance’s call() method. Returns An FREObject variable. The default return value is an FREObject for which the type is FRE_INVALID_OBJECT. Description Implement a function with the FREFunction signature for each native function in the extension. The function name corresponds to the function field of an FRENamedFunction element in the array returned in the functionsToSet parameter of the FREContextInitializer() function. The runtime calls this FREFunction function when the ActionScript side calls the ExtensionContext instance’s call() method. The first parameter of call() is the same as the name field of the FRENamedFunction element. Subsequent parameters to call() correspond to the FREObject variables in the argv array. You define the FREFunction to return an FREObject variable. The type of the FREObject variable corresponds to the ActionScript type returned by the call() method. If the FREFunction has no return value, the default return value is an FREObject variable with the type FRE_INVALID_OBJECT. The default return value results in call() returning null on the ActionScript side. Use the ctx parameter to:

• Get and set data you associate with the extension. This data can be native context data and ActionScript context data. See “Context-specfic data” on page 18.

• Dispatch an asynchronous event to the ExtensionContext instance on the ActionScript side. See “FREDispatchStatusEventAsync()” on page 58. Use the functions in “Functions you use” on page 55 to work with the FREObject parameters and the return value, if any.

More Help topics “FREContextInitializer()” on page 52 “The FREObject type” on page 21

Last updated 12/7/2010

55

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FREInitializer() Signature typedef void (*FREInitializer)( void** extDataToSet, FREContextInitializer* ctxInitializerToSet, FREContextFinalizer* contextFinalizerToSet );

Parameters extDataToSet A pointer to a pointer to the extension data of the ActionScript extension. Create a data structure to

hold extension-specific data. For example, allocate the data from the heap, or provide global data. Set extDataToSet to a pointer to the allocated data. ctxInitializerToSet A pointer to the pointer to the FREContextInitializer() function. Set ctxInitializerToSet to the FREContextInitializer() function you defined. ctxFinalizerToSet A pointer to the pointer to the FREContextFinalizer() function. Set ctxFinalizerToSet to the FREContextFinalizer() function you defined. You can set this pointer to NULL.

Returns Nothing. Description The runtime calls this method once when it loads an ActionScript extension. Implement this function to do any initializations that your extension requires. Then set the output parameters.

More Help topics “FREContextInitializer()” on page 52 “FREContextFinalizer()” on page 51

Functions you use The native extensions C API provides functions that allow you to access and manipulate ActionScript objects and primitive data.

FREAcquireBitmapData() Usage FREResult FREAcquireBitmapData ( FREObject object, FRBitmapData* descriptorToSet );

Parameters object An FREObject. This FREObject parameter represents an ActionScript BitmapData class object.

Last updated 12/7/2010

56

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

descriptorToSet A pointer to a variable of type FREBitmapData. The runtime sets the fields of this structure when the

native C implementation calls this method. See “FREBitmapData” on page 48. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The FRBitmapData parameter is set. The ActionScript BitmapData object is available for you to manipulate. FRE_ILLEGAL_STATE The extension context has already acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases that BitmapData or ByteArray object. FRE_INVALID_ARGUMENT The descriptorToSet parameter is NULL. FRE_INVALID_OBJECT The FREObject object parameter is invalid. FRE_TYPE_MISMATCH The FREObject object parameter does not represent an ActionScript BitmapData class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to acquire the bitmap of an ActionScript BitmapData class object. Once you have successfully called this function, you cannot successfully call any other C API function until you call FREReleaseBitmapData(). This prohibition is because other calls could, as a side effect, execute code that invalidates the pointer to the bitmap contents. After calling this function, you can manipulate the bitmap of the BitmapData object. The bitmap is available in the descriptorToSet parameter, along with other information about the bitmap. To notify the runtime that the bitmap or subrectangle of the bitmap has changed, call FREInvalidateBitmapDataRect(). When you have finished working with the bitmap, call FREReleaseBitmapData().

More Help topics “FREReleaseBitMapData()” on page 72 “FREInvalidateBitmapDataRect()” on page 67

FREAcquireByteArray() Usage FREResult FREAcquireByteArray ( FREObject object, FREByteArray* byteArrayToSet );

Parameters object An FREObject. This FREObject parameter represents an ActionScript ByteArray class object. byteArrayToSet A pointer to a variable of type FREByteArray. The runtime sets the fields of this structure when the native C implementation calls this method. See “FREByteArray” on page 49.

Last updated 12/7/2010

57

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The FREByteArray parameter is set. The ActionScript ByteArray object is available for you to manipulate. FRE_ILLEGAL_STATE The extension context has already acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases that BitmapData or ByteArray object. FRE_INVALID_ARGUMENT The byteArrayToSet parameter is NULL. FRE_INVALID_OBJECT The FREObject object parameter is invalid. FRE_TYPE_MISMATCH The FREObject object parameter does not represent an ActionScript ByteArray class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to acquire the bytes of an ActionScript ByteArray class object. Once you have successfully called this function, you cannot successfully call any other C API function until you call FREReleaseByteArray(). This prohibition is because other calls could, as a side effect, execute code that invalidates the pointer to the byte array contents. After calling this function, you can manipulate the bytes of the ByteArray object. The bytes are available in the byteArrayToSet parameter, along with the number of bytes. When you have finished working with the bytes, call FREReleaseByteArray().

More Help topics “FREReleaseByteArray()” on page 73

FRECallObjectMethod() Usage FREResult FRECallObjectMethod( FREObject object, const uint8_t* methodName, uint32_t argc, FREObject argv[], FREObject* result, FREObject* thrownException );

Parameters object An FREObject that represents the ActionScript class object on which a method is being called. methodName A uint8_t array. This array is a string that is the name of the method being called. Use UTF-8 encoding for the string and terminate it with the null character. argc A uint32_t. The value is the number of parameters passed to the method. This parameter is the length of the argv array parameter. The value can be 0 when the method to call takes no parameters. argv[] An FREObject array. Each FREObject element corresponds to the ActionScript class or primitive type passed

as a parameter to the method being called. The value can be NULL when the method to call takes no parameters.

Last updated 12/7/2010

58

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

result A pointer to an FREObject. This FREObject variable is to receive the return value of the method being called.

The FREObject variable represents the ActionScript class or primitive type that the method being called returns. thrownException A pointer to an FREObject. If calling this method results in the runtime throwing an ActionScript

exception, this FREObject variable represents the ActionScript Error, or Error subclass, object. If no error occurs, the runtime sets this FREObject variable to be invalid. That is, FREGetObjectType() for the thrownException FREObject variable returns FRE_INVALID_OBJECT. This pointer can be NULL if you do not want to handle exception information. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The ActionScript method returned without throwing an exception. FRE_ACTIONSCRIPT_ERROR An ActionScript error occurred. The runtime sets the thrownException parameter to

represent the ActionScript Error class or subclass object. FRE_ILLEGAL_STATE The extension context has acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases the BitmapData or ByteArray object. FRE_INVALID_ARGUMENT The method or result parameter is NULL, or argc is greater than 0 but argv is NULL. FRE_INVALID_OBJECT The FREObject parameter or an argv FREObject element is invalid. FRE_NO_SUCH_NAME The methodName parameter does not match a method of the ActionScript class object that the object parameter represents. Another, less likely, reason for this return value exists. Specifically, consider the unusual case when an ActionScript class has two methods with the same name but the names are in different ActionScript namespaces.

FRE_TYPE_MISMATCH The FREObject parameter does not represent an ActionScript class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to call a method of an ActionScript class object.

More Help topics “The FREObject type” on page 21

FREDispatchStatusEventAsync() Usage FREResult FREDispatchStatusEventAsync( FREContext ctx, const uint8_t* code, const uint8_t* level );

Parameters ctx An FREContext. This value is the FREContext variable that the extension context received in its context initialization function. code A pointer to a uint8_t. The runtime sets the code property of the StatusEvent object to this value. Use UTF-8

encoding for the string and terminate it with the null character.

Last updated 12/7/2010

59

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

level A pointer to a uint8_t. This parameter is a utf8-encoded, null-terminated string. The runtime sets the level property of the StatusEvent object to this value.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. FRE_INVALID_ARGUMENT The ctx, code, or level parameter is NULL. The runtime also returns this value if ctx is

not valid. Description Call this function to dispatch an ActionScript StatusEvent event. The target of the event is the ActionScript ExtensionContext instance that the runtime associated with the context specified by the ctx parameter. Typically, the events this function dispatches are asynchronous. For example, an extension method can start another thread to perform some task. When the task in the other thread completes, that thread calls FREDispatchStatusEventAsync() to inform the ActionScript ExtensionContext instance. Note: The FREDispatchStatusEventAsync() function is the only C API that you can call from any thread of your native implementation. Unless one of its arguments is invalid, FREDispatchStatusEventAsync() return FRE_OK. However, returning FRE_OK does not mean that the event was dispatched. The runtime does not dispatch the event in the following cases:

• The runtime has already disposed of the ExtensionContext instance. • The runtime is in the process of disposing of the ExtensionContext instance. • The ExtensionContext instance has no references. It is eligible for the runtime garbage collector to dispose of it. Set the code and level parameters to any null-terminated, UTF8-encoded string values. These values are anything you want, but coordinate them with the ActionScript side of the extension. Example

More Help topics “FREContext” on page 47

FREGetArrayElementAt() Usage FREResult FREGetArrayElementAt ( FREObject arrayOrVector, uint32_t index, FREObject* value );

Parameters arrayOrVector An FREObject that represents an ActionScript Array or Vector class object. index A uint32_t that contains the index of the Array or Vector element to get. The first element of an Array or Vector

object has index 0.

Last updated 12/7/2010

60

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

value A pointer to an FREObject. This method sets the FREObject variable that this parameter points to. The method sets the FREObject variable to correspond to the Array or Vector element at the requested index.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The value parameter is set to the requested Array or Vector element. FRE_ILLEGAL_STATE The extension context has acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases the BitmapData or ByteArray object. FRE_INVALID_ARGUMENT The arrayOrVector parameter corresponds to an ActionScript Vector object but the index

is greater than the index of the final element. Another reason for this return value is if the value parameter is NULL. FRE_INVALID_OBJECT The arrayOrVector FREObject parameter is invalid. FRE_TYPE_MISMATCH The arrayOrVector FREObject parameter does not represent an ActionScript Array or

Vector class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to get the ActionScript class object or primitive value at the specified index of the ActionScript Array or Vector class object. The FREObject parameter arrayOrVector represents the Array or Vector object. The runtime sets the FREObject variable that the value parameter points to. It sets the FREObject variable to correspond to the appropriate Array or Vector element. If an ActionScript Array object does not have a value at the requested index, the runtime sets the FREObject value parameter to invalid, but returns FRE_OK.

More Help topics “FRESetArrayElementAt()” on page 74 “FRESetArrayLength()” on page 74

FREGetArrayLength() Usage FREResult FREGetArrayLength ( FREObject arrayOrVector, uint32_t* length );

Parameters arrayOrVector An FREObject that represents an ActionScript Array or Vector class object. length A pointer to a uint32_t. This method sets the uint32_t variable pointed to by this parameter with the length of

the Array or Vector class object.

Last updated 12/7/2010

61

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The method set the uint32_t variable that the length parameter points to. It sets the variable to the length of the Array or Vector object. FRE_ILLEGAL_STATE The extension context has acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases the BitmapData or ByteArray object. FRE_INVALID_ARGUMENT The length parameter is NULL. FRE_INVALID_OBJECT The arrayOrVector FREObject parameter is invalid. FRE_TYPE_MISMATCH The arrayOrVector FREObject parameter does not represent an ActionScript Array or

Vector class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to get the length of an Array or Vector class object. The FREObject parameter arrayOrVector represents the Array or Vector object. The runtime returns the length in the uint32_t variable that the length parameter points to.

More Help topics “FRESetArrayLength()” on page 74 “FRESetArrayElementAt()” on page 74

FREGetContextActionScriptData() Usage FREResult FREGetContextActionScriptData( FREContext ctx, FREObject *actionScriptData);

Parameters ctx An FREContext variable. The runtime passed this value to FREContextInitializer(). See “FREContextInitializer()” on page 52. actionScriptData A pointer to an FREObject variable. When FREGetContextActionScriptData() is successful, the runtime sets this parameter. The value corresponds to the ActionScript object previously saved with FRESetContextActionScriptData().

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The actionScriptData parameter corresponds to the ActionScript object previously saved with FRESetContextActionScriptData(). FRE_INVALID_ARGUMENT The actionScriptData parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Last updated 12/7/2010

62

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

Description Call this function to get an extension context’s ActionScript data.

More Help topics “FRESetContextActionScriptData()” on page 75 “Context-specfic data” on page 18

FREGetContextNativeData() Usage FREResult FREGetContextNativeData( FREContext ctx, void** nativeData );

Parameters ctx An FREContext variable. The runtime passed this value to FREContextInitializer(). See “FREContextInitializer()” on page 52. nativeData A pointer to a pointer to the native data.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The nativeData parameter is set to point to the context’s native data. FRE_INVALID_ARGUMENT The nativeData parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to get an extension context’s native data.

More Help topics “FRESetContextNativeData()” on page 76 “Context-specfic data” on page 18

FREGetObjectAsBool() Usage FREResult FREGetObjectAsBool

( FREObject object, bool *value );

Parameters object An FREObject. value A pointer to a bool. The function sets this value to correspond to the value of the Boolean ActionScript variable that the FREObject variable represents.

Last updated 12/7/2010

63

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the value parameter is correctly set. FRE_TYPE_MISMATCH The FREObject parameter does not contain a Boolean ActionScript value. FRE_INVALID_OBJECT The FREObject parameter is invalid. FRE_INVALID_ARGUMENT The value parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to set the value of a C bool variable to the value of an ActionScript Boolean variable.

More Help topics “FRENewObjectFromBool()” on page 69 “The FREObject type” on page 21

FREGetObjectAsDouble() Usage FREResult FREGetObjectAsDouble ( FREObject object, double *value );

Parameters object An FREObject. value A pointer to a double. The function sets this value to correspond to the Boolean, int, or Number ActionScript variable that the FREObject variable represents.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the value parameter is correctly set. FRE_TYPE_MISMATCH The FREObject parameter does not contain a Boolean, int, or Number ActionScript value. FRE_INVALID_OBJECT The FREObject parameter is invalid. FRE_INVALID_ARGUMENT The value parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to set the value of a C double variable to the value of an ActionScript Boolean, int, or Number variable.

More Help topics “FRENewObjectFromDouble()” on page 70 “The FREObject type” on page 21

Last updated 12/7/2010

64

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FREGetObjectAsInt32() Usage FREResult FREGetObjectAsInt32 ( FREObject object, int32_t *value );

Parameters object An FREObject. value A pointer to an int32_t. The function sets this value to correspond to the value of the Boolean or int ActionScript variable that the FREObject variable represents.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the value parameter is correctly set. FRE_TYPE_MISMATCH The FREObject parameter does not contain a Boolean or int ActionScript value. FRE_INVALID_OBJECT The FREObject parameter is invalid. FRE_INVALID_ARGUMENT The value parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an

outstanding call to a native extension function. Description Call this function to set the value of a C int32_t variable to the value of an int or Boolean ActionScript variable.

More Help topics “FRENewObjectFromInt32()” on page 70 “The FREObject type” on page 21

FREGetObjectAsUint32() Usage FREResult FREGetObjectAsUint32 ( FREObject object, uint32_t *value );

Parameters object An FREObject. value A pointer to a uint32_t. The function sets this value to correspond to the value of the Boolean or int ActionScript variable that the FREObject variable represents.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the value parameter is correctly set. FRE_TYPE_MISMATCH The FREObject parameter does not contain a Boolean or int ActionScript value. An int

ActionScript value that is negative also results in this return value. FRE_INVALID_OBJECT The FREObject parameter is invalid.

Last updated 12/7/2010

65

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FRE_INVALID_ARGUMENT The value parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to set the value of a C uint32_t variable to the value of an ActionScript Boolean or int variable.

More Help topics “FRENewObjectFromUint32()” on page 71 “The FREObject type” on page 21

FREGetObjectAsUTF8() Usage FREResult FREGetObjectAsUTF8(FREObject object, uint32_t* length, const uint8_t** value);

Parameters object An FREObject. length A pointer to a uint32_t. The value of length is the number of bytes in the value array. The length includes

the null terminator. The length corresponds to the length of the String ActionScript variable that the FREObject variable represents. value A pointer to a uint8_t array. The function fills the array with the characters of the String ActionScript variable that the FREObject variable represents. The string uses UTF-8 encoding terminates with the null character.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the value and length parameters are correctly set. FRE_TYPE_MISMATCH The FREObject parameter does not contain a String ActionScript value. FRE_INVALID_OBJECT The FREObject parameter is invalid. FRE_INVALID_ARGUMENT The value or length parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an

outstanding call to a native extension function. Description Call this function to set the value of a uint8_t array to the string value of an ActionScript String object. Consider the following regarding the string returned in the value parameter:

• You cannot change the string. • The string is valid only until the native extension function that the runtime called returns. • The string becomes invalid if you call any other C API function. Therefore, to manipulate or access the string later, copy it immediately into your own array.

Last updated 12/7/2010

66

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

More Help topics “FRENewObjectFromUTF8()” on page 72 “The FREObject type” on page 21

FREGetObjectProperty() Usage FREResult FREGetObjectProperty ( FREObject object, const uint8_t* propertyName, FREObject* propertyValue, FREObject* thrownException );

Parameters object An FREObject that represents the ActionScript class object from which to fetch the value of a property. propertyName A uint8_t array. This array contains a string that is the name of property. Use UTF-8 encoding for the

string and terminate it with the null character. propertyValue A pointer to an FREObject. This method sets this FREObject parameter to represent an ActionScript

object that is the requested property. thrownException A pointer to an FREObject. If calling this method results in the runtime throwing an ActionScript

exception, this FREObject variable represents the ActionScript Error, or Error subclass, object. If no error occurs, the runtime sets this FREObject variable to be invalid. That is, FREGetObjectType() for the thrownException FREObject variable returns FRE_INVALID_OBJECT. This pointer can be NULL if you do not want to handle exception information. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the propertyValue parameter is correctly set. FRE_ACTIONSCRIPT_ERROR An ActionScript error occurred. The runtime sets the thrownException parameter to

represent the ActionScript Error class or subclass object. FRE_ILLEGAL_STATE The extension context has acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases the BitmapData or ByteArray object. FRE_INVALID_ARGUMENT The propertyName or propertyValue parameter is NULL. FRE_INVALID_OBJECT The FREObject parameter is invalid. FRE_NO_SUCH_NAME The propertyName parameter does not match a property of the ActionScript class object that the object parameter represents. Another, less likely, reason for this return value exists. Specifically, consider the unusual case when an ActionScript class has two properties with the same name but the names are in different ActionScript namespaces. FRE_TYPE_MISMATCH The FREObject parameter does not represent an ActionScript class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an

outstanding call to a native extension function.

Last updated 12/7/2010

67

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

Description Call this function to get the FREObject variable to the data that corresponds to a public property of an ActionScript class object specified by the object parameter.

More Help topics “FRESetObjectProperty()” on page 77 “The FREObject type” on page 21

FREGetObjectType() Usage FREResult FREGetObjectType( FREObject object, FREObjectType *objectType );

Parameters object An FREObject variable. objectType A pointer to an FREObjectType variable. FREGetObjectType() sets this variable to one of the

FREObjectType enumeration values. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the objectType parameter is correctly set. FRE_INVALID_ARGUMENT The objectType parameter is NULL. FRE_INVALID_OBJECT The FREObject parameter is invalid. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an

outstanding call to a native extension function. Description Call this function to get the FREObjectType enumeration value that best describes an FREObject variable’s corresponding ActionScript class object or primitive type.

More Help topics “FREObjectType” on page 49 “The FREObject type” on page 21

FREInvalidateBitmapDataRect() Usage FREResult FREInvalidateBitmapDataRect( FREObject object, uint32_t x, uint32_t y, uint32_t width, uint32_t height );

Last updated 12/7/2010

68

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

Parameters object An FREObject that represents a previously acquired ActionScript BitmapData class object. x A uint32_t. This value is the x coordinate in terms of pixels. The value is relative to the upper-left corner of the bitmap. Along with the y parameter, it indicates the upper-left corner of the rectangle to invalidate. y A uint32_t. This value is the y coordinate in terms of pixels. The value is relative to the upper-left corner of the

bitmap. Along with the x parameter, it indicates the upper-left corner of the rectangle to invalidate. width A uint32_t. This value is the width in pixels of the rectangle to invalidate. height A uint32_t. This value is the height in pixels of the rectangle to invalidate.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The specified rectangle has been invalidated. FRE_ILLEGAL_STATE The extension context has not acquired the ActionScript BitmapData object. FRE_INVALID_OBJECT The FREObject object parameter is invalid. FRE_TYPE_MISMATCH The FREObject object parameter does not represent an ActionScript BitmapData class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to invalidate a rectangle of an ActionScript BitmapData class object. Before calling this function, call FREAcquireBitmapData(). Call FREReleaseBitmapData() after you are done manipulating and invalidating the bitmap. Invalidating a rectangle of a BitmapData object indicates to the runtime that it will need to redraw the rectangle.

More Help topics “FREAcquireBitmapData()” on page 55 “FREReleaseBitMapData()” on page 72

FRENewObject() Usage FREResult FRENewObject( const uint8_t* uint32_t FREObject FREObject* FREObject* );

className, argc, argv[], object, thrownException

Parameters className A uint8_t array. A string that is the name of the ActionScript class to create an object of. Use UTF-8 encoding for the string and terminate it with the null character.

Last updated 12/7/2010

69

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

argc A uint32_t. The number of parameters passed to the constructor of the ActionScript class. This parameter is the

length of the argv array parameter. The value can be 0 when the constructor takes no parameters. argv[] An FREObject array. Each FREObject element corresponds to the ActionScript class or primitive type passed

as a parameter to the constructor. The value can be NULL when the constructor takes no parameters. object A pointer to an FREObject. When this method returns successfully, this FREObject variable represents the new ActionScript class object. thrownException A pointer to an FREObject. If calling this method results in the runtime throwing an ActionScript

exception, this FREObject variable represents the ActionScript Error, or Error subclass, object. If no error occurs, the runtime sets this FREObject variable to be invalid. That is, FREGetObjectType() for the thrownException FREObject variable returns FRE_INVALID_OBJECT. This pointer can be NULL if you do not want to handle exception information. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The object parameter represents the new ActionScript class object. FRE_ACTIONSCRIPT_ERROR An ActionScript error occurred. The runtime sets the thrownException parameter to

represent the ActionScript Error class or subclass object. FRE_ILLEGAL_STATE The extension context has acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases the BitmapData or ByteArray object. FRE_INVALID_ARGUMENT The className or object parameter is NULL, or argc is greater than 0 but argv is NULL

or empty. FRE_NO_SUCH_NAME The className parameter does not match an ActionScript class name. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to create an object of an ActionScript class. The constructor that the runtime calls depends on the parameters you pass in the argv array.

More Help topics “The FREObject type” on page 21

FRENewObjectFromBool() Usage FREResult FRENewObjectFromBool ( bool value, FREObject* object);

Parameters value A bool that is the value for a new ActionScript Boolean instance. object A pointer to an FREObject that points to the data that represents a Boolean ActionScript variable.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the object parameter is correctly set.

Last updated 12/7/2010

70

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FRE_INVALID_ARGUMENT The FREObject parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to create an ActionScript Boolean instance with the value parameter. The runtime sets the FREObject variable to the data corresponding to the new ActionScript instance.

More Help topics “FREGetObjectAsBool()” on page 62 “The FREObject type” on page 21

FRENewObjectFromDouble() Usage FREResult FRENewObjectFromDouble ( double value, FREObject* object);

Parameters value A double that is the value for a new ActionScript Number instance. object A pointer to an FREObject that points to the data that represents a Number ActionScript variable.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the object parameter is correctly set. FRE_INVALID_ARGUMENT The FREObject parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to create an ActionScript Number instance with the value parameter. The runtime sets the FREObject variable to the data corresponding to the new ActionScript instance.

More Help topics “FREGetObjectAsDouble()” on page 63 “The FREObject type” on page 21

FRENewObjectFromInt32() Usage FREResult FRENewObjectFromInt32 ( int32_t value, FREObject* object);

Parameters value An int32_t that is the value for a new ActionScript int instance.

Last updated 12/7/2010

71

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

object A pointer to an FREObject that represents an int ActionScript instance.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the object parameter is correctly set. FRE_INVALID_ARGUMENT The FREObject parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an

outstanding call to a native extension function. Description Call this function to create an ActionScript int instance with the value parameter. The runtime sets the FREObject variable to correspond to the new ActionScript instance.

More Help topics “FREGetObjectAsInt32()” on page 64 “The FREObject type” on page 21

FRENewObjectFromUint32() Usage FREResult FRENewObjectFromUint32 ( uint32_t value, FREObject* object);

Parameters value A uint32_t that is the value for a new ActionScript int instance with a value greater than or equal to 0. object A pointer to an FREObject that represents an int ActionScript instance.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the object parameter is correctly set. FRE_INVALID_ARGUMENT The FREObject parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to create an ActionScript int instance with the value parameter. The runtime sets the FREObject variable to correspond to the new ActionScript int instance.

More Help topics “FREGetObjectAsUint32()” on page 64 “The FREObject type” on page 21

Last updated 12/7/2010

72

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FRENewObjectFromUTF8() Usage FREResult FRENewObjectFromUTF8(uint32_t length, const uint8_t* value, FREObject* object);

Parameters length A uint32_t that is the length of the string in the value parameter, including the null terminator. value An array of uint8_t elements. The array is the value for the new ActionScript String object. The FREObject variable represents a String ActionScript variable. Use UTF-8 encoding for the string and terminate it with the null character. object A pointer to an FREObject that points to the data that represents a String ActionScript object.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the object parameter is correctly set. FRE_INVALID_ARGUMENT The object or value parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to create an ActionScript String object with the string value specified in value. This method sets the FREObject output parameter object to correspond to the new ActionScript String instance.

More Help topics “FREGetObjectAsUTF8()” on page 65 “The FREObject type” on page 21

FREReleaseBitMapData() Usage FREResult FREReleaseBitmapData (FREObject object);

Parameters object An FREObject that corresponds to an ActionScript BitmapData class object. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The ActionScript BitmapData object is no longer available for you to manipulate. FRE_ILLEGAL_STATE The extension context has not acquired the ActionScript BitmapData object. FRE_INVALID_OBJECT The FREObject object parameter is invalid. FRE_TYPE_MISMATCH The FREObject object parameter does not represent an ActionScript BitmapData class object.

Last updated 12/7/2010

73

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to release an ActionScript BitmapData class object. Before calling this function, call FREAcquireBitmapData() and FREInvalidateBitmapDataRect(). After calling this function, you can no longer manipulate the bitmap, but you can again call other native extension C API functions.

More Help topics “FREAcquireBitmapData()” on page 55 “FREInvalidateBitmapDataRect()” on page 67

FREReleaseByteArray() Usage FREResult FREReleaseByteArray (FREObject object);

Parameters object An FREObject that corresponds to an ActionScript ByteArray class object. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The ActionScript ByteArray object is no longer available for you to manipulate. FRE_ILLEGAL_STATE The extension context has not acquired the ActionScript ByteArray object. FRE_INVALID_OBJECT The FREObject object parameter is invalid. FRE_TYPE_MISMATCH The FREObject object parameter does not correspond to an ActionScript ByteArray object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to release an ActionScript ByteArray class object. Before calling this function, call FREAcquireByteArray(). After calling this function, you can no longer manipulate the ByteArray bytes, but you can again call other native extension C API functions.

More Help topics “FREAcquireByteArray()” on page 56

Last updated 12/7/2010

74

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FRESetArrayElementAt() Usage FREResult FRESetArrayElementAt ( FREObject arrayOrVector, uint32_t index, FREObject value );

Parameters arrayOrVector An FREObject that points to data that represents an ActionScript Array or Vector class object. index A uint32_t that contains the index of the Array or Vector element to set. The first element of an Array or Vector

object has index 0. value An FREObject. This method sets the Array or Vector element specified by index to the ActionScript object

represented by the FREObject value parameter. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The Array or Vector element is set to the value FREOjbect parameter. FRE_ILLEGAL_STATE The extension context has acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases the BitmapData or ByteArray object. FRE_INVALID_OBJECT The arrayOrVector or value FREObject parameter is invalid. FRE_TYPE_MISMATCH The arrayOrVector FREObject parameter does not point to data that represents an

ActionScript Array or Vector class object. This return value can also mean that the arrayOrVector parameter represents a Vector object and the value parameter is not the correct type for that Vector object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an

outstanding call to a native extension function. Description Call this function to set the ActionScript class object or primitive value at the specified index of an ActionScript Array or Vector class object. The FREObject parameter arrayOrVector corresponds to the Array or Vector object. The FREObject parameter value corresponds to the array element value.

More Help topics “FREGetArrayElementAt()” on page 59 “FREGetArrayLength()” on page 60

FRESetArrayLength() Usage FREResult FRESetArrayLength ( FREObject arrayOrVector, uint32_t length );

Last updated 12/7/2010

75

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

Parameters arrayOrVector An FREObject that represents an ActionScript Array or Vector class object. length A uint32_t. This method sets the length of the Array or Vector class object to this parameter’s value.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. The runtime has changed the size of the Array or Vector object. FRE_ILLEGAL_STATE The extension context has acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases the BitmapData or ByteArray object. FRE_INSUFFICIENT_MEMORY The runtime could not allocate enough memory to change the size of the Array or

Vector object. FRE_INVALID_ARGUMENT The length parameter is greater than 232. FRE_INVALID_OBJECT The arrayOrVector FREObject parameter is invalid. FRE_READ_ONLY The arrayOrVector FREObject parameter represents a ActionScript Vector object that has a fixed

size. (Its fixed property is true.) FRE_TYPE_MISMATCH The arrayOrVector FREObject parameter does not represent an ActionScript Array or

Vector class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to set the length of an ActionScript Array or Vector class object. The FREObject parameter arrayOrVector corresponds to the Array or Vector object. The runtime changes the size of the Array or Vector object as specified by the length parameter.

More Help topics “FREGetArrayElementAt()” on page 59 “FREGetArrayLength()” on page 60

FRESetContextActionScriptData() Usage FREResult FRESetContextActionScriptData( FREContext ctx, FREObject actionScriptData);

Parameters ctx An FREContext variable. The runtime passed this value to FREContextInitializer(). See “FREContextInitializer()” on page 52. actionScriptData An FREObject variable.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded.

Last updated 12/7/2010

76

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FRE_INVALID_OBJECT The actionScriptData parameter is an invalid FREObject variable. FRE_INVALID_ARGUMENT An argument is invalid. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to set an extension context’s ActionScript data.

More Help topics “FREGetContextActionScriptData()” on page 61 “Context-specfic data” on page 18

FRESetContextNativeData() Usage FREResult FRESetContextNativeData( FREContext ctx, void* nativeData );

Parameters ctx An FREContext variable. The runtime passed this value to FREContextInitializer(). See “FREContextInitializer()” on page 52. nativeData A pointer to the native data.

Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded. FRE_INVALID_ARGUMENT The nativeData parameter is NULL. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Description Call this function to set an extension context’s native data.

More Help topics “FREGetContextNativeData()” on page 62 “Context-specfic data” on page 18

Last updated 12/7/2010

77

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

FRESetObjectProperty() Usage FREResult FRESetObjectProperty ( FREObject object, const uint8_t* propertyName, FREObject propertyValue, FREObject* thrownException );

Parameters object An FREObject that represents the ActionScript class object for which a property is to be set. propertyName A uint8_t array. This array contains a string that is the name of property to set. Use UTF-8 encoding

for the string and terminate it with the null character. propertyValue An FREObject that represents the value to set the property to. thrownException A pointer to an FREObject. If calling this method results in the runtime throwing an ActionScript

exception, this FREObject variable represents the ActionScript Error, or Error subclass, object. If no error occurs, the runtime sets this FREObject variable to be invalid. That is, FREGetObjectType() for the thrownException FREObject variable returns FRE_INVALID_OBJECT. This pointer can be NULL if you do not want to handle exception information. Returns An FREResult. The possible return values include, but are not limited to, the following: FRE_OK The function succeeded and the ActionScript class object’s property is correctly set. FRE_ACTIONSCRIPT_ERROR An ActionScript error occurred. The runtime sets the thrownException parameter to

represent the ActionScript Error class or subclass object. FRE_ILLEGAL_STATE The extension context has acquired an ActionScript BitmapData or ByteArray object. The context cannot call this method until it releases the BitmapData or ByteArray object. FRE_INVALID_ARGUMENT The propertyName parameter is NULL. FRE_INVALID_OBJECT The object or propertyValue parameter is an invalid FREObject variable. FRE_NO_SUCH_NAME The propertyName parameter does not match a property of the ActionScript class object that the object parameter represents. Another, less likely, reason for this return value exists. Specifically, consider the unusual case when an ActionScript class has two properties with the same name but the names are in different ActionScript namespaces. FRE_READ_ONLY The property to set is a read-only property. FRE_TYPE_MISMATCH The FREObject object parameter does not represent an ActionScript class object. FRE_WRONG_THREAD The method was called from a thread other than the one on which the runtime has an outstanding call to a native extension function.

Last updated 12/7/2010

78

DEVELOPING ACTIONSCRIPT EXTENSIONS Native C API Reference

Description Call this function to set the value of a public property of the ActionScript class object that an FREObject variable represents. Pass the name of the property to set in the propertyName parameter. Pass the new property value in the propertyValue parameter.

More Help topics “FREGetObjectProperty()” on page 66 “The FREObject type” on page 21

Last updated 12/7/2010