2 * Copyright (c) 2011 - 2016 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __TIZEN_APPFW_APP_INTERNAL_H__
19 #define __TIZEN_APPFW_APP_INTERNAL_H__
22 #include <appcore-common.h>
23 #include <tzplatform_config.h>
25 /* GNU gettext macro is already defined at appcore-common.h */
34 #define TIZEN_PATH_MAX 1024
36 #define PATH_FMT_APP_ROOT tzplatform_getenv(TZ_USER_APP)
37 #define PATH_FMT_RES_DIR "/res"
38 #define PATH_FMT_LOCALE_DIR "/locale"
39 #define PATH_FMT_DATA_DIR "/data"
41 #define PATH_FMT_RO_APP_ROOT tzplatform_getenv(TZ_SYS_RO_APP)
42 #define PATH_FMT_RO_RES_DIR "/res"
43 #define PATH_FMT_RO_LOCALE_DIR "/local"
45 struct app_event_handler {
46 app_event_type_e type;
51 struct app_event_info {
52 app_event_type_e type;
56 app_device_orientation_e app_convert_appcore_rm(enum appcore_rm rm);
58 typedef void (*app_finalizer_cb) (void *data);
60 int app_error(app_error_e error, const char *function, const char *description);
62 app_device_orientation_e app_convert_appcore_rm(enum appcore_rm rm);
64 int app_get_package_app_name(const char *package, char **name);
66 int app_finalizer_add(app_finalizer_cb callback, void *data);
68 int app_finalizer_remove(app_finalizer_cb callback);
70 void app_finalizer_execute(void);
72 int app_get_package(char **package);
76 * @brief Called when the system memory is running low.
78 * @details When a low memory event is dispatched, the application should immediately save state and release resources to save as much memory as possible. \n
79 * If enough memory is not reclaimed during low memory conditions, the system will terminate some of the applications to reclaim the memory.
82 * @param[in] user_data The user data passed from the callback registration function
84 * @see #app_event_callback_s
86 typedef void (*app_low_memory_cb) (void *user_data);
90 * @brief Called when the battery power is running low.
91 * @details When the battery level falls below 5%, it is called.
94 * @param[in] user_data The user data passed from the callback registration function
96 * @see #app_event_callback_s
98 typedef void (*app_low_battery_cb) (void *user_data);
102 * @brief Called when the orientation of the device changes.
105 * @param[in] orientation The orientation of the device
106 * @param[in] user_data The user data passed from the callback registration function
108 * @see #app_event_callback_s
110 typedef void (*app_device_orientation_cb) (app_device_orientation_e orientation, void *user_data);
114 * @brief Called when language setting changes.
117 * @param[in] user_data The user data passed from the callback registration function
119 * @see #app_event_callback_s
121 typedef void (*app_language_changed_cb) (void *user_data);
125 * @brief Called when region format setting changes.
128 * @param[in] user_data The user data passed from the callback registration function
130 * @see #app_event_callback_s
132 typedef void (*app_region_format_changed_cb) (void *user_data);
136 * @brief The structure type containing the set of callback functions for handling application events.
137 * @details It is one of the input parameters of the app_main() function.
141 * @see app_create_cb()
142 * @see app_pause_cb()
143 * @see app_resume_cb()
144 * @see app_terminate_cb()
145 * @see app_control_cb()
146 * @see app_low_memory_cb()
147 * @see app_low_battery_cb()
148 * @see app_device_orientation_cb()
149 * @see app_language_changed_cb()
150 * @see app_region_format_changed_cb()
153 app_create_cb create; /**< This callback function is called at the start of the application. */
154 app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
155 app_pause_cb pause; /**< This callback function is called each time the application is completely obscured by another application and becomes invisible to the user. */
156 app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */
157 app_control_cb app_control; /**< This callback function is called when another application sends the launch request to the application. */
158 app_low_memory_cb low_memory; /**< The registered callback function is called when the system runs low on memory. */
159 app_low_battery_cb low_battery; /**< The registered callback function is called when the battery is low. */
160 app_device_orientation_cb device_orientation; /**< The registered callback function is called when the orientation of the device changes */
161 app_language_changed_cb language_changed; /**< The registered callback function is called when language setting changes. */
162 app_region_format_changed_cb region_format_changed; /**< The registered callback function is called when region format setting changes. */
163 } app_event_callback_s;
167 * @brief Runs the application's main loop until app_exit() is called.
169 * @details This function is the main entry point of the Tizen application.
170 * The app_create_cb() callback function is called to initialize the application before the main loop of application starts up.
171 * After the app_create_cb() callback function returns true, the main loop starts up and the app_control_cb() callback function is subsequently called.
172 * If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called.
175 * @param[in] argc The argument count
176 * @param[in] argv The argument vector
177 * @param[in] callback The set of callback functions to handle application events
178 * @param[in] user_data The user data to be passed to the callback functions
180 * @return 0 on success, otherwise a negative error value
181 * @retval #APP_ERROR_NONE Successful
182 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
183 * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
184 * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts
186 * @see app_create_cb()
187 * @see app_terminate_cb()
188 * @see app_pause_cb()
189 * @see app_resume_cb()
190 * @see app_control_cb()
191 * @see app_low_memory_cb()
192 * @see app_low_battery_cb()
193 * @see app_device_orientation_cb()
194 * @see app_language_changed_cb()
195 * @see app_region_format_changed_cb()
197 * @see #app_event_callback_s
199 int app_main(int argc, char **argv, app_event_callback_s *callback, void *user_data);
203 * @brief Runs the application's main loop until app_efl_exit() is called.
205 * @details This function is the main entry point of the Tizen application.
206 * The app_create_cb() callback function is called to initialize the application before the main loop of the application starts up.
207 * After the app_create_cb() callback function returns @c true, the main loop starts up and the app_control_cb() callback function is subsequently called.
208 * If the app_create_cb() callback function returns @c false, the main loop doesn't start up and the app_terminate_cb() callback function is called.
211 * @param[in] argc The argument count
212 * @param[in] argv The argument vector
213 * @param[in] callback The set of callback functions to handle application events
214 * @param[in] user_data The user data to be passed to the callback functions
216 * @return @c 0 on success,
217 * otherwise a negative error value
218 * @retval #APP_ERROR_NONE Successful
219 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
220 * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
221 * @retval #APP_ERROR_ALREADY_RUNNING The main loop has already started
223 * @see app_create_cb()
224 * @see app_terminate_cb()
225 * @see app_pause_cb()
226 * @see app_resume_cb()
227 * @see app_control_cb()
228 * @see app_low_memory_cb()
229 * @see app_low_battery_cb()
230 * @see app_device_orientation_cb()
231 * @see app_language_changed_cb()
232 * @see app_region_format_changed_cb()
233 * @see app_efl_exit()
234 * @see #app_event_callback_s
236 int app_efl_main(int *argc, char ***argv, app_event_callback_s *callback, void *user_data);
240 * @brief Exits the main loop of application.
242 * @details The main loop of application stops and app_terminate_cb() is invoked.
245 * @see app_terminate_cb()
251 * @brief Exits the main loop of the application.
253 * @details The main loop of the application stops and app_terminate_cb() is invoked.
255 * @see app_efl_main()
256 * @see app_terminate_cb()
258 void app_efl_exit(void);
264 #endif /* __TIZEN_APPFW_APP_INTERNAL_H__ */