The PIM API refers to the databases as PIMList objects.
A PIMItem represents a collection of data for a single
PIM entry. Three types of PIMList are supported by the
API: ContactList, EventList, and ToDoList.
The PIM class has two openPIMList methods
to get access to a given PIMList. The method will take
the type of database and access mode used (READ_ONLY, WRITE_ONLY, READ_WRITE).
The PIM class is a singleton that can be obtained using
the getInstance() static method. To reduce the need for
security permissions, it is recommended that you request the minimum access
rights needed when opening a database.
Each database is identified by a unique name that is used when opening
the database. This name is implementation dependent but the listPIMLists method
can be used to get a list of all the database names available for a given
type. Moreover, in S60 and
Series 40 devices this name corresponds to the localized name of
the database. This means that the main contacts database could be called "Contacts,"
"Contactos," or "Puhelinluettelo," depending on the device's language. In
addition, high-end devices have the ability to let the user customize this
name or create new lists. Therefore, it is strongly advised to call the listPIMLists method
instead of using a hard-coded list name when opening a database.
PIMList contains several items() methods
to access the full content of PIMItems and selecting
a particular subset of them. These methods should be used with care since
they can be slow if the underlying database is very large.
PIMList also supports creating, modifying, and
deleting PIMItems. It is important to notice that when
creating new items or modifying existing ones, the modifications are not reflected
in the native database until the commit() method is called.
On the contrary, deleting an entry is done immediately upon request. To perform
any of these operations, the database has to be open in either WRITE_ONLY or READ_WRITE mode.
There are three types of PIMItems corresponding
to each type of PIMList: Contact, Event,
and ToDo. They contain the actual data for a particular
item. The data is stored in fields that contain data such as telephone numbers
or addresses. These fields are different for Contact, Event,
and ToDo objects and are identified by numerical constants
defined on each of the interfaces. A field may contain more than one entry
for the same field type, for instance, a Contact may
contain multiple telephone numbers.
Each PIMList doesn't necessarily support all the
fields described in the API. Instead, each implementation will define the
supported fields, and in case of Nokia devices, this corresponds to the fields
on the underlying native database. (For a list of supported fields, see PIM
API Implementation notes.) Hence, it
is highly recommended to make sure that a field is available in a given PIMList by
calling the isSupportedField() or getSupportedFields() methods
before attempting to read a field.
Note that even databases residing in the same device may have a different
set of fields; for example, the contact list from a device's memory contains
several extra fields compared to the contact list stored in a SIM card which
contains only two fields. These different sets of fields should be accounted
for when designing an application so that it is compatible with a wide variety
of devices. Each supported field may contain zero or more entries for a given PIMItem.
The countValues() method should be used to ensure that
a PIMItem's field has been populated and to count how
many entries it contains. Failing to do so may lead to IndexOutOfBounds exceptions
being thrown.
Each entry may also have extra attributes to further describe an item.
For example, Contact.TEL fields frequently have attributes
to indicate if it is a fixed line, a fax, or a mobile line number. It is important
to verify that a PIMList supports the attributes you
are interested in; this can be done by using the isSupportedAttribute() and getSupportedAttributes() methods.
The fields and attributes described in the API are logical values, and
often it is necessary to produce a human-readable label for a specific item.
The getFieldLabel() and getAttributeLabel() methods
in PIMList will return localized labels as indicated
by the implementation. The getSupportedFields() method
is also useful for a good user interface, given that it returns the supported
fields in the order recommended for the device's UI.
The API also supports categories to group sets of fields. S60 and Series 40 devices support categories conforming to the support for them in the native databases.
The PIM API contains methods for serializing and deserializing PIMItems thus
enabling MIDlets to operate with external applications. The serialization
format is the standard vCard for Contacts and vCalendar
for Event and ToDo items. The exact
version of the supported standards is implementation dependent and it can
be obtained with the PIM.supportedSerialFormats method.
When it is necessary to verify that the PIM API is actually available
in a particular device, the system property microedition.pim.version should
be checked. If the package is available, this property will contain the version
of the API available, currently version 1.0, otherwise it will be null.