The App Common API provides functions to 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 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 given event info.
int	app_event_get_region_format (app_event_info_h event_info, char **region)
	Gets the region format from 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 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)
	Gets the absolute path to the application's external shared data directory which is used to share data with other applications.
Typedefs
typedef struct app_event_handler *	app_event_handler_h
	The event handler that returned from add event handler function.
typedef struct app_event_info *	app_event_info_h
	The system event information.
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.1

Parameters:

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

See also:: 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.

Since :: 2.3.1

See also:: app_event_type_e; app_add_event_handler; app_remove_event_handler; app_event_info_h

typedef struct app_event_info* app_event_info_h

The system event information.

Since :: 2.3.1

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

Enumeration Type Documentation

enum app_device_orientation_e

Enumeration for device orientation.

Since :: 2.3.1

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_event_low_battery_status_e

Enumeration for battery status.

Since :: 2.3.1

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.1

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.1

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

Function Documentation

int app_event_get_device_orientation	(	app_event_info_h	event_info,
		app_device_orientation_e *	orientation
	)

Gets the device orientation from given event info.

Since :: 2.3.1

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 given event info.

Since :: 2.3.1

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.1

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 given event info.

Since :: 2.3.1

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 given event info.

Since :: 2.3.1

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

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.1

Remarks:: The returned path should be released.
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.1

Remarks:: The returned path should be released.

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

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.1

Remarks:: The returned path should be released.
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.

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.1

Remarks:: The returned path should be released.
The important files stored in the application's external data directory should be encrypted because they can be exported via the external sdcard.

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.

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.1

Remarks:: The specified path should be released.

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.1

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 illegally launched, 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.1

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 illegally launched, 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.1

Remarks:: The returned path should be released.

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.1

Remarks:: The returned path should be released.

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

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.1

Remarks:: The returned path should be released.

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.1

Remarks:: The returned path should be released.

Returns:: The absolute path to the application's shared trusted 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.1

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 illegally launched, not launched by the launch system
APP_ERROR_OUT_OF_MEMORY	Out of memory

Required Header

Overview

Application Package

Getting Information About the Application

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation