Overview

By using Tizen Application API you can do the following jobs:

• Launch other application(s): The Application interface provides methods to launch other applications either by using the tizen.application.launch() method or through tizen.application.launchAppControl() method.
• Manage application: The Application interface provides methods to perform application management actions such as hide or exit the calling/running application.
• Access the installed application(s): The Application interface provides methods to retrieve information about the applications installed on the device. You can retrieve information such as name, icon path, version details, and application identifier.
• Access the context of running application(s): The Application interface provides methods to retrieve the context(s) of application(s) on the device.
• Receive Notifications: The Application interface provides methods and event listeners to receive notifications for the modifications in the list of applications installed on the device.

To use this API, add the required permissions to the config.xml file (see prerequisites section below). When the application is launched, an application object is instantiated automatically in the tizen object. The tizen.application object is an instance of the ApplicationObject interface.

Figure-1 shows how the API objects are structured inside the application window.

• Launch an Application
• Launch a Service
• Provide a Service
• Manage Application
• Retrieve the List of Installed Applications
• Retrieve Application Information
• Retrieve the List of Running Applications
• Retrieve Application Context
• Receive Notifications
• Demo

Prerequisites

The Application API has different levels of access to retrieve information about applications and to manage applications. You can enable different permissions for the Application API in the config.xmlfile. Open the config.xml file, choose the "Feature" tab, and check below features to enable them to use in your applications.

• http://tizen.org/api/application: Privilege to allow access to all features of the Application API.
• http://tizen.org/api/application.read: Privilege to allow access to getting application information API.
• http://tizen.org/api/application.launch: Privilege to allow access to launching application API. This includes the read feature.
• http://tizen.org/api/application.kill: Privilege to allow access to killing application API. This includes the read feature.

If you want to do it manually, add the following <feature> tag to the config.xml as shown below.

<widget xmlns="http://www.w3.org/ns/widgets" xmlns:tizen="http://tizen.org/ns/widgets" id="http://yourdomain/Application" version="1.0.0" viewmodes="maximized" >
    <tizen:application id="qwpTZHja3a" required_version="1.0"/>
    <icon src="icon.png"/>
    <content src="index.html"/>
    <name>Application </name>
	
    <tizen:privilege name="http://tizen.org/privilege/tizen"/>
    <tizen:privilege name="http://tizen.org/privilege/application.kill"/>
    <tizen:privilege name="http://tizen.org/privilege/application.launch"/>
    <tizen:privilege name="http://tizen.org/privilege/application.read"/>
	
</widget>

Launch an Application

Using tizen.application.launch() method, you can start a particular application based on Application ID. Its arguments are:

• id - Unique string representing application ID.
• successCallback- Function called when the invocation ends successfully.
• errorCallback- Function called when an error occurs.
• argument- Parameters (array) for the launched application.

In this example, we will launch the calculator application which has the tlp6xwqzos.Calculator application ID.

function onsuccess() {
   console.log("Application has launched successfully");
 }
 tizen.application.launch("tlp6xwqzos.Calculator", onsuccess);

Launch a Service

If you don't want to launch an application using its identifier (Application ID), but instead need an application that provides certain functionality, you can request that the system launches an application basing on your requirements.

Using the tizen.ApplicationControl() method, you can request system to launch a particular service. It takes the following arguments:

• service- Object describing service details (see below).
• id- Identifier of the application to be launched.
• successCallback- Function called when the invocation ends successfully.
• errorCallback- Function called when an error occurs.
• replyCallback- Response callback (this is of type ApplicationServiceDataArrayReplyCallback).

ApplicationService

An ApplicationService interface consists of Operation, URI and MIME type. The ApplicationService describes an action to be performed by other application and can carry the result from the subsequent application by using ApplicationServiceDataArrayReplyCallback interface.

Once system receives the launch request with the ApplicationService object, then system finds a proper application (or shows applications in the application selector) and launches the selected application.

An ApplicationService object consists of the following primary information:

• Operation- The operation is a string that defines the action to be performed by the Application Service. The operation is the mandatory information for sending a launch request. You can also define your own operation to describe specific action of your application.
• URI- the URI defines the data on which the action will be performed.
• MIME- the MIME type defines the specific type of the URI.
• category- An attribute to store the category of the application to be launched.
• ApplicationControlData Data- the ApplicationControlData is key-value pairs to provide additional information for the launch request and can be used for the result of the request.

ApplicationServiceDataArrayReplyCallback

If the requested operation completes successfully, the onsuccess() method is invoked. It receives data that the launched application has returned as the result of the operation. The data is delivered as an array of ApplicationServiceData objects. Each such object contains two attributes: key and value. The value attribute is actually an array of values. The function below will print all received data. In case of failure onfail() method is invoked.

An ApplicationServiceDataArrayReplyCallback object consists of the following two methods:

• onsuccess()- The method invoked when the service provider calls ApplicationService.replyResult().
• onfail()- The method invoked when the service provider calls ApplicationService.replyFailure().

Resolve the launch request

There are two kinds of the launch request:

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

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

//Create a service.
var appControl = new
	tizen.ApplicationControl("http://tizen.org/appcontrol/operation/pick", null, "IMAGE/*");
var appControlReplyCallback = {
// callee now sends a reply onsuccess:
function(data) {
for(var i=0; i < data.length; i++) {
console.log("#"+i+" key:"+data[i].key);
for(var j=0; j < data[i].value.length; j++) {
console.log("value#"+j+":"+data[i].value[j]); } } }, // Something went wrong onfail:
function() {
console.log('The launch application control failed'); } }
//Launch a service.
tizen.application.launchAppControl(appControl, null,
function() {console.log("launch application control succeed");
},
function(e) {
console.log("launch application control failed. reason: " + e.message); },
appControlReplyCallback );

• Explicit launch For explicit launch, you must specify the exact applicationID of the service provider as an argument in ApplicationControl() method. The operation http://tizen.org/appcontrol/operation/default is typically used for launching other application simply without any other information (URI, MIME type).
• Implicit launch If you don't provide the exact application ID of the application, you must provide enough information for the system to determine which of the available applications is best to handle for the launch request. Only three attributes of a launch request are used for resolving which application is launched:
  • Operation
  • URI scheme
  • MIME type

  The system compares all three information against the launch request to determine which of the available application is best for the launch request. The launch request is resolved only if all specified information match one of the service descriptions that are exported by installed applications. The Application control Data is not used in resolving the launch request. In the example below we are requesting for an application that can allow you to "pick"" image files from the list of images on the system.

Provide a Service

If you want your application to provide multiple services, then you need to declare these services in the config.xml file. Each service description specifies the operation, URI scheme and MIME type.

<tizen:app-control src="[PAGE]" operation="[OPERATION]" scheme="[URI_SCHEME]" mime="[MIME_TYPE]" />

• src- is a page that will handle the request.
• operation- is the identifier of the operation.
• mime- is the allowed MIME type.
• scheme- is the protocol, (e.g. "tel", "http"), the requesting application will be able to use it to describe the object of the operation.

In the below example, you are providing an image picker service. If the system runs the service, the image_selection_service.html file will be loaded

<tizen:app-control src="image_selection_service.html" operation="http://tizen.org/appcontrol/operation/pick" mime="image/*"/>

Once the service provider application has finished the service, it must pass control back to the requesting application with the result of the services it has provided. To do this, you should call the tizen.application.getRequestedAppControl() method in the service provider application to get the reference of the RequestedApplicationControl object that has been passed to it in the launchAppControl() method.

To pass control back to requesting application call either the reqAppControl.replyResult() method (in case of success) or the reqAppControl.replyFailure() method (in case of failure) of RequestedApplicationControl object. Output/result is passed as a parameter, that contains an array of ApplicationControlData objects to reqAppControl.replyResult() method. The ApplicationControlDataArrayReplyCallback.onsuccess() method is invoked in the requesting application.

//This function is invoked once the html is loaded.
function onLoad() {
	var reqAppControl = tizen.application.getCurrentApplication().getRequestedAppControl();
    if (reqAppControl) {
        var processedData = processData(reqAppControl.appControl);
            reqAppControl.replyResult(processedData);
        }
    }

Manage Application

The Application API provides the Application interface, which lets you control your application lifecycle.

Exit an Application

The tizen.application.exit() method is used to exit the current application.

 var app = tizen.application.getCurrentApplication();
 app.exit();

Hide an Application

The tizen.application.hide() method is used to send the current application to background.

 var app = tizen.application.getCurrentApplication();
 app.hide();

Retrieve the List of Installed Applications

Using the tizen.application.getAppsInfo() method, you can get the list of installed applications on the device. The method takes two arguments, the success callback (called when the operation is successful) and the error callback (called otherwise), and an array of the installed applications will be returned as an argument of the success callback.

The success callback receives an array of ApplicationInformation objects, and each object contains the following attributes:

• id- Identifier of the application.
• name- Name of the application.
• iconPath- Path of the application's icon.
• version- Version of the application.
• show- Informs if the application should be shown or not.

function onListInstalledApps(applications) {
     for (var i = 0; i < applications.length; i++)
         addToApplicationGrid(applications[i]);
	 console.log('Application ID: ' + appInfo.id);
         console.log('Icon Path: ' + appInfo.iconPath);
         console.log('Name: ' + appInfo.name);
         console.log('Version: ' + appInfo.version);
         console.log('Show: ' + appInfo.show);
         console.log('');
 }
 tizen.application.getAppsInfo(onListInstalledApps);

Retrieve Application Information

The tizen.application.getAppInfo() method is used to get application information for an application which is identified by the application ID. If no application ID is set, you get information of the calling application.

  var appInfo = tizen.application.getAppInfo("org.tizen.application");

Retrieve the List of Running Applications

Using the tizen.application.getAppsContext() method, you can get the list of running applications on the device. The method takes two arguments, the success callback (called when the operation is successful) and the error callback (called otherwise), and an array of the running applications will be returned as an argument of the success callback.

The success callback receives an array of ApplicationContext objects, and each object contains the following attributes:

• id- Identifier of the running application.
• name- Identifier of the installed application.

 tizen.application.getAppsContext(onRunningAppsContext);
  function onsuccess(contexts) {
    for (var i = 0; i < contexts.length; i++)
        addToTaskManager(contexts[i]);
        console.log('Application ID: ' + contextInfo.appId);
        console.log('Context ID: ' + contextInfo.id);
        console.log('');
  }
tizen.application.getAppsContext(onsuccess, onError);

Retrieve Application Context

The tizen.application.getAppContext() method is used to get context information for an application which is identified by the context ID. If no context ID is set, you get information of the calling application.

var appContext = tizen.application.getAppContext(null);
 console.log("Application context retrieved for app " + appContext.id);

Receive Notifications

The Application interface provides methods and event listeners to provide notifications of modifications in the list of applications installed on the device.

Your application can receive notifications when an application information event takes place. There are three kinds of application information events: installation, uninstallation, and update of the given application.

Registering an Event Listener

The tizen.application.addAppInfoEventListener() method lets you register an event listener that handles changes in the list of applications installed on the device. This method takes two arguments: ApplicationInformationEventCallback to be invoked when event takes place, ErrorCallback to be invoked error occurs.

An ApplicationInformationEventCallback object consists of the following functions:

var appEventCB = {
	oninstalled: function(application) {
        console.log('Application ' + application.name + ' installed');
	},
	onupdated: function(application) {
        console.log('Application ' + application.name + ' updated');
	},
	onuninstalled: function(appid) {
        console.log('Application ' + appid + ' uninstalled');
	}
};

var listenerID = tizen.application.addAppInfoEventListener(appEventCB);

Removing an Event Listener

The tizen.application.removeAppInfoEventListener() method is used to remove an event listener that handles the changes in the list of applications installed on the device.

var appEventCB = {
    oninstalled: function(application) {
        console.log('Application ' + application.name + ' installed');
    },
    onupdated: function(application) {
        console.log('Application ' + application.name + ' updated');
    },
    onuninstalled: function(appid) {
        console.log('Application ' + appid + ' uninstalled');
    }
};

var listenerID = tizen.application.addAppInfoEventListener(appEventCB);
tizen.application.removeAppInfoEventListener(listenerID);