Bondi logo

The Bondi applauncher Module - Version 1.1

12 May 2009

Authors

© 2009 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

To launch applications from the Web context

Table of Contents

Summary of Methods

InterfaceMethod
AppLauncherSuccessCallbackvoid onSuccess(StringArray obj)
AppLauncherManagerPendingOperation launchApplication(SuccessCallback successCallback, ErrorCallback errorCallback, DOMString appURI, StringArray params)
PendingOperation getInstalledApplications(AppLauncherSuccessCallback successCallback, ErrorCallback errorCallback)
DOMString getDefaultApplication(DOMString mimeType)
AppLauncherManagerObject

1. Introduction

The BONDI applauncher interface provides access to the installed applications. It also provides access to the native applications such as messaging, telephony and newly installed applications.
This API creates (or represents) a link between the standard URI prefix and native applications, following is a list of the minimum supported protocols and their native applications:
- http,https: default browser installed in the device.
- tel: default telephony application
- sms: default sms composing application
- mailto: default email composing application
-file: access to any file stored in the device. The file will be opened with its default application. also an executable would be pointed using this protocol. If a executable is pointed the application will be launched with the possibility to pass parameter to this application. You can launch applications using the applauncher.launchApplication method.

This API provides functionality to run the installed applications in the device. The application listed using this option are those that have been registered in the system. Not all the executables are listed using this functionality. You can get the installed applications using the applauncher.getInstalledApplications method.

This API provides functionality to get the default application for a given MIME type. The MIME types supported are those that the device has applications to manage them. You can get the default applications for a given MIME type using the applauncher.getDefaultApplication method.

1.1. Feature set

This is the URI used to declare this API's feature set, for use in bondi.requestFeature. For the URL, the list of features included by the feature set is provided.

http://bondi.omtp.org/api/applauncher

All the AppLauncher features

Includes API features:

  • http://bondi.omtp.org/api/applauncher.launch
  • http://bondi.omtp.org/api/applauncher.get

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

When any of the features

is successfully requested, the interface AppLauncherManager is instantiated, and the resulting object appears in the global namespace as Bondi.appLauncherManager.

http://bondi.omtp.org/api/applauncher.launch

Call to AppLauncherManager methods launchApplication

Device capabilities:

  • applauncher.launch
http://bondi.omtp.org/api/applauncher.get

Call to AppLauncherManager methods for getting list of applications

Device capabilities:

  • applauncher.get

1.3. Device capabilities

applauncher.launch

Launches an application stored in the phone terminal

Security parameters:

  • knownName: Known name of application, from the list given after this table. Empty bag if application being launched does not have a well Known name. The Known application name is determined by the implementation from the information provided in the API.
    List of known names:
    "browser" Browser application.
    "email" Email sending application.
    "phone" Phone application
    "sms" SMS application
    "mms" MMS application
    "mediaplayer" Media player application.
    Empty Bag An application not recognised as one of the above.
  • appParam: Parameter to application; meaning dependent on knownName.
  • path: allow or deny to launch a given application path
applauncher.get

Gets the list of installed applications or the default one for a given mime type

2. Interfaces

2.1. AppLauncherSuccessCallback

Success callback for retrieving a list of applications 

        [Callback=FunctionOnly, NoInterfaceObject] interface AppLauncherSuccessCallback {
                void onSuccess(in StringArray obj);
        };

Success callback that is used in the asynchronous operation to retrieve a list of applications.

Methods

onSuccess

The callback that is invoked when retrieving the list of applications completes successfully.

Signature
void onSuccess(in StringArray obj);
Parameters
  • obj: A string array containing the list of Application URIs.

2.2. AppLauncherManager

Application management base interface 

         interface AppLauncherManager {

                PendingOperation launchApplication(in SuccessCallback successCallback,
                                                   in ErrorCallback errorCallback,
                                                   in DOMString appURI,
                                                   [Optional] in StringArray params)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation getInstalledApplications(in AppLauncherSuccessCallback successCallback,
                                                          in ErrorCallback errorCallback)
                        raises(DeviceAPIError);

                 DOMString getDefaultApplication(in DOMString mimeType)
                        raises(DeviceAPIError);
        };

The application manager interface offers methods concerned with retrieving and launching applications.

Code example
        // Define the launchApplication success callback.
        function appSuccessCallback(response) {
                // Application launched successfully.
        }

        // Define the requestFeature success callback.
        function successCallback(response) {
                // Feature acquired successfully - now launch an application.
                bondi.appLauncher.launchApplication(appSuccessCallback,errorCallback,"tel:+34666666666");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", occurred");
        }

        // Request the applauncher feature.
        bondi.requestFeature(successCallback, errorCallback, "applauncher");

Methods

launchApplication

Launches an application addressed by an URI string.

Signature
PendingOperation launchApplication(in SuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString appURI, in StringArray params);

Asynchronous method.


The following URIs are the minimal set that are supported
- http://
- https://
- tel:
- mailto:
- sms:
- file://

Parameters
  • successCallback: function called when the application is launched successfully.
  • errorCallback: function called when an error occurs, the input parameter is a DeviceAPIError object with error code giving information about the type of error that occurred.
  • appURI: URI string for the application to be launched. Known name will be a valid application to be launched.
  • params: Optional array of Strings containing extra parameters to be passed to the applicationURI when the URI prefix used is "file" (command line format, i.e. "file://windows/app.exe param1 param2").
Return value
PendingOperation object providing the ability to cancel the pending asynchronous operation
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    NOT_FOUND_ERROR if the application given to be launched is not found

    INVALID_ARGUMENT_ERROR If an invalid parameter is given (Datatype Mismatch) If the URI passed as appURI is malformed (Protocol not supported or invalid URI parameters). If params are wrong (parameter is wrong for the application given in the appURI)

API features
http://bondi.omtp.org/api/applauncher.launch
Code example
        // Define the success callback.
        function successCallback(response) {
                alert("Application launches successful");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", occurred launching an application");
        }

        // launch the phone application
        bondi.applauncher.launchApplication(successCallback,errorCallback,"tel:+34666666666");

        // launch the browser with the http address passed as parameter
        bondi.applauncher.launchApplication(successCallback,errorCallback,"http://www.huescalamagia.es");
getInstalledApplications

Returns an array of strings containing the installed applications on the device. (applications that have somehow been registered in the platform). The format of the strings returned would be one of the following two ways: - If the application is from the list of known names the application string returned will be the known name (known names were explained earlier in this document) - If the application is amongst the list of known names, but is registered in the device registry then ´file:// + application path´ string will be returned.

Signature
PendingOperation getInstalledApplications(in AppLauncherSuccessCallback successCallback, in ErrorCallback errorCallback);

Asynchronous method.

Parameters
  • successCallback: uses the response object to retrieve the array of strings with the path to the application in the terminal file system. If application is one of the known names, the known name will be returned instead of the path.
  • errorCallback: function called when an error occurs, the input parameter is an Error object with the error code giving information about the type of error that occurred.
Return value
PendingOperation object which can be used to cancel the underlying asynchronous operation
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR If an invalid parameter is given (DataType mismatch)

API features
http://bondi.omtp.org/api/applauncher.get
Code example
        // Define the launchApplication success callback.
        function launchedCallback(response)
        {
                alert("Application launched successful");
        }

        // Define the getInstalledApplications success callback.
        function successCallback(response) {
                // Response is an array of application paths - let's launch the first application.
                bondi.applauncher.launchApplication(launchedCallback,errorCallback,"file://"+ response[0]);
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", occurred");
        }

        // Get the installed applications.
        bondi.applauncher.getInstalledApplications(successCallback,errorCallback,null);
getDefaultApplication

Returns the application path URI (file://) for a given mime type.

Signature
DOMString getDefaultApplication(in DOMString mimeType);

If the default application is one of the known names, the known name will be returned

Returns null if no default application is found for the given MIME Type

Parameters
  • mimeType: String containing the MIME Type.
Return value
DOMString the path where the application is stored in the terminal file system
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid MIME type is given. The supported MIME types are the same as the terminal has registered.

API features
http://bondi.omtp.org/api/applauncher.get
Code example
        // Define the success callback.
        function successCallback(response) {
                alert("Application launches successful");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", occurred launching an application");
        }

        // Get the default application for the text/plain mime type.
        var app = bondi.applauncher.getDefaultApplication("text/plain");
        
        // Launch the application.
        bondi.applauncher.launchApplication(successCallback,errorCallback,app,"/text.txt", null);

2.3. AppLauncherManagerObject

Specifies what is instantiated at feature request 

        interface AppLauncherManagerObject {
                readonly attribute AppLauncherManager appLauncherManager; 
        };
        Bondi implements AppLauncherManagerObject;