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.

The following are the examples for using LaunchDoc:


appmanager_id = appmanager_handle.call('LaunchDoc', 
                                       {'Document': {'DocumentPath': u'c:\\data\\beak.jpg'}})


appmanager_id = appmanager_handle.call('LaunchDoc', 
                                       {'Document': {'DocumentPath': u'c:\\data\\beak.jpg'}}, 

where, launch_doc_callback is a user defined callback function.

The following table summarizes the specification of LaunchDoc:

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

Input Parameters

Input parameter specifies the DocumentPath, MimeType, and mode options.

Table 6.10: Input parameters for Launchdoc
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.

Chained mode is applicable for UI based applications only.

Output Parameters

Output parameters contain ReturnValue. They also contain ErrorCode, and an ErrorMessage, if the operation fails.

Table 6.11: Output parameters for LaunchDoc
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.


The following table lists the error codes and their values:

Table 6.12: Error codes
Error code value Description
0 Success
1004 Service not supported
1012 Item not found

Error Messages

The following table lists the error messages and their description:

Table 6.13: Error messages
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"]
        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
# 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!"
print "Request complete!"

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