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