6.2.3 LaunchDoc

LaunchDoc is used to launch a document in standalone mode or embedded mode. It takes a set of input parameters that specifies the DocumentPath, MimeType, and options.

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

Name	Type	Range	Description
Document	map	Key: `DocumentPath` or `Handle` Value: `string`	Specifies path of the document to launch. If `MimeType` is not given in input then, it is mandatory to give document as input parameter. If Handle and DocumentPath both are present in map then Handle will get preference.
`MimeType`	unicode string	NA	`MimeType` of the application to be Launch. If document is not given in input then it is mandatory to give `MimeType` as input parameter.
[Options]	map	Key: `Mode` Value: Chained or Standalone	By default the mode is Standalone.

Launchdoc finds the Handler application internally, in the absence of MimeType. It launches the application based on the MIME type and returns the path of the new document, if the Document is absent from the input.

In Asynchronous mode the launching application receives a 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.

Output parameters contain ReturnValue. They also contain 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.
[ReturnValue]	string	`LaunchDoc` returns the document name if it creates a new one. (that is, Return value is optional as only some application creates default document.) If `Document` is not mentioned and only the `MimeType` is mentioned, then application is launched based on the `MimeType` and returns the default document of the application. Creation of the default document depends upon the launched application.

Error code value	Description
`0`	Success
`1004`	Service not supported
`1012`	Item not found

Error messages	Description
`AppManager:LaunchDoc: Document/MimeType Missing or datatype mismatch`	Indicates missing of `Document` or `MimeType` or a mismatch in the datatype of the given `Document` or `MimeType`.
`AppManager:LaunchDoc: OptionMap type mismatch`	Indicates a mismatch in the datatype of Command Line.
`AppManager:LaunchDoc: OptionMap type mismatch`	Indicates a mismatch in the datatype of Options.

The following sample code illustrates how to launch an application on S60 device, in asynchronous mode:

import scriptext
import e32
lock = e32.Ao_lock()

# Callback function will be called when the requested service is complete
def launch_doc_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
# Path dependent on the environment on which the application is run
appmanager_id = appmanager_handle.call('LaunchDoc', {'Document': {'DocumentPath': u'c:\\data\\beak.jpg'}}, callback=launch_doc_callback)
print "Waiting for the request to be processed!"
lock.wait()
print "Request complete!"