Application

Application management and launch features include retrieving information about the applications installed or currently running on the device, such as application name, icon path, version details, and application ID. You can also receive notifications if applications are updated or removed, or new applications are installed. You can also perform application management tasks, such as launching, closing, or exiting a running application.

Note
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.

The Tizen Application API provides means to interact with other applications using the ApplicationControl (in mobile and wearable applications) and RequestedApplicationControl (in mobile and wearable applications) interfaces. The application uses the application control to request a specific operation to be performed. The operation can be, for example, making a phone call, browsing local files so the user can pick an image of their choosing, or starting a video player with a specific movie. The Web application can also register itself as able to perform such operations. It can then be launched by another application and respond by using the RequestedApplicationControl interface.

The main application management and launch features are:

• Application management

  You can manage and retrieve information about the current application with the Application object (in mobile and wearable applications), which is retrieved using the getCurrentApplication() method of the ApplicationManager interface (in mobile and wearable applications). You can exit or hide the current application using the Application interface.

• Application information retrieval

  You can retrieve information about applications in various ways:

  • Retrieve information about installed applications with the getAppInfo() and getAppsInfo() methods of the ApplicationManager interface.
  • Use the ApplicationInformation interface (in mobile and wearable applications) to retrieve information about installed applications, such as name, icon path, and version.
  • Use the ApplicationContext interface (in mobile and wearable applications) to retrieve the application ID and context ID of the running application. The application ID can be used to retrieve application information, or to launch an application. The context ID is a unique identifier given by the platform to a running application.
• Application change notifications

  You can receive notifications when there is a change in the list of installed applications.

  The addAppInfoEventListener() method of the ApplicationManager interface registers an event listener, which starts asynchronously once the addAppInfoEventListener() method returns the subscription identifier for the listener. To unsubscribe the listener, use the removeAppInfoEventListener() method with the subscription identifier. You can use the ApplicationInformationEventCallback interface (in mobile and wearable applications) to define listener event handlers for receiving the notifications.

• Application control

  You can launch other applications based on their functionality using the launchAppControl() method of the ApplicationManager interface.

• Handling incoming AppControl requests

  You can handle an incoming application control request using the getRequestedAppControl() method of the Application interface. The RequestedApplicationControl interface (in mobile and wearable applications) is used to respond to the requested application control.

Application Controls

The application control is a standard mechanism for using specific operations exported by other applications, such as calling, Web browsing, and playing media items. It allows you to launch other applications whose functionalities you need in your application. Basically, launching an application control means that if you need an application that provides certain functionality, you can request that the system launches it according to your requirements. The application control allows you to launch applications without knowing their identifiers or specifications, based on your immediate needs.

The application control consists of an operation, URI, MIME type, and some data, and it describes the request to be performed by the newly launched application. This information is used to resolve the application control. When the system gets an application control request, it finds the proper control provider application by resolving the application control, and then launches the provider application. Once the provider application has performed the requested task, it must pass control back to the requesting application with the result of the operation it has provided.

The provider application calls the getRequestedAppControl() method of the Application interface to get the reference of the RequestedApplicationControl object containing the application control passed by the launchAppControl() method from the calling application. Then, the provider application calls either the replyResult() method (in case of success) or the replyFailure() method (in case of failure) of the RequestedApplicationControl interface to return the control back to the requesting application. The result of the provided operation (if any), is delivered as an array of ApplicationControlData objects (in mobile and wearable applications). The result is received in the original calling application through the ApplicationControlDataArrayReplyCallback event handler (in mobile and wearable applications).

The application control uses the following primary information:

• Application ID

  Used to identify the provider application of the requested application control. Besides the application ID, a platform-defined application control has a special alias name for the application ID with the prefix tizen. For example, the platform phone application has the alias application ID of tizen.phone.

  Tizen Alias ID is deprecated since Tizen 2.3.1.

• Operation

  Describes an action to be performed by the provider application. The operation ID of the platform-provided operation is in the http://tizen.org/appcontrol/operation/<verb> format. For example, http://tizen.org/appcontrol/operation/view.

For more information on how to export application control functionality from your application to allow other applications to use it, see Exporting Application Control Functionality.

Platform Application Controls

Tizen provides base applications, such as Web browser, image viewer, music player, and video player. Using the ApplicationControl interface (in mobile and wearable applications), you can easily use the functionality of the Tizen base applications. The following table lists the services provided by the Tizen base applications.

Table: Tizen base application services

Service	Operation	Scheme	MIME
Browsing a Web page	http://tizen.org/appcontrol/operation/view	http https	-
Displaying an image	http://tizen.org/appcontrol/operation/view	file http https	image/bmp image/gif image/jpeg image/png
Playing a sound file		file	audio/aac audio/amr audio/mp3 audio/wav
Playing a video file			video/mp4 video/3gpp
Selecting a file	http://tizen.org/appcontrol/operation/pick		*/* image/* video/* audio/*

Note
Tizen provides support for the defined MIME types of the base application services depending on the platform implementation.

Browsing a Web Page

The browsing a Web page application control service allows you to display Web pages in your own application using the device's Web browser.

Application ID

This application control can be accessed using aliased application ID of "tizen.internet".

Tizen Alias ID is deprecated since Tizen 2.3.1.

VIEW Operation

This application control supports the http://tizen.org/appcontrol/operation/view operation only.

This operation launches a Web browser and displays a specific Web page. The device user can access other Web pages, manage bookmarks, search for text on the Web page, and modify brightness and Internet settings. If the Internet connection is not available or if the specified Web page does not exist, an error message is displayed.

The following example shows how to display a Web page:

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

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

Selecting a File

The selecting a file application control service allows you to handle media files (image, audio, or video) in your own application.

Application ID

This application control can be accessed using aliased application ID of "tizen.filemanager".

Tizen Alias ID is deprecated since Tizen 2.3.1.

PICK Operation

This application control supports the http://tizen.org/appcontrol/operation/pick operation only.

This operation displays a list of specific type of media files found in the Media folder on the device or memory card, and returns the selected files back to your own application. The device user can browse all the subfolders and select items from one of the subfolders. The operation only displays files that are of the specified type. You can also display all types of media files by defining all as the type in the operation input data.

The results of the operation are returned in the ApplicationControlDataArrayReplyCallback event handler (in mobile and wearable applications). The results include the path to the retrieved media file.

The following example shows how to retrieve media files:

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

var appControlReplyCallback = 
{
   /* Provider application 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]);
         }
      }
   },
   /* Provider application returned a failure */
   onfailure: function() 
   {
      /* Error handling */
   }
}

tizen.application.launchAppControl(appControl, "tizen.filemanager",
                                   function() {console.log("launch application control succeed");},
                                   function(e) {/* Error handling */}, appControlReplyCallback);

Launching an Application with Application Controls

There are different types of application control requests for launching other applications. The system determines which application is suitable for handling the application control request:

• Explicit launch

  You determine which application must be launched. If you specify the exact application ID, the application ID determines which application is launched and the application performs the operation as specified in the application control request.

• Implicit launch

  You provide information to describe the request to be performed by the newly launched application without the application ID. The system uses the information to resolve the application control, by trying to find the proper application to perform the requested application control and then launching the selected application.

For more information on launching platform applications through application controls, see Launching Platform Applications.

Explicit Launch

If you specify the exact application ID of the application for the launchAppControl() method of the Application interface, you can request the application control from a specific application. The application ID determines which application is launched and the application performs the operation as specified in the control request.

Note
An explicit launch request cannot be completed if the user does not have the specified application on their device. Hence implicit launches can be more effective, since the system can find an available application to complete the request. The implicit launch also enhances the user experience by allowing the user to select their preferred application to complete the task.

Implicit Launch

If you do not provide an exact application ID with the control request in the launchAppControl() method, you must provide enough information for the system to determine which of the available applications can best handle the control request (for example, the nature of the service or the file types that the application can handle).

The application control consists of the operation ID, URI, MIME type, and some additional data. The system compares the attributes of the control request against the installed applications to determine which of the available applications is most suitable for the control request. The control request is resolved only if all specified information matches the service descriptions retrieved from the installed applications. The application control data attribute is not used in resolving the control request.

The following attributes are used to resolve which application is launched:

• Operation

  Mandatory string that defines the action to be performed by the application control. You can define your own operation to describe a specific action of your application.

  The following table lists the standard operations and data keys for delivering specific data to launch or return.

  Table: Standard operations

  Operation	Key	Description
  http://tizen.org/appcontrol/operation/view	-	Display the requested data (show an image or text, or play music or a video). The URI scheme must contain the path to the requested data.
  http://tizen.org/appcontrol/operation/call	-	Make a call to a specific phone number. The URI scheme must be tel: or set to NULL. The public level privilege http://tizen.org/privilege/call is required for this operation. Launching this operation without the privilege triggers a security error.
  http://tizen.org/appcontrol/operation/pick	http://tizen.org/appcontrol/data/selected	Provide a selection window for requested items and return the selection. The return value (the path to the selected item) must be stored with the data key.
  http://tizen.org/appcontrol/operation/create_content	http://tizen.org/appcontrol/data/selected	Create content (such as a photo or video). The return value (the path to the created content) must be stored with the data key.
  http://tizen.org/appcontrol/operation/dial	-	Show the dialer UI and dial a number using the requested phone number. The URI scheme must be tel: or set to NULL. If the URI scheme is NULL, the dialer UI is shown without a phone number.
  http://tizen.org/appcontrol/operation/share	-	Share content (for example, share a picture with friends using SNS services). The URI scheme must contain the path of the data.
  http://tizen.org/appcontrol/operation/multi_share	http://tizen.org/appcontrol/data/path	Share multiple files. Each data path must be saved as an ApplicationControlData object with the data key.

• URI scheme

  Data on which the action is performed. For example, if you want to use http://tizen.org/appcontrol/operation/pick operation to pick an image, the URI must be the URI of the image (which can be obtained using the toURI() method after resolving the file path). The same operation can be used to launch a Web page in a browser, except that the URI in that case is the URL of the Website, such as https://www.tizen.org/.

• MIME type

  Specific type of the URI. For example, if you want to pick images, the possible MIME types are image/bmp, image/gif, image/jpeg, image/png, or image/*. The MIME type is important because it helps to find an application that is capable of dealing with the specified MIME type.

• Application control data

  Key-value pairs providing additional information for the control request. They can also be used for the result of the request. The previous table shows some examples of keys. The data depends on the other parameters of the application control interface. For example, the ImageViewer application control can take different types of input and output data than the Camera application control.

The following code example shows an ApplicationControl instance (in mobile and wearable applications) that launches an application to pick images. If there are multiple applications that can fulfill the request, the system shows a pop-up allowing the user to select the application they want:

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

tizen.application.launchAppControl(appControl, null, successCb, errCb, null);

Launching Platform Applications

The Tizen platform provides predefined application controls, such as phone, file manager, image viewer, and Internet. You can run Tizen base applications explicitly with the aliased application IDs.

The following code example demonstrates an ApplicationControl interface instance for explicitly launching the image viewer for cropping an image:

/* Assuming that the filesystem virtual root "images" has been resolved and saved in variable images */
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/image/crop",
                                              images.resolve("image12.jpg").toURI(),
                                              "image/*", null , null);
tizen.application.launchAppControl(appControl, "tizen.imageviewer", successCb, errCb, null);

The aliased application ID (tizen.imageviewer) is used, and a crop operation on the image12.jpg file is launched.

Tizen Alias ID is deprecated since Tizen 2.3.1.

Note

If you are unsure about whether a user's device has a specific application, use one of the standard Tizen platform applications, such as the phone, image viewer, or file manager, because some version of these applications is available on all Tizen devices. The platform applications use predefined platform application controls and aliased application IDs, which also simplifies the task of launching them. Tizen Alias ID is deprecated since Tizen 2.3.1.

If you want to select and launch an application that provides a specific operation, you can use the findAppControl() method of Application interface to search for applications providing the functionalities you need. The following code example demonstrates an implicit launch of an application to provide the image crop operation that is found using the findAppControl() method:

/* Assuming that the filesystem virtual root "images" has been resolved and saved in variable images */
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/image/crop",
                                              images.resolve("image12.jpg").toURI(),
                                              "image/*", null , null);
tizen.application.findAppControl(appControl, function(appInfos, appCtrl) 
{
   if (appInfos.length >= 1) 
   {
      tizen.application.launchAppControl(appCtrl, appInfos[0].id, successCB, errCB, null);
   }
}, function(e) {/* Error handling */});

Exporting Application Control Functionality

The system compares the attributes of the application control request against the installed applications to determine which of the available applications is most suitable for the control request. The installed applications have a service description, which contains the information details on what the application can handle. The control request is resolved only if all specified information matches with the service description retrieved from the installed application. The application control data attribute is not used in resolving the control request.

To allow other applications to use the functionalities of your application implicitly without the application ID (basically, to allow the system to launch your application based on a request from another application), you can define 1 or more application control service descriptions in the config.xml file. Each description specifies the operation, URI scheme, and MIME type of the application control service your application can offer.

The following code example demonstrates a service description for an application control for image edition:

<tizen:app-control>
   <src name="edit.html"/>
   <operation name="http://tizen.org/appcontrol/operation/edit"/>
   <uri name="file"/>
   <mime name="image/jpeg"/>
</tizen:app-control>

The src field describes the application page (usually an HTML file) that handles the request. The operation field is mandatory, while the scheme and mime fields are optional. If the value of scheme field is file, the value can be left out.

The uri field in the service description is used to inform the platform about how to interpret and process the rest of the URI. For example, the http URI scheme informs the platform to interpret and process the URI as a Web resource using HTTP. However, if the uri field value is set to file, leave the attribute out of the service description.

For example, consider the following example of an ApplicationControl instance:

/* Assuming that the filesystem virtual root "images" has been resolved and saved in variable images */
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/view",
                                              images.resolve("image12.jpg").toURI(),
                                              null, null , null);

The application with the following service description does not launch based on the above application control request:

<tizen:app-control>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <uri name="file"/>
   <mime name="image/*"/>
</tizen:app-control>

However, the application with the following service description definitely launches:

<tizen:app-control>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <mime name="image/*"/>
</tizen:app-control>

Note that if multiple service descriptions in your application have common parameters (such as the same operation), they must be written out once for each service description and enclosed in a <tizen:app-control> element. For example, if your application can handle both image and audio file MIME types with the view operation, 2 <tizen:app-control> elements with different MIME types and the same http://tizen.org/appcontrol/operation/view operation are required. The service description does not work if the http://tizen.org/appcontrol/operation/view is only written in 1 of the elements. The following example shows how to define the service descriptions for 2 MIME types for the same operation in the config.xml file:

<tizen:app-control>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <mime name="image/*"/>
</tizen:app-control>

<tizen:app-control>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <mime name="audio/*"/>
</tizen:app-control>