You can register your application to receive notification of changes to the contact lists on a BlackBerry® device by implementing the PIMListListener interface. The PIMListListener interface provides the following methods:

• itemAdded(PIMItem item), which is invoked when an item is added to a contact list
• itemUpdated(PIMItem oldItem, PIMItem newItem), which is invoked when an item changes
• itemRemoved(PIMItem item), which is invoked when an item is deleted from a contact list

1. Import the required classes and interfaces.

   import net.rim.blackberry.api.pdap.BlackBerrryContact;
   import net.rim.blackberry.api.pdap.BlackBerryContactList;
   import net.rim.blackberry.api.pdap.BlackBerryPIMList;
   import net.rim.blackberry.api.pdap.PIMListListener;
   import net.rim.device.api.system.ControlledAccessException;
   import javax.microedition.pim.PIMList;
   import javax.microedition.pim.PIMException;

2. To receive change notifications for the default contact list, invoke PIM.openPIMList(int, int) to open the default contact list instance, passing in as parameters the type of list to open (PIM.CONTACT_LIST), and the access mode with which to open the list (PIM.READ_WRITE, PIM.READ_ONLY, or PIM.WRITE_ONLY). Proceed to step 4.

   BlackBerryContactList contactList = (BlackBerryContactList) 
      PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);

3. To receive change notifications for a contact list that is not the default contact list, perform the following actions:
   1. Invoke listPIMLists(int), passing in as the parameter the type of list to open (PIM.CONTACT_LIST), to return an array of String objects. The returned array provides the system-assigned name for each contact list. The default contact list is returned at index 0 of the array.

      String[] lists = PIM.listPIMLists(PIM.CONTACT_LIST);

   2. Iterate over the array that PIM.listPIMLists() returns to search for the system-assigned name for the contact list that you want to receive change notifications for.
   3. Invoke PIM.openPIMList(int, int, String) to open the contact list instance, passing in as parameters the type of list to open (PIM.CONTACT_LIST), the access mode with which to open the list (PIM.READ_WRITE, PIM.READ_ONLY, or PIM.WRITE_ONLY), and the contact list name.

      BlackBerryContactList contactList = (BlackBerryContactList) 
         PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, name);

4. Invoke BlackBerryPIMList.addListener() to register a listener for the contact list.

   (BlackBerryPIMList) contactList.addListener(new PIMListListener());

5. Override the PIMListListener.itemAdded(), PIMListListener.itemUpdated(), and PIMListListener.itemRemoved() methods to configure the notification behavior.

   public void itemAdded(PIMItem item) 
   {
      System.out.println("ITEM ADDED: " + 
         (BlackBerryContact) item.getString(BlackBerryContact.UID, 0));
   }
   
   public void itemUpdated(PIMItem oldItem, PIMItem newItem) 
   {
      System.out.println("ITEM UPDATED: " + (BlackBerryContact) 
         oldItem.getString(BlackBerryContact.UID, 0) + " to " + 
         (BlackBerryContact) newItem.getString(Contact.UID, 0));
   }
   
   public void itemRemoved(PIMItem item) 
   {
      System.out.println("ITEM REMOVED: " + 
         (BlackBerryContact) item.getString(BlackBerryContact.UID, 0));
   }
   

6. Check for PIMException, and check for ControlledAccessException if your application does not have permission to access the application that it invokes.