android ndk native_activity.h

#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.
     * android.app.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.
     * 它是不能被框架使用，但是可被应用程序来设置它自己的实例状态。
     * 注：参见 native_app_glue/android_native_app_glue.c 文件中的
     * 　　onDestroy 函数体的使用来看，该成员变量是用来指向开发人员自定义的数据结构体。
     */
    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 结构信息已发生改变。
     * 注：AConfiguration 结构在 configuration.h 中声明。
     *
     * The new configuration can be retrieved from assetManager.
     * 新的配置可以从 activity->assetManager 中重新得到。
     * 注：用 configuration.h 中声明的 AConfiguration_fromAssetManager 函数来重新得到。
     */
    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 参数指向数据中你需要的数据 -- 它将在这个函数返回后被框架释放。
* 注：savedState 和 savedStateSize 参数取值来源，
* 　　可参见上面 ANativeActivityCallbacks 结构体中的 onSaveInstanceState 回调函数指针。
*/
typedef void
ANativeActivity_createFunc( ANativeActivity* activity,
                            void*            savedState,
                            size_t           savedStateSize );

/**
* The name of the function that Native Instance looks for when launching its native code.
* 在本地实例启动它的本地代码时寻找这个函数名。
*
* 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="替换的函数名" />
* 来明确说明使用一个不同的函数名。
* 注：别忘了在你的代码中定义实现一个如下函数：
* void ANativeActivity_onCreate( ANativeActivity* activity,
*                                void*            savedState,
*                                size_t           savedStateSize )
* {
*      ... // 具体实现语句
* }
*/
extern ANativeActivity_createFunc ANativeActivity_onCreate;

/**
* Finish the given activity.
* 结束给定的活动。
*
* Its finish() method will be called,
* causing it to be stopped and destroyed.
* android.app.Activity 类的 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.
* 改变给定活动的窗口格式(即一个窗口可以使用的像素格式)。
* 注：参见 native_window.h 中的以 WINDOW_FORMAT_ 开头的宏值定义。
*
* Calls getWindow().setFormat() of the given activity.
* 调用给定活动的 getWindow().setFormat() 。
* 注：先调用 android.app.Activity 类对象的 getWindow 方法得到 android.view.Window 类对象，
* 　　再调用 android.view.Window 类对象的 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 函数的 flags 参数用的标志；
*
* see the Java InputMethodManager API for documentation.
* 参见 Java 中关于 android.view.inputmethod.InputMethodManager API 的文档。
*/
enum {
    /* Flag for showSoftInput(View, int) to indicate
     * that this is an implicit request to show the input window,
     * not as the result of a direct request by the user.
     * 该标志为 ANativeActivity_showSoftInput 函数的 flags 参数的取值之一，
     * 指出这是一个显示输入法窗口不明确的请求，不作为用户直接请求的结果。
     *
     * The window may not be shown in this case.
     * 在这种情况中输入法窗口可以不显示。
     */
    ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001,

    /* Flag for showSoftInput(View, int) to indicate
     * that the user has forced the input method open
     * (such as by long-pressing menu)
     * so it should not be closed until they explicitly do so.
     * 该标志为 ANativeActivity_showSoftInput 函数的 flags 参数的取值之一，
     * 指出用户强制打开输入法(例如通过长按菜单键)，因此它将一直保持打开直到用户明确关闭。
     */
    ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002,
};

/**
* Show the IME while in the given activity.
* 在给定活动里显示输入法。
*
* Calls InputMethodManager.showSoftInput() for the given activity.
* 为给定活动调用 android.view.inputmethod.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 函数的 flags 参数用的标志；
*
* see the Java InputMethodManager API for documentation.
* 参见 Java 中关于 android.view.inputmethod.InputMethodManager API 的文档。
*/
enum {
    /* Flag for hideSoftInputFromWindow(IBinder, int) to indicate
     * that the soft input window should only be hidden
     * if it was not explicitly shown by the user.
     * 该标志为 ANativeActivity_hideSoftInput 函数的 flags 参数的取值之一，
     * 指出如果用户没有明确地要显示输入法窗口的话，则隐藏它。
     */
    ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001,

    /* Flag for hideSoftInputFromWindow(IBinder, int) to indicate
     * that the soft input window should normally be hidden,
     * unless it was originally shown with SHOW_FORCED.
     * 该标志为 ANativeActivity_hideSoftInput 函数的 flags 参数的取值之一，
     * 指出输入法窗口通常是隐藏的，
     * 除非它起初是用 ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED 标志显示的。
     */
    ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002,
};

/**
* Hide the IME while in the given activity.
* 在给定活动里隐藏输入法。
*
* Calls InputMethodManager.hideSoftInput() for the given activity.
* 为给定活动调用 android.view.inputmethod.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 结束调用将发生的地方，它将发送一个消息到进程的主线程。
*/
void
ANativeActivity_hideSoftInput( ANativeActivity* activity,
                               uint32_t         flags );

#ifdef __cplusplus
};
#endif

#endif // ANDROID_NATIVE_ACTIVITY_H