Application: Providing Information about Applications and Controlling Applications

This tutorial demonstrates how you can manage and launch applications.

The Application API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

Warm-up

Become familiar with the Application API basics by learning about:

Retrieving Application Information
Display a list of applications that are currently installed or running on the device, and retrieve application information, such as application name, application ID, and context ID.
Managing Applications
Launch, stop, hide, or exit applications.
Launching Applications with the Application Control
Launch applications by a request based on their functionality.
Handling Application Control Requests
Handle requests from other applications and reply with a result.
Broadcasting and Listening for Events
Broadcast your own events and listen for events from other applications.

Retrieving Application Information

Learning how to retrieve information about installed and running applications allows you to manage all the device applications from your application:

To retrieve a list of installed applications, use the getAppsInfo() method of the ApplicationManager interface (in mobile and wearable applications):
```
function onListInstalledApplications(applications)
{
   console.log("The number of installed applications is " + applications.length);
}
tizen.application.getAppsInfo(onListInstalledApplications);
```
The list of applications is returned to the ApplicationInformationArraySuccessCallback event handler as an array of ApplicationInformation objects (in mobile and wearable applications).
To retrieve a list of running applications, use the getAppsContext() method of the ApplicationManager interface:
```
function onRunningApplicationContexts(contexts)
{
   console.log("The number of running applications is " + contexts.length);
}
tizen.application.getAppsContext(onRunningApplicationContexts);
```
The list of application contexts is returned to the given event handler as an array of the ApplicationContext objects.
To retrieve basic application information, use the getAppInfo() method of the ApplicationManager interface.

Provide the application ID of the application whose information you want as a parameter for the method. If no application ID is set, the method retrieves the information about the application calling the method.
```
var appinfo = tizen.application.getAppInfo("org.tizen.application");
console.log("The application icon path :" + appinfo.iconPath);
console.log("The application name :" + appinfo.name);
```
To retrieve application context information, use the getAppContext() method of the ApplicationManager interface.

Provide the context ID of the application whose context information you want as a parameter for the method. If no context ID is set, the method retrieves the information about the application calling the method.
```
var appContext = tizen.application.getAppContext();
console.log("Application context retrieved for app " + appContext.id);
```

Managing Applications

Learning how to launch and stop other applications, and hide or exit applications running on the device, allows you to manage all the device applications from your application:

To launch or stop another application, you need the application ID (for launching) or context ID (for stopping) to identify the application.

To launch an application, use the launch() method of the ApplicationManager interface (in mobile and wearable applications), and to stop an application, use the kill() method.

In the following example, the application to be launched and stopped is an alarm, with the "samplealarm" ID.
```
/* Launch the application */
tizen.application.launch("samplealarm", onsuccess);

/* Stop the application */
function onGetAppsContextSuccess(appcontexts)
{
   for (int i=0; i < appcontexts.length; i++)
   {
      if (appcontexts[i].appId === "samplealarm")
      {
         tizen.application.kill(appcontexts[i].id);
      }
   }
}

tizen.application.getAppsContext(onGetAppsContextSuccess);
```
You can also launch an application using the application control.
To retrieve the current application, use the getCurrentApplication() method:
```
var currApp = tizen.application.getCurrentApplication();
```
To hide the current application, use the hide() method:
```
currApp.hide();
```
To exit the current application, use the exit() method:
```
currApp.exit();
```

Launching Applications with the Application Control

Learning to use application controls to launch other applications from your application allows you to take advantage of the functionality of other device applications.

An installed application can provide a service which can be identified by the operation name. Other applications can request and use the provided service of the provider application (and optionally passing some data to the service). The provider application responds to requests with an ApplicationControlData instance (in mobile and wearable applications) (which can also contain some data).

To use the application control mechanism to pick image files from a list of images, create an ApplicationControl object (in mobile and wearable applications).

Define the functionality required from the external application which you want to launch. The application control request must have an operation type suitable for selecting images, with the URI set as null, and the MIME type set as image/*.
```
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/pick", null, "image/*");
```

Define the format of the reply you want to receive from the application control:

var appControlReplyCB =
{
   /* Reply is sent if the requested operation is successfully delivered */
   onsuccess: function(reply)
   {
      for (var num = 0; num < reply.length; num++)
      {
         if (reply[num].key == "http://tizen.org/appcontrol/data/path")
         {
            console.log("picked image path: " + reply[num].value[0]);
         }
      }
   }
}

Call the launchAppControl() method to find a suitable application to select the images:

tizen.application.launchAppControl(appControl, null,
                                   function(){console.log("launch appControl succeeded");},
                                   function(e){/* Error handling */},
                                   appControlReplyCB);

Handling Application Control Requests

Learning how to handle requests from other applications allows you to create Web applications that can be called from other applications to perform specific actions.

Web applications can provide a service which can be identified by an operation name. Other applications can request and use the provided service of other applications (and optionally pass some data to the service). The provider application receives the request, performs some actions, and sends the result to the caller application in an ApplicationControlData array (in mobile and wearable applications).

To enable an application to receive application control requests, open the Web application configuration editor in the Tizen IDE and add an operation in the app-control section of the Tizen tab.

In this example, the name of the operation is http://example.tizen.org/operation/get_time. The config.xml file contains a <tizen:app-control> element:
```
<tizen:app-control>
   <tizen:src name="index.html"/>
   <tizen:operation name="http://example.tizen.org/operation/get_time"/>
</tizen:app-control>
```
For more information, see Exporting Application Control Functionality.

To retrieve an object of the RequestedApplicationControl interface (in mobile and wearable applications), use the getCurrentApplication() method of the ApplicationManager interface (in mobile and wearable applications) and the getRequestedAppControl() method of the Application interface (in mobile and wearable applications):

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

if (reqAppControl && reqAppControl.callerAppId)
{
   console.log("Requester AppID: " + reqAppControl.callerAppId + "\nwith operation: " + reqAppControl.appControl.operation);
}
else
{
   console.log("The application was not launched with Application Control.");
}

To send a reply to the caller application, use the replyResult() method of the RequestedApplicationControl interface:

try
{
   /* Construct result data */
   var data = new tizen.ApplicationControlData("current-time", [new Date().toString()]);
   /* Reply to caller */
   reqAppControl.replyResult([data]);
}

For more information on launching an application, see Launching Applications with the Application Control.

Broadcasting and Listening for Events

Learning how to broadcast and listen for events allows you to create Web applications that can send and receive data between each other:

The first application can broadcast an event.
To broadcast events, use the broadcastEvent() method:
```
var app = tizen.application.getCurrentApplication();
var appEvent = {name: "first_app_event_1"};
var data = {foo: "bar"};

app.broadcastEvent(appEvent, data);
```
Web applications can also broadcast trusted events for trusted listeners with the same certificate as the sender application. To broadcast trusted events, use the broadcastTrustedEvent() method:
```
app.broadcastTrustedEvent(appEvent, data);
```

The second application can listen for the first application and receive data.

To receive data from the first application, use the addEventListener() method with the sender application ID and event name:

var app = tizen.application.getCurrentApplication();

var watchId = app.addEventListener({appId: "a234567890.FirstApp", name: "first_app_event_1"}, 
                                   function(event, data) 
                                   {
                                      /* Data from first app must be received here */
                                      console.log("Data: " + JSON.stringify(data));
                                   });

To stop receiving data from the first application, use the removeEventListener() method with the proper watchId:

app.removeEventListener(watchId);