Contacts databases

The ContactList class represents a database containing contacts. The Contact class is used to represent individual contacts. You can use ContactLists to access the contacts information available on a device.

Series 40 and Symbian devices have at least one native contacts database available: the default contacts database. However, devices commonly have two separate contacts databases: the default one stored on the device, and another one for contacts stored on the SIM card. Depending on the device, even more databases can be available.

Accessing contacts databases

To access a specific contacts database on a device:

Retrieve the names of all available contacts databases by using the PIM.listPIMLists method:
```
PIM pim = PIM.getInstance();
String[] contactsDbNames = pim.listPIMLists(PIM.CONTACT_LIST);
```
The database names are localized, so the exact names returned by the method depend on the locale selected on the device. Moreover, different devices can use different names for the standard contacts databases. In some cases, the names can even be user-defined. Therefore, never hard-code the names in a MIDlet, but rather obtain them dynamically by using the PIM.listPIMLists method as shown above.
Typically, the first name returned in the string array identifies the default contacts database stored on the device, and the second name identifies the contacts database stored on the SIM card.
Select the name of the database you want to access. You can either force the selection yourself by selecting a specific item from the string array returned by the PIM.listPIMLists method, or you can allow the user to select the name from a list of available databases. If you want to access the default contacts database, select the first item from the string array returned by the PIM.listPIMLists method:
```
String contactsDbName = contactsDbNames[0];
```
Open the database by using the PIM.openPIMList(int pimListType, int mode, String name) method, with the name of the database specified in the name parameter:
```
ContactList contactsDb = (ContactList)pim.openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, contactsDbName);
```
Alternatively, if you are accessing the default contacts database, use the PIM.openPIMList(int pimListType, int mode) method, which opens the default database of the specified type directly:
```
ContactList contactsDb = (ContactList)pim.openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
```
If you use this approach, you do not need to separately retrieve and select the database name.
Use the ContactList and Contact methods to read and write data from and to the opened database.

More information

For information about the supported ContactList fields and attributes, see the PIM API implementation notes.

For examples on using the phone book and other contacts functions on a device, see the following articles in the Nokia Developer Wiki: