# 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.