Tizen Native API  6.5

The Application Manager API provides functions to get information about installed or running applications and manage the applications.

Required Header

#include <app_manager.h>

Overview

The Application Manager API provides information about applications. There are several different sorts of queries. Two iterator functions step through a list of applications. One is used in running applications(app_manager_foreach_app_context()), and the other is used in available ("installed") but not necessarily running applications(app_manager_foreach_app_info()). Each will call a callback function, passing the package name of each application found. A query function will respond whether the application represented by a particular package name is running. Other query functions return static information about an application, such as a name, a type, an icon path, or a version. The API provides functions to manage applications also. By using them, it is possible to resume(app_manager_resume_app) applications.

Functions

int app_manager_set_app_context_event_cb (app_manager_app_context_event_cb callback, void *user_data)
 Registers a callback function to be invoked when the applications get launched or terminated.
void app_manager_unset_app_context_event_cb (void)
 Unregisters the callback function.
int app_manager_foreach_app_context (app_manager_app_context_cb callback, void *user_data)
 Retrieves all application contexts of running applications.
int app_manager_foreach_running_app_context (app_manager_app_context_cb callback, void *user_data)
 Retrieves all application contexts of running applications including sub apps.
int app_manager_get_app_context (const char *app_id, app_context_h *app_context)
 Gets the application context for the given ID of the application.
int app_manager_get_app_id (pid_t pid, char **app_id)
 Gets the ID of the application for the given process ID.
int app_manager_is_running (const char *app_id, bool *running)
 Checks whether the application with the given ID of the application is running.
int app_manager_resume_app (app_context_h app_context)
 Resumes the application.
int app_manager_request_terminate_bg_app (app_context_h app_context)
 Terminates the back ground application.
UI applications that are in paused state or some service applications could be required to terminate by this function.
int app_manager_foreach_app_info (app_manager_app_info_cb callback, void *user_data)
 Retrieves all installed applications information.
int app_manager_get_app_info (const char *app_id, app_info_h *app_info)
 Gets the application information for the given application ID.
int app_manager_get_shared_data_path (const char *app_id, char **path)
 Gets the absolute path to the shared data directory of the application specified with an application ID.
int app_manager_get_shared_resource_path (const char *app_id, char **path)
 Gets the absolute path to the shared resource directory of the application specified with an application ID.
int app_manager_get_shared_trusted_path (const char *app_id, char **path)
 Gets the absolute path to the shared trusted directory of the application specified with an application ID.
int app_manager_get_external_shared_data_path (const char *app_id, char **path) TIZEN_DEPRECATED_API
 Gets the absolute path to the shared data directory of the application specified with an application ID.
int app_manager_event_create (app_manager_event_h *handle)
 Creates a app manager event handle.
int app_manager_event_set_status (app_manager_event_h handle, int status_type)
 Sets the event to handle to listen. You can combine multiple status using OR operation which you want to listen.
int app_manager_set_event_cb (app_manager_event_h handle, app_manager_event_cb callback, void *user_data)
 Registers a callback function to be invoked when the app is event has occurred.
int app_manager_unset_event_cb (app_manager_event_h handle)
 Unregisters the callback function.
int app_manager_event_destroy (app_manager_event_h handle)
 Destroys the app manager event handle.
int app_manager_set_app_icon (const char *app_id, const char *icon_path)
 Sets the application's icon path into given path.

Typedefs

typedef struct
app_manager_event_s * 
app_manager_event_h
 App manager event handle.
typedef void(* app_manager_event_cb )(const char *type, const char *app_id, app_manager_event_type_e event_type, app_manager_event_state_e event_state, app_manager_event_h handle, void *user_data)
 Called when the application is enabled or disabled.
typedef void(* app_manager_app_context_event_cb )(app_context_h app_context, app_context_event_e event, void *user_data)
 Called when an application is launched or terminated.
typedef bool(* app_manager_app_context_cb )(app_context_h app_context, void *user_data)
 Called to get the application context once for each running application.
typedef bool(* app_manager_app_info_cb )(app_info_h app_info, void *user_data)
 Called to get the application information once for each installed application.

Typedef Documentation

typedef bool(* app_manager_app_context_cb)(app_context_h app_context, void *user_data)

Called to get the application context once for each running application.

Since :
2.3
Parameters:
[in]app_contextThe application context of each running application
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
otherwise false to break out of the loop
Precondition:
app_manager_foreach_app_context() will invoke this callback.
See also:
app_manager_foreach_app_context()
typedef void(* app_manager_app_context_event_cb)(app_context_h app_context, app_context_event_e event, void *user_data)

Called when an application is launched or terminated.

Since :
2.4
Remarks:
Please don't try to free the handle of app_context, because it is managed by the framework.
Parameters:
[in]app_contextThe application context of the application launched or terminated
[in]eventThe application context event
[in]user_dataThe user data passed from the foreach function
Precondition:
This function is called when an application gets launched or terminated, after you register this callback using app_manager_set_app_context_event_cb().
See also:
app_manager_set_app_context_event_cb()
app_manager_unset_app_context_event_cb()
typedef bool(* app_manager_app_info_cb)(app_info_h app_info, void *user_data)

Called to get the application information once for each installed application.

Since :
2.3
Parameters:
[in]app_infoThe application information of each installed application
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
otherwise false to break out of the loop
Precondition:
app_manager_foreach_app_info() will invoke this callback.
See also:
app_manager_foreach_app_info()
typedef void(* app_manager_event_cb)(const char *type, const char *app_id, app_manager_event_type_e event_type, app_manager_event_state_e event_state, app_manager_event_h handle, void *user_data)

Called when the application is enabled or disabled.

Since :
3.0
Parameters:
[in]typeThe type of the app to be enabled or disabled
[in]app_idThe app id to be enabled or disabled
[in]event_typeThe event type of the app
[in]event_stateThe current event state of the app
[in]handleThe app manager event handle
[in]user_dataThe user data passed from app_manager_set_event_cb()
Precondition:
This function is called when an application being disabled or enabled, after you register this callback using app_manager_set_event_cb().
See also:
app_manager_set_event_cb()
app_manager_unset_event_cb()
typedef struct app_manager_event_s* app_manager_event_h

App manager event handle.

Since :
3.0

Enumeration Type Documentation

Enumerations for Application Manager Error.

Since :
2.3
Enumerator:
APP_MANAGER_ERROR_NONE 

Successful

APP_MANAGER_ERROR_INVALID_PARAMETER 

Invalid parameter

APP_MANAGER_ERROR_OUT_OF_MEMORY 

Out of memory

APP_MANAGER_ERROR_IO_ERROR 

Internal I/O error

APP_MANAGER_ERROR_NO_SUCH_APP 

No such application

APP_MANAGER_ERROR_DB_FAILED 

Database error

APP_MANAGER_ERROR_INVALID_PACKAGE 

Invalid package name

APP_MANAGER_ERROR_APP_NO_RUNNING 

App is not running

APP_MANAGER_ERROR_REQUEST_FAILED 

Internal aul request error

APP_MANAGER_ERROR_PERMISSION_DENIED 

Permission denied

APP_MANAGER_ERROR_NOT_SUPPORTED 

Not supported (Since 3.0)

Enumeration for app manager event state.

Since :
3.0
Enumerator:
APP_MANAGER_EVENT_STATE_STARTED 

Started event state

APP_MANAGER_EVENT_STATE_COMPLETED 

Completed event state

APP_MANAGER_EVENT_STATE_FAILED 

Failed event state

Enumeration for app manager status type.

Since :
3.0
Enumerator:
APP_MANAGER_EVENT_STATUS_TYPE_ALL 

All Status

APP_MANAGER_EVENT_STATUS_TYPE_ENABLE 

Application enable status

APP_MANAGER_EVENT_STATUS_TYPE_DISABLE 

Application disable status

Enumeration for app manager event type.

Since :
3.0
Enumerator:
APP_MANAGER_EVENT_ENABLE_APP 

Application enable event

APP_MANAGER_EVENT_DISABLE_APP 

Application disable event.


Function Documentation

Creates a app manager event handle.

Since :
3.0
Remarks:
You must release handle using app_manager_event_destroy().
Parameters:
[out]handleThe app manager event handle that is newly created on success
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_manager_event_destroy()

Destroys the app manager event handle.

Since :
3.0
Parameters:
[in]handleThe app manager event handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_REQUEST_FAILEDInternal error
See also:
app_manager_event_create()
int app_manager_event_set_status ( app_manager_event_h  handle,
int  status_type 
)

Sets the event to handle to listen. You can combine multiple status using OR operation which you want to listen.

Since :
3.0
Parameters:
[in]handleThe app manager event handle
[in]status_typeThe status of the application
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_REQUEST_FAILEDInternal error
See also:
app_manager_event_status_type_e
app_manager_set_event_cb()
int app_manager_foreach_app_context ( app_manager_app_context_cb  callback,
void *  user_data 
)

Retrieves all application contexts of running applications.

Since :
2.3
Remarks:
In case of ui applications, sub apps in application groups will not be shown.
Parameters:
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_IO_ERRORInternal I/O error
Postcondition:
This function invokes app_manager_app_context_cb() for each application context.
See also:
app_manager_app_context_cb()
int app_manager_foreach_app_info ( app_manager_app_info_cb  callback,
void *  user_data 
)

Retrieves all installed applications information.

Since :
2.3
Parameters:
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
Postcondition:
This function invokes app_manager_app_info_cb() for each application information.
See also:
app_manager_app_info_cb()
int app_manager_foreach_running_app_context ( app_manager_app_context_cb  callback,
void *  user_data 
)

Retrieves all application contexts of running applications including sub apps.

You can iterate all the running application contexts using this function. This function is similar to app_manager_foreach_app_context() except that this function iterates application contexts including sub apps in application groups.

Since :
3.0
Parameters:
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_IO_ERRORInternal I/O error
Postcondition:
This function invokes app_manager_app_context_cb() for each application context.
See also:
app_manager_app_context_cb()
int app_manager_get_app_context ( const char *  app_id,
app_context_h app_context 
)

Gets the application context for the given ID of the application.

Since :
2.3
Remarks:
This function returns APP_MANAGER_ERROR_NO_SUCH_APP if the application with the given application ID is not running.
You must release app_context using app_context_destroy().
Parameters:
[in]app_idThe ID of the application
[out]app_contextThe application context of the given application ID
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
APP_MANAGER_ERROR_NO_SUCH_APPNo such application
int app_manager_get_app_id ( pid_t  pid,
char **  app_id 
)

Gets the ID of the application for the given process ID.

Since :
2.3
Remarks:
This function returns APP_MANAGER_ERROR_NO_SUCH_APP if the application with the given process ID is not valid.
You must release app_id using free().
Parameters:
[in]pidThe process ID of the application
[out]app_idThe ID of the application
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
int app_manager_get_app_info ( const char *  app_id,
app_info_h app_info 
)

Gets the application information for the given application ID.

Since :
2.3
Remarks:
You must release app_info using app_info_destroy().
Parameters:
[in]app_idThe ID of the application
[out]app_infoThe application information for the given application ID
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
APP_MANAGER_ERROR_NO_SUCH_APPNo such application
int app_manager_get_external_shared_data_path ( const char *  app_id,
char **  path 
)

Gets the absolute path to the shared data directory of the application specified with an application ID.

Deprecated:
Deprecated since 2.4.

An application can only read the files of other application's shared data directory.

Since :
2.3
Remarks:
The specified path should be released with free().
To access the path returned by this function may not work as intended in certain devices due to some implementation issues.
Parameters:
[in]app_idThe ID of the application
[in,out]pathThe absolute path to the shared data directory of the application specified with the app_id
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_NO_SUCH_APPNo such application
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
int app_manager_get_shared_data_path ( const char *  app_id,
char **  path 
)

Gets the absolute path to the shared data directory of the application specified with an application ID.

An application can only read the files of other application's shared data directory.

Since :
2.3
Remarks:
The specified path should be released with free().
Since Tizen 3.0, the shared/data directory is supported only for the applications that declare the http://tizen.org/privilege/appdir.shareddata privilege. The function will fail with APP_MANAGER_ERROR_NOT_SUPPORTED if the privilege is not declared.
Parameters:
[in]app_idThe ID of the application
[out]pathThe absolute path to the shared data directory of the application specified with the app_id
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_NOT_SUPPORTEDNot supported
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_NO_SUCH_APPNo such application
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
int app_manager_get_shared_resource_path ( const char *  app_id,
char **  path 
)

Gets the absolute path to the shared resource directory of the application specified with an application ID.

An application can only read the files of other application's shared resource directory.

Since :
2.3
Remarks:
The specified path should be released with free().
Parameters:
[in]app_idThe ID of the application
[in,out]pathThe absolute path to the shared resource directory of the application specified with the app_id
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_NO_SUCH_APPNo such application
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
int app_manager_get_shared_trusted_path ( const char *  app_id,
char **  path 
)

Gets the absolute path to the shared trusted directory of the application specified with an application ID.

An application signed with the same certificate can read and write the files of other application's shared trusted directory.

Since :
2.3
Remarks:
The specified path should be released with free().
Parameters:
[in]app_idThe ID of the application
[in,out]pathThe absolute path to the shared trusted directory of the application specified with the app_id
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_NO_SUCH_APPNo such application
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
int app_manager_is_running ( const char *  app_id,
bool *  running 
)

Checks whether the application with the given ID of the application is running.

Since :
2.3
Parameters:
[in]app_idThe ID of the application
[out]runningtrue if the application is running,
otherwise false if not running
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter

Terminates the back ground application.
UI applications that are in paused state or some service applications could be required to terminate by this function.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/appmanager.kill.bgapp
Remarks:
This function returns after it just sends a request for terminating a background application.
Platform will decide if the target application could be terminated or not according to the state of the target application.
Parameters:
[in]app_contextThe application context
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_PERMISSION_DENIEDPermission denied
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_REQUEST_FAILEDFailed to send terminate request
int app_manager_resume_app ( app_context_h  app_context)

Resumes the application.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/appmanager.launch
Parameters:
[in]app_contextThe application context
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_PERMISSION_DENIEDPermission denied
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_APP_NO_RUNNINGApp is not running
APP_MANAGER_ERROR_REQUEST_FAILEDInternal resume error

Registers a callback function to be invoked when the applications get launched or terminated.

Since :
2.4
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
APP_MANAGER_ERROR_IO_ERRORInternal I/O error
Postcondition:
It will invoke app_manager_app_context_event_cb() when the application is launched or terminated.
See also:
app_manager_unset_app_context_event_cb()
app_manager_app_context_event_cb()
int app_manager_set_app_icon ( const char *  app_id,
const char *  icon_path 
)

Sets the application's icon path into given path.

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/packagemanager.admin
Remarks:
The icon file should be included in package which the applications belongs to.
Parameters:
[in]app_idThe ID of the application
[in]icon_pathThe path of icon file
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_PERMISSION_DENIEDPermission denied
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_OUT_OF_MEMORYOut of memory
APP_MANAGER_ERROR_IO_ERRORInternal error
See also:
app_manager_event_create()
int app_manager_set_event_cb ( app_manager_event_h  handle,
app_manager_event_cb  callback,
void *  user_data 
)

Registers a callback function to be invoked when the app is event has occurred.

Since :
3.0
Parameters:
[in]handleThe app manager event handle
[in]callbackThe callback function to be registered
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_REQUEST_FAILEDInternal error
Postcondition:
app_manager_event_cb() will be invoked.
See also:
app_manager_event_set_status()
app_manager_event_cb()
app_manager_unset_event_cb()

Unregisters the callback function.

Since :
2.4
See also:
app_manager_app_context_event_cb()

Unregisters the callback function.

Since :
3.0
Parameters:
[in]handleThe app manager event handle
Returns:
0 on success, otherwise a negative error value
Return values:
APP_MANAGER_ERROR_NONESuccessful
APP_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
APP_MANAGER_ERROR_REQUEST_FAILEDInternal error
See also:
app_manager_event_cb()
app_manager_set_event_cb()