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