1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18 #ifndef ANDROID_NATIVE_ACTIVITY_H 19 #define ANDROID_NATIVE_ACTIVITY_H 20 21 #include <stdint.h> 22 #include <sys/types.h> 23 24 #include <jni.h> 25 26 #include <android/asset_manager.h> 27 #include <android/input.h> 28 #include <android/native_window.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 struct ANativeActivityCallbacks; 35 36 /** 37 * This structure defines the native side of an android.app.NativeActivity. 38 * It is created by the framework, and handed to the application's native 39 * code as it is being launched. 40 */ 41 typedef struct ANativeActivity { 42 /** 43 * Pointer to the callback function table of the native application. 44 * You can set the functions here to your own callbacks. The callbacks 45 * pointer itself here should not be changed; it is allocated and managed 46 * for you by the framework. 47 */ 48 struct ANativeActivityCallbacks* callbacks; 49 50 /** 51 * The global handle on the process's Java VM. 52 */ 53 JavaVM* vm; 54 55 /** 56 * JNI context for the main thread of the app. Note that this field 57 * can ONLY be used from the main thread of the process; that is, the 58 * thread that calls into the ANativeActivityCallbacks. 59 */ 60 JNIEnv* env; 61 62 /** 63 * The NativeActivity object handle. 64 * 65 * IMPORTANT NOTE: This member is mis-named. It should really be named 66 * 'activity' instead of 'clazz', since it's a reference to the 67 * NativeActivity instance created by the system for you. 68 * 69 * We unfortunately cannot change this without breaking NDK 70 * source-compatibility. 71 */ 72 jobject clazz; 73 74 /** 75 * Path to this application's internal data directory. 76 */ 77 const char* internalDataPath; 78 79 /** 80 * Path to this application's external (removable/mountable) data directory. 81 */ 82 const char* externalDataPath; 83 84 /** 85 * The platform's SDK version code. 86 */ 87 int32_t sdkVersion; 88 89 /** 90 * This is the native instance of the application. It is not used by 91 * the framework, but can be set by the application to its own instance 92 * state. 93 */ 94 void* instance; 95 96 /** 97 * Pointer to the Asset Manager instance for the application. The application 98 * uses this to access binary assets bundled inside its own .apk file. 99 */ 100 AAssetManager* assetManager; 101 } ANativeActivity; 102 103 /** 104 * These are the callbacks the framework makes into a native application. 105 * All of these callbacks happen on the main thread of the application. 106 * By default, all callbacks are NULL; set to a pointer to your own function 107 * to have it called. 108 */ 109 typedef struct ANativeActivityCallbacks { 110 /** 111 * NativeActivity has started. See Java documentation for Activity.onStart() 112 * for more information. 113 */ 114 void (*onStart)(ANativeActivity* activity); 115 116 /** 117 * NativeActivity has resumed. See Java documentation for Activity.onResume() 118 * for more information. 119 */ 120 void (*onResume)(ANativeActivity* activity); 121 122 /** 123 * Framework is asking NativeActivity to save its current instance state. 124 * See Java documentation for Activity.onSaveInstanceState() for more 125 * information. The returned pointer needs to be created with malloc(); 126 * the framework will call free() on it for you. You also must fill in 127 * outSize with the number of bytes in the allocation. Note that the 128 * saved state will be persisted, so it can not contain any active 129 * entities (pointers to memory, file descriptors, etc). 130 */ 131 void* (*onSaveInstanceState)(ANativeActivity* activity, size_t* outSize); 132 133 /** 134 * NativeActivity has paused. See Java documentation for Activity.onPause() 135 * for more information. 136 */ 137 void (*onPause)(ANativeActivity* activity); 138 139 /** 140 * NativeActivity has stopped. See Java documentation for Activity.onStop() 141 * for more information. 142 */ 143 void (*onStop)(ANativeActivity* activity); 144 145 /** 146 * NativeActivity is being destroyed. See Java documentation for Activity.onDestroy() 147 * for more information. 148 */ 149 void (*onDestroy)(ANativeActivity* activity); 150 151 /** 152 * Focus has changed in this NativeActivity's window. This is often used, 153 * for example, to pause a game when it loses input focus. 154 */ 155 void (*onWindowFocusChanged)(ANativeActivity* activity, int hasFocus); 156 157 /** 158 * The drawing window for this native activity has been created. You 159 * can use the given native window object to start drawing. 160 */ 161 void (*onNativeWindowCreated)(ANativeActivity* activity, ANativeWindow* window); 162 163 /** 164 * The drawing window for this native activity has been resized. You should 165 * retrieve the new size from the window and ensure that your rendering in 166 * it now matches. 167 */ 168 void (*onNativeWindowResized)(ANativeActivity* activity, ANativeWindow* window); 169 170 /** 171 * The drawing window for this native activity needs to be redrawn. To avoid 172 * transient artifacts during screen changes (such resizing after rotation), 173 * applications should not return from this function until they have finished 174 * drawing their window in its current state. 175 */ 176 void (*onNativeWindowRedrawNeeded)(ANativeActivity* activity, ANativeWindow* window); 177 178 /** 179 * The drawing window for this native activity is going to be destroyed. 180 * You MUST ensure that you do not touch the window object after returning 181 * from this function: in the common case of drawing to the window from 182 * another thread, that means the implementation of this callback must 183 * properly synchronize with the other thread to stop its drawing before 184 * returning from here. 185 */ 186 void (*onNativeWindowDestroyed)(ANativeActivity* activity, ANativeWindow* window); 187 188 /** 189 * The input queue for this native activity's window has been created. 190 * You can use the given input queue to start retrieving input events. 191 */ 192 void (*onInputQueueCreated)(ANativeActivity* activity, AInputQueue* queue); 193 194 /** 195 * The input queue for this native activity's window is being destroyed. 196 * You should no longer try to reference this object upon returning from this 197 * function. 198 */ 199 void (*onInputQueueDestroyed)(ANativeActivity* activity, AInputQueue* queue); 200 201 /** 202 * The rectangle in the window in which content should be placed has changed. 203 */ 204 void (*onContentRectChanged)(ANativeActivity* activity, const ARect* rect); 205 206 /** 207 * The current device AConfiguration has changed. The new configuration can 208 * be retrieved from assetManager. 209 */ 210 void (*onConfigurationChanged)(ANativeActivity* activity); 211 212 /** 213 * The system is running low on memory. Use this callback to release 214 * resources you do not need, to help the system avoid killing more 215 * important processes. 216 */ 217 void (*onLowMemory)(ANativeActivity* activity); 218 } ANativeActivityCallbacks; 219 220 /** 221 * This is the function that must be in the native code to instantiate the 222 * application's native activity. It is called with the activity instance (see 223 * above); if the code is being instantiated from a previously saved instance, 224 * the savedState will be non-NULL and point to the saved data. You must make 225 * any copy of this data you need -- it will be released after you return from 226 * this function. 227 */ 228 typedef void ANativeActivity_createFunc(ANativeActivity* activity, 229 void* savedState, size_t savedStateSize); 230 231 /** 232 * The name of the function that NativeInstance looks for when launching its 233 * native code. This is the default function that is used, you can specify 234 * "android.app.func_name" string meta-data in your manifest to use a different 235 * function. 236 */ 237 extern ANativeActivity_createFunc ANativeActivity_onCreate; 238 239 /** 240 * Finish the given activity. Its finish() method will be called, causing it 241 * to be stopped and destroyed. Note that this method can be called from 242 * *any* thread; it will send a message to the main thread of the process 243 * where the Java finish call will take place. 244 */ 245 void ANativeActivity_finish(ANativeActivity* activity); 246 247 /** 248 * Change the window format of the given activity. Calls getWindow().setFormat() 249 * of the given activity. Note that this method can be called from 250 * *any* thread; it will send a message to the main thread of the process 251 * where the Java finish call will take place. 252 */ 253 void ANativeActivity_setWindowFormat(ANativeActivity* activity, int32_t format); 254 255 /** 256 * Change the window flags of the given activity. Calls getWindow().setFlags() 257 * of the given activity. Note that this method can be called from 258 * *any* thread; it will send a message to the main thread of the process 259 * where the Java finish call will take place. See window.h for flag constants. 260 */ 261 void ANativeActivity_setWindowFlags(ANativeActivity* activity, 262 uint32_t addFlags, uint32_t removeFlags); 263 264 /** 265 * Flags for ANativeActivity_showSoftInput; see the Java InputMethodManager 266 * API for documentation. 267 */ 268 enum { 269 ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001, 270 ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002, 271 }; 272 273 /** 274 * Show the IME while in the given activity. Calls InputMethodManager.showSoftInput() 275 * for the given activity. Note that this method can be called from 276 * *any* thread; it will send a message to the main thread of the process 277 * where the Java finish call will take place. 278 */ 279 void ANativeActivity_showSoftInput(ANativeActivity* activity, uint32_t flags); 280 281 /** 282 * Flags for ANativeActivity_hideSoftInput; see the Java InputMethodManager 283 * API for documentation. 284 */ 285 enum { 286 ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001, 287 ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002, 288 }; 289 290 /** 291 * Hide the IME while in the given activity. Calls InputMethodManager.hideSoftInput() 292 * for the given activity. Note that this method can be called from 293 * *any* thread; it will send a message to the main thread of the process 294 * where the Java finish call will take place. 295 */ 296 void ANativeActivity_hideSoftInput(ANativeActivity* activity, uint32_t flags); 297 298 #ifdef __cplusplus 299 }; 300 #endif 301 302 #endif // ANDROID_NATIVE_ACTIVITY_H 303 304
