Accessing and managing information about contacts

The Contacts Service API allows widgets to access and manage information about contacts. This information can reside in one or more contacts databases stored on a device or in the SIM card database. You can use the Contacts Service to create widgets that:

  • Retrieve information about contacts, contact groups, and contacts databases

  • Create, edit, and delete contacts and contact groups

  • Import and export contacts

  • Organize contacts into contact groups

The default contacts database is stored on the device and its URI is cntdb://c:contacts.cdb. It is created when the first contact is added to it. The URI for the SIM card database is sim://global_adn.

Accessing the API and supported methods

To create a service object for the Contacts Service API, use Service.Contact to identify the service provider and IDataSource to identify the supported interface:

var so = device.getServiceObject("Service.Contact", "IDataSource");

The IDataSource interface provides the following methods:

  • GetList()

    Use the GetList() method to retrieve information about contacts, contact groups, or contacts databases.

  • Add()

    Use the Add() method to add a contact or contact group to a contacts database. You can also use this method to edit an existing contact or contact group.

  • Delete()

    Use the Delete() method to delete one or more contacts or contact groups from a contacts database.

  • Import()

    Use the Import() method to import a contact to a contacts database. The information must be imported from a vCard file.

  • Export()

    Use the Export() method to export a contact from a contacts database. The information is exported to a vCard file.

  • Organise()

    Use the Organise() method to add contacts to a contact group or to remove contacts from a contact group.

  • Cancel()

    Use the Cancel() method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Contacts Service API.

Using the service in a widget

To access and manage information about contacts using the Contacts Service API:

  1. Create a service object for the API using device.getServiceObject().

  2. Define the tasks you want to perform and choose the correct methods for them.

  3. Optionally, define how you want the results filtered.

  4. Define a handler method to process the results.

  5. Use the methods defined in step 2 to perform the tasks. Use asynchronous methods together with callback().

  6. Process the results in the handler method defined in step 4.

For the complete source of a sample widget that demonstrates how to use this service, see the full example.

© Nokia 2008.