6.4.1 GetList

GetList retrieves a list of contacts, contact groups, or contacts databases. Contacts and contact groups are retrieved from the specified contacts database. If no database is specified, from the default one. This method can be called both in synchronous and asynchronous mode.

Interface	`IDataSource`
Description	Retrieves a list of contacts or groups in the default or specified database, also used to get the list of existing databases.
Response Model	Synchronous and asynchronous in case of Third Edition FP2 and Fifth Edition devices, except for `GetList` with Type as Database, which will always be synchronous. In case of Third Edition and Third Edition FP1 devices: Synchronous for Get Single Contact and Group. Asynchronous and synchronous for the rest of the functionality.
Pre-condition	`IDataSource` interface is loaded.
Post-condition	Nil

GetList retrieves a list of contacts objects and metadata from the S60 messaging center based on Search or Sort inputs. This is an object that specifies what contact information is returned and how the returned information is sorted.

Name Type Range Description

Type unicode string Contact
Group
Database Operation is performed on the specified type.

[Filter]

Contact (map)
[DBUri]: unicode string
[id]: unicode string
[SearchVal]: unicode string
Group (map)
[DBUri]: unicode string
[Id]: unicode string
Database
No map required.

DBUri: Database on which search must be performed.
Id: Id is the unique identifier of the contact item or group to be retrieved. If Id is specified, SearchVal and DBUri are not required, and they will be ignored.

SearchVal: Value searched for in the given DBUri. It cannot exceed 255 characters.
If Filter is not supplied and Type is Contact, then it gets all the contacts of the default database.

If Filter is not supplied and Type is Group, then it gets all the groups of the default database.

SearchVal: Value searched for in the given DBUri (If default database is not specified). If SearchVal is not specified then, it loads all the contacts in the database.

SearchVal is looked for in first name and last name fields in case of Third Edition FP2 and Fifth Edition devices and it looks in all fields in case of Third Edition and Third Edition FP1 devices.

With Type as Contact, it retrieves the list of contacts based on the Filter map input (if provided).

With Type as Group, it gets a list of all the groups in the default database, if Filter is not specified. If Filter is specified, and Id is given, it fetches the group that the Id represents (DBUri is ignored in this case). Searching for a group by its name is not supported.

With Type as Database, it gets the list of all the open databases.

Output parameter contains ReturnValue. It also contains ErrorCode and an ErrorMessage if the operation fails. ReturnValue contains complete contact item, group, or database information requested by GetList.

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 list of maps	Contact (map) 6.61 Group (map) 6.62 Database (map) `DBUri`: string	Every Next operation on the iterator returns a map. Each map contains complete contact item/group/database information. Every Next operation on a contact gives a map with: `id`: It is a unique identifier for the contact that the map represents. Key1, Key2..: Gets as many keys available for a particular contact. For more information on keys, refer the section Key Values 6.4.7. Label and value give the information for the key. Next: In case, the key has multiple values, then it is added as another map. Every Next operation on group gives a map with: `id`: It is a unique identifier for the group that the map represents. `GroupLabel`: Label to the group. Contents: List of `ids` of the contacts that belong to the particular group. For example, Contact Id1, Contact Id2. Every Next operation on database gives a map with: `DBUri`: Uri of the database that is represented by the particular map.

Error messages	Description
`Contacts:GetList:Type is missing`	Indicates Type is missing
`Contacts:GetList: Invalid value for Type, Must be Contact/Group/Database`	Indicates invalid value for Type
`Contacts:GetList:Invalid Sort Type, Map is required`	Indicates that the sort order type passed is invalid, map is expected
`Contacts:GetList:Sort Order Value is not a String`	Indicates that the value for order must be a string
`Contacts:GetList:Invalid Type of Filter, Map is required`	Indicates that the value for Filter must be a map
`Contacts:GetList:Wrong Type of Sort Order value`	Indicates that sort order value is not ascending or descending
`Contacts:GetList:Wrong Type of Search value`	Indicates that search value is not a string
`Contacts:GetList:Wrong Type of ContentType`	Indicates that the Type is not a string.

The following sample code illustrates how to list full name of contact matched by last name in asynchronous mode:

import scriptext
import e32

# Using e32.Ao_lock() to make main function wait till callback is hit
lock = e32.Ao_lock()

# Callback function will be called when the requested service is complete
def get_list(trans_id, event_id, input_params):
    if event_id != scriptext.EventCompleted:   
# Check the event status
        print "Error in retrieving required info"
        print "Error code is: " + str(input_params["ReturnValue"]["ErrorCode"])
        if "ErrorMessage" in input_params["ReturnValue"]:
        print "Error message:" + input_params["ReturnValue"]["ErrorMessage"]
    else:
        print "The contacts matching are"
        for i in input_params["ReturnValue"]:
            print i["FirstName"]["Value"] + i["LastName"]["Value"]
    lock.signal()

# Load contacts module
contacts_handle = scriptext.load("Service.Contact", "IDataSource")

event_id = contacts_handle.call('GetList', {'Type': u'Contact', 'Filter':{'SearchVal': u'Craig'}}, callback=get_list)

print "Waiting for the request to be processed!"
lock.wait()
print "Request complete!"