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 * @addtogroup NativeActivity Native Activity
19 * @{
20 */
21
22/**
23 * @file native_activity.h
24 */
25
26#ifndef ANDROID_NATIVE_ACTIVITY_H
27#define ANDROID_NATIVE_ACTIVITY_H
28
29#include <stdint.h>
30#include <sys/types.h>
31
32#include <jni.h>
33
34#include <android/asset_manager.h>
35#include <android/input.h>
36#include <android/native_window.h>
37
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/**
43 * {@link ANativeActivityCallbacks}
44 */
45struct ANativeActivityCallbacks;
46
47/**
48 * This structure defines the native side of an android.app.NativeActivity.
49 * It is created by the framework, and handed to the application's native
50 * code as it is being launched.
51 */
52typedef struct ANativeActivity {
53    /**
54     * Pointer to the callback function table of the native application.
55     * You can set the functions here to your own callbacks.  The callbacks
56     * pointer itself here should not be changed; it is allocated and managed
57     * for you by the framework.
58     */
59    struct ANativeActivityCallbacks* callbacks;
60
61    /**
62     * The global handle on the process's Java VM.
63     */
64    JavaVM* vm;
65
66    /**
67     * JNI context for the main thread of the app.  Note that this field
68     * can ONLY be used from the main thread of the process; that is, the
69     * thread that calls into the ANativeActivityCallbacks.
70     */
71    JNIEnv* env;
72
73    /**
74     * The NativeActivity object handle.
75     *
76     * IMPORTANT NOTE: This member is mis-named. It should really be named
77     * 'activity' instead of 'clazz', since it's a reference to the
78     * NativeActivity instance created by the system for you.
79     *
80     * We unfortunately cannot change this without breaking NDK
81     * source-compatibility.
82     */
83    jobject clazz;
84
85    /**
86     * Path to this application's internal data directory.
87     */
88    const char* internalDataPath;
89
90    /**
91     * Path to this application's external (removable/mountable) data directory.
92     */
93    const char* externalDataPath;
94
95    /**
96     * The platform's SDK version code.
97     */
98    int32_t sdkVersion;
99
100    /**
101     * This is the native instance of the application.  It is not used by
102     * the framework, but can be set by the application to its own instance
103     * state.
104     */
105    void* instance;
106
107    /**
108     * Pointer to the Asset Manager instance for the application.  The application
109     * uses this to access binary assets bundled inside its own .apk file.
110     */
111    AAssetManager* assetManager;
112
113    /**
114     * Available starting with Honeycomb: path to the directory containing
115     * the application's OBB files (if any).  If the app doesn't have any
116     * OBB files, this directory may not exist.
117     */
118    const char* obbPath;
119} ANativeActivity;
120
121/**
122 * These are the callbacks the framework makes into a native application.
123 * All of these callbacks happen on the main thread of the application.
124 * By default, all callbacks are NULL; set to a pointer to your own function
125 * to have it called.
126 */
127typedef struct ANativeActivityCallbacks {
128    /**
129     * NativeActivity has started.  See Java documentation for Activity.onStart()
130     * for more information.
131     */
132    void (*onStart)(ANativeActivity* activity);
133
134    /**
135     * NativeActivity has resumed.  See Java documentation for Activity.onResume()
136     * for more information.
137     */
138    void (*onResume)(ANativeActivity* activity);
139
140    /**
141     * Framework is asking NativeActivity to save its current instance state.
142     * See Java documentation for Activity.onSaveInstanceState() for more
143     * information.  The returned pointer needs to be created with malloc();
144     * the framework will call free() on it for you.  You also must fill in
145     * outSize with the number of bytes in the allocation.  Note that the
146     * saved state will be persisted, so it can not contain any active
147     * entities (pointers to memory, file descriptors, etc).
148     */
149    void* (*onSaveInstanceState)(ANativeActivity* activity, size_t* outSize);
150
151    /**
152     * NativeActivity has paused.  See Java documentation for Activity.onPause()
153     * for more information.
154     */
155    void (*onPause)(ANativeActivity* activity);
156
157    /**
158     * NativeActivity has stopped.  See Java documentation for Activity.onStop()
159     * for more information.
160     */
161    void (*onStop)(ANativeActivity* activity);
162
163    /**
164     * NativeActivity is being destroyed.  See Java documentation for Activity.onDestroy()
165     * for more information.
166     */
167    void (*onDestroy)(ANativeActivity* activity);
168
169    /**
170     * Focus has changed in this NativeActivity's window.  This is often used,
171     * for example, to pause a game when it loses input focus.
172     */
173    void (*onWindowFocusChanged)(ANativeActivity* activity, int hasFocus);
174
175    /**
176     * The drawing window for this native activity has been created.  You
177     * can use the given native window object to start drawing.
178     */
179    void (*onNativeWindowCreated)(ANativeActivity* activity, ANativeWindow* window);
180
181    /**
182     * The drawing window for this native activity has been resized.  You should
183     * retrieve the new size from the window and ensure that your rendering in
184     * it now matches.
185     */
186    void (*onNativeWindowResized)(ANativeActivity* activity, ANativeWindow* window);
187
188    /**
189     * The drawing window for this native activity needs to be redrawn.  To avoid
190     * transient artifacts during screen changes (such resizing after rotation),
191     * applications should not return from this function until they have finished
192     * drawing their window in its current state.
193     */
194    void (*onNativeWindowRedrawNeeded)(ANativeActivity* activity, ANativeWindow* window);
195
196    /**
197     * The drawing window for this native activity is going to be destroyed.
198     * You MUST ensure that you do not touch the window object after returning
199     * from this function: in the common case of drawing to the window from
200     * another thread, that means the implementation of this callback must
201     * properly synchronize with the other thread to stop its drawing before
202     * returning from here.
203     */
204    void (*onNativeWindowDestroyed)(ANativeActivity* activity, ANativeWindow* window);
205
206    /**
207     * The input queue for this native activity's window has been created.
208     * You can use the given input queue to start retrieving input events.
209     */
210    void (*onInputQueueCreated)(ANativeActivity* activity, AInputQueue* queue);
211
212    /**
213     * The input queue for this native activity's window is being destroyed.
214     * You should no longer try to reference this object upon returning from this
215     * function.
216     */
217    void (*onInputQueueDestroyed)(ANativeActivity* activity, AInputQueue* queue);
218
219    /**
220     * The rectangle in the window in which content should be placed has changed.
221     */
222    void (*onContentRectChanged)(ANativeActivity* activity, const ARect* rect);
223
224    /**
225     * The current device AConfiguration has changed.  The new configuration can
226     * be retrieved from assetManager.
227     */
228    void (*onConfigurationChanged)(ANativeActivity* activity);
229
230    /**
231     * The system is running low on memory.  Use this callback to release
232     * resources you do not need, to help the system avoid killing more
233     * important processes.
234     */
235    void (*onLowMemory)(ANativeActivity* activity);
236} ANativeActivityCallbacks;
237
238/**
239 * This is the function that must be in the native code to instantiate the
240 * application's native activity.  It is called with the activity instance (see
241 * above); if the code is being instantiated from a previously saved instance,
242 * the savedState will be non-NULL and point to the saved data.  You must make
243 * any copy of this data you need -- it will be released after you return from
244 * this function.
245 */
246typedef void ANativeActivity_createFunc(ANativeActivity* activity,
247        void* savedState, size_t savedStateSize);
248
249/**
250 * The name of the function that NativeInstance looks for when launching its
251 * native code.  This is the default function that is used, you can specify
252 * "android.app.func_name" string meta-data in your manifest to use a different
253 * function.
254 */
255extern ANativeActivity_createFunc ANativeActivity_onCreate;
256
257/**
258 * Finish the given activity.  Its finish() method will be called, causing it
259 * to be stopped and destroyed.  Note that this method can be called from
260 * *any* thread; it will send a message to the main thread of the process
261 * where the Java finish call will take place.
262 */
263void ANativeActivity_finish(ANativeActivity* activity);
264
265/**
266 * Change the window format of the given activity.  Calls getWindow().setFormat()
267 * of the given activity.  Note that this method can be called from
268 * *any* thread; it will send a message to the main thread of the process
269 * where the Java finish call will take place.
270 */
271void ANativeActivity_setWindowFormat(ANativeActivity* activity, int32_t format);
272
273/**
274 * Change the window flags of the given activity.  Calls getWindow().setFlags()
275 * of the given activity.  Note that this method can be called from
276 * *any* thread; it will send a message to the main thread of the process
277 * where the Java finish call will take place.  See window.h for flag constants.
278 */
279void ANativeActivity_setWindowFlags(ANativeActivity* activity,
280        uint32_t addFlags, uint32_t removeFlags);
281
282/**
283 * Flags for ANativeActivity_showSoftInput; see the Java InputMethodManager
284 * API for documentation.
285 */
286enum {
287    /**
288     * Implicit request to show the input window, not as the result
289     * of a direct request by the user.
290     */
291    ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001,
292
293    /**
294     * The user has forced the input method open (such as by
295     * long-pressing menu) so it should not be closed until they
296     * explicitly do so.
297     */
298    ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002,
299};
300
301/**
302 * Show the IME while in the given activity.  Calls InputMethodManager.showSoftInput()
303 * for the given activity.  Note that this method can be called from
304 * *any* thread; it will send a message to the main thread of the process
305 * where the Java finish call will take place.
306 */
307void ANativeActivity_showSoftInput(ANativeActivity* activity, uint32_t flags);
308
309/**
310 * Flags for ANativeActivity_hideSoftInput; see the Java InputMethodManager
311 * API for documentation.
312 */
313enum {
314    /**
315     * The soft input window should only be hidden if it was not
316     * explicitly shown by the user.
317     */
318    ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001,
319    /**
320     * The soft input window should normally be hidden, unless it was
321     * originally shown with {@link ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED}.
322     */
323    ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002,
324};
325
326/**
327 * Hide the IME while in the given activity.  Calls InputMethodManager.hideSoftInput()
328 * for the given activity.  Note that this method can be called from
329 * *any* thread; it will send a message to the main thread of the process
330 * where the Java finish call will take place.
331 */
332void ANativeActivity_hideSoftInput(ANativeActivity* activity, uint32_t flags);
333
334#ifdef __cplusplus
335};
336#endif
337
338#endif // ANDROID_NATIVE_ACTIVITY_H
339
340/** @} */
341