Criteria for retrieving contact information

The criteria object specifies what contact information is returned and how the returned information is sorted.

Each GetList call targets one type of contact information:

  • Contacts are individual contact entries in a contacts database. You can retrieve a specific contact or a list of contacts depending on the filtering criteria.

  • Contact groups are associations that group individual contacts together by ID. You can retrieve a specific group or a list of groups depending on the filtering criteria.

  • Contacts databases are databases that store information about contacts and contact groups. You can retrieve a list of all the open databases.

The criteria object has three main properties: Type, Filter, and Sort. These are described in the following table. Properties enclosed in brackets are optional.

Note: All string values in the object are Unicode.

Table: Criteria object properties

Property

Description

Type

Value

criteria.Type

Specifies the type of contact information to retrieve.

Note: If this property is set to "Database", the call automatically retrieves a list of all available databases. No Filter criteria are used.

string

Possible values:

  • "Contact"

  • "Group"

  • "Database"

[criteria.Filter]

Specifies how the information to be retrieved is filtered.

This property is valid only if Type is "Contact" or "Group".

If this property is not specified and Type is "Contact", then all contacts are retrieved from the default database.

If this property is not specified and Type is "Group", then all contact groups are retrieved from the default database.

object

Object with the properties specified below

[criteria.Filter.DBUri]

Specifies the contacts database from which to retrieve the information.

If this property is not specified, the default database is used.

string

  

[criteria.Filter.id]

Specifies the unique identifier of the contact or contact group to retrieve.

If this property is specified, Filter.DBUri and Filter.SearchVal are ignored.

string

  

[criteria.Filter.SearchVal]

Specifies a text string by which to search for contacts. The search is based on first name and last name. Any contact whose first name or last name contains this string is retrieved.

If this property is not specified, all contacts are retrieved from the database.

Note: This property is valid only if Type is "Contact".

string

The string cannot exceed 255 characters.

[criteria.Sort]

Specifies how the returned list of information is sorted.

Sorting is based on last name and first name, in that order of priority. By default, sorting is done in ascending order.

Note: Sorting is done only if Type is "Contact". Sorting is not supported for calls whose Type is "Group" or "Database".

object

Object with the properties specified below

[criteria.Sort.Order]

Specifies the sort order.

string

Possible values:

  • "Ascending"

  • "Descending"
© Nokia 2009.