Java Reference
In-Depth Information
elements matching the element passed as a parameter to this method. Finally, a
close()
method is
provided.
The functionality to get access to the contact list(s) stored on the device is provided by the PIM class.
The PIM class provides two static
openContactList()
methods and one method for retrieving the
names of the non-default contact databases. The first
openContactList()
method takes the mode
in which the contact database should be opened, either
PIM.READ_ONLY
or
PIM.READ_WRITE
.
This method is used to open the default contact database. The second
openContactList()
method
takes two parameters: the mode and the contact database name. In order to get an overview of all
possible contact database names, the
listContactLists()
method is supported; it returns a string
array containing the database names. The first entry in the array contains the name of the default
database.
Now you are able to create a new
Contact
associated with the default
ContactList
and fill it with
personal information, as shown in the code snippet below:
ContactList myContacts = PIM.openContactList (PIM.READ_WRITE);
Contact myContact = list.createContact;
myContact.setString(Contact.FORMATTED_NAME, "John Smith");
myContact.setString(Contact.TEL, TYPE_WORK, "555-1177");
myContact.setString(Contact.TEL, TYPE_HOME, "555-7711");
Once the contact is created, it can be added to the default contact database:
myContact.commit();
myContacts.close();
The second operation that is of importance when using a contact database is to update an already
existing element. This might be necessary, for example, if the phone number of a given contact has
changed. In order to update an element of the
ContactList
, you need to get the instance of the
Contact
first. The
ContactList
provides an
element()
method for searching existing
Contact
s, taking a
Contact
template as parameter. The template is filled with the information the
search is based on. The
element()
method returns an enumeration containing all
Contact
s
matching the template. A partially filled
Contact
object is used as template.
In the following code snippet, you can see how to retrieve a given contact, update a phone number, and
then write it back to the database. There is no check whether the enumeration contains more than one
elements. In a real application, a corresponding test would be appropriate:
ContactList myContacts = PIM.openContactList (PIM.READ_WRITE);
Contact matchContact = myContacts.create();
matchContact.setString(Contact.FORMATTED_NAME, "John Smith");
Enumeration enum = myContacts.elements(matchContact);
Contact myContact = (Contact)enum.nextElement();
myContact.setString(Contact.TEL, TYPE_HOME, "555-1177");
myContact.commit();
myContacts.close();
In order to make sure that only the desired contact is returned, the UID field could be used in the
template instead of the formatted name. Another important operation provided by the
ContactList
is the ability to delete a previously added
Contact
from the database. This can be performed by
passing the element to be deleted to the
removeElement()
method. So, you have to read the
particular contact as you did when updating a contact. You can use the same code snippet used for
updating a contact, except that you don't call
setString()
to modify a phone number; instead, you
pass the element stored in
myContact
directly to the
removeContact()
method after you read it
from the enumerator. This procedure is shown in the following code snippet:
Search WWH ::
Custom Search