Application API

This API provides a way to launch other applications and access application management.

The ApplicationManager interface also provides methods to launch other applications explicitly and implicitly through the ApplicationControl interface. The ApplicationControl interface consists of an operation, URI, and MIME type and also describes an action to be performed by other applications and can carry the result from the subsequent application. The ApplicationManager interface also provides methods to handle the application lifecycle, to access the installed applications on the device, and to let an application be notified of a change in the application list.

The Application interface defines the current application's information and the basic operations for the current application such as exit or hide.

The Application interface provides application event broadcasting and listening features. An application can broadcast user events to other listening applications and listen to broadcasted user events from other applications and from system.

For more information on the Application features, see Application Guide, Application Group Guide or Application Control Guide.

Since: 1.0

Table of Contents


Summary of Interfaces and Methods

Interface Method
ApplicationManagerObject
ApplicationManager
void kill (ApplicationContextId contextId, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void launch (ApplicationId id, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void launchAppControl (ApplicationControl appControl, optional ApplicationId? id, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional ApplicationControlDataArrayReplyCallback? replyCallback)
void findAppControl (ApplicationControl appControl, FindAppControlSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void getAppsContext (ApplicationContextArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
void getAppsInfo (ApplicationInformationArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
DOMString getAppSharedURI (optional ApplicationId? id)
void getBatteryUsageInfo (BatteryUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional long? days, optional long? limit)
void getAppsUsageInfo (AppsUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional ApplicationUsageMode? mode, optional ApplicationUsageFilter? filter, optional long? limit)
long addAppStatusChangeListener (StatusEventCallback eventCallback, optional ApplicationId? appId)
void removeAppStatusChangeListener (long watchId)
ApplicationUsageFilter
Application
void exit ()
void hide ()
void removeEventListener (long watchId)
ApplicationInformation
ApplicationContext
ApplicationBatteryUsage
ApplicationUsage
ApplicationControlData
ApplicationControl
RequestedApplicationControl
void replyResult (optional ApplicationControlData[]? data)
void replyFailure ()
ApplicationCertificate
ApplicationMetaData
BatteryUsageInfoArraySuccessCallback
void onsuccess (ApplicationBatteryUsage[] batteryInfoArray)
AppsUsageInfoArraySuccessCallback
void onsuccess (ApplicationUsage[] appsInfoArray)
ApplicationInformationArraySuccessCallback
void onsuccess (ApplicationInformation[] informationArray)
FindAppControlSuccessCallback
void onsuccess (ApplicationInformation[] informationArray, ApplicationControl appControl)
ApplicationContextArraySuccessCallback
void onsuccess (ApplicationContext[] contexts)
ApplicationControlDataArrayReplyCallback
void onsuccess (optional ApplicationControlData[]? data)
void onfailure ()
SystemEventData
EventCallback
void onevent (EventInfo event, EventData data)
StatusEventCallback
void onchange (ApplicationId appId, boolean isActive)
EventInfo

1. Type Definitions

1.1. ApplicationId

The unique ID for an installed application.
  typedef DOMString ApplicationId;

Since: 1.0

1.2. ApplicationContextId

The unique ID for a running application.
  typedef DOMString ApplicationContextId;

Since: 1.0

1.3. UserEventData

Specifies the user event data.
  typedef object UserEventData;

Since: 3.0

1.4. EventData

Specifies the user or system defined event data.
  typedef (SystemEventData or UserEventData) EventData;

Since: 3.0

1.5. ApplicationControlLaunchMode

Specifies the application launch mode when it is launched by launchAppControl(). This value may be overriden if application launched by launchAppControl() has value SINGLE configured in application manifest.
  enum ApplicationControlLaunchMode { "SINGLE", "GROUP" };

Since: 3.0

The launch modes defined by this enumerator are:

  • SINGLE - Launch application as standalone instance.
  • GROUP - Launch application in subgroup.

1.6. ApplicationUsageMode

Specifies the possible modes of getting statistics of application usage.
  enum ApplicationUsageMode { "RECENTLY", "FREQUENTLY" };

Since: 4.0

Possible types are:

  • RECENTLY - Indicates most recently used applications, in a descending order of the application use counts.
  • FREQUENTLY - Indicates most frequently used applications, in a descending order of the application use counts.

2. Interfaces

2.1. ApplicationManagerObject

This interface defines what is instantiated by the Tizen object on the Tizen Platform.
  [NoInterfaceObject] interface ApplicationManagerObject {
    readonly attribute ApplicationManager application;
  };
  Tizen implements ApplicationManagerObject;

Since: 2.0

The tizen.application object allows access to the Application API's functionality.

Attributes

  • readonly ApplicationManager application
    Object representing a account manager.

    Since: 2.0

2.2. ApplicationManager

The ApplicationManager interface provides methods to retrieve application information, launch, install application, etc.
  [NoInterfaceObject] interface ApplicationManager {
    Application getCurrentApplication() raises(WebAPIException);
    void kill(ApplicationContextId contextId, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
              raises(WebAPIException);
    void launch(ApplicationId id, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
                raises(WebAPIException);
    void launchAppControl(ApplicationControl appControl, optional ApplicationId? id, optional SuccessCallback? successCallback,
                          optional ErrorCallback? errorCallback, optional ApplicationControlDataArrayReplyCallback? replyCallback)
                          raises(WebAPIException);
    void findAppControl(ApplicationControl appControl, FindAppControlSuccessCallback successCallback,
                        optional ErrorCallback? errorCallback) raises(WebAPIException);
    void getAppsContext(ApplicationContextArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                        raises(WebAPIException);
    ApplicationContext getAppContext(optional ApplicationContextId? contextId) raises(WebAPIException);
    void getAppsInfo(ApplicationInformationArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                     raises(WebAPIException);
    ApplicationInformation getAppInfo(optional ApplicationId? id) raises(WebAPIException);
    ApplicationCertificate[] getAppCerts(optional ApplicationId? id) raises(WebAPIException);
    DOMString getAppSharedURI(optional ApplicationId? id) raises(WebAPIException);
    ApplicationMetaData[] getAppMetaData(optional ApplicationId? id) raises(WebAPIException);
    void getBatteryUsageInfo(BatteryUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                             optional long? days, optional long? limit) raises(WebAPIException);
    void getAppsUsageInfo(AppsUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                          optional ApplicationUsageMode? mode, optional ApplicationUsageFilter? filter, optional long? limit)
                          raises(WebAPIException);
    long addAppStatusChangeListener(StatusEventCallback eventCallback, optional ApplicationId? appId) raises(WebAPIException);
    void removeAppStatusChangeListener(long watchId) raises(WebAPIException);
  };

Since: 2.0

Methods

getCurrentApplication
Gets the Application object defining the current application.
Application getCurrentApplication();

Since: 2.0

Remark: This method is not supported by Web Widget.

Return value:

    Application: The data structure that defines the current application.

Exceptions:

  • WebAPIException
    • with error type UnknownError, if the application cannot be retrieved because of an unknown error.

Code example:

var app = tizen.application.getCurrentApplication();
console.log("Current application's app id is " + app.appInfo.id);
kill
Kills an application with the specified application context ID.
void kill(ApplicationContextId contextId, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 2.0

The ErrorCallback method is launched with these error types:

  • NotFoundError - If the context is not found with the specified context ID.
  • InvalidValuesError - If any of the input parameters contain an invalid value or if the specified context ID matches the context ID of the calling application.
  • UnknownError - If any other error occurs.

Privilege level: partner

Privilege: http://tizen.org/privilege/appmanager.kill

Parameters:

  • contextId: The identifier of the application to kill.
  • successCallback [optional] [nullable]: The method to invoke when an application is killed successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

function onKillSuccess()
{
  console.log("Application terminated successfully");
}

function onRunningAppsContext(contexts)
{
  /* Let's assume that the application "targetApp0.main" has been installed. */
  var targetId = "targetApp0.main";

  for (var i = 0; i < contexts.length; i++)
  {
    if (contexts[i].appId == targetId)
    {
      tizen.application.kill(contexts[i].id, onKillSuccess);
    }
  }
}

tizen.application.getAppsContext(onRunningAppsContext);
launch
Launches an application with the given application ID.
void launch(ApplicationId id, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 2.0

The ErrorCallback method is launched with these error types:

  • NotFoundError - If the application is not found with the specified ID.
  • UnknownError - If any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/application.launch

Remark: Since Tizen 2.4, the launch request of the service application from other package is restricted by the platform.

Parameters:

  • id: A unique string representing the application ID.
  • successCallback [optional] [nullable]: The method to call when the invocation ends successfully.
  • errorCallback [optional] [nullable]: The method to call when an error occurs.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

function onsuccess()
{
  console.log("The application has launched successfully");
}

/* Let's assume that application "targetApp0.main" has been installed. */
tizen.application.launch("targetApp0.main", onsuccess);
launchAppControl
Launches an application with the specified application control.
void launchAppControl(ApplicationControl appControl, optional ApplicationId? id, optional SuccessCallback? successCallback,
                      optional ErrorCallback? errorCallback, optional ApplicationControlDataArrayReplyCallback? replyCallback);

Since: 2.0

An application can launch other applications with the application control, and get back the results from the launched applications.

The application control consists of an operation, URI, and MIME type, and describes the request to be performed by the newly launched application. The application control is passed to the launchAppControl() method to launch an application. The system tries to find the proper application to perform the requested application control, then launches the selected application.

The application control request is passed to the newly launched application and it can be accessed by the getRequestedAppControl() method. The passed application control contains the reason the application has been launched and information about what the application is doing. The launched application can send a result to the caller application with the replyResult() method of the RequestedApplicationControl interface.

The ErrorCallback method is launched with these error types:

  • NotFoundError - If the system cannot find the application that matches the specified application control.
  • SecurityError - If the application does not have the privilege to call the specified application control operation.
  • UnknownError: If any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/application.launch

Remark: Since Tizen 2.4, the launch request of the service application from other package is restricted by the platform. Also, implicit launch requests are NOT delivered to service applications since 2.4. To launch a service application, an explicit launch request with ApplicationId id MUST be sent.

Parameters:

  • appControl: The data structure describing application control details.
  • id [optional] [nullable]: An identifier of the application to be launched. If the ID is null or not specified, then the system tries to find the application to be launched for the requested application control.
  • successCallback [optional] [nullable]: The method to call when the invocation ends successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.
  • replyCallback [optional] [nullable]: The method to invoke when the application gets back results from the launched application.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

var appControl = new tizen.ApplicationControl(
    "http://tizen.org/appcontrol/operation/pick", null, "image/jpeg", null);

var appControlReplyCallback =
{
  /* Callee sent a reply. */
  onsuccess: function(data)
  {
    for (var i = 0; i < data.length; i++)
    {
      if (data[i].key == "http://tizen.org/appcontrol/data/selected")
      {
        console.log("Selected image is " + data[i].value[0]);
      }
    }
  },
  /* Callee returned failure. */
  onfailure: function()
  {
    console.log("The launch application control failed");
  }
};

tizen.application.launchAppControl(appControl, null,
    function()
    {
      console.log("Launch application control succeed");
    },
    function(e)
    {
      console.log("Launch application control failed, reason: " + e.message);
    },
    appControlReplyCallback);
findAppControl
Finds which applications can be launched with the given application control.
void findAppControl(ApplicationControl appControl, FindAppControlSuccessCallback successCallback,
                    optional ErrorCallback? errorCallback);

Since: 2.0

An application can get a list of other applications that can be launched with the application control.

The ErrorCallback method is launched with these error types:

  • NotFoundError - If the application is not found with the given Appcontrol.
  • UnknownError - If any other error occurs.

Parameters:

  • appControl: A data structure describing application control details.
  • successCallback: The method to call that returns a list of application information.
  • errorCallback [optional] [nullable]: The method to call when an error occurs.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example:

var appControl = new tizen.ApplicationControl(
    "http://tizen.org/appcontrol/operation/pick", null, "image/jpeg", null);

function successCB(appInfos, appControl)
{
  /* appControl is same object with the value passed as first parameter to findAppControl(). */
  var appControlReplyCallback =
  {
    /* Callee sent a reply. */
    onsuccess: function(data)
    {
      for (var i = 0; i < data.length; i++)
      {
        if (data[i].key == "http://tizen.org/appcontrol/data/selected")
        {
          console.log("Selected image is " + data[i].value[0]);
        }
      }
    },
    /* Callee returned failure. */
    onfailure: function()
    {
      console.log("The launch application control failed");
    }
  };

  var appId = appInfos[0].id;  /* Select first app's id. */

  tizen.application.launchAppControl(appControl, appId,
      function()
      {
        console.log("Launch application control succeed");
      },
      function(e)
      {
        console.log("Launch application control failed, reason: " + e.message);
      },
      appControlReplyCallback);
}

tizen.application.findAppControl(appControl, successCB);
getAppsContext
Gets a list of application contexts for applications that are currently running on a device. The information contained for each application corresponds to the application state at the time when the list had been generated.
void getAppsContext(ApplicationContextArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.0

The ErrorCallback method is launched with this error type:

  • UnknownError - If an unknown error occurs.

Parameters:

  • successCallback: The method to call when the invocation ends successfully.
  • errorCallback [optional] [nullable]: The method to call when an error occurs.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example:

function onRunningAppsContext(contexts)
{
  for (var i = 0; i < contexts.length; i++)
  {
    console.log("ID: " + contexts[i].id);
  }
}

tizen.application.getAppsContext(onRunningAppsContext);
getAppContext
Gets the application context for the specified application context ID. If the ID is set to null or is not set at all, the method returns the application context of the current application. The list of running applications and their application IDs is obtained with getAppsContext().
ApplicationContext getAppContext(optional ApplicationContextId? contextId);

Since: 2.0

Parameters:

  • contextId [optional] [nullable]: A string representing an application context ID
    If the ID is not provided, the application context of the calling application is returned.

Return value:

    ApplicationContext: A data structure that lists running application details.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if the application context is not found with the specified ID.

    • with error type UnknownError, if the application context cannot be retrieved because of an unknown error.

Code example:

var appContext = tizen.application.getAppContext(null);
console.log("Application context retrieved for app " + appContext.appId);
getAppsInfo
Gets the list of installed applications' information on a device. The information contained on each application corresponds to the application state at the time when the list had been generated.
void getAppsInfo(ApplicationInformationArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.0

The ErrorCallback method is launched with this error type:

  • UnknownError - If an unknown error occurs.

Parameters:

  • successCallback: The method to call when the invocation ends successfully.
  • errorCallback [optional] [nullable]: The method to call when an error occurs.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example:

function onListInstalledApps(applications)
{
  for (var i = 0; i < applications.length; i++)
  {
    console.log("ID: " + applications[i].id);
  }
}

tizen.application.getAppsInfo(onListInstalledApps);
getAppInfo
Gets application information for a specified application ID.
ApplicationInformation getAppInfo(optional ApplicationId? id);

Since: 2.0

If the ID is set to null or not set at all, it returns application information for the current application. The list of installed applications and their application IDs is obtained with getAppsInfo().

Parameters:

  • id [optional] [nullable]: A string representing an application ID
    If the ID is not provided, the application information of the calling application is returned.

Return value:

    ApplicationInformation: The information of an application.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if the application is not found with the specified ID.

    • with error type UnknownError, if the application cannot be retrieved because of an unknown error.

Code example:

var appInfo = tizen.application.getAppInfo(null);
console.log("Current application name: " + appInfo.name);
getAppCerts
Gets application certificates for a specified application ID.
ApplicationCertificate[] getAppCerts(optional ApplicationId? id);

Since: 2.0

If the ID is set to null or not set at all, it returns application certificates for the current application.

The certificate types are listed below:

  • AUTHOR_ROOT - Author Root Certificate
  • AUTHOR_INTERMEDIATE - Author Intermediate Certificate
  • AUTHOR_SIGNER - Author Signer Certificate
  • DISTRIBUTOR_ROOT - Distributor Root Certificate
  • DISTRIBUTOR_INTERMEDIATE - Distributor Intermediate Certificate
  • DISTRIBUTOR_SIGNER - Distributor Signer Certificate
  • DISTRIBUTOR2_ROOT - Distributor2 Root Certificate
  • DISTRIBUTOR2_INTERMEDIATE - Distributor2 Intermediate Certificate
  • DISTRIBUTOR2_SIGNER - Distributor2 Signer Certificate

Privilege level: partner

Privilege: http://tizen.org/privilege/appmanager.certificate

Parameters:

  • id [optional] [nullable]: A string representing an application ID. If the ID is not provided, the application certificate of the calling application is returned.

Return value:

    ApplicationCertificate[]: Array of certificate information of a specified application.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotFoundError, if the application is not found with the specified ID.

    • with error type UnknownError, if the application cannot be retrieved because of an unknown error.

Code example:

var appCerts = tizen.application.getAppCerts(null);

for (var i = 0; i < appCerts.length; i++)
{
  console.log("#" + i + " type: " + appCerts[i].type);
  console.log("#" + i + " value: " + appCerts[i].value);
}
getAppSharedURI
Gets the URI of the read-only shared directory of an application for a specified application ID.
DOMString getAppSharedURI(optional ApplicationId? id);

Since: 2.1

The shared directory is used to export data to other applications. Its structure is described in File System Directory Hierarchy.

If the ID is set to null or not set at all, it returns the shared directory URI for the current application.

Remark: Since Tizen 3.0, shared/data directory is not created for web applications. For other applications it will be not created by default and should be considered as optional (refer to table about shared/data for more details).

Parameters:

  • id [optional] [nullable]: A string representing an application ID. If the ID is not provided, the shared directory URI of the calling application is returned.

Return value:

    DOMString: The shared directory URI of an application.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if the application is not found with the specified ID.

    • with error type UnknownError, if the application cannot be retrieved because of an unknown error.

Code example:

var sharedDir = tizen.application.getAppSharedURI(null);
console.log("Shared directory: " + sharedDir);
getAppMetaData
Gets the application meta data array for a specified application ID.
ApplicationMetaData[] getAppMetaData(optional ApplicationId? id);

Since: 2.2

If the ID is set to null or not set at all, it returns the application meta data array for the current application.

Privilege level: public

Privilege: http://tizen.org/privilege/application.info

Parameters:

  • id [optional] [nullable]: A string representing an application ID. If the ID is not provided, the application metadata array of the calling application is returned.

Return value:

    ApplicationMetaData[]: Array of meta data of a specified application. If there are no meta data for a specified application, an empty array is returned

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotFoundError, if the application is not found with the specified ID.

    • with error type UnknownError, if the application cannot be retrieved because of an unknown error.

Code example:

var metaDataArray = tizen.application.getAppMetaData(null);
console.log("Size of metadata: " + metaDataArray.length);
getBatteryUsageInfo
Gets information about battery usage per application.
void getBatteryUsageInfo(BatteryUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                         optional long? days, optional long? limit);

Since: 4.0

This method provides information about battery usage collected in last days days, through callback successCallback. Maximum number of retrieved objects can be set in limit parameter.

If the days is not given, this method retrieves information about battery usage since the time the device was unplugged, after reaching full charge.

The ErrorCallback method is launched with these error types:

  • AbortError - if any system error occurred.
  • InvalidValuesError - if any of the input parameters contains an invalid value.

Privilege level: public

Privilege: http://tizen.org/privilege/apphistory.read

Remark: This method is available only on mobile and wearable devices. An attempt to call this method on other profile will result in throwing NotSupportedError exception.

Parameters:

  • successCallback: The method to call when the invocation ends successfully.
  • errorCallback [optional] [nullable]: The method to call when an error occurs.
  • days [optional] [nullable]: Number of days. If parameter was not given, method will behave as described above.
  • limit [optional] [nullable]: This parameter defines maximum number of ApplicationBatteryUsage objects in an array in successCallback callback. By default, it is set to 30.

Exceptions:

  • WebAPIException
    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example:

var successCallback = function(batteryUsageInfoArray)
{
  batteryUsageInfoArray.forEach(function(abuInfo)
  {
    console.log("ApplicationID: " + abuInfo.appId + ", usage: " + abuInfo.batteryUsage);
  });
};

tizen.application.getBatteryUsageInfo(successCallback);

Output example:

ApplicationID: 3gWRkEPXz5.BasicUI3, usage: 51.78
ApplicationID: org.tizen.homescreen-efl, usage: 28.72
ApplicationID: org.tizen.lockscreen, usage: 6.05
ApplicationID: org.tizen.quickpanel, usage: 4.83
ApplicationID: org.tizen.indicator, usage: 3.69
ApplicationID: org.tizen.calendar.widget, usage: 1.79
ApplicationID: org.tizen.volume, usage: 1.34
ApplicationID: org.tizen.powerkey-syspopup, usage: 0.98
ApplicationID: org.tizen.task-mgr, usage: 0.46
ApplicationID: org.tizen.msg-manager, usage: 0.36
getAppsUsageInfo
Gets the usage statistics of applications.
void getAppsUsageInfo(AppsUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                      optional ApplicationUsageMode? mode, optional ApplicationUsageFilter? filter, optional long? limit);

Since: 4.0

The method gets the most frequently or recently used applications statistics, depending on parameter mode, which meet conditions in filter object. Maximum number of retrieved objects can be set in limit parameter.

Applications which have not been used will not be included in results.

If an attribute endTime from filter object is less than or equal to startTime date, an empty array will be returned.

The ErrorCallback method is launched with these error types:

  • AbortError - if any system error occurred.
  • InvalidValuesError - if any of the input parameters contains an invalid value.

Privilege level: public

Privilege: http://tizen.org/privilege/apphistory.read

Remark: This method is available only on mobile and wearable devices. An attempt to call this method on other profile will result in throwing NotSupportedError exception.

Parameters:

  • successCallback: The method to call when the invocation ends successfully.
  • errorCallback [optional] [nullable]: The method to call when an error occurs.
  • mode [optional] [nullable]: The parameter defines a type of application usage to acquire. By default, it is set to FREQUENTLY.
  • filter [optional] [nullable]: The filter for selecting period of time, from which data is accumulated. By default, this parameter has attribute timeSpan set to 30 days.
  • limit [optional] [nullable]: This parameter defines maximum count of objects ApplicationUsage in returned array. By default, it is set to 10.

Exceptions:

  • WebAPIException
    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example:

var successCallback = function(appsUsageInfo)
{
  appsUsageInfo.forEach(function(auInfo)
  {
    console.log("ApplicationID: " + auInfo.appId + ", count: " + auInfo.totalCount +
                ", duration: " + auInfo.totalDuration + ", last used at: " + auInfo.lastTime);
  });
};

tizen.application.getAppsUsageInfo(successCallback, null, "FREQUENTLY", {timeSpan: 7}, 5);

Output example:

ApplicationID: w5ucNMnbVi.BasicUI, count: 17, duration: 3471, last used at: Tue Aug 01 2017 12:13:06 GMT+0200 (CEST)
ApplicationID: org.tizen.message, count: 16, duration: 2964, last used at: Wed Aug 02 2017 08:22:14 GMT+0200 (CEST)
ApplicationID: api1getcap.sysinfo, count: 16, duration: 1957, last used at: Tue Aug 01 2017 12:13:03 GMT+0200 (CEST)
ApplicationID: org.tizen.email, count: 10, duration: 1209, last used at: Fri Jul 21 2017 10:15:09 GMT+0200 (CEST)
ApplicationID: org.tizen.setting, count: 5, duration: 519, last used at: Wed Aug 02 2017 06:52:51 GMT+0200 (CEST)
addAppStatusChangeListener
Adds a listener for receiving any notification for status changes of the installed applications on a device.
long addAppStatusChangeListener(StatusEventCallback eventCallback, optional ApplicationId? appId);

Since: 4.0

Parameters:

  • eventCallback: The method to call when status of the installed applications is changed.
  • appId [optional] [nullable]: The id of the application which status changes should be monitored. If the application id is ommitted or it is equal to null, all applications status changes will be monitored.

Return value:

    long: Listener id that can be used to remove the listener later.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if the application id parameter is an empty string.

    • with error type AbortError, if it fails to add a listener.

Code example:

function appStatusEventCallback(appId, isActive)
{
  console.log("The application " + appId + " has been " + (isActive ? "activated" : "deactivated"));
}

var watchId = tizen.application.addAppStatusChangeListener(appStatusEventCallback);

Output example:

The application testAppId has been activated
removeAppStatusChangeListener
Removes the listener to stop receiving notifications for status changes of the installed applications on a device.
void removeAppStatusChangeListener(long watchId);

Since: 4.0

Calling this function has no effect if there is no listener with given id.

Parameters:

  • watchId: An ID that identifies the listener.

Exceptions:

  • WebAPIException
    • with error type AbortError, if it fails to remove listener.

Code example:

function appStatusEventCallback(appId, isActive)
{
  console.log("The application " + appId + " has been " + (isActive ? "activated" : "deactivated"));
}

try
{
  var watchId = tizen.application.addAppStatusChangeListener(appStatusEventCallback);
  tizen.application.removeAppStatusChangeListener(watchId);
  console.log("Listener with id " + watchId + " has been removed");
}
catch (err)
{
  console.log("Exception: " + err.name);
}

Output example:

Listener with id 1 has been removed

2.3. ApplicationUsageFilter

This interface represents filter for defining period of time, which will be used as a condition in getAppsUsageInfo method.
  dictionary ApplicationUsageFilter {
    long? timeSpan;
    Date? startTime;
    Date? endTime;
  };

Since: 4.0

The maximum retention period is 90 days.

Dictionary members

long? timeSpan
The attribute to store period of time, from which data is accumulated, in days. The period of time begins timeSpan days ago and ends with current date.

If the attribute is given, the attributes startTime and endTime of this interface are not taken into an account. If timeSpan is greater than 90, 90 will be used instead.

Since: 4.0

Date? startTime
The attribute to store the date, which is used as a lower bound for selecting data.

If only startTime attribute is given, by default endTime is equal to the current date. If startTime date predates the 90 days from the current time, data will be accumulated from last 90 days.

Since: 4.0

Date? endTime
The attribute to store the date, which is used as an upper bound for selecting data.

If only endTime attribute is given, data will be accumulated from 90 days ago to endTime date.

Since: 4.0

2.4. Application

This interface defines the current application's information and the basic operations (such as exit or hide) for the current application.
  [NoInterfaceObject] interface Application {
    readonly attribute ApplicationInformation appInfo;
    readonly attribute ApplicationContextId contextId;
    void exit() raises(WebAPIException);
    void hide() raises(WebAPIException);
    RequestedApplicationControl getRequestedAppControl() raises(WebAPIException);
    long addEventListener(EventInfo event, EventCallback callback) raises(WebAPIException);
    void removeEventListener(long watchId) raises(WebAPIException);
    void broadcastEvent(EventInfo event, UserEventData data) raises(WebAPIException);
    void broadcastTrustedEvent(EventInfo event, UserEventData data) raises(WebAPIException);
  };

Since: 2.0

Attributes

  • readonly ApplicationInformation appInfo
    An attribute to store the application information for the current application.

    Since: 2.0

  • readonly ApplicationContextId contextId
    An attribute to store the ID of a running application.

    Since: 2.0

Methods

exit
Exits the current application.
void exit();

Since: 2.0

Remark: This method is not supported by Web Widget.

Exceptions:

  • WebAPIException
    • with error type UnknownError, if any other error occurs.

Code example:

var app = tizen.application.getCurrentApplication();

app.exit();
hide
Hides the current application.
void hide();

Since: 2.0

Remark: This method is not supported by Web Widget.

Exceptions:

  • WebAPIException
    • with error type UnknownError, if any other error occurs.

Code example:

var app = tizen.application.getCurrentApplication();

app.hide();
getRequestedAppControl
Gets the requested application control passed to the current application.
RequestedApplicationControl getRequestedAppControl();

Since: 2.0

Gets the requested application control that contains the application control passed by the launchAppControl() method from the calling application. The requested application control contains the reason the application is launched and what it has to perform. For example, an application might be launched to display an image on a page by another application's request. In all of these cases, the application is responsible for checking the contents of the application control and responding appropriately when it is launched.

Remark: This method is not supported by Web Widget.

Return value:

    RequestedApplicationControl: The details of a requested application control.

Exceptions:

  • WebAPIException
    • with error type UnknownError, if the application control cannot be retrieved because of an unknown error.

Code example:

var reqAppControl = tizen.application.getCurrentApplication().getRequestedAppControl();

if (reqAppControl)
{
  console.log("Requester AppID: " + reqAppControl.callerAppId);
}
addEventListener
Adds a listener which will invoke a callback function when an event occurs.
long addEventListener(EventInfo event, EventCallback callback);

Since: 2.4

System events do not require an application identifier to be specified. Therefore, the appId attribute of the EventInfo dictionary should not be specified when listening for system events. If it is specified, the event to listen for will be interpreted as an user event.

Parameters:

  • event: Event which will invoke the callback.
  • callback: Callback function to be invoked when the event occurs.

Return value:

    long: Listener identifier.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type.

    • with error type UnknownError in any other error case.

Code example:

var app = tizen.application.getCurrentApplication();

/* For user events: sender's application ID and event name must be provided by using a dictionary. */
/* Let's assume that at least two applications are installed. */
function onListInstalledApps(appsInfo)
{
  var appId = null;

  if (appsInfo.length > 0 && app.appInfo.id != appsInfo[0].id)
  {
    appId = appsInfo[0].id;
  }
  else if (appsInfo.length > 1)
  {
    appId = appsInfo[1].id;
  }

  if (appId)
  {
    var watchId =
        app.addEventListener({"appId": appId, "name": "custom_user_event"}, function(event, data)
        {
          console.log("Data: " + JSON.stringify(data));
          /* Do something. */
        });
  }
}
tizen.application.getAppsInfo(onListInstalledApps);
removeEventListener
Removes an event listener with a specified listener identifier.
void removeEventListener(long watchId);

Since: 2.4

Calling this function has no effect if there is no listener with given id.

Parameters:

  • watchId: Listener identifier.

Exceptions:

  • WebAPIException
    • with error type UnknownError in any other error case.

Code example:

var app = tizen.application.getCurrentApplication();

/* For user events: sender's application ID and event name must be provided by using a dictionary. */
/* Let's assume that at least two applications are installed. */
function onListInstalledApps(appsInfo)
{
  var appId = null;
  var watchId = null;

  if (appsInfo.length > 0 && app.appInfo.id != appsInfo[0].id)
  {
    appId = appsInfo[0].id;
  }
  else if (appsInfo.length > 1)
  {
    appId = appsInfo[1].id;
  }

  if (appId)
  {
    watchId =
        app.addEventListener({"appId": appId, "name": "custom_user_event"}, function(event, data)
        {
          if (watchId)
          {
            app.removeEventListener(watchId);
            watchId = null;
          }
        });
  }
}
tizen.application.getAppsInfo(onListInstalledApps);
broadcastEvent
Broadcasts a user defined event to all the listeners which are listening for this event.
void broadcastEvent(EventInfo event, UserEventData data);

Since: 2.4

An application can listen to events from other applications. However, it can only broadcast its own events. Therefore, the appId attribute of the EventInfo dictionary must be the identifier of the application which calls this method.

Parameters:

  • event: Event to broadcast.
  • data: User defined event data to broadcast.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError in any other error case.

Code example:

var myCustomData = {foo: "bar"};

var app = tizen.application.getCurrentApplication();

app.broadcastEvent({"name": "custom_user_event"}, myCustomData);
broadcastTrustedEvent
Broadcasts a user defined event to all the trusted listeners which are listening for this event. Applications which have the same certificate as the sending application can receive the event.
void broadcastTrustedEvent(EventInfo event, UserEventData data);

Since: 2.4

An application can listen to events from other applications. However, it can only broadcast its own events. Therefore, the appId attribute of the EventInfo dictionary must be the identifier of the application which calls this method.

Parameters:

  • event: Trusted event to broadcast.
  • data: User defined trusted event data to broadcast.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError in any other error case.

Code example:

var myTrustedCustomData = {foo: "bar"};

var app = tizen.application.getCurrentApplication();

app.broadcastTrustedEvent({"name": "custom_user_event"}, myTrustedCustomData);

2.5. ApplicationInformation

This interface defines the general information available to an installed application.
  [NoInterfaceObject] interface ApplicationInformation {
    readonly attribute ApplicationId id;
    readonly attribute DOMString name;
    readonly attribute DOMString iconPath;
    readonly attribute DOMString version;
    readonly attribute boolean show;
    readonly attribute DOMString[] categories;
    readonly attribute Date installDate;
    readonly attribute long size raises(WebAPIException);
    readonly attribute PackageId packageId;
  };

Since: 1.0

Attributes

  • readonly ApplicationId id
    An attribute to store the identifier of an application for application management.

    Since: 1.0

  • readonly DOMString name
    An attribute to store the name of an application.

    Since: 1.0

  • readonly DOMString iconPath
    An attribute to store the icon path of an application.

    Since: 1.0

  • readonly DOMString version
    An attribute to store the version of an application.

    Since: 1.0

  • readonly boolean show
    An attribute that determines whether the application information should be shown (such as in menus).

    Since: 1.0

  • readonly DOMString[] categories
    An array of attributes to store the categories that the app belongs to.

    Since: 2.0

  • readonly Date installDate
    An attribute to store the application install/update time.

    Since: 2.0

  • readonly long size
    An attribute to store the application size (installed space).

    Since: 2.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/application.info

    Exceptions:

    • WebAPIException
      • with error type SecurityError, if this attribute is not allowed.

  • readonly PackageId packageId
    An attribute to store the package ID of an application.

    Since: 2.1

2.6. ApplicationContext

This interface defines the information available about a running application.
  [NoInterfaceObject] interface ApplicationContext {
    readonly attribute ApplicationContextId id;
    readonly attribute ApplicationId appId;
  };

Since: 1.0

Attributes

  • readonly ApplicationContextId id
    An attribute to store the ID of a running application.

    Since: 1.0

  • readonly ApplicationId appId
    An attribute to store the ID of an installed application.

    Since: 1.0

2.7. ApplicationBatteryUsage

This interface defines information about battery usage of application.
  [NoInterfaceObject] interface ApplicationBatteryUsage {
    readonly attribute ApplicationId appId;
    readonly attribute double batteryUsage;
  };

Since: 4.0

Attributes

  • readonly ApplicationId appId
    An attribute storing ID of an application.

    Since: 4.0

  • readonly double batteryUsage
    An attribute which stores information about battery usage of an application with ApplicationId appId. Battery usage is a ratio of battery consumption of the application with ApplicationId appId to the total battery consumption of all applications. The attribute value scales from 0 to 1, the higher value, the more battery is consumed.

    Since: 4.0

2.8. ApplicationUsage

This interface defines information about usage of application.
  [NoInterfaceObject] interface ApplicationUsage {
    readonly attribute ApplicationId appId;
    readonly attribute unsigned long totalCount;
    readonly attribute unsigned long totalDuration;
    readonly attribute Date lastTime;
  };

Since: 4.0

Attributes

  • readonly ApplicationId appId
    An attribute to store the ID of an application.

    Since: 4.0

  • readonly unsigned long totalCount
    An attribute to store the total number of times the application was in the foreground.

    Since: 4.0

  • readonly unsigned long totalDuration
    An attribute to store the total time of application usage in seconds.

    Since: 4.0

  • readonly Date lastTime
    An attribute to store the last time when the application was used.

    Since: 4.0

2.9. ApplicationControlData

This interface defines a key/value pair used to pass data between applications through the ApplicationControl interface.
  [Constructor(DOMString key, DOMString[] value)]
  interface ApplicationControlData {
    attribute DOMString key;
    attribute DOMString[] value;
  };

Since: 2.0

Code example:

var appControlData = new tizen.ApplicationControlData("image", [imagedata1]);

Constructors

Constructor (DOMString, DOMString[])
ApplicationControlData(DOMString key, DOMString[] value);

Attributes

  • DOMString key
    An attribute to store the name of a key.

    Since: 2.0

  • DOMString[] value
    An attribute to store the value associated with a key.

    Since: 2.0

2.10. ApplicationControl

This interface consists of an operation, URI, MIME type, and data. It describes an action to be performed by other applications and is passed to launch other applications. If the system gets the application control request, it finds the corresponding application to be launched with the delivered application control and launches the selected application.
  [Constructor(DOMString operation, optional DOMString? uri, optional DOMString? mime, optional DOMString? category,
               optional ApplicationControlData[]? data, optional ApplicationControlLaunchMode? launchMode)]
  interface ApplicationControl {
    attribute DOMString operation;
    attribute DOMString? uri;
    attribute DOMString? mime;
    attribute DOMString? category;
    attribute ApplicationControlData[] data;
    attribute ApplicationControlLaunchMode launchMode;
  };

Since: 2.0

Code example:

var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/view", null,
    "image/jpeg", null, [new tizen.ApplicationControlData("images", [imagedata1, imagedata2])]);

Constructors

Constructor (DOMString, DOMString?, DOMString?, DOMString?, ApplicationControlData[]?, ApplicationControlLaunchMode?)
ApplicationControl(DOMString operation, optional DOMString? uri, optional DOMString? mime, optional DOMString? category,
                   optional ApplicationControlData[]? data, optional ApplicationControlLaunchMode? launchMode);

Attributes

  • DOMString operation
    An attribute to store the string that defines the action to be performed by an application control.

    Since: 2.0

  • DOMString uri [nullable]
    An attribute to store the URI needed by an application control.

    Since: 2.0

  • DOMString mime [nullable]
    An attribute to store the MIME type of content.

    Since: 2.0

  • DOMString category [nullable]
    An attribute to store the category of the application to be launched.

    Since: 2.0

  • ApplicationControlData[] data
    An array of attributes to store the data needed for an application control.

    Since: 2.0

  • ApplicationControlLaunchMode launchMode
    An attribute to specify launch mode. Default application launch mode is SINGLE.

    Since: 2.4

2.11. RequestedApplicationControl

This interface has an application control information requested and passed from another application and is passed to launch other applications. The newly launched application can get the requested application control through the getRequestedAppControl() method, and send the results to the calling application through the replyResult() method after performing the required action requested by the calling application.
  [NoInterfaceObject] interface RequestedApplicationControl {
    readonly attribute ApplicationControl appControl;
    readonly attribute ApplicationId callerAppId;
    void replyResult(optional ApplicationControlData[]? data) raises(WebAPIException);
    void replyFailure() raises(WebAPIException);
  };

Since: 2.0

Attributes

  • readonly ApplicationControl appControl
    An attribute to store the application control object that describes the caller application's request. It contains the information that the calling application passed to launchAppControl.

    Since: 2.0

  • readonly ApplicationId callerAppId
    An attribute to store the caller application's ID.

    Since: 2.1

Methods

replyResult
Sends the results to the caller application.
void replyResult(optional ApplicationControlData[]? data);

Since: 2.0

Parameters:

  • data [optional] [nullable]: An array of ApplicationControlData objects.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type NotFoundError, if the caller app is not alive or there is no response from the caller app.

    • with error type UnknownError, if the reply request fails because of an unknown error.

Code example:

var reqAppControl = tizen.application.getCurrentApplication().getRequestedAppControl();
if (reqAppControl)
{
  console.log("Requester AppID: " + reqAppControl.callerAppId);

  var appControl = reqAppControl.appControl;
  if (appControl.operation == "http://tizen.org/appcontrol/operation/pick")
  {
    var data = new tizen.ApplicationControlData(
        "http://tizen.org/appcontrol/data/selected", ["Image1.jpg"]);
    reqAppControl.replyResult([data]);
  }
}
replyFailure
Notifies the calling application that the application failed to perform the requested action.
void replyFailure();

Since: 2.0

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if the caller app is not alive or there is no response from the caller app.

    • with error type UnknownError, if the reply request fails because of an unknown error.

Code example:

var reqAppControl = tizen.application.getCurrentApplication().getRequestedAppControl();
if (reqAppControl)
{
  console.log("Requester AppID: " + reqAppControl.callerAppId);

  var appControl = reqAppControl.appControl;
  if (appControl.operation == "http://tizen.org/appcontrol/operation/pick")
  {
    reqAppControl.replyFailure();
  }
}

2.12. ApplicationCertificate

This interface defines the certificate information of an installed application.
  [NoInterfaceObject] interface ApplicationCertificate {
    readonly attribute DOMString type;
    readonly attribute DOMString value;
  };

Since: 2.0

Attributes

  • readonly DOMString type
    An attribute to store the type of the application certificate

    Since: 2.0

  • readonly DOMString value
    An attribute to store the value of the application certificate

    Since: 2.0

2.13. ApplicationMetaData

This interface defines the meta data of an installed application
  [NoInterfaceObject] interface ApplicationMetaData {
    readonly attribute DOMString key;
    readonly attribute DOMString value;
  };

Since: 2.2

Attributes

  • readonly DOMString key
    An attribute to store the key of the application meta data

    Since: 2.2

  • readonly DOMString value
    An attribute to store the value of the application meta data

    Since: 2.2

2.14. BatteryUsageInfoArraySuccessCallback

This callback interface specifies a success callback that is invoked when the battery usage per application array is retrieved.
  [Callback=FunctionOnly, NoInterfaceObject] interface BatteryUsageInfoArraySuccessCallback {
    void onsuccess(ApplicationBatteryUsage[] batteryInfoArray);
  };

Since: 4.0

This callback interface specifies a success method with an array of ApplicationBatteryUsage objects as an input parameter. It is used in ApplicationManager.getBatteryUsageInfo() method.

Methods

onsuccess
Called when the asynchronous call completes successfully.
void onsuccess(ApplicationBatteryUsage[] batteryInfoArray);

Since: 4.0

Remark: Example of usage can be find at getBatteryUsageInfo code example.

Parameters:

  • batteryInfoArray: An array of data containing information about battery usage per application.

2.15. AppsUsageInfoArraySuccessCallback

This callback interface specifies a success callback that is invoked when the application usage statistics array is retrieved.
  [Callback=FunctionOnly, NoInterfaceObject] interface AppsUsageInfoArraySuccessCallback {
    void onsuccess(ApplicationUsage[] appsInfoArray);
  };

Since: 4.0

This callback interface specifies a success method with an array of ApplicationUsage objects as an input parameter. It is used in ApplicationManager.getAppsUsageInfo() method.

Methods

onsuccess
Called when the asynchronous call completes successfully.
void onsuccess(ApplicationUsage[] appsInfoArray);

Since: 4.0

Remark: An example of usage can be find at getAppsUsageInfo code example.

Parameters:

  • appsInfoArray: An array of data containing information about usage per application.

2.16. ApplicationInformationArraySuccessCallback

This callback interface specifies a success callback that is invoked when the installed application list is retrieved.
  [Callback=FunctionOnly, NoInterfaceObject] interface ApplicationInformationArraySuccessCallback {
    void onsuccess(ApplicationInformation[] informationArray);
  };

Since: 1.0

This callback interface specifies a success method with an array of ApplicationInformation objects as an input parameter. It is used in ApplicationManager.getAppsInfo().

Methods

onsuccess
Called when the asynchronous call completes successfully.
void onsuccess(ApplicationInformation[] informationArray);

Since: 1.0

Parameters:

  • informationArray: A list of installed applications.

Code example:

function onListInstalledApps(applications)
{
  for (var i = 0; i < applications.length; i++)
  {
    console.log("ID: " + applications[i].id);
  }
}

tizen.application.getAppsInfo(onListInstalledApps);

2.17. FindAppControlSuccessCallback

This callback interface specifies a success callback that is invoked when the system has finished searching applications that match a specific application control .
  [Callback=FunctionOnly, NoInterfaceObject] interface FindAppControlSuccessCallback {
    void onsuccess(ApplicationInformation[] informationArray, ApplicationControl appControl);
  };

Since: 2.0

This callback interface specifies a success method with an array of ApplicationInformation objects and application control as an input parameter. It is used in ApplicationManager.findAppControl().

Methods

onsuccess
Called when the asynchronous call completes successfully.
void onsuccess(ApplicationInformation[] informationArray, ApplicationControl appControl);

Since: 2.0

Parameters:

  • informationArray: A list of installed applications.
  • appControl: The application control that is passed to ApplicationManager.findAppControl()

Code example:

var appControl = new tizen.ApplicationControl(
    "http://tizen.org/appcontrol/operation/pick", null, "image/jpeg", null);

/* FindAppControlSuccessCallback instance. */
function successCB(appInfos, appControl)
{
  /* appControl is same object with the value passed as first parameter to findAppControl(). */
  var appControlReplyCallback =
  {
    /* Callee sent a reply. */
    onsuccess: function(data)
    {
      for (var i = 0; i < data.length; i++)
      {
        if (data[i].key == "http://tizen.org/appcontrol/data/selected")
        {
          console.log("Selected image is " + data[i].value[0]);
        }
      }
    },
    /* Callee returned failure. */
    onfailure: function()
    {
      console.log("The launch application control failed");
    }
  };

  var appId = appInfos[0].id;  /* Select first app's id. */

  tizen.application.launchAppControl(appControl, appId,
      function()
      {
        console.log("Launch application control succeed");
      },
      function(e)
      {
        console.log("Launch application control failed, reason: " + e.message);
      },
      appControlReplyCallback);
}

tizen.application.findAppControl(appControl, successCB);

2.18. ApplicationContextArraySuccessCallback

This callback interface specifies a success callback that is invoked when the list of running applications is retrieved.
  [Callback=FunctionOnly, NoInterfaceObject] interface ApplicationContextArraySuccessCallback {
    void onsuccess(ApplicationContext[] contexts);
  };

Since: 1.0

This callback interface specifies a success method with an array of ApplicationContext objects as an input parameter. It is used in ApplicationManager.getAppsContext().

Methods

onsuccess
Called when ApplicationManager.getAppsContext() completes successfully.
void onsuccess(ApplicationContext[] contexts);

Since: 1.0

Parameters:

  • contexts: A list of running applications.

2.19. ApplicationControlDataArrayReplyCallback

The ApplicationControlDataArrayReplyCallback callback specifies success callbacks that are invoked as a reply from the requested application control within the application control requester.
  [Callback, NoInterfaceObject] interface ApplicationControlDataArrayReplyCallback {
    void onsuccess(optional ApplicationControlData[]? data);
    void onfailure();
  };

Since: 2.0

This callback interface specifies two methods:

  • onsuccess() - Invoked if the callee application calls RequestedApplicationControl.replyResult().
  • onfailure() - Invoked if the callee application calls RequestedApplicationControl.replyFailure().

Code example:

var appControl = new tizen.ApplicationControl(
    "http://tizen.org/appcontrol/operation/pick", null, "image/jpeg", null);

/* ApplicationControlDataArrayReplyCallback instance. */
var appControlReplyCallback =
{
  /* Callee sent a reply. */
  onsuccess: function(data)
  {
    for (var i = 0; i < data.length; i++)
    {
      if (data[i].key == "http://tizen.org/appcontrol/data/selected")
      {
        console.log("Selected image is " + data[i].value[0]);
      }
    }
  },
  /* Callee returned failure. */
  onfailure: function()
  {
    console.log("The launch application control failed");
  }
};

tizen.application.launchAppControl(appControl, null,
    function()
    {
      console.log("Launch application control succeed");
    },
    function(e)
    {
      console.log("Launch application control failed, reason: " + e.message);
    },
    appControlReplyCallback);

Methods

onsuccess
Called when the callee application calls RequestedApplicationControl.replyResult().
void onsuccess(optional ApplicationControlData[]? data);

Since: 2.0

Parameters:

  • data [optional] [nullable]: An array of ApplicationControlData objects.
onfailure
Called when the callee application calls RequestedApplicationControl.replyFailure().
void onfailure();

Since: 2.0

2.20. SystemEventData

The SystemEventData interface defines what is retrieved from the event listener.
  [NoInterfaceObject] interface SystemEventData {
    attribute DOMString value;
    attribute DOMString type;
  };

Since: 3.0

Platform modules will be able to broadcast system events in a future Tizen release.

Attributes

  • DOMString value
    Value of the system event data item.

    Since: 3.0

  • DOMString type
    Type of the system event data item.

    Since: 3.0

2.21. EventCallback

The EventCallback interface specifies a callback for getting notified when a specified event occurs.
  [Callback=FunctionOnly, NoInterfaceObject] interface EventCallback {
    void onevent(EventInfo event, EventData data);
  };

Since: 3.0

Methods

onevent
Called when the event occurs.
void onevent(EventInfo event, EventData data);

Since: 3.0

Parameters:

  • event: Broadcasted event which invokes this callback.
  • data: Broadcasted event data.

Code example:

var app = tizen.application.getCurrentApplication();

/* For user events: sender's application ID and event name must be provided by using a dictionary. */
/* Let's assume that at least two applications are installed. */
function onListInstalledApps(appsInfo)
{
  var appId = null;

  if (appsInfo.length > 0 && app.appInfo.id != appsInfo[0].id)
  {
    appId = appsInfo[0].id;
  }
  else if (appsInfo.length > 1)
  {
    appId = appsInfo[1].id;
  }

  var eventCB = function(event, data)
  {
    console.log("Data: " + JSON.stringify(data));
    /* Do something. */
  };

  if (appId)
  {
    var watchId = app.addEventListener({"appId": appId, "name": "custom_user_event"}, eventCB);
  }
}
tizen.application.getAppsInfo(onListInstalledApps);

2.22. StatusEventCallback

The StatusEventCallback interface specifies a callback for getting notified when status of the installed application has been changed.
  [Callback=FunctionOnly, NoInterfaceObject] interface StatusEventCallback {
    void onchange(ApplicationId appId, boolean isActive);
  };

Since: 4.0

Methods

onchange
Called when the status event occurs.
void onchange(ApplicationId appId, boolean isActive);

Since: 4.0

Example of using can be find at addAppStatusChangeListener code example.

Parameters:

  • appId: Id of the application that status has been changed.
  • isActive: The new status of the application.

2.23. EventInfo

The EventInfo dictionary identifies an event with information such as event name. If it is an user event, the broadasting application's identifier is also specified.
  dictionary EventInfo {
    ApplicationId appId;
    DOMString name;
  };

Since: 2.4

System events do not require an application identifier to be specified. If one is specified, the event will be interpreted as an user event. List of supported system event is available in Native API guides.

Dictionary members

ApplicationId appId
The unique identifier of the application which is broadcasting an event.

An application can listen to events from other applications. However, it can only broadcast its own events. Therefore, when broadcasting an event, this dictionary member must be the identifier of the application which is broadcasting the event.

System events do not require an application identifier to be specified. If one is specified, the event will be interpreted as an user event.

Since: 2.4

DOMString name
Name which describes the event.

Must only contain the ASCII characters "[A-Z][a-z][0-9]_" and may not begin with a digit. Must be at least 1 byte in length and not exceed the maximum name length of 127 bytes.

Since: 2.4

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee the running of the application on a device which supports Application History feature, declare the following feature requirement in the config file:

  • http://tizen.org/feature/app_history
  • To guarantee the running of the application on a device which has battery, declare the following feature requirement in the config file:

  • http://tizen.org/feature/battery
  • For more information, see Application Filtering.

    4. Full WebIDL

    module Application {
      typedef DOMString ApplicationId;
      typedef DOMString ApplicationContextId;
      typedef object UserEventData;
      typedef (SystemEventData or UserEventData) EventData;
      enum ApplicationControlLaunchMode { "SINGLE", "GROUP" };
      enum ApplicationUsageMode { "RECENTLY", "FREQUENTLY" };
      dictionary ApplicationUsageFilter {
        long? timeSpan;
        Date? startTime;
        Date? endTime;
      };
      dictionary EventInfo {
        ApplicationId appId;
        DOMString name;
      };
      Tizen implements ApplicationManagerObject;
      [NoInterfaceObject] interface ApplicationManagerObject {
        readonly attribute ApplicationManager application;
      };
      [NoInterfaceObject] interface ApplicationManager {
        Application getCurrentApplication() raises(WebAPIException);
        void kill(ApplicationContextId contextId, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
                  raises(WebAPIException);
        void launch(ApplicationId id, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
                    raises(WebAPIException);
        void launchAppControl(ApplicationControl appControl, optional ApplicationId? id, optional SuccessCallback? successCallback,
                              optional ErrorCallback? errorCallback, optional ApplicationControlDataArrayReplyCallback? replyCallback)
                              raises(WebAPIException);
        void findAppControl(ApplicationControl appControl, FindAppControlSuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
        void getAppsContext(ApplicationContextArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                            raises(WebAPIException);
        ApplicationContext getAppContext(optional ApplicationContextId? contextId) raises(WebAPIException);
        void getAppsInfo(ApplicationInformationArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                         raises(WebAPIException);
        ApplicationInformation getAppInfo(optional ApplicationId? id) raises(WebAPIException);
        ApplicationCertificate[] getAppCerts(optional ApplicationId? id) raises(WebAPIException);
        DOMString getAppSharedURI(optional ApplicationId? id) raises(WebAPIException);
        ApplicationMetaData[] getAppMetaData(optional ApplicationId? id) raises(WebAPIException);
        void getBatteryUsageInfo(BatteryUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                                 optional long? days, optional long? limit) raises(WebAPIException);
        void getAppsUsageInfo(AppsUsageInfoArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                              optional ApplicationUsageMode? mode, optional ApplicationUsageFilter? filter, optional long? limit)
                              raises(WebAPIException);
        long addAppStatusChangeListener(StatusEventCallback eventCallback, optional ApplicationId? appId) raises(WebAPIException);
        void removeAppStatusChangeListener(long watchId) raises(WebAPIException);
      };
      [NoInterfaceObject] interface Application {
        readonly attribute ApplicationInformation appInfo;
        readonly attribute ApplicationContextId contextId;
        void exit() raises(WebAPIException);
        void hide() raises(WebAPIException);
        RequestedApplicationControl getRequestedAppControl() raises(WebAPIException);
        long addEventListener(EventInfo event, EventCallback callback) raises(WebAPIException);
        void removeEventListener(long watchId) raises(WebAPIException);
        void broadcastEvent(EventInfo event, UserEventData data) raises(WebAPIException);
        void broadcastTrustedEvent(EventInfo event, UserEventData data) raises(WebAPIException);
      };
      [NoInterfaceObject] interface ApplicationInformation {
        readonly attribute ApplicationId id;
        readonly attribute DOMString name;
        readonly attribute DOMString iconPath;
        readonly attribute DOMString version;
        readonly attribute boolean show;
        readonly attribute DOMString[] categories;
        readonly attribute Date installDate;
        readonly attribute long size raises(WebAPIException);
        readonly attribute PackageId packageId;
      };
      [NoInterfaceObject] interface ApplicationContext {
        readonly attribute ApplicationContextId id;
        readonly attribute ApplicationId appId;
      };
      [NoInterfaceObject] interface ApplicationBatteryUsage {
        readonly attribute ApplicationId appId;
        readonly attribute double batteryUsage;
      };
      [NoInterfaceObject] interface ApplicationUsage {
        readonly attribute ApplicationId appId;
        readonly attribute unsigned long totalCount;
        readonly attribute unsigned long totalDuration;
        readonly attribute Date lastTime;
      };
      [Constructor(DOMString key, DOMString[] value)]
      interface ApplicationControlData {
        attribute DOMString key;
        attribute DOMString[] value;
      };
      [Constructor(DOMString operation, optional DOMString? uri, optional DOMString? mime, optional DOMString? category,
                   optional ApplicationControlData[]? data, optional ApplicationControlLaunchMode? launchMode)]
      interface ApplicationControl {
        attribute DOMString operation;
        attribute DOMString? uri;
        attribute DOMString? mime;
        attribute DOMString? category;
        attribute ApplicationControlData[] data;
        attribute ApplicationControlLaunchMode launchMode;
      };
      [NoInterfaceObject] interface RequestedApplicationControl {
        readonly attribute ApplicationControl appControl;
        readonly attribute ApplicationId callerAppId;
        void replyResult(optional ApplicationControlData[]? data) raises(WebAPIException);
        void replyFailure() raises(WebAPIException);
      };
      [NoInterfaceObject] interface ApplicationCertificate {
        readonly attribute DOMString type;
        readonly attribute DOMString value;
      };
      [NoInterfaceObject] interface ApplicationMetaData {
        readonly attribute DOMString key;
        readonly attribute DOMString value;
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface BatteryUsageInfoArraySuccessCallback {
        void onsuccess(ApplicationBatteryUsage[] batteryInfoArray);
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface AppsUsageInfoArraySuccessCallback {
        void onsuccess(ApplicationUsage[] appsInfoArray);
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface ApplicationInformationArraySuccessCallback {
        void onsuccess(ApplicationInformation[] informationArray);
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface FindAppControlSuccessCallback {
        void onsuccess(ApplicationInformation[] informationArray, ApplicationControl appControl);
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface ApplicationContextArraySuccessCallback {
        void onsuccess(ApplicationContext[] contexts);
      };
      [Callback, NoInterfaceObject] interface ApplicationControlDataArrayReplyCallback {
        void onsuccess(optional ApplicationControlData[]? data);
        void onfailure();
      };
      [NoInterfaceObject] interface SystemEventData {
        attribute DOMString value;
        attribute DOMString type;
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface EventCallback {
        void onevent(EventInfo event, EventData data);
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface StatusEventCallback {
        void onchange(ApplicationId appId, boolean isActive);
      };
    };