android ndk native_activity.h
#ifndefANDROID_NATIVE_ACTIVITY_H
#defineANDROID_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
structANativeActivityCallbacks;
/**
*Thisstructuredefinesthenativesideofanandroid.app.NativeActivity.
*该结构体定义了本地端的android.app.NativeActivity。
*
*Itiscreatedbytheframework,
*andhandedtotheapplication'snativecodeasitisbeinglaunched.
*它是由框架创建且在应用程序的本地代码正在启动时交给它。
*/
typedefstructANativeActivity{
/**
*Pointertothecallbackfunctiontableofthenativeapplication.
*指向本地应用程序的回调函数表的指针。
*
*Youcansetthefunctionsheretoyourowncallbacks.
*你可以在这里设置你自己的回调函数。
*
*Thecallbackspointeritselfhereshouldnotbechanged;
*回调指针自身在这里将不会改变；
*
*itisallocatedandmanagedforyoubytheframework.
*它是由框架为你分配和管理。
*/
structANativeActivityCallbacks*callbacks;
/**
*Theglobalhandleontheprocess'sJavaVM.
*进程的Java虚拟机全局句柄。
*/
JavaVM*vm;
/**
*JNIcontextforthemainthreadoftheapp.
*应用程序主线程用JNI环境。
*
*NotethatthisfieldcanONLYbeusedfromthemainthreadoftheprocess;
*注意这个成员变量仅可以被进程的主线程使用；
*
*thatis,thethreadthatcallsintotheANativeActivityCallbacks.
*即，进程的主线程调用进入到ANativeActivityCallbacks里指向的某个回调函数中。
*/
JNIEnv*env;
/**
*TheNativeActivityJavaclass.
*android.app.NativeActivityJava类。
*/
jobjectclazz;
/**
*Pathtothisapplication'sinternaldatadirectory.
*本应用程序的内部数据目录路径。
*/
constchar*internalDataPath;
/**
*Pathtothisapplication'sexternal(removable/mountable)datadirectory.
*本应用程序的外部(可移除的或可安装的)数据目录路径。
*/
constchar*externalDataPath;
/**
*Theplatform'sSDKversioncode.
*平台的SDK版本代码。
*/
int32_tsdkVersion;
/**
*Thisisthenativeinstanceoftheapplication.
*这是应用程序的本地实例。
*
*Itisnotusedbytheframework,
*butcanbesetbytheapplicationtoitsowninstancestate.
*它是不能被框架使用，但是可被应用程序来设置它自己的实例状态。
*注：参见native_app_glue/android_native_app_glue.c文件中的
* onDestroy函数体的使用来看，该成员变量是用来指向开发人员自定义的数据结构体。
*/
void*instance;
/**
*PointertotheAssetManagerinstancefortheapplication.
*指向应用程序资产管理器实例的指针。
*
*Theapplicationusesthistoaccessbinaryassetsbundledinsideitsown.apkfile.
*应用程序使用它来访问包在它自己.apk文件里面的二进制资产。
*/
AAssetManager*assetManager;
}ANativeActivity;
/**
*Thesearethecallbackstheframeworkmakesintoanativeapplication.
*这些回调使得框架进入一个本地应用程序。
*
*Allofthesecallbackshappenonthemainthreadoftheapplication.
*这些回调全部发生在应用程序的主线程上。
*
*Bydefault,allcallbacksareNULL;
*默认情况下，全部回调函数指针都是NULL值 ;
*settoapointertoyourownfunctiontohaveitcalled.
*设置回调函数指针值为你自己的允许被调用的函数地址。
*/
typedefstructANativeActivityCallbacks{
/**
*NativeActivityhasstarted.
*NativeActivity已经启动。
*
*SeeJavadocumentationforActivity.onStart()formoreinformation.
*参见Java文档中的Activity.onStart方法的更多信息。
*注：该方法说明了将要显示给用户的活动。
*/
void(*onStart)(ANativeActivity*activity);
/**
*NativeActivityhasresumed.
*NativeActivity已经(中断后)继续。
*
*SeeJavadocumentationforActivity.onResume()formoreinformation.
*参见Java文档中的Activity.onResume方法的更多信息。
*注：用户可以开始与活动进行交互时会调用该方法。这个方法非常适合开始播放动画和音乐。
*/
void(*onResume)(ANativeActivity*activity);
/**
*FrameworkisaskingNativeActivitytosaveitscurrentinstancestate.
*框架请求NativeActivity去保存它的当前实例状态。
*
*SeeJavadocumentationforActivity.onSaveInstanceState()formoreinformation.
*参见Java文档中的Activity.onSaveInstanceState方法的更多信息。
*注：Android调用该方法的作用是让活动可以保存每个实例的状态，如光标在文本字段中的位置。
*
*Thereturnedpointerneedstobecreatedwithmalloc();
*返回的指针是用malloc函数创建的；
*
*theframeworkwillcallfree()onitforyou.
*框架将为你调用free函数释放它。
*
*YoualsomustfillinoutSizewiththenumberofbytesintheallocation.
*你同样必须用outSize传出参数来得到分配的字节数量。
*
*Notethatthesavedstatewillbepersisted,
*soitcannotcontainanyactiveentities(pointerstomemory,filedescriptors,etc).
*注意已保存的状态将是持久的，所以它不能包含任何活动的实体(指向内存的指针值、文件描述符，等等)。
*/
void*(*onSaveInstanceState)(ANativeActivity*activity,
size_t*outSize);
/**
*NativeActivityhaspaused.
*NativeActivity已经暂停。
*
*SeeJavadocumentationforActivity.onPause()formoreinformation.
*参见Java文档中的Activity.onPause方法的更多信息。
*注：活动将要进入后台时会运行该方法，活动进入后台的原因通常是在前台启动了另一个活动。
* 还应该在该方法中保存程序的持久性状态，如正在编辑的数据库记录。
*/
void(*onPause)(ANativeActivity*activity);
/**
*NativeActivityhasstopped.
*NativeActivity已经停止。
*
*SeeJavadocumentationforActivity.onStop()formoreinformation.
*参见Java文档中的Activity.onStop方法的更多信息。
*注：用户无需看到某个活动，或者在一段时间内不需要某个活动时，可以调用该方法。
* 如果内存不足，可能永远都不会调用该方法，系统可能只是终止进程。
*/
void(*onStop)(ANativeActivity*activity);
/**
*NativeActivityisbeingdestroyed.
*NativeActivity正在被销毁。
*
*SeeJavadocumentationforActivity.onDestroy()formoreinformation.
*参见Java文档中的Activity.onDestroy方法的更多信息。
*注：销毁活动前会调用该方法。
* 如果内存不足，可能永远都不会调用该方法，系统可能只是终止进程。
*/
void(*onDestroy)(ANativeActivity*activity);
/**
*FocushaschangedinthisNativeActivity'swindow.
*在这个NativeActivity的窗口里焦点已经改变。
*Thisisoftenused,forexample,topauseagamewhenitlosesinputfocus.
*这是常常被使用的，例如，当一个游戏失去输入焦点时暂停。
*/
void(*onWindowFocusChanged)(ANativeActivity*activity,
inthasFocus);
/**
*Thedrawingwindowforthisnativeactivityhasbeencreated.
*这个本地活动的绘图窗口已经创建完成。
*
*Youcanusethegivennativewindowobjecttostartdrawing.
*你可以使用给定的本地窗口对象开始绘图。
*/
void(*onNativeWindowCreated)(ANativeActivity*activity,
ANativeWindow*window);
/**
*Thedrawingwindowforthisnativeactivityhasbeenresized.
*这个本地活动的绘图窗口调整大小已完成。
*
*Youshouldretrievethenewsizefromthewindowandensure
*thatyourrenderinginitnowmatches.
*你将重新得到窗口的新大小并且确保现在你的绘制与它相一致。
*/
void(*onNativeWindowResized)(ANativeActivity*activity,
ANativeWindow*window);
/**
*Thedrawingwindowforthisnativeactivityneedstoberedrawn.
*这个本地活动的绘图窗口需要重绘。
*
*Toavoidtransientartifactsduringscreenchanges(suchresizingafterrotation),
*applicationsshouldnotreturnfromthisfunction
*untiltheyhavefinisheddrawingtheirwindowinitscurrentstate.
*为预防短暂的伪像在屏幕改变期间(在屏幕旋转（横变纵或纵变横）之后调整大小)，
*应用程序将不能从这个函数返回直到它们用它们的当前状态绘画完成它们的窗口。
*/
void(*onNativeWindowRedrawNeeded)(ANativeActivity*activity,
ANativeWindow*window);
/**
*Thedrawingwindowforthisnativeactivityisgoingtobedestroyed.
*这个本地活动的绘图窗口将被销毁。
*
*YouMUSTensure
*thatyoudonottouchthewindowobjectafterreturningfromthisfunction:
*你必须确保在从这个函数返回后你触摸不了窗口对象了：
*
*inthecommoncaseofdrawingtothewindowfromanotherthread,
*thatmeanstheimplementationofthiscallbackmustproperlysynchronize
*withtheotherthreadtostopitsdrawingbeforereturningfromhere.
*在由其它线程绘画窗口的通常情况中，
*那意味着从这里返回之前该回调的实现必须正确地与其它线程停止它的绘画同步。
*/
void(*onNativeWindowDestroyed)(ANativeActivity*activity,
ANativeWindow*window);
/**
*Theinputqueueforthisnativeactivity'swindowhasbeencreated.
*这个本地活动窗口的输入队列已经创建完成。
*
*Youcanusethegiveninputqueuetostartretrievinginputevents.
*你可以使用给定的输入队列开始检索输入事件。
*/
void(*onInputQueueCreated)(ANativeActivity*activity,
AInputQueue*queue);
/**
*Theinputqueueforthisnativeactivity'swindowisbeingdestroyed.
*这个本地活动窗口的输入队列是正在被销毁。
*
*Youshouldnolongertrytoreferencethisobjectuponreturningfromthisfunction.
*从该函数返回后你将不能再试图引用这个对象了。
*/
void(*onInputQueueDestroyed)(ANativeActivity*activity,
AInputQueue*queue);
/**
*Therectangleinthewindowinwhichcontentshouldbeplacedhaschanged.
*在窗口中将放置发生改变内容的矩形。
*/
void(*onContentRectChanged)(ANativeActivity*activity,
constARect*rect);
/**
*ThecurrentdeviceAConfigurationhaschanged.
*当前设备的AConfiguration结构信息已发生改变。
*注：AConfiguration结构在configuration.h中声明。
*
*ThenewconfigurationcanberetrievedfromassetManager.
*新的配置可以从activity->assetManager中重新得到。
*注：用configuration.h中声明的AConfiguration_fromAssetManager函数来重新得到。
*/
void(*onConfigurationChanged)(ANativeActivity*activity);
/**
*Thesystemisrunninglowonmemory.
*该系统运行内存不足。
*
*Usethiscallbacktoreleaseresourcesyoudonotneed,
*tohelpthesystemavoidkillingmoreimportantprocesses.
*使用这个回调去释放你不需要的资源，以帮助系统避免杀死更多重要的进程。
*/
void(*onLowMemory)(ANativeActivity*activity);
}ANativeActivityCallbacks;
/**
*Thisisthefunctionthat
*mustbeinthenativecodetoinstantiatetheapplication'snativeactivity.
*这是必须用本地代码来实例化应用程序的本地活动的函数。
*
*Itiscalledwiththeactivityinstance(seeabove);
*它是被活动实例调用的(参见上文)；
*
*ifthecodeisbeinginstantiatedfromapreviouslysavedinstance,
*thesavedStatewillbenon-NULLandpointtothesaveddata.
*如果代码正在实例化之前保存的实例，那么savedState参数值将是非NULL值并且指向已保存的数据。
*
*Youmustmakeanycopyofthisdatayouneed--
*itwillbereleasedafteryoureturnfromthisfunction.
*你必须备份savedState参数指向数据中你需要的数据--它将在这个函数返回后被框架释放。
*注：savedState和savedStateSize参数取值来源，
* 可参见上面ANativeActivityCallbacks结构体中的onSaveInstanceState回调函数指针。
*/
typedefvoid
ANativeActivity_createFunc(ANativeActivity*activity,
void*savedState,
size_tsavedStateSize);
/**
*ThenameofthefunctionthatNativeInstancelooksforwhenlaunchingitsnativecode.
*在本地实例启动它的本地代码时寻找这个函数名。
*
*Thisisthedefaultfunctionthatisused,
*youcanspecify"android.app.func_name"stringmeta-datain
*yourmanifesttouseadifferentfunction.
*这是被用作默认函数，你可以在你的AndroidManifest.xml里的activity标签下用
*<meta-dataandroid:name="android.app.func_name"android:value="替换的函数名"/>
*来明确说明使用一个不同的函数名。
*注：别忘了在你的代码中定义实现一个如下函数：
*voidANativeActivity_onCreate(ANativeActivity*activity,
*void*savedState,
*size_tsavedStateSize)
*{
*...//具体实现语句
*}
*/
externANativeActivity_createFuncANativeActivity_onCreate;
/**
*Finishthegivenactivity.
*结束给定的活动。
*
*Itsfinish()methodwillbecalled,
*causingittobestoppedanddestroyed.
*android.app.Activity类的finish方法将是被调用，导致活动停止且销毁。
*
*Notethatthismethodcanbecalledfrom*any*thread;
*注意该方法可以是被任何线程调用；
*
*itwillsendamessagetothemainthreadoftheprocess
*wheretheJavafinishcallwilltakeplace.
*在Java结束调用将发生的地方，它将发送一个消息到进程的主线程。
*/
void
ANativeActivity_finish(ANativeActivity*activity);
/**
*Changethewindowformatofthegivenactivity.
*改变给定活动的窗口格式(即一个窗口可以使用的像素格式)。
*注：参见native_window.h中的以WINDOW_FORMAT_开头的宏值定义。
*
*CallsgetWindow().setFormat()ofthegivenactivity.
*调用给定活动的getWindow().setFormat()。
*注：先调用android.app.Activity类对象的getWindow方法得到android.view.Window类对象，
* 再调用android.view.Window类对象的setFormat方法设置窗口的格式。
*
*Notethatthismethodcanbecalledfrom*any*thread;
*注意该方法可以是被任何线程调用；
*
*itwillsendamessagetothemainthreadoftheprocess
*wheretheJavafinishcallwilltakeplace.
*在Java结束调用将发生的地方，它将发送一个消息到进程的主线程。
*/
void
ANativeActivity_setWindowFormat(ANativeActivity*activity,
int32_tformat);
/**
*Changethewindowflagsofthegivenactivity.
*改变给定活动的窗口标志。
*
*CallsgetWindow().setFlags()ofthegivenactivity.
*调用给定活动的getWindow().setFlags()。
*
*Notethatthismethodcanbecalledfrom*any*thread;
*注意该方法可以是被任何线程调用；
*
*itwillsendamessagetothemainthreadoftheprocess
*wheretheJavafinishcallwilltakeplace.
*在Java结束调用将发生的地方，它将发送一个消息到进程的主线程。
*
*Seewindow.hforflagconstants.
*参见window.h中的标志常量。
*/
void
ANativeActivity_setWindowFlags(ANativeActivity*activity,
uint32_taddFlags,
uint32_tremoveFlags);
/**
*FlagsforANativeActivity_showSoftInput;
*ANativeActivity_showSoftInput函数的flags参数用的标志；
*
*seetheJavaInputMethodManagerAPIfordocumentation.
*参见Java中关于android.view.inputmethod.InputMethodManagerAPI的文档。
*/
enum{
/*FlagforshowSoftInput(View,int)toindicate
*thatthisisanimplicitrequesttoshowtheinputwindow,
*notastheresultofadirectrequestbytheuser.
*该标志为ANativeActivity_showSoftInput函数的flags参数的取值之一，
*指出这是一个显示输入法窗口不明确的请求，不作为用户直接请求的结果。
*
*Thewindowmaynotbeshowninthiscase.
*在这种情况中输入法窗口可以不显示。
*/
ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT=0x0001,
/*FlagforshowSoftInput(View,int)toindicate
*thattheuserhasforcedtheinputmethodopen
*(suchasbylong-pressingmenu)
*soitshouldnotbecloseduntiltheyexplicitlydoso.
*该标志为ANativeActivity_showSoftInput函数的flags参数的取值之一，
*指出用户强制打开输入法(例如通过长按菜单键)，因此它将一直保持打开直到用户明确关闭。
*/
ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED=0x0002,
};
/**
*ShowtheIMEwhileinthegivenactivity.
*在给定活动里显示输入法。
*
*CallsInputMethodManager.showSoftInput()forthegivenactivity.
*为给定活动调用android.view.inputmethod.InputMethodManager类对象的showSoftInput方法。
*
*Notethatthismethodcanbecalledfrom*any*thread;
*注意该方法可以是被任何线程调用；
*
*itwillsendamessagetothemainthreadoftheprocess
*wheretheJavafinishcallwilltakeplace.
*在Java结束调用将发生的地方，它将发送一个消息到进程的主线程。
*/
void
ANativeActivity_showSoftInput(ANativeActivity*activity,
uint32_tflags);
/**
*FlagsforANativeActivity_hideSoftInput;
*ANativeActivity_hideSoftInput函数的flags参数用的标志；
*
*seetheJavaInputMethodManagerAPIfordocumentation.
*参见Java中关于android.view.inputmethod.InputMethodManagerAPI的文档。
*/
enum{
/*FlagforhideSoftInputFromWindow(IBinder,int)toindicate
*thatthesoftinputwindowshouldonlybehidden
*ifitwasnotexplicitlyshownbytheuser.
*该标志为ANativeActivity_hideSoftInput函数的flags参数的取值之一，
*指出如果用户没有明确地要显示输入法窗口的话，则隐藏它。
*/
ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY=0x0001,
/*FlagforhideSoftInputFromWindow(IBinder,int)toindicate
*thatthesoftinputwindowshouldnormallybehidden,
*unlessitwasoriginallyshownwithSHOW_FORCED.
*该标志为ANativeActivity_hideSoftInput函数的flags参数的取值之一，
*指出输入法窗口通常是隐藏的，
*除非它起初是用ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED标志显示的。
*/
ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS=0x0002,
};
/**
*HidetheIMEwhileinthegivenactivity.
*在给定活动里隐藏输入法。
*
*CallsInputMethodManager.hideSoftInput()forthegivenactivity.
*为给定活动调用android.view.inputmethod.InputMethodManager类对象的hideSoftInput方法。
*
*Notethatthismethodcanbecalledfrom*any*thread;
*注意该方法可以是被任何线程调用；
*
*itwillsendamessagetothemainthreadoftheprocess
*wheretheJavafinishcallwilltakeplace.
*在Java结束调用将发生的地方，它将发送一个消息到进程的主线程。
*/
void
ANativeActivity_hideSoftInput(ANativeActivity*activity,
uint32_tflags);
#ifdef__cplusplus
};
#endif
#endif//ANDROID_NATIVE_ACTIVITY_H