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 102 /** 103 * Available starting with Honeycomb: path to the directory containing 104 * the application's OBB files (if any). If the app doesn't have any 105 * OBB files, this directory may not exist. 106 */ 107 const char* obbPath; 108 } ANativeActivity; 109 110 /** 111 * These are the callbacks the framework makes into a native application. 112 * All of these callbacks happen on the main thread of the application. 113 * By default, all callbacks are NULL; set to a pointer to your own function 114 * to have it called. 115 */ 116 typedef struct ANativeActivityCallbacks { 117 /** 118 * NativeActivity has started. See Java documentation for Activity.onStart() 119 * for more information. 120 */ 121 void (*onStart)(ANativeActivity* activity); 122 123 /** 124 * NativeActivity has resumed. See Java documentation for Activity.onResume() 125 * for more information. 126 */ 127 void (*onResume)(ANativeActivity* activity); 128 129 /** 130 * Framework is asking NativeActivity to save its current instance state. 131 * See Java documentation for Activity.onSaveInstanceState() for more 132 * information. The returned pointer needs to be created with malloc(); 133 * the framework will call free() on it for you. You also must fill in 134 * outSize with the number of bytes in the allocation. Note that the 135 * saved state will be persisted, so it can not contain any active 136 * entities (pointers to memory, file descriptors, etc). 137 */ 138 void* (*onSaveInstanceState)(ANativeActivity* activity, size_t* outSize); 139 140 /** 141 * NativeActivity has paused. See Java documentation for Activity.onPause() 142 * for more information. 143 */ 144 void (*onPause)(ANativeActivity* activity); 145 146 /** 147 * NativeActivity has stopped. See Java documentation for Activity.onStop() 148 * for more information. 149 */ 150 void (*onStop)(ANativeActivity* activity); 151 152 /** 153 * NativeActivity is being destroyed. See Java documentation for Activity.onDestroy() 154 * for more information. 155 */ 156 void (*onDestroy)(ANativeActivity* activity); 157 158 /** 159 * Focus has changed in this NativeActivity's window. This is often used, 160 * for example, to pause a game when it loses input focus. 161 */ 162 void (*onWindowFocusChanged)(ANativeActivity* activity, int hasFocus); 163 164 /** 165 * The drawing window for this native activity has been created. You 166 * can use the given native window object to start drawing. 167 */ 168 void (*onNativeWindowCreated)(ANativeActivity* activity, ANativeWindow* window); 169 170 /** 171 * The drawing window for this native activity has been resized. You should 172 * retrieve the new size from the window and ensure that your rendering in 173 * it now matches. 174 */ 175 void (*onNativeWindowResized)(ANativeActivity* activity, ANativeWindow* window); 176 177 /** 178 * The drawing window for this native activity needs to be redrawn. To avoid 179 * transient artifacts during screen changes (such resizing after rotation), 180 * applications should not return from this function until they have finished 181 * drawing their window in its current state. 182 */ 183 void (*onNativeWindowRedrawNeeded)(ANativeActivity* activity, ANativeWindow* window); 184 185 /** 186 * The drawing window for this native activity is going to be destroyed. 187 * You MUST ensure that you do not touch the window object after returning 188 * from this function: in the common case of drawing to the window from 189 * another thread, that means the implementation of this callback must 190 * properly synchronize with the other thread to stop its drawing before 191 * returning from here. 192 */ 193 void (*onNativeWindowDestroyed)(ANativeActivity* activity, ANativeWindow* window); 194 195 /** 196 * The input queue for this native activity's window has been created. 197 * You can use the given input queue to start retrieving input events. 198 */ 199 void (*onInputQueueCreated)(ANativeActivity* activity, AInputQueue* queue); 200 201 /** 202 * The input queue for this native activity's window is being destroyed. 203 * You should no longer try to reference this object upon returning from this 204 * function. 205 */ 206 void (*onInputQueueDestroyed)(ANativeActivity* activity, AInputQueue* queue); 207 208 /** 209 * The rectangle in the window in which content should be placed has changed. 210 */ 211 void (*onContentRectChanged)(ANativeActivity* activity, const ARect* rect); 212 213 /** 214 * The current device AConfiguration has changed. The new configuration can 215 * be retrieved from assetManager. 216 */ 217 void (*onConfigurationChanged)(ANativeActivity* activity); 218 219 /** 220 * The system is running low on memory. Use this callback to release 221 * resources you do not need, to help the system avoid killing more 222 * important processes. 223 */ 224 void (*onLowMemory)(ANativeActivity* activity); 225 } ANativeActivityCallbacks; 226 227 /** 228 * This is the function that must be in the native code to instantiate the 229 * application's native activity. It is called with the activity instance (see 230 * above); if the code is being instantiated from a previously saved instance, 231 * the savedState will be non-NULL and point to the saved data. You must make 232 * any copy of this data you need -- it will be released after you return from 233 * this function. 234 */ 235 typedef void ANativeActivity_createFunc(ANativeActivity* activity, 236 void* savedState, size_t savedStateSize); 237 238 /** 239 * The name of the function that NativeInstance looks for when launching its 240 * native code. This is the default function that is used, you can specify 241 * "android.app.func_name" string meta-data in your manifest to use a different 242 * function. 243 */ 244 extern ANativeActivity_createFunc ANativeActivity_onCreate; 245 246 /** 247 * Finish the given activity. Its finish() method will be called, causing it 248 * to be stopped and destroyed. Note that this method can be called from 249 * *any* thread; it will send a message to the main thread of the process 250 * where the Java finish call will take place. 251 */ 252 void ANativeActivity_finish(ANativeActivity* activity); 253 254 /** 255 * Change the window format of the given activity. Calls getWindow().setFormat() 256 * of the given activity. Note that this method can be called from 257 * *any* thread; it will send a message to the main thread of the process 258 * where the Java finish call will take place. 259 */ 260 void ANativeActivity_setWindowFormat(ANativeActivity* activity, int32_t format); 261 262 /** 263 * Change the window flags of the given activity. Calls getWindow().setFlags() 264 * of the given activity. Note that this method can be called from 265 * *any* thread; it will send a message to the main thread of the process 266 * where the Java finish call will take place. See window.h for flag constants. 267 */ 268 void ANativeActivity_setWindowFlags(ANativeActivity* activity, 269 uint32_t addFlags, uint32_t removeFlags); 270 271 /** 272 * Flags for ANativeActivity_showSoftInput; see the Java InputMethodManager 273 * API for documentation. 274 */ 275 enum { 276 ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001, 277 ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002, 278 }; 279 280 /** 281 * Show the IME while in the given activity. Calls InputMethodManager.showSoftInput() 282 * for the given activity. Note that this method can be called from 283 * *any* thread; it will send a message to the main thread of the process 284 * where the Java finish call will take place. 285 */ 286 void ANativeActivity_showSoftInput(ANativeActivity* activity, uint32_t flags); 287 288 /** 289 * Flags for ANativeActivity_hideSoftInput; see the Java InputMethodManager 290 * API for documentation. 291 */ 292 enum { 293 ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001, 294 ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002, 295 }; 296 297 /** 298 * Hide the IME while in the given activity. Calls InputMethodManager.hideSoftInput() 299 * for the given activity. Note that this method can be called from 300 * *any* thread; it will send a message to the main thread of the process 301 * where the Java finish call will take place. 302 */ 303 void ANativeActivity_hideSoftInput(ANativeActivity* activity, uint32_t flags); 304 305 #ifdef __cplusplus 306 }; 307 #endif 308 309 #endif // ANDROID_NATIVE_ACTIVITY_H 310 311