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 #ifndef _ANDROID_NATIVE_APP_GLUE_H 18 #define _ANDROID_NATIVE_APP_GLUE_H 19 20 #include <poll.h> 21 #include <pthread.h> 22 #include <sched.h> 23 24 #include <android/configuration.h> 25 #include <android/looper.h> 26 #include <android/native_activity.h> 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * The native activity interface provided by <android/native_activity.h> 34 * is based on a set of application-provided callbacks that will be called 35 * by the Activity's main thread when certain events occur. 36 * 37 * This means that each one of this callbacks _should_ _not_ block, or they 38 * risk having the system force-close the application. This programming 39 * model is direct, lightweight, but constraining. 40 * 41 * The 'android_native_app_glue' static library is used to provide a different 42 * execution model where the application can implement its own main event 43 * loop in a different thread instead. Here's how it works: 44 * 45 * 1/ The application must provide a function named "android_main()" that 46 * will be called when the activity is created, in a new thread that is 47 * distinct from the activity's main thread. 48 * 49 * 2/ android_main() receives a pointer to a valid "android_app" structure 50 * that contains references to other important objects, e.g. the 51 * ANativeActivity object instance the application is running in. 52 * 53 * 3/ the "android_app" object holds an ALooper instance that already 54 * listens to two important things: 55 * 56 * - activity lifecycle events (e.g. "pause", "resume"). See APP_CMD_XXX 57 * declarations below. 58 * 59 * - input events coming from the AInputQueue attached to the activity. 60 * 61 * Each of these correspond to an ALooper identifier returned by 62 * ALooper_pollOnce with values of LOOPER_ID_MAIN and LOOPER_ID_INPUT, 63 * respectively. 64 * 65 * Your application can use the same ALooper to listen to additional 66 * file-descriptors. They can either be callback based, or with return 67 * identifiers starting with LOOPER_ID_USER. 68 * 69 * 4/ Whenever you receive a LOOPER_ID_MAIN or LOOPER_ID_INPUT event, 70 * the returned data will point to an android_poll_source structure. You 71 * can call the process() function on it, and fill in android_app->onAppCmd 72 * and android_app->onInputEvent to be called for your own processing 73 * of the event. 74 * 75 * Alternatively, you can call the low-level functions to read and process 76 * the data directly... look at the process_cmd() and process_input() 77 * implementations in the glue to see how to do this. 78 * 79 * See the sample named "native-activity" that comes with the NDK with a 80 * full usage example. Also look at the JavaDoc of NativeActivity. 81 */ 82 83 struct android_app; 84 85 /** 86 * Data associated with an ALooper fd that will be returned as the "outData" 87 * when that source has data ready. 88 */ 89 struct android_poll_source 90 { 91 // The identifier of this source. May be LOOPER_ID_MAIN or 92 // LOOPER_ID_INPUT. 93 int32_t id; 94 95 // The android_app this ident is associated with. 96 struct android_app *app; 97 98 // Function to call to perform the standard processing of data from 99 // this source. 100 void (*process)(struct android_app *app, struct android_poll_source *source); 101 }; 102 103 /** 104 * This is the interface for the standard glue code of a threaded 105 * application. In this model, the application's code is running 106 * in its own thread separate from the main thread of the process. 107 * It is not required that this thread be associated with the Java 108 * VM, although it will need to be in order to make JNI calls any 109 * Java objects. 110 */ 111 struct android_app 112 { 113 // The application can place a pointer to its own state object 114 // here if it likes. 115 void *userData; 116 117 // Fill this in with the function to process main app commands (APP_CMD_*) 118 void (*onAppCmd)(struct android_app *app, int32_t cmd); 119 120 // Fill this in with the function to process input events. At this point 121 // the event has already been pre-dispatched, and it will be finished upon 122 // return. Return 1 if you have handled the event, 0 for any default 123 // dispatching. 124 int32_t (*onInputEvent)(struct android_app *app, AInputEvent *event); 125 126 // The ANativeActivity object instance that this app is running in. 127 ANativeActivity *activity; 128 129 // The current configuration the app is running in. 130 AConfiguration *config; 131 132 // This is the last instance's saved state, as provided at creation time. 133 // It is NULL if there was no state. You can use this as you need; the 134 // memory will remain around until you call android_app_exec_cmd() for 135 // APP_CMD_RESUME, at which point it will be freed and savedState set to NULL. 136 // These variables should only be changed when processing a APP_CMD_SAVE_STATE, 137 // at which point they will be initialized to NULL and you can malloc your 138 // state and place the information here. In that case the memory will be 139 // freed for you later. 140 void *savedState; 141 size_t savedStateSize; 142 143 // The ALooper associated with the app's thread. 144 ALooper *looper; 145 146 // When non-NULL, this is the input queue from which the app will 147 // receive user input events. 148 AInputQueue *inputQueue; 149 150 // When non-NULL, this is the window surface that the app can draw in. 151 ANativeWindow *window; 152 153 // Current content rectangle of the window; this is the area where the 154 // window's content should be placed to be seen by the user. 155 ARect contentRect; 156 157 // Current state of the app's activity. May be either APP_CMD_START, 158 // APP_CMD_RESUME, APP_CMD_PAUSE, or APP_CMD_STOP; see below. 159 int activityState; 160 161 // This is non-zero when the application's NativeActivity is being 162 // destroyed and waiting for the app thread to complete. 163 int destroyRequested; 164 165 // ------------------------------------------------- 166 // Below are "private" implementation of the glue code. 167 168 pthread_mutex_t mutex; 169 pthread_cond_t cond; 170 171 int msgread; 172 int msgwrite; 173 174 pthread_t thread; 175 176 struct android_poll_source cmdPollSource; 177 struct android_poll_source inputPollSource; 178 179 int running; 180 int stateSaved; 181 int destroyed; 182 int redrawNeeded; 183 AInputQueue *pendingInputQueue; 184 ANativeWindow *pendingWindow; 185 ARect pendingContentRect; 186 }; 187 188 enum 189 { 190 /** 191 * Looper data ID of commands coming from the app's main thread, which 192 * is returned as an identifier from ALooper_pollOnce(). The data for this 193 * identifier is a pointer to an android_poll_source structure. 194 * These can be retrieved and processed with android_app_read_cmd() 195 * and android_app_exec_cmd(). 196 */ 197 LOOPER_ID_MAIN = 1, 198 199 /** 200 * Looper data ID of events coming from the AInputQueue of the 201 * application's window, which is returned as an identifier from 202 * ALooper_pollOnce(). The data for this identifier is a pointer to an 203 * android_poll_source structure. These can be read via the inputQueue 204 * object of android_app. 205 */ 206 LOOPER_ID_INPUT = 2, 207 208 /** 209 * Start of user-defined ALooper identifiers. 210 */ 211 LOOPER_ID_USER = 3, 212 }; 213 214 enum 215 { 216 /** 217 * Command from main thread: the AInputQueue has changed. Upon processing 218 * this command, android_app->inputQueue will be updated to the new queue 219 * (or NULL). 220 */ 221 APP_CMD_INPUT_CHANGED, 222 223 /** 224 * Command from main thread: a new ANativeWindow is ready for use. Upon 225 * receiving this command, android_app->window will contain the new window 226 * surface. 227 */ 228 APP_CMD_INIT_WINDOW, 229 230 /** 231 * Command from main thread: the existing ANativeWindow needs to be 232 * terminated. Upon receiving this command, android_app->window still 233 * contains the existing window; after calling android_app_exec_cmd 234 * it will be set to NULL. 235 */ 236 APP_CMD_TERM_WINDOW, 237 238 /** 239 * Command from main thread: the current ANativeWindow has been resized. 240 * Please redraw with its new size. 241 */ 242 APP_CMD_WINDOW_RESIZED, 243 244 /** 245 * Command from main thread: the system needs that the current ANativeWindow 246 * be redrawn. You should redraw the window before handing this to 247 * android_app_exec_cmd() in order to avoid transient drawing glitches. 248 */ 249 APP_CMD_WINDOW_REDRAW_NEEDED, 250 251 /** 252 * Command from main thread: the content area of the window has changed, 253 * such as from the soft input window being shown or hidden. You can 254 * find the new content rect in android_app::contentRect. 255 */ 256 APP_CMD_CONTENT_RECT_CHANGED, 257 258 /** 259 * Command from main thread: the app's activity window has gained 260 * input focus. 261 */ 262 APP_CMD_GAINED_FOCUS, 263 264 /** 265 * Command from main thread: the app's activity window has lost 266 * input focus. 267 */ 268 APP_CMD_LOST_FOCUS, 269 270 /** 271 * Command from main thread: the current device configuration has changed. 272 */ 273 APP_CMD_CONFIG_CHANGED, 274 275 /** 276 * Command from main thread: the system is running low on memory. 277 * Try to reduce your memory use. 278 */ 279 APP_CMD_LOW_MEMORY, 280 281 /** 282 * Command from main thread: the app's activity has been started. 283 */ 284 APP_CMD_START, 285 286 /** 287 * Command from main thread: the app's activity has been resumed. 288 */ 289 APP_CMD_RESUME, 290 291 /** 292 * Command from main thread: the app should generate a new saved state 293 * for itself, to restore from later if needed. If you have saved state, 294 * allocate it with malloc and place it in android_app.savedState with 295 * the size in android_app.savedStateSize. The will be freed for you 296 * later. 297 */ 298 APP_CMD_SAVE_STATE, 299 300 /** 301 * Command from main thread: the app's activity has been paused. 302 */ 303 APP_CMD_PAUSE, 304 305 /** 306 * Command from main thread: the app's activity has been stopped. 307 */ 308 APP_CMD_STOP, 309 310 /** 311 * Command from main thread: the app's activity is being destroyed, 312 * and waiting for the app thread to clean up and exit before proceeding. 313 */ 314 APP_CMD_DESTROY, 315 }; 316 317 /** 318 * Call when ALooper_pollAll() returns LOOPER_ID_MAIN, reading the next 319 * app command message. 320 */ 321 int8_t android_app_read_cmd(struct android_app *android_app); 322 323 /** 324 * Call with the command returned by android_app_read_cmd() to do the 325 * initial pre-processing of the given command. You can perform your own 326 * actions for the command after calling this function. 327 */ 328 void android_app_pre_exec_cmd(struct android_app *android_app, int8_t cmd); 329 330 /** 331 * Call with the command returned by android_app_read_cmd() to do the 332 * final post-processing of the given command. You must have done your own 333 * actions for the command before calling this function. 334 */ 335 void android_app_post_exec_cmd(struct android_app *android_app, int8_t cmd); 336 337 /** 338 * No-op function that used to be used to prevent the linker from stripping app 339 * glue code. No longer necessary, since __attribute__((visibility("default"))) 340 * does this for us. 341 */ 342 __attribute__(( 343 deprecated("Calls to app_dummy are no longer necessary. See " 344 "https://github.com/android-ndk/ndk/issues/381."))) void 345 app_dummy(void); 346 347 /** 348 * This is the function that application code must implement, representing 349 * the main entry to the app. 350 */ 351 extern void android_main(struct android_app *app); 352 353 #ifdef __cplusplus 354 } 355 #endif 356 357 #endif /* _ANDROID_NATIVE_APP_GLUE_H */ 358