Home | History | Annotate | Download | only in native_app_glue
      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
     30 extern "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 identifier returned by
     63  *    ALooper_pollOnce with values of LOOPER_ID_MAIN and LOOPER_ID_INPUT,
     64  *    respectively.
     65  *
     66  *    Your application can use the same ALooper to listen to additional
     67  *    file-descriptors.  They can either be callback based, or with return
     68  *    identifiers starting with LOOPER_ID_USER.
     69  *
     70  * 4/ Whenever you receive a LOOPER_ID_MAIN or LOOPER_ID_INPUT event,
     71  *    the returned data will point to an android_poll_source structure.  You
     72  *    can call the process() function on it, and fill in android_app->onAppCmd
     73  *    and android_app->onInputEvent to be called for your own processing
     74  *    of the event.
     75  *
     76  *    Alternatively, you can call the low-level functions to read and process
     77  *    the data directly...  look at the process_cmd() and process_input()
     78  *    implementations in the glue to see how to do this.
     79  *
     80  * See the sample named "native-activity" that comes with the NDK with a
     81  * full usage example.  Also look at the JavaDoc of NativeActivity.
     82  */
     83 
     84 struct android_app;
     85 
     86 /**
     87  * Data associated with an ALooper fd that will be returned as the "outData"
     88  * when that source has data ready.
     89  */
     90 struct android_poll_source {
     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     // The application can place a pointer to its own state object
    113     // here if it likes.
    114     void* userData;
    115 
    116     // Fill this in with the function to process main app commands (APP_CMD_*)
    117     void (*onAppCmd)(struct android_app* app, int32_t cmd);
    118 
    119     // Fill this in with the function to process input events.  At this point
    120     // the event has already been pre-dispatched, and it will be finished upon
    121     // return.  Return 1 if you have handled the event, 0 for any default
    122     // dispatching.
    123     int32_t (*onInputEvent)(struct android_app* app, AInputEvent* event);
    124 
    125     // The ANativeActivity object instance that this app is running in.
    126     ANativeActivity* activity;
    127 
    128     // The current configuration the app is running in.
    129     AConfiguration* config;
    130 
    131     // This is the last instance's saved state, as provided at creation time.
    132     // It is NULL if there was no state.  You can use this as you need; the
    133     // memory will remain around until you call android_app_exec_cmd() for
    134     // APP_CMD_RESUME, at which point it will be freed and savedState set to NULL.
    135     // These variables should only be changed when processing a APP_CMD_SAVE_STATE,
    136     // at which point they will be initialized to NULL and you can malloc your
    137     // state and place the information here.  In that case the memory will be
    138     // freed for you later.
    139     void* savedState;
    140     size_t savedStateSize;
    141 
    142     // The ALooper associated with the app's thread.
    143     ALooper* looper;
    144 
    145     // When non-NULL, this is the input queue from which the app will
    146     // receive user input events.
    147     AInputQueue* inputQueue;
    148 
    149     // When non-NULL, this is the window surface that the app can draw in.
    150     ANativeWindow* window;
    151 
    152     // Current content rectangle of the window; this is the area where the
    153     // window's content should be placed to be seen by the user.
    154     ARect contentRect;
    155 
    156     // Current state of the app's activity.  May be either APP_CMD_START,
    157     // APP_CMD_RESUME, APP_CMD_PAUSE, or APP_CMD_STOP; see below.
    158     int activityState;
    159 
    160     // This is non-zero when the application's NativeActivity is being
    161     // destroyed and waiting for the app thread to complete.
    162     int destroyRequested;
    163 
    164     // -------------------------------------------------
    165     // Below are "private" implementation of the glue code.
    166 
    167     pthread_mutex_t mutex;
    168     pthread_cond_t cond;
    169 
    170     int msgread;
    171     int msgwrite;
    172 
    173     pthread_t thread;
    174 
    175     struct android_poll_source cmdPollSource;
    176     struct android_poll_source inputPollSource;
    177 
    178     int running;
    179     int stateSaved;
    180     int destroyed;
    181     int redrawNeeded;
    182     AInputQueue* pendingInputQueue;
    183     ANativeWindow* pendingWindow;
    184     ARect pendingContentRect;
    185 };
    186 
    187 enum {
    188     /**
    189      * Looper data ID of commands coming from the app's main thread, which
    190      * is returned as an identifier from ALooper_pollOnce().  The data for this
    191      * identifier is a pointer to an android_poll_source structure.
    192      * These can be retrieved and processed with android_app_read_cmd()
    193      * and android_app_exec_cmd().
    194      */
    195     LOOPER_ID_MAIN = 1,
    196 
    197     /**
    198      * Looper data ID of events coming from the AInputQueue of the
    199      * application's window, which is returned as an identifier from
    200      * ALooper_pollOnce().  The data for this identifier is a pointer to an
    201      * android_poll_source structure.  These can be read via the inputQueue
    202      * object of android_app.
    203      */
    204     LOOPER_ID_INPUT = 2,
    205 
    206     /**
    207      * Start of user-defined ALooper identifiers.
    208      */
    209     LOOPER_ID_USER = 3,
    210 };
    211 
    212 enum {
    213     /**
    214      * Command from main thread: the AInputQueue has changed.  Upon processing
    215      * this command, android_app->inputQueue will be updated to the new queue
    216      * (or NULL).
    217      */
    218     APP_CMD_INPUT_CHANGED,
    219 
    220     /**
    221      * Command from main thread: a new ANativeWindow is ready for use.  Upon
    222      * receiving this command, android_app->window will contain the new window
    223      * surface.
    224      */
    225     APP_CMD_INIT_WINDOW,
    226 
    227     /**
    228      * Command from main thread: the existing ANativeWindow needs to be
    229      * terminated.  Upon receiving this command, android_app->window still
    230      * contains the existing window; after calling android_app_exec_cmd
    231      * it will be set to NULL.
    232      */
    233     APP_CMD_TERM_WINDOW,
    234 
    235     /**
    236      * Command from main thread: the current ANativeWindow has been resized.
    237      * Please redraw with its new size.
    238      */
    239     APP_CMD_WINDOW_RESIZED,
    240 
    241     /**
    242      * Command from main thread: the system needs that the current ANativeWindow
    243      * be redrawn.  You should redraw the window before handing this to
    244      * android_app_exec_cmd() in order to avoid transient drawing glitches.
    245      */
    246     APP_CMD_WINDOW_REDRAW_NEEDED,
    247 
    248     /**
    249      * Command from main thread: the content area of the window has changed,
    250      * such as from the soft input window being shown or hidden.  You can
    251      * find the new content rect in android_app::contentRect.
    252      */
    253     APP_CMD_CONTENT_RECT_CHANGED,
    254 
    255     /**
    256      * Command from main thread: the app's activity window has gained
    257      * input focus.
    258      */
    259     APP_CMD_GAINED_FOCUS,
    260 
    261     /**
    262      * Command from main thread: the app's activity window has lost
    263      * input focus.
    264      */
    265     APP_CMD_LOST_FOCUS,
    266 
    267     /**
    268      * Command from main thread: the current device configuration has changed.
    269      */
    270     APP_CMD_CONFIG_CHANGED,
    271 
    272     /**
    273      * Command from main thread: the system is running low on memory.
    274      * Try to reduce your memory use.
    275      */
    276     APP_CMD_LOW_MEMORY,
    277 
    278     /**
    279      * Command from main thread: the app's activity has been started.
    280      */
    281     APP_CMD_START,
    282 
    283     /**
    284      * Command from main thread: the app's activity has been resumed.
    285      */
    286     APP_CMD_RESUME,
    287 
    288     /**
    289      * Command from main thread: the app should generate a new saved state
    290      * for itself, to restore from later if needed.  If you have saved state,
    291      * allocate it with malloc and place it in android_app.savedState with
    292      * the size in android_app.savedStateSize.  The will be freed for you
    293      * later.
    294      */
    295     APP_CMD_SAVE_STATE,
    296 
    297     /**
    298      * Command from main thread: the app's activity has been paused.
    299      */
    300     APP_CMD_PAUSE,
    301 
    302     /**
    303      * Command from main thread: the app's activity has been stopped.
    304      */
    305     APP_CMD_STOP,
    306 
    307     /**
    308      * Command from main thread: the app's activity is being destroyed,
    309      * and waiting for the app thread to clean up and exit before proceeding.
    310      */
    311     APP_CMD_DESTROY,
    312 };
    313 
    314 /**
    315  * Call when ALooper_pollAll() returns LOOPER_ID_MAIN, reading the next
    316  * app command message.
    317  */
    318 int8_t android_app_read_cmd(struct android_app* android_app);
    319 
    320 /**
    321  * Call with the command returned by android_app_read_cmd() to do the
    322  * initial pre-processing of the given command.  You can perform your own
    323  * actions for the command after calling this function.
    324  */
    325 void android_app_pre_exec_cmd(struct android_app* android_app, int8_t cmd);
    326 
    327 /**
    328  * Call with the command returned by android_app_read_cmd() to do the
    329  * final post-processing of the given command.  You must have done your own
    330  * actions for the command before calling this function.
    331  */
    332 void android_app_post_exec_cmd(struct android_app* android_app, int8_t cmd);
    333 
    334 /**
    335  * Dummy function you can call to ensure glue code isn't stripped.
    336  */
    337 void app_dummy();
    338 
    339 /**
    340  * This is the function that application code must implement, representing
    341  * the main entry to the app.
    342  */
    343 extern void android_main(struct android_app* app);
    344 
    345 #ifdef __cplusplus
    346 }
    347 #endif
    348 
    349 #endif /* _ANDROID_NATIVE_APP_GLUE_H */
    350