2 * Copyright (c) 2014 - 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_COMMON_H__
19 #define __TIZEN_APPFW_APP_COMMON_H__
21 #include <app_types.h>
32 * @addtogroup CAPI_APP_COMMON_MODULE
38 * @brief Enumeration for system events
39 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
42 APP_EVENT_LOW_MEMORY, /**< The low memory event */
43 APP_EVENT_LOW_BATTERY, /**< The low battery event */
44 APP_EVENT_LANGUAGE_CHANGED, /**< The system language changed event */
45 APP_EVENT_DEVICE_ORIENTATION_CHANGED, /**< The device orientation changed event */
46 APP_EVENT_REGION_FORMAT_CHANGED, /**< The region format changed event */
47 APP_EVENT_SUSPENDED_STATE_CHANGED, /**< The suspended state changed event of the application (since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)
48 @see app_event_get_suspended_state */
52 * @brief Enumeration for device orientation.
53 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
56 APP_DEVICE_ORIENTATION_0 = 0, /**< The device is oriented in a natural position */
57 APP_DEVICE_ORIENTATION_90 = 90, /**< The device's left side is at the top */
58 APP_DEVICE_ORIENTATION_180 = 180, /**< The device is upside down */
59 APP_DEVICE_ORIENTATION_270 = 270, /**< The device's right side is at the top */
60 } app_device_orientation_e;
63 * @brief Enumeration for low memory status.
64 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
67 APP_EVENT_LOW_MEMORY_NORMAL = 0x01, /**< Normal status */
68 APP_EVENT_LOW_MEMORY_SOFT_WARNING = 0x02, /**< Soft warning status */
69 APP_EVENT_LOW_MEMORY_HARD_WARNING = 0x04, /**< Hard warning status */
70 } app_event_low_memory_status_e;
73 * @brief Enumeration for battery status.
74 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
77 APP_EVENT_LOW_BATTERY_POWER_OFF = 1, /**< The battery status is under 1% */
78 APP_EVENT_LOW_BATTERY_CRITICAL_LOW, /**< The battery status is under 5% */
79 } app_event_low_battery_status_e;
82 * @brief Enumeration for suspended state
83 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
86 APP_SUSPENDED_STATE_WILL_ENTER = 0, /**< Application will enter the suspended state */
87 APP_SUSPENDED_STATE_DID_EXIT, /**< Application did exit from the suspended state */
88 } app_suspended_state_e;
91 * @brief The event handler that returned from add event handler function
93 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
94 * @see app_event_type_e
95 * @see app_add_event_handler
96 * @see app_remove_event_handler
97 * @see app_event_info_h
99 typedef struct app_event_handler *app_event_handler_h;
103 * @brief The system event information
105 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
106 * @see app_event_get_low_memory_status
107 * @see app_event_get_low_battery_status
108 * @see app_event_get_language
109 * @see app_event_get_region_format
110 * @see app_event_get_device_orientation
111 * @see app_event_get_suspended_state
113 typedef struct app_event_info *app_event_info_h;
117 * @brief The system event callback function
119 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
120 * @param[in] event_info The system event information
121 * @param[in] user_data The user data passed from the add event handler function
123 * @see app_add_event_handler
124 * @see app_event_info_h
126 * @remarks If the given @a event_info has #APP_SUSPENDED_STATE_WILL_ENTER value,
127 * the application should not call any asynchronous operations in this callback.
128 * After the callback returns, process of the application will be changed to suspended
129 * state immediately. Thus, asynchronous operations may work incorrectly. (since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif)
132 typedef void (*app_event_cb)(app_event_info_h event_info, void *user_data);
136 * @brief Gets the low memory status from given event info
138 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
139 * @param[in] event_info The system event info
140 * @param[out] status The low memory status
142 * @return 0 on success, otherwise a negative error value
143 * @retval #APP_ERROR_NONE Successful
144 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
145 * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
147 * @see app_event_info_h
148 * @see app_event_low_memory_status_e
150 int app_event_get_low_memory_status(app_event_info_h event_info, app_event_low_memory_status_e *status);
154 * @brief Gets the low battery status from given event info
156 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
157 * @param[in] event_info The system event info
158 * @param[out] status The low battery status
160 * @return 0 on success, otherwise a negative error value
161 * @retval #APP_ERROR_NONE Successful
162 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
163 * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
165 * @see app_event_info_h
166 * @see app_event_low_battery_status_e
168 int app_event_get_low_battery_status(app_event_info_h event_info, app_event_low_battery_status_e *status);
172 * @brief Gets the language from given event info
174 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
175 * @remarks @a lang must be released using free()
176 * @param[in] event_info The system event info
177 * @param[out] lang The language changed
179 * @return 0 on success, otherwise a negative error value
180 * @retval #APP_ERROR_NONE Successful
181 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
182 * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
184 * @see app_event_info_h
186 int app_event_get_language(app_event_info_h event_info, char **lang);
190 * @brief Gets the region format from given event info
192 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
193 * @remarks @a region must be released using free()
194 * @param[in] event_info The system event info
195 * @param[out] region The region format changed
197 * @return 0 on success, otherwise a negative error value
198 * @retval #APP_ERROR_NONE Successful
199 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
200 * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
202 * @see app_event_info_h
204 int app_event_get_region_format(app_event_info_h event_info, char **region);
208 * @brief Gets the device orientation from given event info
210 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
211 * @param[in] event_info The system event info
212 * @param[out] orientation The device orientation changed
214 * @return 0 on success, otherwise a negative error value
215 * @retval #APP_ERROR_NONE Successful
216 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
217 * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
219 * @see app_event_info_h
220 * @see app_device_orientation_e
222 int app_event_get_device_orientation(app_event_info_h event_info, app_device_orientation_e *orientation);
226 * @brief Gets the suspended state of the application from given event info.
228 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
229 * @param[in] event_info The handle for getting the suspended state
230 * @param[out] state The suspended state of the application
232 * @return 0 on success, otherwise a negative error value
233 * @retval #APP_ERROR_NONE Successful
234 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
235 * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
237 * @remarks The application should not use any asynchronous operations in #APP_SUSPENDED_STATE_WILL_ENTER event.
238 * Because applications will be changed to suspended state just after #APP_SUSPENDED_STATE_WILL_ENTER,
239 * asynchronous calls are not guaranteed to work properly.
241 int app_event_get_suspended_state(app_event_info_h event_info, app_suspended_state_e *state);
245 * @brief Gets the ID of the application.
247 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
248 * @remarks @a id must be released using free().
250 * @param[out] id The ID of the application
252 * @return @c 0 on success,
253 * otherwise a negative error value
255 * @retval #APP_ERROR_NONE Successful
256 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
257 * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
258 * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
260 int app_get_id(char **id);
264 * @brief Gets the localized name of the application.
266 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
267 * @remarks @a name must be released using free().
269 * @param[out] name The name of the application
271 * @return @c 0 on success,
272 * otherwise a negative error value
274 * @retval #APP_ERROR_NONE Successful
275 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
276 * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
277 * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
279 int app_get_name(char **name);
283 * @brief Gets the version of the application package.
285 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
286 * @remarks @a version must be released using free().
288 * @param[out] version The version of the application
290 * @return @c 0 on success,
291 * otherwise a negative error value
293 * @retval #APP_ERROR_NONE Successful
294 * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
295 * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
296 * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
298 int app_get_version(char **version);
302 * @brief Gets the absolute path to the application's data directory which is used to store private
303 * data of the application.
304 * @details An application can read and write its own files in the application's data directory.
305 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
306 * @remarks The returned path should be released.
308 * @return The absolute path to the application's data directory, @n
309 * otherwise a null pointer if the memory is insufficient
311 char *app_get_data_path(void);
315 * @brief Gets the absolute path to the application's cache directory which is used to store
316 * temporary data of the application.
317 * @details An application can read and write its own files in the application's cache directory.
318 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
319 * @remarks The returned path should be released. @n
320 * The files stored in the application's cache directory can be removed by Setting
321 * application or platform while the application is running.
323 * @return The absolute path to the application's cache directory, @n
324 * otherwise a null pointer if the memory is insufficient
326 char *app_get_cache_path(void);
330 * @brief Gets the absolute path to the application resource directory. The resource files
331 * are delivered with the application package.
332 * @details An application can only read its own files in the application's resource directory.
333 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
334 * @remarks The returned path should be released.
336 * @return The absolute path to the application's resource directory, @n
337 * otherwise a null pointer if the memory is insufficient
339 char *app_get_resource_path(void);
343 * @deprecated Deprecated since 3.0.
344 * @brief Gets the absolute path to the application's shared data directory which is used to share
345 * data with other applications.
346 * @details An application can read and write its own files in the application's shared data
347 * directory and others can only read the files.
348 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
349 * @remarks The returned path should be released. @n
350 * shared/data directory is not supported since Tizen 3.0.
351 * You MUST NOT use this API when you develop new application.
352 * Actually, we strongly recommend to stop using shared/data path for all your previous applications.
353 * Files in shared/data directory can be read by all other applications.
354 * You cannot control what applications can read the files in shared/data directory.
355 * If you want to share files with other applications, consider passing path via @ref CAPI_APP_CONTROL_MODULE API.
356 * The @ref CAPI_APP_CONTROL_MODULE API supports giving permission to other applications by passing path via app_control. @n
357 * shared/data directory is only available for applications with api-version lower than 3.0 from Tizen 3.0 platform.
358 * The applications with api-version from 3.0 cannot access other applications' shared/data directory.
359 * For example, a Tizen 2.4 application can access another Tizen 2.4 application's shared/data directory as it did in Tizen 2.4 platform.
360 * However, a Tizen 3.0 application cannot access another application's shared/data directory even the another application is Tizen 2.4 application.
361 * Note that Tizen 3.0 platform only supports shared/data directory among applications with api-version lower than 3.0 for minimum backward compatibility. @n
362 * The specific error code can be obtained using the get_last_result(). Error codes are described in Exception section.
364 * @return The absolute path to the application's shared data directory, @n
365 * otherwise a null pointer if the memory is insufficient. It will return NULL for 3.0 application, and set to APP_ERROR_NOT_SUPPORTED.
366 * @exception APP_ERROR_NONE Success
367 * @exception APP_ERROR_OUT_OF_MEMORY Out of memory
368 * @exception APP_ERROR_NOT_SUPPORTED Not supported
370 char *app_get_shared_data_path(void);
374 * @brief Gets the absolute path to the application's shared resource directory which is used to
375 * share resources with other applications.
376 * @details An application can read its own files in the application's shared resource directory
377 * and others can only read the files.
378 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
379 * @remarks The returned path should be released.
381 * @return The absolute path to the application's shared resource directory, @n
382 * otherwise a null pointer if the memory is insufficient
384 char *app_get_shared_resource_path(void);
388 * @brief Gets the absolute path to the application's shared trusted directory which is used to share data
389 * with a family of trusted applications.
390 * @details An application can read and write its own files in the application's shared trusted directory
391 * and the family applications signed with the same certificate can read and write the files in the
392 * shared trusted directory.
393 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
394 * @remarks The returned path should be released.
396 * @return The absolute path to the application's shared trusted directory, @n
397 * otherwise a null pointer if the memory is insufficient
399 char *app_get_shared_trusted_path(void);
403 * @brief Gets the absolute path to the application's external data directory which is used to
404 * store data of the application.
405 * @details An application can read and write its own files in the application's external data
407 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
408 * @remarks The returned path should be released. @n
409 * The important files stored in the application's external data directory should be
410 * encrypted because they can be exported via the external sdcard.
411 * @remarks To access the path returned by this function requires the privilege
412 * that is "http://tizen.org/privilege/externalstorage.appdata".
414 * @return The absolute path to the application's external data directory, @n
415 * otherwise a null pointer if the memory is insufficient
417 char *app_get_external_data_path(void);
421 * @brief Gets the absolute path to the application's external cache directory which is used to
422 * store temporary data of the application.
423 * @details An application can read and write its own files in the application's external cache
425 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
426 * @remarks The returned path should be released. @n
427 * The files stored in the application's external cache directory can be removed by
428 * Setting application while the application is running. @n
429 * The important files stored in the application's external cache directory should be
430 * encrypted because they can be exported via the external sdcard.
431 * @remarks To access the path returned by this function requires the privilege
432 * that is "http://tizen.org/privilege/externalstorage.appdata".
434 * @return The absolute path to the application's external cache directory, @n
435 * otherwise a null pointer if the memory is insufficient
437 char *app_get_external_cache_path(void);
441 * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif.
442 * @brief Gets the absolute path to the application's external shared data directory which is
443 * used to share data with other applications.
444 * @details An application can read and write its own files in the application's external shared
445 * data directory and others can only read the files.
446 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
447 * @remarks The specified @a path should be released.
448 * @remarks To access the path returned by this function requires the privilege
449 * that is "http://tizen.org/privilege/externalstorage.appdata".
450 * @remarks The function may not work as intended in certain devices due to some implementation issues.
452 * @return The absolute path to the application's external shared data directory, @n
453 * otherwise a null pointer if the memory is insufficient
455 char *app_get_external_shared_data_path(void);
458 * @brief Gets the absolute path to the application's TEP(Tizen Expansion Package) directory.
459 * The resource files are delivered with the expansion package.
460 * @details An application can only read its own files in the application's TEP(Tizen Expansion Package) directory.
461 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
462 * @remarks The returned path should be released.
464 * @return The absolute path to the application's TEP(Tizen Expansion Package) directory, @n
465 * otherwise a null pointer if the memory is insufficient
467 char *app_get_tep_resource_path(void);
477 #endif /* __TIZEN_APPFW_APP_H__ */