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.

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.

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

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!"
        return

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

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

    lock.signal()


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'}}, 
                                   callback=media_callback)

lock.wait()