The App Common API provides functions for getting information about the application.

Required Header

#include <app_common.h>

Overview

The App common API provides common APIs that can be used at UI application and Service application. This API provides interfaces for getting information about the application.

Application Package

The Tizen native application consists of structured directories to manage the application executable file, library files, resource files, and data. When you build the application, the Tizen SDK packages those as an application package for distribution.

Application package

Directories	Description
<package id>	The fully qualified name of an application (such as org.tizen.calculator).
bin	The executable file of the application.
lib	The application library files
res	The root directory in which all resource files are located. The application cannot write and modify any resource files
data	The root directory in which an application's private data is located. The application can read and write its own data files in the application's data directory.
shared/	The shared directory for sharing with other applications.

Getting Information About the Application

The API provides functions for obtaining an application's package name and absolute path to specified resources like Image, Sound, Video, UI layout (EDJ), and so on. It also provides functions to:

Get the current orientation of the device
Get the Internal/External root folders which are shared among all applications

Functions
int	app_event_get_low_memory_status (app_event_info_h event_info, app_event_low_memory_status_e *status)
	Gets the low memory status from the given event info.
int	app_event_get_low_battery_status (app_event_info_h event_info, app_event_low_battery_status_e *status)
	Gets the low battery status from given event info.
int	app_event_get_language (app_event_info_h event_info, char **lang)
	Gets the language from the given event info.
int	app_event_get_region_format (app_event_info_h event_info, char **region)
	Gets the region format from the given event info.
int	app_event_get_device_orientation (app_event_info_h event_info, app_device_orientation_e *orientation)
	Gets the device orientation from the given event info.
int	app_event_get_suspended_state (app_event_info_h event_info, app_suspended_state_e *state)
	Gets the suspended state of the application from the given event info.
int	app_get_id (char **id)
	Gets the ID of the application.
int	app_get_name (char **name)
	Gets the localized name of the application.
int	app_get_version (char **version)
	Gets the version of the application package.
char *	app_get_data_path (void)
	Gets the absolute path to the application's data directory which is used to store private data of the application.
char *	app_get_cache_path (void)
	Gets the absolute path to the application's cache directory which is used to store temporary data of the application.
char *	app_get_resource_path (void)
	Gets the absolute path to the application resource directory. The resource files are delivered with the application package.
char *	app_get_shared_data_path (void)
	Gets the absolute path to the application's shared data directory which is used to share data with other applications.
char *	app_get_shared_resource_path (void)
	Gets the absolute path to the application's shared resource directory which is used to share resources with other applications.
char *	app_get_shared_trusted_path (void)
	Gets the absolute path to the application's shared trusted directory which is used to share data with a family of trusted applications.
char *	app_get_external_data_path (void)
	Gets the absolute path to the application's external data directory which is used to store data of the application.
char *	app_get_external_cache_path (void)
	Gets the absolute path to the application's external cache directory which is used to store temporary data of the application.
char *	app_get_external_shared_data_path (void) TIZEN_DEPRECATED_API
	Gets the absolute path to the application's external shared data directory which is used to share data with other applications.
char *	app_get_tep_resource_path (void)
	Gets the absolute path to the application's TEP (Tizen Expansion Package) directory. The resource files are delivered with the expansion package.
int	app_get_display_state (app_display_state_e *display_state)
	Gets the display state.
int	app_watchdog_timer_enable (void)
	Sends the enable request to activate the watchdog timer.
int	app_watchdog_timer_disable (void)
	Sends the disable request to deactivate the watchdog timer.
int	app_watchdog_timer_kick (void)
	Sends the kick request to reset the watchdog timer.
Typedefs
typedef struct app_event_handler *	app_event_handler_h
	The event handler that returned from add event handler function to handle.
typedef struct app_event_info *	app_event_info_h
	The system event information handle.
typedef void(*	app_event_cb )(app_event_info_h event_info, void *user_data)
	The system event callback function.

Typedef Documentation

typedef void(* app_event_cb)(app_event_info_h event_info, void *user_data)

The system event callback function.

Since :: 2.3

Remarks:: If the given event_info has APP_SUSPENDED_STATE_WILL_ENTER value, the application should not call any asynchronous operations in this callback. After the callback returns, process of the application will be changed to suspended state immediately. Thus, asynchronous operations may work incorrectly. (since 2.4)

Parameters:

[in]	event_info	The system event information
[in]	user_data	The user data passed from the add event handler function

See also:: ui_app_add_event_handler; app_event_info_h

typedef struct app_event_handler* app_event_handler_h

The event handler that returned from add event handler function to handle.

Since :: 2.3

See also:: app_event_type_e; ui_app_add_event_handler; ui_app_remove_event_handler; app_event_info_h

typedef struct app_event_info* app_event_info_h

The system event information handle.

Since :: 2.3

See also:: app_event_get_low_memory_status(); app_event_get_low_battery_status(); app_event_get_language(); app_event_get_region_format(); app_event_get_device_orientation(); app_event_get_suspended_state()

Enumeration Type Documentation

enum app_device_orientation_e

Enumeration for device orientation.

Since :: 2.3

Enumerator:

APP_DEVICE_ORIENTATION_0	The device is oriented in a natural position
APP_DEVICE_ORIENTATION_90	The device's left side is at the top
APP_DEVICE_ORIENTATION_180	The device is upside down
APP_DEVICE_ORIENTATION_270	The device's right side is at the top

enum app_display_state_e

Enumeration for display state.

Since :: 5.5

Enumerator:

APP_DISPLAY_STATE_ON	Display state is on
APP_DISPLAY_STATE_OFF	Display state is off

enum app_event_low_battery_status_e

Enumeration for battery status.

Since :: 2.3

Enumerator:

APP_EVENT_LOW_BATTERY_POWER_OFF	The battery status is under 1%
APP_EVENT_LOW_BATTERY_CRITICAL_LOW	The battery status is under 5%

enum app_event_low_memory_status_e

Enumeration for low memory status.

Since :: 2.3

Enumerator:

APP_EVENT_LOW_MEMORY_NORMAL	Normal status
APP_EVENT_LOW_MEMORY_SOFT_WARNING	Soft warning status
APP_EVENT_LOW_MEMORY_HARD_WARNING	Hard warning status

enum app_event_type_e

Enumeration for system events.

Since :: 2.3

Enumerator:

APP_EVENT_LOW_MEMORY	The low memory event
APP_EVENT_LOW_BATTERY	The low battery event
APP_EVENT_LANGUAGE_CHANGED	The system language changed event
APP_EVENT_DEVICE_ORIENTATION_CHANGED	The device orientation changed event
APP_EVENT_REGION_FORMAT_CHANGED	The region format changed event
APP_EVENT_SUSPENDED_STATE_CHANGED	The suspended state changed event of the application (since 2.4) See also: app_event_get_suspended_state()
APP_EVENT_UPDATE_REQUESTED	The update requested event (Since 3.0) This event can occur when an app needs to be updated. It is dependent on target devices.

enum app_suspended_state_e

Enumeration for suspended state.

Since :: 2.4

Enumerator:

APP_SUSPENDED_STATE_WILL_ENTER	Application will enter the suspended state
APP_SUSPENDED_STATE_DID_EXIT	Application did exit from the suspended state

Function Documentation

int app_event_get_device_orientation	(	app_event_info_h	event_info,
		app_device_orientation_e *	orientation
	)

Gets the device orientation from the given event info.

Since :: 2.3

Parameters:

[in]	event_info	The system event info
[out]	orientation	The device orientation changed

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	Invalid event context

See also:: app_event_info_h; app_device_orientation_e

int app_event_get_language	(	app_event_info_h	event_info,
		char **	lang
	)

Gets the language from the given event info.

Since :: 2.3

Remarks:: lang must be released using free().

Parameters:

[in]	event_info	The system event info
[out]	lang	The language changed

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	Invalid event context

See also:: app_event_info_h

int app_event_get_low_battery_status	(	app_event_info_h	event_info,
		app_event_low_battery_status_e *	status
	)

Gets the low battery status from given event info.

Since :: 2.3

Parameters:

[in]	event_info	The system event info
[out]	status	The low battery status

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	Invalid event context

See also:: app_event_info_h; app_event_low_battery_status_e

int app_event_get_low_memory_status	(	app_event_info_h	event_info,
		app_event_low_memory_status_e *	status
	)

Gets the low memory status from the given event info.

Since :: 2.3

Parameters:

[in]	event_info	The system event info
[out]	status	The low memory status

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	Invalid event context

See also:: app_event_info_h; app_event_low_memory_status_e

int app_event_get_region_format	(	app_event_info_h	event_info,
		char **	region
	)

Gets the region format from the given event info.

Since :: 2.3

Remarks:: region must be released using free().

Parameters:

[in]	event_info	The system event info
[out]	region	The region format changed

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	Invalid event context

See also:: app_event_info_h

int app_event_get_suspended_state	(	app_event_info_h	event_info,
		app_suspended_state_e *	state
	)

Gets the suspended state of the application from the given event info.

Since :: 2.4

Remarks:: The application should not use any asynchronous operations in APP_SUSPENDED_STATE_WILL_ENTER event. Because applications will be changed to suspended state just after APP_SUSPENDED_STATE_WILL_ENTER, asynchronous calls are not guaranteed to work properly.

Parameters:

[in]	event_info	The handle for getting the suspended state
[out]	state	The suspended state of the application

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	Invalid event context

char* app_get_cache_path ( void )

Gets the absolute path to the application's cache directory which is used to store temporary data of the application.

An application can read and write its own files in the application's cache directory.

Since :: 2.3

Remarks:: The returned value should be released using free().
The files stored in the application's cache directory can be removed by setting application or platform while the application is running.

Returns:: The absolute path to the application's cache directory,
otherwise a null pointer if the memory is insufficient

char* app_get_data_path ( void )

Gets the absolute path to the application's data directory which is used to store private data of the application.

An application can read and write its own files in the application's data directory.

Since :: 2.3

Remarks:: The returned value should be released using free().

Returns:: The absolute path to the application's data directory,
otherwise a null pointer if the memory is insufficient

int app_get_display_state ( app_display_state_e * display_state )

Gets the display state.

Since :: 5.5

Remarks:: If the application is service-application, this function returns APP_ERROR_INVALID_CONTEXT. In the headless device, this function returns APP_ERROR_NOT_SUPPORTED.

Parameters:

[out] display_state The display state

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_NOT_SUPPORTED	Not supported
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	The display is in an unknown state.

char* app_get_external_cache_path ( void )

Gets the absolute path to the application's external cache directory which is used to store temporary data of the application.

An application can read and write its own files in the application's external cache directory.

Since :: 2.3

Remarks:: The returned value should be released using free().
The files stored in the application's external cache directory can be removed by setting application while the application is running.
The important files stored in the application's external cache directory should be encrypted because they can be exported via the external sdcard. To access the path returned by this function requires the privilege that is "http://tizen.org/privilege/externalstorage.appdata".

Returns:: The absolute path to the application's external cache directory,
otherwise a null pointer if the memory is insufficient

char* app_get_external_data_path ( void )

Gets the absolute path to the application's external data directory which is used to store data of the application.

An application can read and write its own files in the application's external data directory.

Since :: 2.3

Remarks:: The returned value should be released using free().
The important files stored in the application's external data directory should be encrypted because they can be exported via the external sdcard. To access the path returned by this function requires the privilege that is "http://tizen.org/privilege/externalstorage.appdata".

Returns:: The absolute path to the application's external data directory,
otherwise a null pointer if the memory is insufficient

char* app_get_external_shared_data_path ( void )

Gets the absolute path to the application's external shared data directory which is used to share data with other applications.

Deprecated:: Deprecated since 2.4.

An application can read and write its own files in the application's external shared data directory, and others can only read the files.

Since :: 2.3

Remarks:: The returned value should be released using free(). To access the path returned by this function requires the privilege that is "http://tizen.org/privilege/externalstorage.appdata". The function may not work as intended in certain devices due to some implementation issues.

Returns:: The absolute path to the application's external shared data directory,
otherwise a null pointer if the memory is insufficient

int app_get_id ( char ** id )

Gets the ID of the application.

Since :: 2.3

Remarks:: id must be released using free().

Parameters:

[out] id The ID of the application

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	The application is launched illegally, not launched by the launch system
APP_ERROR_OUT_OF_MEMORY	Out of memory

int app_get_name ( char ** name )

Gets the localized name of the application.

Since :: 2.3

Remarks:: name must be released using free().

Parameters:

[out] name The name of the application

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	The application is launched illegally, not launched by the launch system
APP_ERROR_OUT_OF_MEMORY	Out of memory

char* app_get_resource_path ( void )

Gets the absolute path to the application resource directory. The resource files are delivered with the application package.

An application can only read its own files in the application's resource directory.

Since :: 2.3

Remarks:: The returned value should be released using free().

Returns:: The absolute path to the application's resource directory,
otherwise a null pointer if the memory is insufficient

char* app_get_shared_data_path ( void )

Gets the absolute path to the application's shared data directory which is used to share data with other applications.

An application can read and write its own files in the application's shared data directory and others can only read the files.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/appdir.shareddata

Remarks:: The returned value should be released using free().
Since Tizen 3.0, an application that want to use shared/data directory must declare http://tizen.org/privilege/appdir.shareddata privilege. If the application doesn't declare the privilege, the framework will not create shared/data directory for the application. Carefully consider the privacy implications when deciding whether to use the shared/data directory, since the application cannot control access to this directory by other applications. If you want to share files with other applications, consider passing path via App Control API. The App Control API supports giving permission to other applications by passing path via app_control.
The specific error code can be obtained using the get_last_result(). Error codes are described in Exception section.

Returns:: The absolute path to the application's shared data directory,
otherwise a null pointer if the memory is insufficient. It will return NULL for applications with api-version 3.0 or later, and set APP_ERROR_PERMISSION_DENIED if the application does not declare the shareddata privilege.

Exceptions:

APP_ERROR_NONE	Success
APP_ERROR_PERMISSION_DENIED	Permission denied
APP_ERROR_OUT_OF_MEMORY	Out of memory

char* app_get_shared_resource_path ( void )

Gets the absolute path to the application's shared resource directory which is used to share resources with other applications.

An application can read its own files in the application's shared resource directory, and others can only read the files.

Since :: 2.3

Remarks:: The returned value should be released using free().

Returns:: The absolute path to the application's shared resource directory,
otherwise a null pointer if the memory is insufficient

char* app_get_shared_trusted_path ( void )

Gets the absolute path to the application's shared trusted directory which is used to share data with a family of trusted applications.

An application can read and write its own files in the application's shared trusted directory and the family applications signed with the same certificate can read and write the files in the shared trusted directory.

Since :: 2.3

Remarks:: The returned value should be released using free().

Returns:: The absolute path to the application's shared trusted directory,
otherwise a null pointer if the memory is insufficient

char* app_get_tep_resource_path ( void )

Gets the absolute path to the application's TEP (Tizen Expansion Package) directory. The resource files are delivered with the expansion package.

An application can only read its own files in the application's TEP (Tizen Expansion Package) directory.

Since :: 2.4

Remarks:: The returned value should be released using free().

Returns:: The absolute path to the application's TEP (Tizen Expansion Package) directory,
otherwise a null pointer if the memory is insufficient

int app_get_version ( char ** version )

Gets the version of the application package.

Since :: 2.3

Remarks:: version must be released using free().

Parameters:

[out] version The version of the application

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_PARAMETER	Invalid parameter
APP_ERROR_INVALID_CONTEXT	The application is launched illegally, not launched by the launch system
APP_ERROR_OUT_OF_MEMORY	Out of memory

int app_watchdog_timer_disable ( void )

Sends the disable request to deactivate the watchdog timer.

Since :: 5.5

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_CONTEXT	Invalid context

See also:: app_watchdog_timer_enable()

int app_watchdog_timer_enable ( void )

Sends the enable request to activate the watchdog timer.

Since :: 5.5

Remarks:: After this function is called, the system detects a timeout error. If, due to a program error as ANR (Application Not Responding), the system fails to reset the watchdog, the timer will elapse and generate a signal to terminate the running application. If the running application has to process a lot of operations, the application should disable or reset the watchdog timer.

Returns:: 0 on success, otherrwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_CONTEXT	Invalid context

See also:: app_watchdog_timer_disable(); app_watchdog_timer_kick()

int app_watchdog_timer_kick ( void )

Sends the kick request to reset the watchdog timer.

Since :: 5.5

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_ERROR_NONE	Successful
APP_ERROR_INVALID_CONTEXT	Invalid context

See also:: app_watchdog_timer_enable()

Required Header

Overview

Application Package

Getting Information About the Application

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation