Android NDK rb5 文档之 native_activity.h 文件翻译

/**
* Copyright (C) 2010 The Android Open Source Project
* 版权（C）2010 Android 开源工程
*
* Licensed under the Apache License, Version 2.0 (the "License");
* 根据 2.0 版本 Apache 许可证授权
* you may not use this file except in compliance with the License.
* 根据本许可证，你可以不使用此文件。
* You may obtain a copy of the License at
* 你可以获得许可证的副本在
*
*      http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* 除非因适用法律需要或书面同意，
* 根据许可证分发的软件是基于"按原样"原则提供，无任何明示的或暗示的保证或条件。
* See the License for the specific language governing permissions and
* limitations under the License.
* 详见根据许可证许可下，特定语言的管辖权限和限制。
*/


#ifndef ANDROID_NATIVE_ACTIVITY_H
#define ANDROID_NATIVE_ACTIVITY_H

#include <stdint.h>
#include <sys/types.h>

#include <jni.h>

#include <android/asset_manager.h>
#include <android/input.h>
#include <android/native_window.h>

#ifdef __cplusplus
extern "C" {
#endif

struct ANativeActivityCallbacks;

/**
* This structure defines the native side of an android.app.NativeActivity.
* 本结构体定义了 android.app.NativeActivity 的本地部分。
*
* It is created by the framework,
* and handed to the application's native code as it is being launched.
* 它是被框架创建并在应用程序的本地代码运行时传入。
*/
typedef struct ANativeActivity {
    /**
     * Pointer to the callback function table of the native application.
     * 指向本地应用程序的回调函数表。
     *
     * You can set the functions here to your own callbacks.
     * 你可以在这里设置你的回调函数。
     *
     * The callbacks pointer itself here should not be changed;
     * 回调指针自身在这里将不会改变；
     *
     * it is allocated and managed for you by the framework.
     * 由框架为你分配和管理。
     */
    struct ANativeActivityCallbacks* callbacks;

    /**
     * The global handle on the process's Java VM.
     * 进程的 Java 虚拟机全局句柄。
     */
    JavaVM* vm;

    /**
     * JNI context for the main thread of the app.
     * 应用程序主线程用 JNI 环境。
     *
     * Note that this field can ONLY be used from the main thread of the process;
     * 注意这个成员变量仅可以被进程的主线程使用；
     *
     * that is, the thread that calls into the ANativeActivityCallbacks.
     * 即，该进程的主线程调用进入到 ANativeActivityCallbacks 里。
     */
    JNIEnv* env;

    /**
     * The NativeActivity Java class.
     * NativeActivity Java 类。
     */
    jobject clazz;

    /**
     * Path to this application's internal data directory.
     * 本应用程序的内部数据目录路径。
     */
    const char* internalDataPath;
   
    /**
     * Path to this application's external (removable/mountable) data directory.
     * 本应用程序的外部(可移除的或可安装的)数据目录路径。
     */
    const char* externalDataPath;
   
    /**
     * The platform's SDK version code.
     * 平台的 SDK 版本代码。
     */
    int32_t sdkVersion;
   
    /**
     * This is the native instance of the application.
     * 这是应用程序的本地实例。
     *
     * It is not used by the framework,
     * but can be set by the application to its own instance state.
     * 它是不能被框架使用，但是可以被应用程序设置它自己的实例状态。
     */
    void* instance;

    /**
     * Pointer to the Asset Manager instance for the application.
     * 指向应用程序资产管理器实例。
     *
     * The application uses this to access binary assets bundled inside its own .apk file.
     * 应用程序使用它来存取包在它自己 .apk 文件里面的二进制资产。
     */
    AAssetManager* assetManager;
} ANativeActivity;

/**
* These are the callbacks the framework makes into a native application.
* 这些回调使框架转变成一个本地应用程序。
*
* All of these callbacks happen on the main thread of the application.
* 这些回调全部发生在应用程序的主线程上。
*
* By default, all callbacks are NULL;
* 默认情况下，全部回调都是 NULL;
* set to a pointer to your own function to have it called.
* 设置指向你自己的函数允许被调用。
*/
typedef struct ANativeActivityCallbacks {
    /**
     * NativeActivity has started.
     * NativeActivity 已经启动。
     * See Java documentation for Activity.onStart() for more information.
     * 看 Java 文档中的 Activity.onStart() 的更多信息。
     * 注：该方法说明了将要显示给用户的活动。
     */
    void (*onStart)( ANativeActivity* activity );
   
    /**
     * NativeActivity has resumed.
     * NativeActivity 已经(中断后)继续。
     * See Java documentation for Activity.onResume() for more information.
     * 看 Java 文档中的 Activity.onResume() 的更多信息。
     * 注：用户可以开始与活动进行交互时会调用该方法。这个方法非常适合开始播放动画和音乐。
     */
    void (*onResume)( ANativeActivity* activity );
   
    /**
     * Framework is asking NativeActivity to save its current instance state.
     * 框架寻问 NativeActivity 去保存它的当前实例状态。
     *
     * See Java documentation for Activity.onSaveInstanceState() for more information.
     * 看 Java 文档中的 Activity.onSaveInstanceState() 的更多信息。
     * 注：Android调用该方法的作用是让活动可以保存每个实例的状态，如光标在文本字段中的位置。
     *
     * The returned pointer needs to be created with malloc();
     * 返回值指针是用 malloc() 创建的；
     *
     * the framework will call free() on it for you.
     * 框架将为你调用 free() 释放它。
     *
     * You also must fill in outSize with the number of bytes in the allocation.
     * 你还必须用 outSize 来得到分配的字节数量。
     *
     * Note that the saved state will be persisted,
     * so it can not contain any active entities (pointers to memory, file descriptors, etc).
     * 注意保存状态将是持续的，所以它不能包含任何活动实体(指向内存、文件描述，等等)。
     */
    void* (*onSaveInstanceState)( ANativeActivity* activity,
                                  size_t*          outSize );
   
    /**
     * NativeActivity has paused.
     * NativeActivity 已经暂停。
     *
     * See Java documentation for Activity.onPause() for more information.
     * 看 Java 文档中的 Activity.onPause() 的更多信息。
     * 注：活动将要进入后台时会运行该方法，活动进入后台的原因通常是在前台启动了另一个活动。
     * 　　还应该在该方法中保存程序的持久性状态，如正在编辑的数据库记录。
     */
    void (*onPause)( ANativeActivity* activity );
   
    /**
     * NativeActivity has stopped.
     * NativeActivity 已经停止。
     *
     * See Java documentation for Activity.onStop() for more information.
     * 看 Java 文档中的 Activity.onStop() 的更多信息。
     * 注：用户无需看到某个活动，或者在一段时间内不需要某个活动时，可以调用该方法。
     * 　　如果内存不足，可能永远都不会调用该方法，系统可能只是终止进程。
     */
    void (*onStop)( ANativeActivity* activity );
   
    /**
     * NativeActivity is being destroyed.
     * NativeActivity 正在被销毁。
     *
     * See Java documentation for Activity.onDestroy() for more information.
     * 看 Java 文档中的 Activity.onDestroy() 的更多信息。
     * 注：销毁活动前会调用该方法。
     * 　　如果内存不足，可能永远都不会调用该方法，系统可能只是终止进程。
     */
    void (*onDestroy)( ANativeActivity* activity );

    /**
     * Focus has changed in this NativeActivity's window.
     * 在这个 NativeActivity 的窗口里焦点已经改变。
     * This is often used, for example, to pause a game when it loses input focus.
     * 这是通常用来，例如，当一个游戏丢失输入焦点时暂停。
     */
    void (*onWindowFocusChanged)( ANativeActivity* activity,
                                  int              hasFocus );
   
    /**
     * The drawing window for this native activity has been created.
     * 这个本地活动已经创建了图形窗口。
     *
     * You can use the given native window object to start drawing.
     * 你可以使用特定的本地窗口对象开始绘画。
     */
    void (*onNativeWindowCreated)( ANativeActivity* activity,
                                   ANativeWindow*   window );

    //
     * The drawing window for this native activity has been resized.
     * 这个本地活动已经重设图形窗口大小。
     *
     * You should retrieve the new size from the window and ensure that
     * your rendering in it now matches.
     * 你将重新得到窗口的新大小并且保证你的绘制现在用它相一致。
     */
    void (*onNativeWindowResized)( ANativeActivity* activity,
                                   ANativeWindow*   window );

    /**
     * The drawing window for this native activity needs to be redrawn.
     * 这个本地活动需要重绘图形窗口。
     *
     * To avoid transient artifacts during screen changes (such resizing after rotation),
     * applications should not return from this function
     * until they have finished drawing their window in its current state.
     * 为预防短暂的错失在屏幕改变期间(在交替之后重新恢复到应有尺寸)，
     * 应用程序将不能从这个函数返回直到它们用它们的当前状态绘画它们的窗口完成。
     */
    void (*onNativeWindowRedrawNeeded)( ANativeActivity* activity,
                                        ANativeWindow*   window );

    /**
     * The drawing window for this native activity is going to be destroyed.
     * 这个本地活动将要销毁图形窗口。
     *
     * You MUST ensure that
     * you do not touch the window object after returning from this function:
     * 你必须确保你没有触摸窗口对象在从这个函数返回后：
     *
     * in the common case of drawing to the window from another thread,
     * that means the implementation of this callback must properly synchronize
     * with the other thread to stop its drawing before returning from here.
     * 在窗口出自其它线程的共同绘图情况中，意味着该回调实现必须妥善同步，在从这里退出之前其它线程停止它们的绘图。
     */
    void (*onNativeWindowDestroyed)( ANativeActivity* activity,
                                     ANativeWindow*   window );
   
    /**
     * The input queue for this native activity's window has been created.
     * 这个本地活动窗口的输入队列已经创建。　
     *
     * You can use the given input queue to start retrieving input events.
     * 你可以使用给定的输入队列开始检索输入事件。
     */
    void (*onInputQueueCreated)( ANativeActivity* activity,
                                 AInputQueue*     queue );
   
    /**
     * The input queue for this native activity's window is being destroyed.
     * 这个本地活动窗口的输入队列已经销毁。
     *
     * You should no longer try to reference this object upon returning from this function.
     * 一旦从该函数返回你将不能再试图引用这个对象了。
     */
    void (*onInputQueueDestroyed)( ANativeActivity* activity,
                                   AInputQueue*     queue );

    /**
     * The rectangle in the window in which content should be placed has changed.
     * 窗口内容矩形被放置改变。
     */
    void (*onContentRectChanged)( ANativeActivity* activity,
                                  const ARect*     rect );

    /**
     * The current device AConfiguration has changed.
     * 当前设备 AConfiguration 已发生改变。
     *
     * The new configuration can be retrieved from assetManager.
     * 新的配置可以从 activity->assetManager 中检索到。
     */
    void (*onConfigurationChanged)( ANativeActivity* activity );

    /**
     * The system is running low on memory.
     * 系统正在用尽内存。
     *
     * Use this callback to release resources you do not need,
     * to help the system avoid killing more important processes.
     * 使用这个回调去释放你不需要的资源，以免系统杀死更多重要的进程。
     */
    void (*onLowMemory)( ANativeActivity* activity );
} ANativeActivityCallbacks;

/**
* This is the function that
* must be in the native code to instantiate the application's native activity.
* 必须在本地代码中实例化应用程序的本地活动。
*
* It is called with the activity instance (see above);
* 它是被活动实例调用的(参见上文)；
*
* if the code is being instantiated from a previously saved instance,
* the savedState will be non-NULL and point to the saved data.
* 如果正在被实例化用之前保存的实例，savedState 参数值将非 NULL 且指向已保存的数据。
*
* You must make any copy of this data you need --
* it will be released after you return from this function.
* 你必须备份 savedState 中你需要的数据 -- 它将在从这个函数中返回后释放。
*/
typedef void ANativeActivity_createFunc( ANativeActivity* activity,
                                         void*            savedState,
                                         size_t           savedStateSize );

/**
* The name of the function that NativeInstance looks for when launching its native code.
* 当启动它的本地代码时，NativeInstance 寻找这个函数名。
*
* This is the default function that is used,
* you can specify "android.app.func_name" string meta-data in
* your manifest to use a different function.
* 被用作默认函数，你可以在你的 AndroidManifest.xml 里的 activity 标签下用
* <meta-data android:name="android.app.func_name" android:value="替换的函数名" />
* 明确说明使用一个不同的函数。
*/
extern ANativeActivity_createFunc ANativeActivity_onCreate;

/**
* Finish the given activity.
* 结束给定的活动。
*
* Its finish() method will be called,
* causing it to be stopped and destroyed.
* 它的 finish() 方法将是被调用，导致它停止且销毁。
*
* Note that this method can be called from *any* thread;
* 注意该方法可以被任何线程调用；
*
* it will send a message to the main thread of the process
* where the Java finish call will take place.
* 它将发送一个消息到进程的主线程，在那里 Java 结束调用将发生。
*/
void ANativeActivity_finish( ANativeActivity* activity );

/**
* Change the window format of the given activity.
* 改变给定活动的窗口样式。
*
* Calls getWindow().setFormat() of the given activity.
* 调用给定活动的 getWindow().setFormat() 。
*
* Note that this method can be called from *any* thread;
* 注意该方法可以被任何线程调用；
*
* it will send a message to the main thread of the process
* where the Java finish call will take place.
* 它将发送一个消息到进程的主线程，在那里 Java 结束调用将发生。
*/
void ANativeActivity_setWindowFormat( ANativeActivity* activity,
                                      int32_t          format );

/**
* Change the window flags of the given activity.
* 改变给定活动的窗口标志。
*
* Calls getWindow().setFlags() of the given activity.
* 调用给定活动的 getWindow().setFlags() 。
*
* Note that this method can be called from *any* thread;
* 注意该方法可以被任何线程调用；
*
* it will send a message to the main thread of the process
* where the Java finish call will take place.
* 它将发送一个消息到进程的主线程，在那里 Java 结束调用将发生。
*
* See window.h for flag constants.
* 看 window.h 中的标志常量。
*/
void ANativeActivity_setWindowFlags( ANativeActivity* activity,
                                     uint32_t         addFlags,
                                     uint32_t         removeFlags );

/**
* Flags for ANativeActivity_showSoftInput;
* ANativeActivity_showSoftInput 的标志；
*
* see the Java InputMethodManager API for documentation.
* 看 Java 中关于 InputMethodManager API 的文档。
*/
enum {
    ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001,
    ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002,
};

/**
* Show the IME while in the given activity.
* 在给定活动里显示输入法时。
*
* Calls InputMethodManager.showSoftInput() for the given activity.
* 为给定活动调用 InputMethodManager.showSoftInput() 。
*
* Note that this method can be called from *any* thread;
* 注意该方法可以被任何线程调用；
*
* it will send a message to the main thread of the process
* where the Java finish call will take place.
* 它将发送一个消息到进程的主线程，在那里 Java 结束调用将发生。
*/
void ANativeActivity_showSoftInput(ANativeActivity* activity, uint32_t flags);

/**
* Flags for ANativeActivity_hideSoftInput;
* ANativeActivity_hideSoftInput 的标志；
*
* see the Java InputMethodManager API for documentation.
* 看 Java 中关于 InputMethodManager API 的文档。
*/
enum {
    ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001,
    ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002,
};

/**
* Hide the IME while in the given activity.
* 在给定活动里隐藏输入法时。
*
* Calls InputMethodManager.hideSoftInput() for the given activity.
* 为给定活动调用 InputMethodManager.hideSoftInput() 。
*
* Note that this method can be called from *any* thread;
* 注意该方法可以被任何线程调用；
*
* it will send a message to the main thread of the process
* where the Java finish call will take place.
* 看 Java 中关于 InputMethodManager API 的文档。
*/
void ANativeActivity_hideSoftInput(ANativeActivity* activity, uint32_t flags);

#ifdef __cplusplus
};
#endif

#endif // ANDROID_NATIVE_ACTIVITY_H