6.9.1 GetList

GetList takes a set of input parameters that define filter and sort criteria, and retrieves the metadata of media files based on media and metadata type.

GetList implements the main functionality of Media Management service. It is available only in asynchronous mode.

Input parameter specifies the Type, the metadata of media file to fetch and the criteria for sorting. Input parameter has three properties: Type, Filter, and Sort.

Name	Type	Range	Description
Type	unicode string	`Fileinfo`	Operation performed on the specified type. This field is mandatory.
Filter	map	For more information, refer table 6.187	It specifies the type of media file to fetch, and key for filtering the media files with their range. `FileType` field is mandatory. If key is specified, then it is mandatory to specify the range. You must only mention the StartRange for keys, where EndRange is not applicable. For example, if key is `FileName` then, mention the desired file name in the StartRange and leaving the EndRange empty.
[Sort]	map	For more information, refer table 6.188	It specifies the key name on which the resulting output will be sorted and can be one of the values mentioned in the Value column. By default, sorting is done in ascending order based on the `FileName`.

Key	Value	Type
`FileType`	`Music` `Sound` `Image` `Video` `StreamingURL`	unicode string
`[Key]`	`FileName` `FileExtension` `Drive` `FileSize` `FileDate` `MimeType` `FileNameAndPath` `SongName` `Artist` `Album` `Genre` `TrackNumber` `Composer` `LinkFirstURL`	unicode string
`[StartRange]`	Valid for all keys	unicode string
`[EndRange]`	Valid for the following keys: `FileSize`(bytes) `FileDate`(YYYYMMDD:HHMMSS) For example, 20070303:010101	unicode string

Key	Value	Type
`[Key]`	`FileName` `FileExtension` `Drive` `FileSize` `FileDate` `MimeType` `FileNameAndPath` `SongName` `Artist` `Album` `Genre` `TrackNumber` `Composer` `LinkFirstURL`	unicode string
`[Order]`	Ascending or descending	unicode string

Output contains ReturnValue. It also 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.
`ReturnValue`	Iterable maps	Type: string `FileName`: string `FileExtension`: string `Drive`: string `FileSize`: int `FileDate`: datetime `MediaType`: int `FileNameAndPath`: string `SongName`: string `Artist`: string `Album`: string `Genre`: string `TrackNumber`: string `Composer`: string `MimeType`: string `LinkFirstURL`: string	The output is an iterable which on each invocation returns a map, which will be filled by the service provider. Map stores the key names and its values. The key-value pair that is, Property name and Value in the output map depends upon the file type in the input -Filter map.

Error messages	Description
`MediaMgmt:GetList:Server busy`	Indicates provider is busy in processing another request.
`MediaMgmt:GetList:Type Missing`	Indicates Type parameter is missing.
`MediaMgmt:GetList:Type not supported(should be FileInfo)`	Indicates that the content type is incorrect.
`MediaMgmt:GetList:Filter parameter missing`	Indicates that the Filter parameter which is mandatory is missing.
`MediaMgmt:GetList:Filter parameter type mismatch`	Indicates that the type of Filter parameter is incorrect.
`MediaMgmt:GetList:Sort parameter type mismatch`	Indicates that the type of Sort parameter is incorrect.
`MediaMgmt:GetList:FileType missing in Filter map`	Indicates that `FileType` parameter is not present in Filter map or, `FileType` parameter type is incorrect.

import scriptext
import e32

def media_callback(trans_id, event_id, output_params):
    if trans_id == media_trans_id:
        if event_id == scriptext.EventCompleted:
            song_list = []
            for item in output_params['ReturnValue']:
                song_list.append(item['FileName'])
            print "List of files retrieved:", song_list
        else:
            print "Event ID was not EventCompleted"
    else:
        print "Invalid Transaction ID"
    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',
                                               'Filter': {'FileType': u'Music',
                                                          'Key': u'FileExtension',
                                                          'StartRange': u'.mp3'},
                                               'Sort': {'Key': u'FileName',
                                                        'Order': u'Ascending'}},
                                   callback=media_callback)

lock.wait()

Interface	`IDataSource`
Description	Retrieves the metadata of media files based on media and metadata type.
Response Model	Asynchronous
Pre-condition	Valid service object representing the provider and interface.
Post-condition	Nil