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