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:

Create a service +object for the API using device.getServiceObject().
+
Define the +tasks you want to perform and choose the correct methods for them.
+
Optionally, +define how you want the results filtered.
Define a handler +method to process the results.
Use the methods +defined in step 2 to perform the tasks. Use asynchronous methods together +with callback().
+
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.