Tizen Native API

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.

capi_appfw_application_package.png
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_infoThe system event information
[in]user_dataThe 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

Enumeration Type Documentation

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

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%

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

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

Gets the device orientation from given event info.

Since :
2.3.1
Parameters:
[in]event_infoThe system event info
[out]orientationThe device orientation changed
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTInvalid 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_infoThe system event info
[out]langThe language changed
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTInvalid event context
See also:
app_event_info_h

Gets the low battery status from given event info.

Since :
2.3.1
Parameters:
[in]event_infoThe system event info
[out]statusThe low battery status
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTInvalid event context
See also:
app_event_info_h
app_event_low_battery_status_e

Gets the low memory status from given event info.

Since :
2.3.1
Parameters:
[in]event_infoThe system event info
[out]statusThe low memory status
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTInvalid 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_infoThe system event info
[out]regionThe region format changed
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTInvalid 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

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]idThe ID of the application
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTThe application is illegally launched, not launched by the launch system
APP_ERROR_OUT_OF_MEMORYOut 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]nameThe name of the application
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTThe application is illegally launched, not launched by the launch system
APP_ERROR_OUT_OF_MEMORYOut 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]versionThe version of the application
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTThe application is illegally launched, not launched by the launch system
APP_ERROR_OUT_OF_MEMORYOut of memory