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