The Bondi applauncher Module - Version 1.1

February 2010

Authors

Guillermo Caudevilla Laliena <guillermo.caudevilla@vodafone.com>
Pedro Fraca Tarancon <pfracat@corp.vodafone.es>

Abstract

To launch applications from the Web context

1. Introduction
- 1.1. Feature set
- 1.2. Features
- 1.3. Device Capabilities
2. Interfaces
- 2.1. AppLauncherSuccessCallback
- 2.2. AppLauncherManager
- 2.3. AppLauncherManagerObject

Summary of Methods

Interface	Method
AppLauncherSuccessCallback	void onSuccess(StringArray obj)
AppLauncherManager	PendingOperation launchApplication(SuccessCallback successCallback, ErrorCallback errorCallback, DOMString appURI, StringArray params) PendingOperation getInstalledApplications(AppLauncherSuccessCallback successCallback, ErrorCallback errorCallback) DOMString getDefaultApplication(DOMString mimeType)
AppLauncherManagerObject

1. Introduction

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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 through its fully qualified path. 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/1.1/applauncher

All the AppLauncher features

Includes API features:

http://bondi.omtp.org/api/1.1/applauncher.launch
http://bondi.omtp.org/api/1.1/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

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

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

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

Call to AppLauncherManager methods launchApplication

Device capabilities:

applauncher.launch

http://bondi.omtp.org/api/1.1/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.
"camera" Camera application.
Empty Bag An application not recognised as one of the above.
appparam: Parameter to application; meaning dependent on knownname.
path: allows limiting filesystem location from which applications can be launched

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 or the handler for a given mime type complete 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);

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

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

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

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://

If the method is executed successfully the successcallback is raised If the access is denied by the Security Policy, the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR If an invalid parameter is passed such as malformed URIs (protocol not supported or invalid URI parameters), the ErrorCallback will be invoked with an DeviceAPIError INVALID_ARGUMENT_ERROR If the application is not found, the ErrorCallback is invoked with a DeviceAPIError NOT_FOUND_ERROR

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

API features

http://bondi.omtp.org/api/1.1/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 returned strings are fully qualified application paths

Signature

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

Asynchronous method.

If the method is executed successfully the successCallback is raised. If no applications are installed in the device an empty array will be returned to the successCallback If the access is denied by the Security Policy, the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR If an invalid parameter is passed the ErrorCallback will be invoked with an DeviceAPIError INVALID_ARGUMENT_ERROR

Parameters

successCallback: uses the response object to retrieve the array of strings with the fully qualified path to the application in the terminal file system.
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

API features

http://bondi.omtp.org/api/1.1/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 fully qualified 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 for the default handler for a given mime type.

Signature

DOMString getDefaultApplication(in DOMString mimeType);

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

Parameters

mimeType: String containing the MIME Type.

Return value

DOMString the fully qualified 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.

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, "file://" + app, "/text.txt");

2.3. `AppLauncherManagerObject`

Specifies what is instantiated at feature request

        interface AppLauncherManagerObject {
                readonly attribute AppLauncherManager applauncher;
        };

        Bondi implements AppLauncherManagerObject;

The Bondi applauncher Module - Version 1.1

February 2010

Authors

Abstract

Table of Contents

Summary of Methods

1. Introduction

1.1. Feature set

1.2. Features

1.3. Device capabilities

2. Interfaces

2.1. AppLauncherSuccessCallback

Methods

Signature

Parameters

2.2. AppLauncherManager

Methods

Signature

Parameters

Return value

API features

Code example

Signature

Parameters

Return value

API features

Code example

Signature

Parameters

Return value

Exceptions

Code example

2.3. AppLauncherManagerObject

2.1. `AppLauncherSuccessCallback`

2.2. `AppLauncherManager`

2.3. `AppLauncherManagerObject`