6.2.2 LaunchApp

LaunchApp is used to launch an application. It takes a set of input parameters that define application ID and the options for launching the application.

The following are the examples for using LaunchApp:


appmanager_id = appmanager_handle.call('LaunchApp', {'ApplicationID': u's60uid://0x10005a22'})


appmanager_id = appmanager_handle.call('LaunchApp', 
                                       {'ApplicationID': u's60uid://0x10005a22'},  

where, launch_app_callback is a user defined callback function.

The following table summarizes the specification of LaunchApp:

Interface IAppManager
Description Launches the application based on UID.
Response Model Synchronous and asynchronous
Pre-condition Valid instance of IAppManager interface is instantiated.
Post-condition Nil

Input Parameters

Input parameter specifies the ApplicationID and the mode for launching the application. Input parameter has three properties: application ID, command line argument, and options. Options contain mode, position, and document path.

Table 6.5: Input parameters for LaunchApp
Name Type Range
ApplicationID string s60uid://<UID>
[CmdLine] unicode string Command line argument
[Options] map For detail information on Options, refer to the following table 6.6

Table 6.6: Options that can be used with LaunchApp, default values are emphasized
Key Value
[Mode] Chained or Standalone
[Position] Background or foreground
[DocumentPath] unicode string

In Asynchronous mode the launching application receives the notification when the launched application dies. The notification is not received if this request is cancelled. Cancelling the request does not close the launched application.

Chained mode is applicable for UI based applications only. You will not be able to launch the application in background position in chained mode.

Output Parameters

In asynchronous mode, the input_params that is passed to the callback function contains ErrorCode, and an ErrorMessage if the operation fails.

Table 6.7: Output parameters for LaunchApp
Name Type Range Description
ErrorCode int NA Contains the SAPI specific error code when the operation fails.
ErrorMessage string NA Error Description in Engineering English.


The following table lists the error codes and their values:

Table 6.8: Error codes
Error code value Description
0 Success
1002 Bad argument type
1004 Service not supported
1012 Item not found

Error Messages

The following table lists the error messages and their description:

Table 6.9: Error messages
Error messages Description
AppManager:LaunchApp:Application ID Missing Indicates missing of Application ID or a mismatch in the datatype of the given Application ID.
AppManager:LaunchApp:Command Line type mismatch Indicates a mismatch in the datatype of Command Line.
AppManger:LaunchApp:OptionMap type mismatch Indicates a mismatch in the datatype of Options.


The following sample code illustrates how to launch the Help.exe, in asynchronous mode:

import scriptext
import e32
lock = e32.Ao_lock()

# Callback function will be called when the requested service is complete. 
def launch_app_callback(trans_id, event_id, input_params):
    if trans_id != appmanager_id and event_id != scriptext.EventCompleted:
        print "Error in servicing the request"
        print "Error code is: " + str(input_params["ReturnValue"]["ErrorCode"])
        if "ErrorMessage" in input_params["ReturnValue"]:
            print "Error message is: " + input_params["ReturnValue"]["ErrorMessage"]
        print "Application Launched Successfully: "


# Load appmanage service
appmanager_handle = scriptext.load('Service.AppManager', 'IAppManager')

# Make a request to query the required information in asynchronous mode
appmanager_id = appmanager_handle.call('LaunchApp', {'ApplicationID': u's60uid://0x10005a22'}, callback=launch_app_callback)

print "Waiting for the request to be processed!"
print "Request complete!"

See About this document... for information on suggesting changes.