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.

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

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

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

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

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.

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

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.

Error code value	Description
`0`	Success
`1002`	Bad argument type
`1004`	Service not supported
`1012`	Item not found

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"]
    else:
        print "Application Launched Successfully: "

    lock.signal()

# 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!"
lock.wait()
print "Request complete!"