nuclear@0: /* nuclear@0: * Copyright (C) 2010 The Android Open Source Project nuclear@0: * nuclear@0: * Licensed under the Apache License, Version 2.0 (the "License"); nuclear@0: * you may not use this file except in compliance with the License. nuclear@0: * You may obtain a copy of the License at nuclear@0: * nuclear@0: * http://www.apache.org/licenses/LICENSE-2.0 nuclear@0: * nuclear@0: * Unless required by applicable law or agreed to in writing, software nuclear@0: * distributed under the License is distributed on an "AS IS" BASIS, nuclear@0: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. nuclear@0: * See the License for the specific language governing permissions and nuclear@0: * limitations under the License. nuclear@0: * nuclear@0: */ nuclear@0: nuclear@0: #ifndef _ANDROID_NATIVE_APP_GLUE_H nuclear@0: #define _ANDROID_NATIVE_APP_GLUE_H nuclear@0: nuclear@0: #include nuclear@0: #include nuclear@0: #include nuclear@0: nuclear@0: #include nuclear@0: #include nuclear@0: #include nuclear@0: nuclear@0: #ifdef __cplusplus nuclear@0: extern "C" { nuclear@0: #endif nuclear@0: nuclear@0: /** nuclear@0: * The native activity interface provided by nuclear@0: * is based on a set of application-provided callbacks that will be called nuclear@0: * by the Activity's main thread when certain events occur. nuclear@0: * nuclear@0: * This means that each one of this callbacks _should_ _not_ block, or they nuclear@0: * risk having the system force-close the application. This programming nuclear@0: * model is direct, lightweight, but constraining. nuclear@0: * nuclear@0: * The 'android_native_app_glue' static library is used to provide a different nuclear@0: * execution model where the application can implement its own main event nuclear@0: * loop in a different thread instead. Here's how it works: nuclear@0: * nuclear@0: * 1/ The application must provide a function named "android_main()" that nuclear@0: * will be called when the activity is created, in a new thread that is nuclear@0: * distinct from the activity's main thread. nuclear@0: * nuclear@0: * 2/ android_main() receives a pointer to a valid "android_app" structure nuclear@0: * that contains references to other important objects, e.g. the nuclear@0: * ANativeActivity obejct instance the application is running in. nuclear@0: * nuclear@0: * 3/ the "android_app" object holds an ALooper instance that already nuclear@0: * listens to two important things: nuclear@0: * nuclear@0: * - activity lifecycle events (e.g. "pause", "resume"). See APP_CMD_XXX nuclear@0: * declarations below. nuclear@0: * nuclear@0: * - input events coming from the AInputQueue attached to the activity. nuclear@0: * nuclear@0: * Each of these correspond to an ALooper identifier returned by nuclear@0: * ALooper_pollOnce with values of LOOPER_ID_MAIN and LOOPER_ID_INPUT, nuclear@0: * respectively. nuclear@0: * nuclear@0: * Your application can use the same ALooper to listen to additional nuclear@0: * file-descriptors. They can either be callback based, or with return nuclear@0: * identifiers starting with LOOPER_ID_USER. nuclear@0: * nuclear@0: * 4/ Whenever you receive a LOOPER_ID_MAIN or LOOPER_ID_INPUT event, nuclear@0: * the returned data will point to an android_poll_source structure. You nuclear@0: * can call the process() function on it, and fill in android_app->onAppCmd nuclear@0: * and android_app->onInputEvent to be called for your own processing nuclear@0: * of the event. nuclear@0: * nuclear@0: * Alternatively, you can call the low-level functions to read and process nuclear@0: * the data directly... look at the process_cmd() and process_input() nuclear@0: * implementations in the glue to see how to do this. nuclear@0: * nuclear@0: * See the sample named "native-activity" that comes with the NDK with a nuclear@0: * full usage example. Also look at the JavaDoc of NativeActivity. nuclear@0: */ nuclear@0: nuclear@0: struct android_app; nuclear@0: nuclear@0: /** nuclear@0: * Data associated with an ALooper fd that will be returned as the "outData" nuclear@0: * when that source has data ready. nuclear@0: */ nuclear@0: struct android_poll_source { nuclear@0: // The identifier of this source. May be LOOPER_ID_MAIN or nuclear@0: // LOOPER_ID_INPUT. nuclear@0: int32_t id; nuclear@0: nuclear@0: // The android_app this ident is associated with. nuclear@0: struct android_app* app; nuclear@0: nuclear@0: // Function to call to perform the standard processing of data from nuclear@0: // this source. nuclear@0: void (*process)(struct android_app* app, struct android_poll_source* source); nuclear@0: }; nuclear@0: nuclear@0: /** nuclear@0: * This is the interface for the standard glue code of a threaded nuclear@0: * application. In this model, the application's code is running nuclear@0: * in its own thread separate from the main thread of the process. nuclear@0: * It is not required that this thread be associated with the Java nuclear@0: * VM, although it will need to be in order to make JNI calls any nuclear@0: * Java objects. nuclear@0: */ nuclear@0: struct android_app { nuclear@0: // The application can place a pointer to its own state object nuclear@0: // here if it likes. nuclear@0: void* userData; nuclear@0: nuclear@0: // Fill this in with the function to process main app commands (APP_CMD_*) nuclear@0: void (*onAppCmd)(struct android_app* app, int32_t cmd); nuclear@0: nuclear@0: // Fill this in with the function to process input events. At this point nuclear@0: // the event has already been pre-dispatched, and it will be finished upon nuclear@0: // return. Return 1 if you have handled the event, 0 for any default nuclear@0: // dispatching. nuclear@0: int32_t (*onInputEvent)(struct android_app* app, AInputEvent* event); nuclear@0: nuclear@0: // The ANativeActivity object instance that this app is running in. nuclear@0: ANativeActivity* activity; nuclear@0: nuclear@0: // The current configuration the app is running in. nuclear@0: AConfiguration* config; nuclear@0: nuclear@0: // This is the last instance's saved state, as provided at creation time. nuclear@0: // It is NULL if there was no state. You can use this as you need; the nuclear@0: // memory will remain around until you call android_app_exec_cmd() for nuclear@0: // APP_CMD_RESUME, at which point it will be freed and savedState set to NULL. nuclear@0: // These variables should only be changed when processing a APP_CMD_SAVE_STATE, nuclear@0: // at which point they will be initialized to NULL and you can malloc your nuclear@0: // state and place the information here. In that case the memory will be nuclear@0: // freed for you later. nuclear@0: void* savedState; nuclear@0: size_t savedStateSize; nuclear@0: nuclear@0: // The ALooper associated with the app's thread. nuclear@0: ALooper* looper; nuclear@0: nuclear@0: // When non-NULL, this is the input queue from which the app will nuclear@0: // receive user input events. nuclear@0: AInputQueue* inputQueue; nuclear@0: nuclear@0: // When non-NULL, this is the window surface that the app can draw in. nuclear@0: ANativeWindow* window; nuclear@0: nuclear@0: // Current content rectangle of the window; this is the area where the nuclear@0: // window's content should be placed to be seen by the user. nuclear@0: ARect contentRect; nuclear@0: nuclear@0: // Current state of the app's activity. May be either APP_CMD_START, nuclear@0: // APP_CMD_RESUME, APP_CMD_PAUSE, or APP_CMD_STOP; see below. nuclear@0: int activityState; nuclear@0: nuclear@0: // This is non-zero when the application's NativeActivity is being nuclear@0: // destroyed and waiting for the app thread to complete. nuclear@0: int destroyRequested; nuclear@0: nuclear@0: // ------------------------------------------------- nuclear@0: // Below are "private" implementation of the glue code. nuclear@0: nuclear@0: pthread_mutex_t mutex; nuclear@0: pthread_cond_t cond; nuclear@0: nuclear@0: int msgread; nuclear@0: int msgwrite; nuclear@0: nuclear@0: pthread_t thread; nuclear@0: nuclear@0: struct android_poll_source cmdPollSource; nuclear@0: struct android_poll_source inputPollSource; nuclear@0: nuclear@0: int running; nuclear@0: int stateSaved; nuclear@0: int destroyed; nuclear@0: int redrawNeeded; nuclear@0: AInputQueue* pendingInputQueue; nuclear@0: ANativeWindow* pendingWindow; nuclear@0: ARect pendingContentRect; nuclear@0: }; nuclear@0: nuclear@0: enum { nuclear@0: /** nuclear@0: * Looper data ID of commands coming from the app's main thread, which nuclear@0: * is returned as an identifier from ALooper_pollOnce(). The data for this nuclear@0: * identifier is a pointer to an android_poll_source structure. nuclear@0: * These can be retrieved and processed with android_app_read_cmd() nuclear@0: * and android_app_exec_cmd(). nuclear@0: */ nuclear@0: LOOPER_ID_MAIN = 1, nuclear@0: nuclear@0: /** nuclear@0: * Looper data ID of events coming from the AInputQueue of the nuclear@0: * application's window, which is returned as an identifier from nuclear@0: * ALooper_pollOnce(). The data for this identifier is a pointer to an nuclear@0: * android_poll_source structure. These can be read via the inputQueue nuclear@0: * object of android_app. nuclear@0: */ nuclear@0: LOOPER_ID_INPUT = 2, nuclear@0: nuclear@0: /** nuclear@0: * Start of user-defined ALooper identifiers. nuclear@0: */ nuclear@0: LOOPER_ID_USER = 3, nuclear@0: }; nuclear@0: nuclear@0: enum { nuclear@0: /** nuclear@0: * Command from main thread: the AInputQueue has changed. Upon processing nuclear@0: * this command, android_app->inputQueue will be updated to the new queue nuclear@0: * (or NULL). nuclear@0: */ nuclear@0: APP_CMD_INPUT_CHANGED, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: a new ANativeWindow is ready for use. Upon nuclear@0: * receiving this command, android_app->window will contain the new window nuclear@0: * surface. nuclear@0: */ nuclear@0: APP_CMD_INIT_WINDOW, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the existing ANativeWindow needs to be nuclear@0: * terminated. Upon receiving this command, android_app->window still nuclear@0: * contains the existing window; after calling android_app_exec_cmd nuclear@0: * it will be set to NULL. nuclear@0: */ nuclear@0: APP_CMD_TERM_WINDOW, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the current ANativeWindow has been resized. nuclear@0: * Please redraw with its new size. nuclear@0: */ nuclear@0: APP_CMD_WINDOW_RESIZED, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the system needs that the current ANativeWindow nuclear@0: * be redrawn. You should redraw the window before handing this to nuclear@0: * android_app_exec_cmd() in order to avoid transient drawing glitches. nuclear@0: */ nuclear@0: APP_CMD_WINDOW_REDRAW_NEEDED, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the content area of the window has changed, nuclear@0: * such as from the soft input window being shown or hidden. You can nuclear@0: * find the new content rect in android_app::contentRect. nuclear@0: */ nuclear@0: APP_CMD_CONTENT_RECT_CHANGED, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the app's activity window has gained nuclear@0: * input focus. nuclear@0: */ nuclear@0: APP_CMD_GAINED_FOCUS, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the app's activity window has lost nuclear@0: * input focus. nuclear@0: */ nuclear@0: APP_CMD_LOST_FOCUS, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the current device configuration has changed. nuclear@0: */ nuclear@0: APP_CMD_CONFIG_CHANGED, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the system is running low on memory. nuclear@0: * Try to reduce your memory use. nuclear@0: */ nuclear@0: APP_CMD_LOW_MEMORY, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the app's activity has been started. nuclear@0: */ nuclear@0: APP_CMD_START, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the app's activity has been resumed. nuclear@0: */ nuclear@0: APP_CMD_RESUME, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the app should generate a new saved state nuclear@0: * for itself, to restore from later if needed. If you have saved state, nuclear@0: * allocate it with malloc and place it in android_app.savedState with nuclear@0: * the size in android_app.savedStateSize. The will be freed for you nuclear@0: * later. nuclear@0: */ nuclear@0: APP_CMD_SAVE_STATE, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the app's activity has been paused. nuclear@0: */ nuclear@0: APP_CMD_PAUSE, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the app's activity has been stopped. nuclear@0: */ nuclear@0: APP_CMD_STOP, nuclear@0: nuclear@0: /** nuclear@0: * Command from main thread: the app's activity is being destroyed, nuclear@0: * and waiting for the app thread to clean up and exit before proceeding. nuclear@0: */ nuclear@0: APP_CMD_DESTROY, nuclear@0: }; nuclear@0: nuclear@0: /** nuclear@0: * Call when ALooper_pollAll() returns LOOPER_ID_MAIN, reading the next nuclear@0: * app command message. nuclear@0: */ nuclear@0: int8_t android_app_read_cmd(struct android_app* android_app); nuclear@0: nuclear@0: /** nuclear@0: * Call with the command returned by android_app_read_cmd() to do the nuclear@0: * initial pre-processing of the given command. You can perform your own nuclear@0: * actions for the command after calling this function. nuclear@0: */ nuclear@0: void android_app_pre_exec_cmd(struct android_app* android_app, int8_t cmd); nuclear@0: nuclear@0: /** nuclear@0: * Call with the command returned by android_app_read_cmd() to do the nuclear@0: * final post-processing of the given command. You must have done your own nuclear@0: * actions for the command before calling this function. nuclear@0: */ nuclear@0: void android_app_post_exec_cmd(struct android_app* android_app, int8_t cmd); nuclear@0: nuclear@0: /** nuclear@0: * Dummy function you can call to ensure glue code isn't stripped. nuclear@0: */ nuclear@0: void app_dummy(); nuclear@0: nuclear@0: /** nuclear@0: * This is the function that application code must implement, representing nuclear@0: * the main entry to the app. nuclear@0: */ nuclear@0: extern void android_main(struct android_app* app); nuclear@0: nuclear@0: #ifdef __cplusplus nuclear@0: } nuclear@0: #endif nuclear@0: nuclear@0: #endif /* _ANDROID_NATIVE_APP_GLUE_H */