BlackBerry Application Developer guide pim api (1)

In the previous sections, we talked about the BlackBerry Application Developer guide Mail API and the BlackBerry Application Developer Guide using controlled APIs. This article will introduce BlackBerry's pim api to you, java Personal Information Manager (PIM) API (javax. microedition. pim) and BlackBerry PDAP (Personal Digital Assistant Profile) API (net. rim. blackberry. api. pdap) allows you to access calendars, tasks, and address books on BlackBerry devices.

Note: In version 4.0, net. rom. blackberry. api. the pim package is not in favor of use. now the class in this package is in javax. microedition. pim and net. rim. blackberry. api. pdap .)

The PIM class is an abstract class that provides methods to access the PIM data on BlackBerry devices.

Get a PIM object

Call PIM. getInstance ().

Note: When your application accesses the pim api for the first time, it will check a ControlledAccessException. If the system administrator uses the application to control access to the pim api, a runtime exception will be thrown .)

PIM list

The PIM column interface represents all contacts, events, and common functions of the task column. A column contains 0 or more items, which are subclasses of PIMItem. use the PIM column to organize related items and obtain some or all items in the list.

Note: On a BlackBerry device, each ContactList, ToDoList, or EventList instance involves a local database on the BlackBerry device. A third-party application cannot create a custom list .)

PIM item

The PIMItem interface represents a common function of a column item. Contact, Event, and ToDo interface extends PIMItem. a pim item represents a data set of a single entry, such as a appointment or a Contact.

When you create a PIM item in a specified PIM list, this item is still associated with the list since it exists. you can also use standard formats such as iCal and vCard to import or export data in PIM items.

Field

A pim item stores data in fields. each PIMItem interface-Contact, Event, or ToDo-defines a unique ID for each supported field. for example, the Contact interface defines a field to store an internet Message Address (EMAIL), name (FORMATTED_NAME), and telephone number (TEL ).

Call PIMList. isSupportedField (int) to confirm whether the method is supported before you try to set or obtain the field value.

A field may have a descriptive label associated with it displayed to the user. To obtain the label of this field, call PIMList. getFieldLabel (int ).

Each field has a data type ID, such as INT, BINARY, DATE, BOOLEAN, or STRING. To obtain a data row of a field, call PIMList. getFieldDataType (int ).

The data type determines which method you will use to obtain or set the field data. For example:

◆ If the field data type is STRING, to add a value, call PIMItem. addString (String ).

◆ To change an existing value, call PIM. setString (String ).

◆ To obtain a field value, call PIMItem. getString ().

Listener

When an item in the list changes, your pimlistener interface will receive this notification. The pimlistener interface provides the following methods:

Method

Description

 
 

  
  
itemAdded(PIMItem) 
 
 

Called when an item is added to the list.

 
 

  
  
item.Removed(PIMItem) 
 
 

Called when deleted from the list.

 
 

  
  
itemUpdated(PIMItem,PIMItem) 
 
 

Called when an item changes.

 
 

  
  
ContactList cl = (ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.WRITE_ONLY);  
  
  
 
  
  
((BlackBerryPIMList)cl).addListener(  
  
  
 
  
  
       new PIMListListener() {  
  
  
 
  
  
           public void itemAdded(PIMItem item) {  
  
  
 
  
  
              System.out.println(" ITEM ADDED: " +  
  
  
 
  
  
                     ((Contact)item).getString(Contact.UID, 0));  
  
  
 
  
  
              }  
  
  
 
  
  
            
  
  
 
  
  
           public void itemUpdated(PIMItem oldItem, PIMItem newItem) {  
  
  
 
  
  
              System.out.println(" ITEM UPDATED: " +  
  
  
 
  
  
                      ((Contact)oldItem).getString(Contact.UID, 0) + " to " +  
  
  
 
  
  
                     ((Contact)newItem).getString(Contact.UID, 0));  
  
  
 
  
  
              }  
  
  
 
  
  
            
  
  
 
  
  
           public void itemRemoved(PIMItem item) {  
  
  
 
  
  
              System.out.println(" ITEM REMOVED: " +  
  
  
 
  
  
                     ((Contact)item).getString(Contact.UID, 0));  
  
  
 
  
  
              }  
  
  
 
  
  
});  
  
  
 
 
 

Note: The Listener is still associated with the BlackBerry Device database, even after the corresponding PIMList object has been deleted. to delete a listener, call BlackBerryPIMList. removeListener ().)

Remote address query

Applications that support remote address query should instantiate the BlackBerryContactList interface. This interface extends the ContactList interface and provides the following additional methods:

Method

Description

 
 

  
  
choose(Contact, int, boolean) 
 
 

Start the address book so that you can select an address.

 
 

  
  
void lookup(Contact, RemoteLookupListener) 
 
 

Initialize a remote query.

 
 

  
  
void lookup(String, RemoteLookupListener) 
 
 

Initialize a remote query.

The RemoteLookupListener interface provides a single method, items (), which returns an iteration of the remote address query result.

Use address book

Use a ContactList instance to add or view Contact information in the BlackBerry device address book. Create a Contact object to store separate Contact information, including name, phone number, Email, and street address.

BlackBerry-specific address field

The BlackBerryContact interface extends the Contact interface. to access specific fields of the BlackBerry Contact, it defines the following constants:

Constant

Description

BlackBerryContact. PIN

Access the PIN field.

BlackBerryContact. USER1 to USER4

Access the USER1 to USER4 fields.

To define the tags from USER1 to USER4, call BlackBerryPIMList. setFieldLabel ().

The change takes effect immediately. You do not need to submit the change.

Note: Changing a tag will affect contacts on all BlackBerry devices .)

Open a contact list

Before you add a contact, you must create a contact list. call PIM. openPIMList (). provide the list type as a parameter to open (PIM. CONTACT_LIST), and provides the access mode (READ_WRITE, READ_ONLY, or WRITE_ONLY) to open the list.

If you are writing an application for the BlackBerry device to convert your contact list to BlackBerryContactList, this interface provides an additional method to support remote address query. to enable an application to span multiple compatible Java ME BlackBerry devices, use PDAP.

 
 

  
  
ContactList contactList = null;  
  
  
 
  
  
try {  
  
  
 
  
  
    contactList = (ContactList)PIM.getInstance().openPIMList(  
  
  
 
  
  
                          PIM.CONTACT_LIST, PIM.READ_WRITE);  
  
  
 
  
  
}  
  
  
 
  
  
catch (PimException e) {  
  
  
 
  
  
    return;  
  
  
 
  
  
}  
  
  
 
  
  
   
  
  
 
 
 

Note: The contact will not be added to the database until you submit it .)