学步园

You've done the majority of the coding necessary in creating a native extension, having created Java code that you can extend with additional functions, logic, and (if necessary) even additional extension contexts to expand the
scope of your native extension.

In contrast, creating the ActionScript 3 code necessary to complete this platform bridge is simple. Your tasks include:

• Creating and configuring a Flex Library project.
  创建配置Flex库工程
• Creating an extension.xml file to describe your extension.
  创建描述extension的extension.xml

Your ActionScript 3 library code will consist of one class, which will import the flash.external.ExtensionContext API, and provide the following functions:
你的AS3库包含一个类，它需要import flash.external.ExtensionContext，提供以下功能。

• A constructor, which will create a new Extension Context of the proper ID, and which will call your initMe native function.
  构造函数，它将会创建一个新的Extension Context。它会调用你的InitMe native函数。
• A function called isSupported, which will call our isSupported native function, and which will return trueor false depending on the response from our native code.
  函数isSupported，调用isSupported native函数，该函数会根据native code的处理返回true或flase。
• A function called vibrate, which will accept a Number duration, and call your native vibrateMe function with this number as a parameter.
  函数vibrate，接收一个数值duration。它会以这个值为参数调用native的vibrateMe函数。
• After completing this code, your ActionScript 3 library function will be complete, and you can move on to packaging and using your native extension. Note that the library function defines the ActionScript 3 code necessary to use your native extension, but
  it isn't a sample application. In order to use your native extension, you'll have to reference this library application from a Flex mobile application, which you'll create in a later section of this guide.
  做完这些之后，AS3库的工作告一段落，你可以使用native extension来打包。需要注意的是，虽然这些库函数可以用你的native extension，但它不是一个范例程序。为了使用native extension，你需要创建一个Flex mobile 程序。

Creating a Flex library project
Your ActionScript 3 code will exist inside of a Flex Library project:

• In Flash Builder, open the Flash perspective by selecting it in the top right of the screen.
• Click File > New > Flex Library Project.
• Name the project HelloANELibrary.
• Make sure the Generic library radio button is selected.
• Make sure that "Include Adobe AIR libraries" is checked. The native extension libraries your project will depend on are included with the AIR APIs.
• Click Finish to create the project.
  创建一个新的Flex Library工程。
• Open the HelloANELibrary project in your Package Explorer, right-click the src folder, and select New > ActionScript Class.
• Name the package com.<yourDomain>.nativeExtensions.Vibrate. For example, 
• Name the class Vibrate.
• Set the superclass to flash.events.EventDispatcher. This will allow this class to dispatch events, which will be useful when you integrate native extensions into real applications.
• Click Finish to create the Vibrate class.
  在该库中创建一个类Vibrate。

Coding the ActionScript 3 bridge to your native code
You now have to create the connection to our Extension Context, which will allow you to access the initMe, isSupported, and vibrateMe functions you created in Java.
现在需要创建一个面向Extension Context的连接。通过它访问Java中创建的函数

1.In the Vibrate class, add a private, static reference to an Extension Context:
在class Vibrate中，增加一个静态变量，准备指向Extension Context

private static var extContext:ExtensionContext = null;

2.In the constructor, you're going to verify whether this extContext variable has been initialized. If not, you'll call the static function ExtensionContext.createExtensionContext(), and pass in two identifiers. The first is an ID you'll set in an extension.xml
file shortly. The second is a parameter that's passed to the createContext() function of VibrationExtension. You'll recall that it allows you to create different Extension Contexts; since you only have one, you ignored this parameter in your native code. If
you have multiple extension contexts, you should make your native code parse the value you pass in with an if or switch statement, and create the appropriate values based on the available shared String values. Write the following:
在构造函数中，你要检查一下extContext是否已经被初始化，如果没有，你要调用static function ExtensionContext.createExtensionContext()。该函数需要两个参数，第一个是放在extension.xml中的ID，第二个是VibrationExtension的createContext所需要的参数。这个参数允许你创建不同的Extension
Context，如果你只有一个context，native code中可以忽略这个参数。如果有多个extension context，你应该根据该参数创建不同的context。

if ( !extContext )
   {
          extContext = ExtensionContext.createExtensionContext("com.yourDomain.Vibrate","vibrate");
       extContext.call("initMe");
}

3.Note that you called initMe via extContext.call(), passing in no additional parameters. This will map up with the VibrationInitFunction that you coded in Java, and will initialize the internal data structures necessary for you to vibrate
the device.
注意，你通过extContext.call调用initMe。这将导致Java代码中的VibrationInitFunction被调用。

The Extension Context will now be created and initialized as soon as the Vibrate() constructor is called by any application that uses your new ActionScript 3 library. You still have two functions to implement, however. First create the isSupported() function,
which will connect to the native isSupported function, and inspect the Boolean value that is returned by your application logic.
现在Extension Context已经被创建并初始化完成。还有两个函数需要实现。一个是isSupported，它将要连接native function isSupported。

1.Create a static getter called isSupported, which returns a Boolean:
该函数框架如下

public static function get isSupported():Boolean
   {
       var supported:Boolean = false;

       // ...

       return false;
}

2.Between the two statements, add a call to extContext.call(), passing in isSupported as a String parameter, and which sets your supported variable to the returned Boolean value:
在上述代码中，加入以下代码，判断support

supported = extContext.call("isSupported") as Boolean;

Repeat this process to create the vibrateMe function, which takes in a single Number as the duration. Creation of this function is straightforward:
用上述方法创建vibrateMe函数，如下

public function vibrate(duration:Number):void
{
          extContext.call("vibrateMe",duration);
}

Note that Flash Builder will automatically compile your library into a SWC file, located in the bin folder of the project. The SWC file is an archive that contains library.swf. You have to manually reference both the SWC and SWF whenever you
package an ANE file with ADT. Thus, you should now open the SWC file in an archive management tool, extract library.swf, and place it in the bin/ directory of HelloANELibrary:
Flash Builder会自动把你的库编译成SWC文件到你工程的bin目录。SWC文件是一个包含library.swf的archive。只要你用ADT打包一个ANE文件，你就要手动引用SWC和SWF。因此，现在你应该用解压缩工具打开SWC文件，解压出library.swf，把它放到bin目录下

1. Navigate to HelloANELibrary/bin/.
2. Unzip the HelloANELibrary.swc file, or open it in an archive management tool (e.g., 7-Zip).
3. You'll see a catalog.xml and a library.swf file inside of the SWC archive.
   The library.swf file needs to be placed inside of the native code directory for every platform you target. For example, you'd place this file inside iOS/, android/, x86/, etc., depending on your project's targets. (For more advanced ANEs, you can specify different
   library.swf files, if you require that your AS3 library is different for different platforms. This goes against the best practice of defining a common interface, however, and it's recommended that you stick with a single version of library.swf.)
   从SWC文件中会看到catalog.xml和library.swf。library.swf需要被放置在每个目标平台的native code所在目录。比如，你需要把这个文件放入iOS、android、x86等。（可能有不同的library.swf的情况。。。）
4. When complete, your HelloANELibrary folder should contain both HelloANELibrary.swc, and HelloANENative should contain library.swf.
   操作完成时，文件夹HelloANELibrary应该包含HelloANELibrary.swc，HelloANENative应该包含library.swf。（此话可能翻译不准确）

By extracting library.swf, you now have all the files you need to create a native extension. Note that you have to repeat steps 1 through 4 whenever you change your library code, otherwise library.swf will be out of date.
通过解压获得library.swf后，现在你已经可以创建一个native extension。注意，只要你改变了你的library 代码，你就需要重复这四步，否则library.swf会过时。

At this point, you've written all of the library code you need to use your native extension.

Describing your native extension in an extension.xml file

You've created the requisite code, but you've yet to link everything together into an ANE file. First, create an extension.xml file inside of your Flex library project. For each native target,
this file points to the native code (your JAR file) and describes the package location of the initializer function (and, optionally, a finalizer function, which you don't need in this example). You'll hand this file to the packager when you create your ANE
file (which you'll then use in a sample application).
为了创建一个ANE文件，首先，在Flex库工程中创建一个extension.xml文件，对于每个native target，。。。

Create the extension.xml file inside of your Flex library project:

1. Right-click the src folder in your HelloANELibrary project. Click New > File.
2. Name the file extension.xml.
3. Re-open this file by right-clicking it and selecting Text Editor, rather than the default XML editor.
   建议用文本编辑器来打开
4. The following XML describes the AIR namespace to use (2.5), the ID of the extension, and the single platform we wish to target (note that "iPhone-ARM" is another common target platform):
   

<extension xmlns="http://ns.adobe.com/air/extension/2.5">
       <id>com.yourDomain.Vibrate</id>
          <versionNumber>1</versionNumber>
   
          <platforms>
           <platform name="Android-ARM">
      
           <!-- ... -->
      
           </platform>
       </platforms>
</extension>

Inside of the <platform> tags, you'll now set the location of the JAR file in a <nativeLibrary> tag, and set the
location of the initializer to the location we set in the native code (recall that you created the initialize() function in your VibrationExtension class):
在标签 platform里，你可以在标签nativeLibrary中设定JAR的位置，并且设定Initializer的位置

<applicationDeployment>         
       <nativeLibrary>HelloANENative.jar</nativeLibrary>
         <initializer>com.yourDomain.example.android.helloANE.extensions.VibrationExtension </initializer>
</applicationDeployment> 

You've now successfully created your extension.xml file, and have all the components you need to create your ANE file.

Packaging a native extension

Currently, packaging a native extension requires using the command line tool adt, and passing it a number of parameters. I recommend creating a batch script in Windows (.bat file), or a bash script in OS X (typically a .sh file); the script you'll create will
allow you to set your own variables in the top part of the script, allowing it to be easily adapted to your other native extension projects.
建议使用批处理

There are a number of pieces of information you need to plug into the script. I'll list the information, and show you the values I use on my own system:
以下是脚本中需要的信息

• Location of adt: C:\Program Files\Adobe Flash Builder 4.5\sdks\4.5.2\bin
  adt的位置
• Programming root directory: C:\Users\dan\Programs
• ActionScript 3 library directory: %root_directory%\HelloANELibrary
  AS3库的目录
• Android native directory: %root_directory%\HelloANENative
  Android native的目录
• Signing options: -storetype pkcs12 -keystore "c:\Users\dan\Programs\ cert.p12"
  签名选项
• Destination ANE file: HelloANE.ane
  目标ANE文件名
• Location of extension.xml: %library_directory%\src\extension.xml
  extension.xml的位置
• Location of compiled ActionScript 3 library SWC: %library_directory%\bin\HelloANELibrary.swc
  编译好的SWC的位置

"%adt_directory%"\adt -package %signing_options% -target ane "%dest_ANE%" "%extension_XML%" -swc "%library_SWC%" -platform Android-ARM bin/library.swf -C "%native_directory%" .

This command may look complicated, but it's simply running adt and passing in signing options, specifying ane as the target, providing the extension.xml file, specifying the HelloANELibrary.swc file, targeting Android-ARM as the platform, and telling ADT where
to look for the native library files.
这个命令看起来有点复杂，不过它只是运行adt，并传入签名选项，指定ANE，提供extension名称，指定swc文件，目标平白，在哪里找native library文件

A compile_ane.bat file on Windows may look like this:
Windows平台上的批处理可能如下

set adt_directory=C:\Program Files\Adobe Flash Builder 4.5\sdks\4.5.2\bin
set root_directory=C:\Users\dan\Programs   
set library_directory=%root_directory%\HelloANELibrary
set native_directory=%root_directory%\HelloANENative  
set signing_options=-storetype pkcs12 -keystore "c:\Users\dan\Programs\cert.p12" 
set dest_ANE=HelloANE.ane 
set extension_XML=%library_directory%\src\extension.xml 
set library_SWC=%library_directory%\bin\HelloANELibrary.swc 
"%adt_directory%"/adt -package %signing_options% -target ane "%dest_ANE%" "%extension_XML%" -swc "%library_SWC%" -platform Android-ARM -C "%native_directory%" .

On Mac OS X, the script might look like this:

#!/bin/bash

adt_directory="/Users/Applications/Adobe Flash Builder 4.5/sdks/4.5.2/bin"                                     
root_directory=/Users/dan/Programs                                                                             
library_directory=${root_directory}/HelloANELibrary
native_directory=${root_directory}/HelloANENative  
signing_options="-storetype pkcs12 -keystore /Users/dan/Programs/cert.p12" 
dest_ANE=HelloANE.ane 
extension_XML=${library_directory}/src/extension.xml 
library_SWC=${library_directory}/bin/HelloANELibrary.swc 

"${adt_directory}"/adt -package ${signing_options} -target ane "${dest_ANE}" "${extension_XML}" -swc "${library_SWC}" -platform Android-ARM -C "${native_directory}" .

Note that I use a p12 file as my signing certificate. You can substitute the file you normally use for signing AIR files. If you need to create one, the easiest way to do so is to open a Flex or AIR project in Flash Builder, and go to Project > Export Release
Build. During the second step you'll have the option to create a certificate using the GUI.
注意我使用p12文件作为我的签名证书。你可以用你通常使用的。如果你需要创建一个，最简单的途径就是打开一个Flex或者AIR工程，通过Project > Export Release Build，在第二步里会有机会通过GUI创建一个证书。

Run your script from the command line, enter your cert's password, and the %dest_ANE% file should be created, and ready to use in a sample application!
运行脚本，输入密码，%dest_ANE% 代表的文件应该生成。

Using the native extension in a Flex sample application

You're now going to create a Flex mobile application that uses your native extension! The process of setting up a project and deploying it to Android is simple:

1. In Flash Builder 4.5.2, click File > New > Flex Mobile Project.
   创建一个Flex Mobile工程
2. Name the project HelloANESample.
3. Make sure you're using the 4.5.2 SDK or newer, and click Next.
   确保使用4.5.2 SDK或者更新版本
4. Make sure that only Google Android is selected as a target platform.
5. Choose a View-Based application and click Next.
6. Click Next, as you don't need any server settings.
7. Click the NativeExtensions tab, which allows you to target any ANE files that your application needs.
   迁移至Native Extensions页
8. Click Add and browse to the ANE file you packaged in the previous step. It should be in the HelloANELibrary folder, named HelloANE.ane.
   加入前面所打包的ANE文件
9. Click OK. You should see a green check mark next to the ANE file's entry. If you expand this entry, you should see the following warning: "Launching on win32(Windows-x86) is not supported" (or a similar message for OS X). This is because we didn't target
   our desktop environment when we coded the native portion of our native extension, nor did we configure it when we wrote the extension.xml or ran ADT.
10. Click Finish.
11. We'll now double check that the native extension is included in packaging, and not just in the build paths. Although it should be correctly configured, you may have to perform these steps should you modify the native extension. Right-click your project
    in the Package Explorer and select Properties.

12. Expand Flex Build Packaging and select Google Android.
13. Click the Native Extensions tab.
14. You should see a green check mark next to your native extension, as well as a checkmark in the Package column for that native extension. If not, select the check box.
15. Click OK to close the project properties.

1. Right-click the HelloANESample-app.xml application descriptor, and choose to open it with the text editor.
2. Scroll down to this section:

<android>
    <manifestAdditions><![CDATA[
        <manifest android:installLocation="auto">

        3.   Add permission to use the Vibration controls:

<uses-permission android:name="android.permission.VIBRATE"/>

Using your native extension
Now that the project is configured, you can add a vibrate button to the home view:

1. Between the s:View tags (in the main body of the class), add a new s:Button . Give it a label of Vibrate using ANE, and create a new click handler. Flash Builder should automatically create an fx:Script tag and click handler ActionScript 3 function for
   you.
2. Create a new Vibrate class inside of your click handler, which will expose your native extension via an ActionScript 3 object:

var v:Vibrate = new Vibrate();

        3.  Trace the value of v.isSupported , and then call your main vibrate function, passing in a hard-coded value of 100 for the number of milliseconds the motor should run:

trace("Is this ANE supported on this platform? " + Vibrate.isSupported);
v.vibrate(100);

       4. Click the debug button in the main toolbar.
       5. Select Google Android as the target platform, and choose to launch on the device, with debugging via USB.
       6. Click Debug.

The Flex application should now launch on the device, and provide a button labelled Vibrate using ANE. Tapping this button should produce a 100ms long vibration from the motor in your Android device! You'll also notice the following output in the Console view
in Flash Builder:

[SWF] com.yourDomain.Vibrate - 2,916 bytes after decompression
[SWF] HelloANESample.swf - 2,702,220 bytes after decompression
Is this ANE supported on this platform? True

You can add a TextInput or form of numeric input if you wish to control the duration of the vibration. Simply replace the 100 argument that we hard-coded with a locally scoped variable, and set this variable using a control. At this point,
coding the ActionScript 3 side of your application is no different than other Flex application development.

Where to go from here

In this guide you learned that AIR native extensions allow you to expand the capabilties of Adobe AIR, giving your applications access to device and hardware capabilities that would otherwise be inaccessible via the runtime APIs alone. You learned how to create
native extensions for Android, and can use these skills to target other platforms. In this example, you focused on the simple task of making the vibration motor of an Android device activate for a specified duration; this illustrated how to create and initialize
an native extension, as well as pass data back and forth between your native code and your AIR application.

1. Coded in native Java to interface with the native extension APIs that Adobe AIR provides (FREObject, FREFunction, etc.).
2. Coded a Flex library comprised of ActionScript 3 APIs. These hooked into your native APIs.
3. Wrote an extension.xml describing our extension.
4. Scripted a batch/bash file to package our native extension with the command line utility ADT.
5. Created a mobile Flex project that uses our native extension.

• Although you focused on Android, native extensions work on iOS, Mac OS X, Windows, and Adobe AIR for TV. You can create a single native extension that targets multiple platforms, and your application logic can determine (at runtime or compile-time) if specific
  features are supported on a platform-by-platform basis.
• You now have the knowledge and skills necessary to create your own native extensions. Your applications can access additional hardware features, take advantage of native-optimized code or third party libraries, and even spawn multiple threads to handle
  time-consuming computations without blocking your AIR app.

• On Android, include your assets "res" folder of your Android project path. These files will be merged into the resources directory of your main application, so you need to choose unique names that won't conflict with your other assets. You can access them
  using FREContext.getResourceId(), by passing in the desired resource ID (see also Oliver Goldman's article, Extending Adobe AIR).
• On iOS, resources are accessed via the NSBundle APIs; note that the namespaces are flattened when the project is compiled, and the names you choose for your resources (even if used only in native code) should be guaranteed not to conflict with other resources
  in your project. For example, don't use two resources anywhere in your project that are both named Localizable.strings (see also Oliver Goldman's article, Extending Adobe AIR).

context.dispatchStatusEventAsync("DATA_CHANGED", stringData);

context.addEventListener(StatusEvent.STATUS, onStatus);
...
private function onStatus(e:StatusEvent):void 
{      
    if (e.code == "DATA_CHANGED") 
    {
        var stringData:String = e.level;
        // ...
    }
}