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