【翻译】(24)Native Activity

-----------------

英文文档见android-ndk-r6b的documentation.html

属于Android Native Development Kit (NDK)的一部分

见

http://developer.android.com/sdk/ndk/index.html

翻译仅个人见解

-----------------

 

Native Activities and Applications:

 

原生活动和应用程序：

-----------------------------------

 

I. Overview

 

一、概述

===========

 

The Android SDK provides a helper class, NativeActivity, that allows you to write a completely native activity. With a native activity, it is possible to write a completely native application. NativeActivity handles the communication between the Android framework and your native code, so you do not have to subclass it or call its methods. All you need to do is declare your application to be native in your AndroidManifest.xml file and begin creating your native application.

 

Android SDK提供一个辅助类，NativeActivity，允许你书写一个完全原生的活动。使用一个原生活动，可以书写一个完全原生的应用程序。NativeActivity处理Android框架和你的原生代码间的通信，所以你不必子类化它或调用它的方法。你所需要做的是在你的AndroidManifest.xml文件内声明你的应用程序为原生的，然后开始创建你的原生应用程序。

 

Native activities do not change the fact that Android applications still run in their own virtual machine, sandboxed from other applications. Because of this, you can still access Android framework APIs through the JNI. There are, however, native interfaces to access things such as sensors, input events, and assets that you can use. For more information about what is supported, see the <ndk_root>/docs/STABLE-APIS.HTML.

 

原生活动不会改变Android应用程序仍旧运行在它自己的虚拟机内，和其他应用程序用沙箱隔离的事实。因此，你仍然可以通过JNI访问Android框架API。虽然如此，有一些东西诸如传感器、输入事件和资源的访问，你仍然可以使用它们。想获得更多支持特性的相关信息，请参考<ndk_root>/docs/STABLE-APIS.HTML。

 

If you are developing a native activity, you should still create your projects with Eclipse or the "android create project" command. You still build and package native applications with the usual Android build tools, so the build system can only build Android projects that have the correct structure. Using the android tool or Eclipse helps ensure that.

 

如果你在开发一个原生活动，你仍旧应该用Eclipse或android create project命令创建你的工程。你仍然使用通常的Android构建工具构建和打包应用程序，所以构建系统只能构建拥有正确结构（注：这里应该指目录结构）的Android工程。使用android工具或Eclipse有助于保证这一点。

 

The Android NDK provides you with two choices to implement your native activity:

 

Android NDK为你提供两个实现原生活动的选择：

 

  - The native_activity.h header defines the native version of the NativeActivity class. It contains the callback interface and data structures that you need to create your native activity. Because the main thread of your application handles the callbacks, your callback implementations must not be blocking. If they block, you might receive ANR (Application Not Responding) errors because your main thread will be unresponsive until the callback returns. Read the comments in the <ndk_root>/platforms/android-9/arch-arm/usr/include/android/native_activity.h file for more information.

 

  - native_activity.h头文件定义NativeActivity类的原生版本。它包含你创建原生活动所需的回调接口和数据结构。因为你的应用程序的主线程要处理回调，所以你的回调实现禁止阻塞。如果它们阻塞了，你将收到ANR（应用程序无响应）错误，因为你的主线程在回调返回之前将是无响应的。更多信息请阅读<ndk_root>/platforms/android-9/arch-arm/usr/include/android/native_activity.h文件的注释。

 

  - The android_native_app_glue.h file defines a static helper library built on top of the native_activity.h interface. It spawns another thread to handle things such as callbacks or input events. This prevents any callbacks from blocking your main thread and adds some flexibility in how you implement the callbacks, so you might find this programming model a bit easier to implement. The <ndk_root>/sources/android/native_app_glue/android_native_app_glue.c source is also available to you, so you can modify the implementation if you need. Read the comments in the <ndk_root>/sources/android/native_app_glue/android_native_app_glue.h file for more information.

 

  - android_native_app_glue.h文件定义一个静态辅助库，它在native_activity.h接口基础上构建。它生成另一个线程处理各种事情诸如回调或输入事件。它防止任何回调阻塞你的主线程，并且对你实现回调增加某些灵活性，所以你可能发现这个编程模型稍微较容易实现。<ndk_root>/sources/android/native_app_glue/android_native_app_glue.c的源代码也对你可用，所以你可以根据需要修改其实现。更多信息请阅读<ndk_root>/sources/android/native_app_glue/android_native_app_glue.h文件。

 

II. Using the native-activity.h interface:

 

二、使用native-activity.h接口：

==========================================

 

You can use the native-activity.h interface to implement a completely native activity. If you use this interface you must ensure that your callback implementations do not block the main UI thread. For more information on how to use this interface, see <ndk_root>/platforms/android-9/arch-arm/usr/include/android/native_activity.h.

 

你可以使用native-activity.h接口实现一个完全原生的活动。如果你使用这个接口你必须确保你的回调实现不会阻塞主UI线程。更多关于如何使用这个接口的信息，请参考<ndk_root>/platforms/android-9/arch-arm/usr/include/android/native_activity.h。

 

You might find it easier to use the native_app_glue static helper library that handles the callbacks in an event loop in another thread. See the native-activity sample application for more information on how to use this static library.

 

你可能发现使用native_app_glue静态辅助库较容易在另一个线程的事件循环中处理回调。更多关于如何使用这个静态库的信息，请参考native-activity示例应用程序。

 

To implement a native activity with the native-activity.h interface:

 

要用native-activity.h接口实现一个原生活动：

 

  1/ Create a project with the "android create project" command or from Eclipse. Create a jni/ directory in the project's root directory. This directory stores all of your native code.

 

  1/ 用android create project命令或从Eclipse中创建一个工程。在工程根目录创建一个jni/目录。这个目录保存你的所有原生代码。

 

  2/ Declare your native activity in the AndroidManifest.xml file. An example is shown below:

 

  2/ 在AndroidManifest.xml文件内声明你的原生活动。例子如下：

 

      <manifest xmlns:android="http://schemas.android.com/apk/res/android"

        package="com.example.native_activity"

        android:versionCode="1"

        android:versionName="1.0">  

 

        <uses-sdk android:minSdkVersion="8" />

 

        <application android:label="@string/app_name" android:hasCode="false">

 

          <activity android:name="android.app.NativeActivity"

            android:label="@string/app_name"

            android:configChanges="orientation|keyboardHidden">

 

          <meta-data android:name="android.app.lib_name"

            android:value="native-activity" />

            <intent-filter>

              <action android:name="android.intent.action.MAIN" />

              <category android:name="android.intent.category.LAUNCHER" />

            </intent-filter>

          </activity>

        </application>

      </manifest>

 

    The main things to note are:

 

    要注意的主要事情有：

 

      - The android:name attribute of the activity tag must be set to android.app.NativeActivity. It is possible to subclass the NativeActivity, however, so if you do, specify the name of that class instead.

 

      - activity标签的android:name属性必须设置为android.app.NativeActivity。但可以子类化NativeActivity，然而，如果你这么做，需要在这里改为指定你的子类名称。

 

      - The android:name attribute of the meta-data tag must be in the form of android.app.lib_name where lib_name is the name of the module without the lib prefix and .so suffix.

 

      - meta-data标签的android:name属性必须是android.app.lib_name格式的，这里lib_name是模块名，不带lib前缀和.so后缀。

（注：这里貌似有误，应该是android:value的属性值是模块名，而非lib_name）

 

  3/ Create a file for your native activity and implement the ANativeActivity_onCreate() function,  which is called when your native activity starts. This function receives a pointer to an ANativeActivity structure, which contains function pointers to the various callback implementations that you need to write. Set the applicable callback function pointers in ANativeActivity->callbacks to the implementations of your callbacks.

 

  3/ 为你的原生活动创建一个文件实现ANativeActivity_onCreate()函数，它在你的原生活动开始时被调用。这个函数收到一个ANativeActivity结构体的指针，它包含你需要修改的不同回调实现的函数指针。在ANativeActivity->callbacks里把应用程序回调函数指针设置为你的回调实现。

 

  4/ Set the ANativeActivity->instance field to the address of any instance specific data that you want to use.

 

  4/ 把ANativeActivity->instance域设置为你想使用的任意特定于实例的数据的地址。

 

  5/ Implement any other things that you want your activity to do upon starting.

 

  5/ 实现其它任何你想让你的活动在开始之前完成的事情。

 

  6/ Implement the rest of the callbacks that you set in ANativeActivity->callbacks. For more information on when the callbacks are called, see the SDK documentation for Activity Lifecycles. Remember that your callback implementations must not be blocking, or you might get ANR (Application Not Responding) errors because the main UI thread is waiting for the callbacks to return.

 

  6/ 实现你设置到ANativeActivity->callbacks的其它回调，更多关于回调何时被调用的信息，请参考SDK文档的活动生命周期部分。记住你的回调实现禁止阻塞，否则你可能得到ANR（应用程序无响应）错误，因为主UI线程等待回调返回。

 

  7/ Develop the rest of your application.

 

  7/ 开发你的应用程序的其它部分。

 

  8/ Create an Android.mk file in the jni/ directory of your project to describe your native module to the build system. An Android.mk file is essentially a snippet of a GNU Make file. For example:

 

  8/ 在你的工程的jni/目录下创建Android.mk文件，向构建系统描述你的原生模块。Android.mk文件实质是一个GNU Make文件的片段。例如：

 

       LOCAL_PATH := $(call my-dir) 

       include $(CLEAR_VARS)

       LOCAL_MODULE    := my_native_module

       LOCAL_SRC_FILES := my_native_code.c

       include $(BUILD_SHARED_LIBRARY)

 

     For more information on how to create an Android.mk file and what the variables mean, see the <ndk_root>/docs/ANDROID-MK.TXT file.

 

     更多关于如何创建Android.mk以及变量含义的信息，请参考<ndk_root>/docs/ANDROID-MK.TXT文件。（注：现在是ANDROID-MK.html）

 

  9/ Once you have an Android.mk file, compile your native code using the "ndk-build" command.

 

  9/ 一旦你已经有了Android.mk文件，就可以用ndk-build命令编译原生代码。（注：貌似cygwin在这里可以用相对路径调用ndk-build，或者写shell脚本）

 

       cd path/to/project

       <ndk_root>/ndk-build

 

 10/ Build and install your Android project as usual, using Ant or Eclipse. The build automatically packages your native code into the .apk file if it is present in the jni/ directory.

 

 10/ 像平时那样构建并按照你的Android工程，使用Ant或Eclipse。构建过程会自动打包你的原生代码进.apk文件如果它在jni/目录下给出。

 

（注：注意，概述部分提到两种方法，而NDK自带的示例中native-activity只使用了方法二android_native_app_glue。使用android_native_app_glue的入口点是android_main，其参数是android_app结构体指针，与上面提到的native-activity.h接口的使用是不同的，但原理应该差不多）