6.1.4 Making Asynchronous Request

For making an asynchronous request, a call back function needs to be defined and passed as an additional parameter to the call() API.


result = service_instance_object.call(operation, parameters, callback=callback_function)


The operation argument describes the service requested from the service provider. The parameters argument is a dictionary, which specifies input parameters to the specified request.

callback_function is an user defined callback function.

The following sample code illustrates how to define a callback handler function to handle the response from an asynchronous request:

def callback_function(transactionID, eventID, outParam)

The following table describes the arguments of the call back function:

Argument Description Value
transactionID This is the unique transaction ID associated with the particular asynchronous request. It is returned as part of the result of the initial asynchronous call.
eventID Specifies the asynchronous operation status. For a complete list of EventID, see EventID 6.12.2 section in the Appendix.
outParam This argument is a dictionary that holds the output of an asynchronous call. Refer to the following table for the dictionary items in outParam.

The outParam argument of callback method is a map containing the return value, an error code, and an error message.

Properties Description Values
ReturnValue This key contains the information requested by the asynchronous call that initiated the callback.

This key is present only if the requested service has a value to return. In this case, outParam contains only ErrorCode and ErrorMessage.

Depends on the Platform Service API and the asynchronous method that was called. Not all calls return this property.
ErrorCode Specifies a pre-defined error code For detail information about Platform Service API error codes and their descriptions, see Service API Error Codes and Description 6.12.1 section in the Appendix.
ErrorMessage Describes the error Depends on the Platform Service API and the asynchronous method that is called.


The following sample code illustrates how to retrieve media files from a database, using the operation:

import scriptext
import e32

def media_callback(trans_id, event_id, output_params):
    # Check if we are interested in this transaction
    if trans_id == media_trans_id:
        print "Not the transaction in which we are interested!"

    # Check if the transaction is complete
    if event_id != scriptext.EventCompleted:
        print "Transaction not complete!"

    # Check if the transaction has resulted in any error
    if output_params['ReturnCode'] != 0:
        print output_params['ReturnMessage']
        song_list = []
        for item in output_params['ReturnValue']: 
        print "List of files retrieved:", song_list


lock = e32.Ao_lock()
media_handle = scriptext.load('Service.MediaManagement', 'IDataSource')

# Request for the list of mp3s in ascending order

media_trans_id = media_handle.call('GetList', 
                                   {'Type': u'FileInfo': u'FileExtension', 
                                               'StartRange': u'.mp3'},
                                    'Sort': {'Key': u'FileName', 'Order': u'Ascending'}}, 


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