The PIM API refers to databases as PIMList objects. A PIMItem represents a collection
of data for a single PIM entry. The PIM API supports three types of PIMLists:
ContactList
EventList
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 Series 40
and Symbian 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. Series 40 and Symbian 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.
For more information about using the PIM API, see the following sections: