LaunchApp()

Description:

The LaunchApp method launches an application based on a unique ID for the application (UID). It also provides a way to open a specific document (by specifying a document path), even if it is not the default file type for the application being launched.

The application can be launched as chained (embedded) or standalone. For more information about embedded and standalone applications, see section Accessing and launching installed applications.

This method can be called both synchronously and asynchronously.

Syntax:

For synchronous calls:

LaunchApp(parameters:Object):Object

For asynchronous calls:

LaunchApp(parameters:Object, callback:Object):Object

Arguments:

  • parameters:

    This is an object that specifies which application to launch. For more information about the object properties and how to define them, see section Parameters for launching an application.

  • callback:

    The callback argument is the name of the method that is executed when an asynchronous LaunchApp call has status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method.

    This argument is used only with an asynchronous LaunchApp call.

Return value:

If synchronous, the LaunchApp method returns an object that contains an error code and an error message.

Table: Return value properties for a synchronous LaunchApp

Property

Description

Value

ErrorCode

This is a number that specifies a predefined error code.

See Service API error codes.

ErrorMessage

This is a text string that describes the error.

If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message (see the following table). When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).

Note: If Cancel is called on an ongoing asynchronous request, LaunchApp will not return a notification when the launched application terminates.

Table: Return value properties for an asynchronous LaunchApp

Property

Description

Value

TransactionID

This is a number used as an identification to match transactions started with the asynchronous LaunchApp call to one or more calls it generates to callback.

  

ErrorCode

This is a number that specifies a predefined error code.

See Service API error codes.

ErrorMessage

This is a text string that describes the error.

Remarks:

Use the GetList method to retrieve the unique ID of the application to launch.

Example code:

The following sample code illustrates how to launch the camera application synchronously:

import com.nokia.lib.Service;
var appManager = new Service("Service.AppManager", "IAppManager");
var inParams = {ApplicationID:"s60uid://0x101F857A"};//camera UID 
var outParams = appManager.LaunchApp(inParams);
var errorId = outParams.ErrorCode;

The following sample code illustrates how to launch the audio application asynchronously:

import com.nokia.lib.Service;
var appManager = new Service("Service.AppManager", "IAppManager");
var inParams = {ApplicationID:"s60uid://0x100058CA"};//sound application UID
appManager.LaunchApp(inParams, onApplaunch);
function onApplaunch(transactionID:Number, eventID:String, outParam:Object) {
  var errorId = outParam.ErrorCode;
}
© Nokia 2009.