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.

Note: Calls that retrieve a list of databases must be synchronous.

The following are the examples for using GetList:


list_contacts = contacts_handle.call('GetList', {'Type': u'Contact', 'Filter': {'SearchVal': u'Daniel'}})


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

where, get_list is a user defined function.

The following table summarizes the specification of GetList:

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

Input Parameters

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.

Table 6.59: Input parameters Getlist
Name Type Range Description
Type unicode string Contact
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
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 Parameters

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.

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

Table 6.61: Contact(map)
Key Value NA NA
id string NA NA
Key1 map NA NA
NA Label NA string
NA Value NA string
Key2 map NA NA
NA Label string NA
NA Value string NA
NA Next map NA
NA NA Label string
NA NA Value string
NA NA Next map

Table 6.62: Group(map)
Key Value
id string
GroupLabel string
Contents List
NA Contact id1
NA Contact id2
NA ....


The following table lists the errors and their values:

Table 6.63: Error codes
Error code value Description
0 Success
1002 Bad argument type

Error Messages

The following table lists the error messages and their description:

Table 6.64: Error messages
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"]
        print "The contacts matching are"
        for i in input_params["ReturnValue"]:
            print i["FirstName"]["Value"] + i["LastName"]["Value"]

# 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!"
print "Request complete!"

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