Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Contact list

You can use an instance of the ContactList class or BlackBerryContactList class in your application to add and view contact information in the contacts application on the BlackBerry device. You can create Contact or BlackBerryContact objects to store information for individual contacts such as the name, phone number, email address, and street address.

Your application can perform tasks such as adding, deleting, and changing contact list entries.

Multiple contact lists support

Support for multiple contact lists is available in BlackBerry Java Development Environment 5.0 or later. Each contact list has a system-assigned contact list name and a UID that you can use to retrieve the list. You can change the contact list name by using the BlackBerry Desktop Manager to change the name of the service that is associated with the contact list name. You cannot change the UID.

When deciding how you want to open a contact list, you should consider persistence on the BlackBerry device. If your application requires the contact list name to persist across OS updates, use the UID to open the contact list. If your application requires the contact list name to persist only across BlackBerry device restarts, you can use the contact list name. Because a contact list name can change, you can register a listener for name change events by invoking BlackBerryPIM.addListChangeListener(ListChangeListener listener).

You can retrieve the names of the contact lists that are installed on a BlackBerry device by invoking PIM.listPIMLists(int pimListType) and passing in PIM.CONTACT_LIST as pimListType. The String array that is returned provides the system-assigned names for the contact lists on the device. The contact list name that is at index 0 of the returned String array is the default contact list. You can retrieve the UID of a contact list on a BlackBerry device by invoking BlackBerryPIMList.getPIMListUID().

You can open a contact list by its name by invoking PIM.openPIMList(int pimListType, int mode, String name). You can open a contact list by its UID by invoking BlackBerryPIM.openPIMList(int pimListType, int mode, long uid). You can open a list that combines multiple contact lists on a device by invoking one of the BlackBerryPIM.openUnifiedPIMList() methods.

Open the contacts application

You can open the contacts application on the BlackBerry device by using the Invoke.invokeApplication() method, and passing in the relevant arguments.

Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.Invoke;
import net.rim.blackberry.api.invoke.AddressBookArguments;
import net.rim.device.api.system.ControlledAccessException;

Invoke Invoke.invokeApplication(APP_TYPE_ADDRESSBOOK, AddressBookArguments).

AddressBookArguments abArg = new AddressBookArguments();
Invoke.invokeApplication(Invoke.APP_TYPE_ADDRESSBOOK, abArg);

Check for a ControlledAccessException if your application does not have permission to access the application that it invokes.

Open the contacts application by using contact data

You can open the contacts application on a BlackBerry device and display a contact by using the Invoke.invokeApplication() method, and passing in contact data as a parameter of an AddressBookArguments object.

Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.AddressBookArguments;
import net.rim.blackberry.api.invoke.Invoke;
import net.rim.blackberry.api.pdap.BlackBerryContact;
import net.rim.blackberry.api.pdap.BlackBerryContactList;
import net.rim.device.api.system.ControlledAccessException;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;

Invoke PIM.getInstance() to retrieve a PIM instance, and invoke PIM.openPIMList(int, int) to open the default contact list, 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). To open a named contact list, you can instead invoke PIM.openPIMList(int, int, String).

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

Invoke BlackBerryContactList.getByUID(String uid) to retrieve a contact from the contact list.

BlackBerryContact contact = contactList.getByUID("1XKIOD898");

Create an instance of the AddressBookArguments class, passing in a Contact object as a parameter.

AddressBookArguments abArg = new AddressBookArguments("ARG_VIEW", contact);

Invoke Invoke.invokeApplication(APP_TYPE_ADDRESSBOOK, AddressBookArguments) and use the AddressBookArguments object for the contact.

Invoke.invokeApplication(Invoke.APP_TYPE_ADDRESSBOOK, abArg);

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

Open the contacts application with a specific contact list

You can open the contacts application on a BlackBerry device and display a specific contact list by invoking the BlackBerryContactList.choose() method.

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.BlackBerryContact;
import net.rim.blackberry.api.pdap.BlackBerryContactGroup;
import net.rim.blackberry.api.pdap.BlackBerryContactList;
import net.rim.blackberry.api.pdap.BlackBerryPIM;
import net.rim.blackberry.api.pdap.BlackBerryPIMList;
import net.rim.device.api.system.ControlledAccessException;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;
import javax.microedition.pim.PIMItem;

Invoke PIM.listPIMLists(int pimListType) to return an array of String objects. The returned array provides the system-assigned names, one for each PIM list of the specified type. The default list of the specified type is returned at index 0 of the array.

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

Iterate over the array that is returned from PIM.listPIMLists() to search for the system-assigned name for the contact list that you want to display.

Invoke BlackBerryPIMList.getPIMListUID() to return the UID for contact list.

long uid = cl.getPIMListUID();

Invoke PIM.getInstance() to retrieve a PIM instance, and invoke PIM.openPIMList(int, int, long) to open the contact list, 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 UID.

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

Invoke BlackBerryContactList.choose() to return a BlackBerryContact or a BlackBerryContactGroup PIMItem.

PIMItem item = list.choose(); 
if (item instanceof BlackBerryContact)
{
     BlackBerryContact contact = (BlackBerryContact) item;
     int values = contact.countValues(BlackBerryContact.EMAIL);
     String email = contact.getString(BlackBerryContact.EMAIL, 0);
     System.out.println("Email is: " + email);
}
else if (item instanceof BlackBerryContactGroup)
{
...
}

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

Create a contact and assign it to a contact list

You can create a contact and assign it to either the default contact list or another contact list on a BlackBerry device.

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.BlackBerryContact; 
import net.rim.blackberry.api.pdap.BlackBerryContactList;
import net.rim.blackberry.api.pdap.BlackBerryPIMList;
import net.rim.device.api.system.ControlledAccessException;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMList;
import javax.microedition.pim.PIMException;
import javax.microedition.pim.ContactList;

To add the new contact to 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 PIM.READ_WRITE access mode.

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

To add the new contact to a contact list that is not the default contact list, perform the following actions:

  • Invoke PIM.listPIMLists(int), passing in as the parameter the type of list (PIM.CONTACT_LIST), to return an array of String objects. The returned array provides the system-assigned names for each contact list. The default contact list is returned at index 0 of the array.
    String[] lists = PIM.listPIMLists(PIM.CONTACT_LIST);
  • Iterate over the array that PIM.listPIMLists() returns to search for the system-assigned name for the contact list that you want to open.
  • 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 PIM.READ_WRITE access mode, and the contact list name.
    BlackBerryContactList contactList = (BlackBerryContactList) 
        PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, name);

Invoke ContactList.createContact() to add the new contact to the contact list.

BlackBerryContact contact = contactList.createContact();

Invoke one or more of the following methods to add information for the new contact. For more information about PIMItem methods, see the API reference for the BlackBerry Java Development Environment.

  • addString()
  • addStringArray()
  • addDate()
  • addInt()
  • addBoolean()
  • addBinary()

Invoke the following methods to verify that the information meets the size requirements and type requirements for the specified contact field.

  • Invoke ContactList.isSupportedField(int) to verify that the item supports the field type.
  • Invoke ContactList.isSupportedAttribute(int, int) to verify that the field supports the specified attribute.
  • Invoke PIMList.maxValues(int field) to verify the number of values that the field supports.

Invoke Contact.commit() to commit the changes.

if(contact.isModified())
{
    contact.commit();
}

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

Retrieve contact information

You can retrieve information from a contact list on a BlackBerry device by invoking one of the PIMList.items() methods. These methods return an enumeration of all the contacts in a specific contact list. You can invoke the BlackBerryContactList.items() methods to return contact groups.

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.BlackBerryContact;
import net.rim.blackberry.api.pdap.BlackBerryContactList;
import net.rim.blackberry.api.pdap.BlackBerryPIMList;
import java.util.Enumeration;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;
import javax.microedition.pim.PIMItem;

Invoke PIM.getInstance() to retrieve a PIM instance, and invoke PIM.openPIMList() to open a 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 name if you are not opening the default contact list.

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

Invoke PIMList.items() to retrieve an enumeration of items in a contact list.

Enumeration _enum = contactList.items();

Invoke one of the PIMItem getter methods to retrieve contact information.

  • To retrieve an array of fields that contain the data for a specified contact, invoke PIMItem.getFields().
  • To retrieve a String that represents the value for a specified contact field, invoke PIMItem.getString(int field, int index).
  • To retrieve a date that represents the value for a specified contact field, invoke PIMItem.getDate(int field, int index).
while (_enum.hasMoreElements())
{
     BlackBerryContact c = (BlackBerryContact)_enum.nextElement();
     int[] fieldIds = c.getFields();
     int id;
     for(int index = 0; index < fieldIds.length; ++index)
     {
          id = fieldIds[index];
          if(c.getPIMList().getFieldDataType(id) == BlackBerryContact.STRING)
          {
               for(int j=0; j < c.countValues(id); ++j)
               {
                    String value = c.getString(id, j);
                    System.out.println(c.getPIMList().getFieldLabel(id) + "=" 
                      + value);
               }
          }
     }
}

Retrieve a contact list UID

You can open a contact list on a BlackBerry device by specifying a system-assigned name or a UID. The UID is associated with a BlackBerry Enterprise Server account and persists across all BlackBerry device changes, including OS updates. You can open the contact list by its UID by invoking BlackBerryPIM.openPIMList(int pimListType, int mode, long uid).

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.BlackBerryContactList;
import net.rim.blackberry.api.pdap.BlackBerryPIMList;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;
import javax.microedition.pim.PIMItem;

Access the contact list that you want to work with.

Invoke BlackBerryPIMList.getPIMListUID() to retrieve the UID of the contact list.

long uid = list.getPIMListUID(); 

Export a contact

You can export contact information from a contact list on a BlackBerry device to an output stream. The export process converts a PIM item to a stream of bytes that another application can import. You can export PIM data to a supported serial format by invoking PIM.toSerialFormat(PIMItem, OutputStream, String, String), and passing in as arguments the PIMItem, the OutputStream to which the serialized PIMItem is written, the character encoding format to use when writing to the output stream, and the supported serial format to convert to, such as vCard.

Import the required classes and interfaces.

import java.io.UnsupportedEncodingException;
import java.util.Enumeration;
import javax.microedition.pim.Contact;
import javax.microedition.pim.ContactList;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;

Invoke PIM.supportedSerialFormats() and specify the list type (PIM.CONTACT_LIST) to retrieve a string array of the supported serial formats.

ContactList contactList = (ContactList) 
   PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
String[] dataFormats = PIM.getInstance().supportedSerialFormats(PIM.CONTACT_LIST);

Invoke PIM.getInstance().toSerialFormat(item, stream, enc, dataFormat)to write an item to a supported serial format. Use the enc parameter to specify the character encoding format to use when writing to the output stream. Supported character encoding formats include UTF8, ISO-8859-1, and UTF-16BE. If the enc parameter is null, the method uses UTF-8.

ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
Enumeration e = contactList.items();
while (e.hasMoreElements())
{
   try
   {
      Contact c = (Contact)e.nextElement();
      PIM.getInstance().toSerialFormat(c, byteStream, "UTF8", dataFormats[0]);
   }
   catch (UnsupportedEncodingException ex)
   {
      System.out.println(ex.toString()); 
   }
}

Import a contact

You can import contact information from a compatible input stream to a contact list on a BlackBerry device. You can import contact information by invoking fromSerialFormat(InputStream, String), and passing in as arguments the InputStream from which the PIMItem is written and the character encoding format to use. Supported character encoding formats include UTF8, ISO-8859-1, and UTF-16BE.

Import the required classes and interfaces.

import java.io.ByteArrayOutputStream;
import javax.microedition.pim.Contact;
import javax.microedition.pim.ContactList;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMItem;

Invoke PIM.getInstance().fromSerialFormat() to return an array of PIM items.

ByteArrayInputStream istream = 
   new ByteArrayInputStream(outputStream.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(istream, "UTF8");

Open a contact list and invoke ContactList.importContact() to create a new contact by using a PIM item.

ContactList contactList = (ContactList) 
   PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
Contact contact2 = contactList.importContact((Contact) pi[0]);
contact2.commit();

Delete a contact

You can delete a contact from the default contact list or another contact list on a BlackBerry device.

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.BlackBerryContact; 
import net.rim.blackberry.api.pdap.BlackBerryPIMList;
import net.rim.device.api.system.ControlledAccessException;
import javax.microedition.pim.Contact;
import javax.microedition.pim.ContactList;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;

To delete a contact from 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);

To delete a contact from a contact list that is not the default contact list, perform the following actions:

  • Invoke listPIMLists(int pimListType) 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);
  • Iterate over the array that PIM.listPIMLists() returns to search for the system-assigned name for the contact list that you want to delete.
  • 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);

    Invoke BlackBerryContactList.removeContact() to delete the contact from the contact list.

    contactList.removeContact(contact);

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

Notify an application when a contact list changes

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

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;

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).

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

To receive change notifications for a contact list that is not the default contact list, perform the following actions:

  • 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);
    
  • 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.
  • 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);

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

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

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));
}

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

Creating and removing contact lists

You can create contact lists on a BlackBerry device by invoking BlackBerryPIM.createPIMList(). Currently, the PIM list type you specify when you invoke createPIMList() must be PIM.CONTACT_LIST or a PIMException is thrown.

You can also remove contact lists by invoking BlackBerryPIM.removePIMList(). Currently, this method supports PIM lists only of type PIM.CONTACT_LIST.

Create a contact list

You can create contact lists on a BlackBerry device. Note the following about contact lists that you create:

  • Each contact list has a unique ID, which is the value that is returned by createPIMList().
  • The contact lists do not have service records and do not support wireless synchronization.
  • Applications can register to listen for changes to your contact list by invoking BlackBerryPIMList.addListener().
//Retrieve a BlackBerryPIM object. 
BlackBerryPIM myPIM = (BlackBerryPIM) PIM.getInstance();

try 
{
//Create a contact list
   long listUID = myPIM.createPIMList(PIM.CONTACT_LIST, "test");
        			
//The contact list is named using the name that you provide
//("test" in the preceding example), unless there is another contact list with
//that name on the device, in which case a number is appended to the name to make
//it unique. To reference the contact list later, you should use the list's UID,
//which is the value that is returned by createPIMList().

//Optionally, populate the contact list. 
   BlackBerryContactList contactList = 
      (BlackBerryContactList) myPIM.openPIMList(PIM.CONTACT_LIST, 
       PIM.READ_WRITE, listUID);
   Contact contact = contactList.createContact();
   String[] name = new String[contactList.stringArraySize(Contact.NAME)];
   name[Contact.NAME_GIVEN] = "Noha";
   name[Contact.NAME_FAMILY] = "Toma";
   contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);
   contact.addString(Contact.TEL, Contact.ATTR_HOME, "519-555-0151");
   contact.addString(Contact.TEL, Contact.ATTR_WORK, "519-555-0199");
   contact.commit();

//Close the contact list.
   contactList.close();
} 
catch (PIMException e) 
{
   System.out.println(e.getMessage());
}

Remove a contact list

You can remove contact lists from a BlackBerry device. Note the following about removing contact lists:

  • You cannot remove contact lists that have service records.
  • You cannot remove the last remaining contact list on a device.
  • You cannot remove the default contact list (which has the UID -1).

A BlackBerryPIMRemovalException is thrown if an error occurs when you try to remove a contact list.

Import the required classes and interfaces.

import javax.microedition.pim.PIM;
import net.rim.blackberry.api.pdap.BlackBerryPIM;
import net.rim.blackberry.api.pdap.BlackBerryPIMRemovalException;

Retrieve a BlackBerryPIM object.

BlackBerryPIM myPIM = (BlackBerryPIM) PIM.getInstance();

Retrieve the array of contact lists.

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

The returned array provides the names that are assigned to each contact list.

Iterate through the array to search for the contact list that you want to remove.

Remove the contact list by invoking BlackBerryPIM.removePIMList(). You can provide either the name or the UID of the contact list. By default, the method removes a contact list only if the list is empty. If you want to remove a contact list that is not empty, you must provide the parameter BlackBerryPIM.REMOVE_NON_EMPTY_LIST.

try 
{
   myPIM.removePIMList(PIM.CONTACT_LIST, "test", 
      BlackBerryPIM.REMOVE_NON_EMPTY_LIST);
}

catch (BlackBerryPIMRemovalException e)
{
   // handle the exception
}

Removing a contact list

BlackBerryPIM myPIM = (BlackBerryPIM) PIM.getInstance();
try
{
   myPIM.removePIMList(PIM.CONTACT_LIST, "test", BlackBerryPIM.REMOVE_NON_EMPTY_LIST);
}

catch (BlackBerryPIMRemovalException e)
{
   System.out.println(e.getMessage());
}

Retrieve the contact that is associated with an active call

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.BlackBerryContact;
import net.rim.blackberry.api.phone.*;

Implement a phone listener.

class MyPhoneListener extends AbstractPhoneListener
{
}

Invoke PhoneCall.getContact() in a callback method in the phone listener (for example, in callIncoming() for a new call). The getContact() method searches all contact lists on the BlackBerry device and returns a BlackBerryContact that is associated with the current phone number, or null if there is no matching contact.

public void callIncoming(int callId)
{
   PhoneCall call = Phone.getCall(callId);
   BlackBerryContact contact = call.getContact();
}

Use the retrieved contact information.

public void callIncoming(int callID) // in a phone listener
{
   StringBuffer strBuffer = new StringBuffer();
      
   PhoneCall call = Phone.getCall(callID);        
   BlackBerryContact contact = call.getContact();
            
   if(contact != null)
   {    
      if(contact.countValues(BlackBerryContact.ADDR) > 0)
      {
         String[] strArray = contact.getStringArray(BlackBerryContact.ADDR, 0);
         String city = strArray[BlackBerryContact.ADDR_LOCALITY];
         if(city != null && city.length() > 0)
         {
            strBuffer.append(city);                
         }            
                
         String country = strArray[BlackBerryContact.ADDR_COUNTRY];
         if(country != null && country.length() > 0)
         {
            if(city != null && city.length() > 0)
            {
               strBuffer.append(", ");
            }
                    
            strBuffer.append(country);
         }
      }                         
   }
   // use the contact info, for example, 
   // display it on the incoming phone screen
}

Retrieving the contact that is associated with a completed call

You can retrieve the contact that is associated with a completed call from the call log on a BlackBerry device.

String phoneNum = "519-555-0151";

//Retrieve the caller ID information for a call from the call log.
PhoneCallLogID callLog = new PhoneCallLogID(phoneNum);

// Retrieve the associated contact by invoking PhoneCallLogID.getContact(). 
//The getContact() method searches all contact lists on the BlackBerry
//device for a contact that matches the caller ID information. The method 
//returns null if there is no matching contact.
BlackBerryContact contact = callLog.getContact();
            
if (contact != null)
{
   String[] name = contact.getStringArray(Contact.NAME, 0);
   add(new RichTextField("The matching contact is " + name[Contact.NAME_GIVEN] 
      + " " + name[Contact.NAME_FAMILY]));
}
else
{
   add(new RichTextField("There is no matching contact"));
}

Retrieve contacts by phone number

You can search all contact lists or a specified contact list on a BlackBerry device for contacts that match a specified phone number.

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.BlackBerryContact;
import net.rim.blackberry.api.pdap.BlackBerryContactList;
import net.rim.blackberry.api.pdap.BlackBerryPIMList;
import net.rim.blackberry.api.phone.Phone;
import java.util.*;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;
import javax.microedition.pim.PIMItem;

Do one of the following:

  • To search all contacts lists, invoke Phone.getContactsByPhoneNumber(), which returns a Vector object that contains the contacts that match the specified phone number. The Vector is empty if there are no matching contacts.

    Vector contacts = Phone.getContactsByPhoneNumber(phoneNum);
  • To search a specified contact list, invoke BlackBerryContactList.itemsByPhoneNumber(), which returns an Enumeration object of all contacts that match the specified phone number. Each of the items in the Enumeration is a PIMItem object, which you can cast to a BlackBerryContactList object.

    BlackBerryContactList list = (BlackBerryContactList) 
       PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, "test");
    Enumeration myEnum = list.itemsByPhoneNumber(phoneNum);
    try
    {
       BlackBerryContactList list = (BlackBerryContactList) 
          PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, "test");
     
       Enumeration myEnum = list.itemsByPhoneNumber(phoneNum);
                        
       while (myEnum.hasMoreElements())
       {
          Object o = myEnum.nextElement();
          if (o instanceof BlackBerryContact)
          {
             BlackBerryContact c = (BlackBerryContact) o;
                                
             String[] name = c.getStringArray(Contact.NAME, 0);
             add(new RichTextField("A matching contact is " + 
                name[Contact.NAME_GIVEN] + " " + name[Contact.NAME_FAMILY]));
          }
       }
    }
    catch (Exception e)
    {
       System.out.println(e.getMessage());
    }

Linking third-party contacts with contacts in the Contacts application

You can allow BlackBerry device users to link contact data in your application with contacts in the Contacts application on the BlackBerry device by using the Contact Linking API in the net.rim.blackberry.api.pdap.contactlinking package. For example, you can allow users to link a contact in your CRM application with a contact in the Contacts application.

A contact in a third-party application can be linked with only one contact in the Contacts application. However, a contact in the Contacts application can be linked with contacts in multiple third-party applications. When a user tries to link a contact in your application with a contact in the Contacts application, you can use the Contact Linking API to perform some tasks automatically, such as searching for a matching contact and checking whether the contact is already linked.

You can create menu items that appear in the Contacts application when a user views a contact that is linked with one of your contacts. The menu items can perform any action you want. For example, you can allow a user to add notes in the Contacts application about the contact in your application.

You can define the information to display in the Contacts application when the user is viewing a contact that is linked to one of your contacts.

The Contact Linking Demo sample application is included in the . The application demonstrates how to use the Contact Linking API.

Link a contact

  • Create the contacts in your application by creating and instantiating a class that implements the LinkableContact interface.
  • Define a class that extends LinkedContactInfoProvider and register the class with your application.

You can link a contact in your application with a contact in the Contacts application on the BlackBerry device. You can decide how to interact with the BlackBerry device user when you link a contact. The steps that follow describe one possible approach.

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.*;
import net.rim.blackberry.api.pdap.contactlinking.*;
import javax.microedition.pim.*;

Check to see whether there is a contact in the Contacts application (a BlackBerryContact object) that is a linking candidate for your contact. The LinkedContactUtilities.getContactLinkCandidate() method returns a BlackBerryContact if it finds a contact in the Contacts application that has the same email address or phone number as the LinkableContact that is passed to it. If there is no matching contact, the method returns null.

BlackBerryContact bbContact = 
    LinkedContactUtilities.getContactLinkCandidate(linkableContact);

If a match is found, link your contact with the BlackBerryContact.

bbContact = LinkedContactUtilities.linkContact(bbContact, linkableContact);

If a match is not found, have the user select a contact in the Contacts application to link to the selected contact.

BlackBerryContactList contacts = null;
try
{
    contacts = (BlackBerryContactList) PIM.getInstance().
        openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
}
catch(PIMException e)
{
    ContactLinkingDemo.errorDialog("Couldn't open contacts list.");   
    return;                 
}
                
Object choice = contacts.choose();
if(choice instanceof BlackBerryContact)
{
    bbContact = (BlackBerryContact)choice;
}

Check to see whether the selected contact in the Contacts application is already linked to a contact in your application.

LinkedContactUtilities.isContactLinked(bbContact, 
    linkableContact.getApplicationID())

If the selected contact in the Contacts application is not already linked, link it to the contact in your application.

bbContact = LinkedContactUtilities.linkContact(bbContact, linkableContact);

Code sample: Linking a contact

To see an example of this approach to linking a contact, see linkContact() in the Contact Linking Demo sample application that is included in the .

Remove a link

You can remove a link between a contact in your application and a contact in the Contacts application on the BlackBerry device.

private void unlinkContact(LinkableContact linkableContact)
{

//Retrieve  the contact in the Contacts application that is linked 
//to your contact.
    BlackBerryContact contact =

//Remove the link between the contacts. 
        LinkedContactUtilities.getLinkedContact(linkableContact);
    if(contact != null)
    {
        LinkedContactUtilities.unlinkContact(contact, 
            linkableContact.getApplicationID());
    }
}   

Creating menu items for linked contacts

You can create menu items that are available in the Contacts application on the BlackBerry device when a user views a contact that is linked with a contact in your application by invoking LinkedContactUtilities.registerMenuItems(). You must assign menu items to an application group by using the LinkedContactConstants interface.

Application group

Description

COMPOSE_SN_MENU_GROUP

social networking applications

COMPOSE_IM_MENU_GROUP

instant messaging applications

COMPOSE_OTHER_MENU_GROUP

applications that are not social networking applications or instant messaging applications

If a contact in the Contacts application is linked with contacts in multiple third-party applications, the menu items in the Contacts application are grouped with other applications of the same group.

  • Social networking menu items are grouped under the Social Networking menu item.
  • Instant messaging menu items are grouped under the Instant Messaging menu item.
  • Menu items from other types of applications are grouped under the Contact Using menu item.

The menu items from the third-party applications with linked contacts are integrated with the menu for the Contacts application.

Situation

Result

A group contains one application with linked contacts. The application contains one menu item.

The menu item for the application appears in the menu in the Contacts application.

A group contains one application with linked contacts. The application contains multiple menu items.

The application's name appears in the menu. Selecting the name displays a dialog box that contains a button for each menu item.

A group contains multiple applications with linked contacts.

The group menu item (such as Social Networking) appears in the menu. Selecting the group menu item displays a dialog box with a button for each application with linked contacts in the group.

Create menu items for linked contacts

You can create menu items that are available in the Contacts application on the BlackBerry device when a user views a contact that is linked with a contact in your application.

Import the required classes and interfaces.

import net.rim.blackberry.api.menuitem.ApplicationMenuItem;
import net.rim.blackberry.api.pdap.contactlinking.LinkedContactConstants;
import net.rim.blackberry.api.pdap.contactlinking.LinkedContactUtilities;
import net.rim.device.api.system.ApplicationDescriptor;

Create a class that extends the ApplicationMenuItem class.

public class LinkedMenuItem extends ApplicationMenuItem {...}

Create an application descriptor for your application.

ApplicationDescriptor appdesc = new
    ApplicationDescriptor(ApplicationDescriptor.currentApplicationDescriptor(), 
    "Linking Application", null);

Create a variable to store the unique ID of your application.

public static final long APPLICATION_ID = 0x1eredfe71d34760fdL;

Create an array with one or more menu item instances.

ApplicationMenuItem[] items = new ApplicationMenuItem[1];
items[0] = new LinkedMenuItem();

Invoke LinkedContactUtilities.registerMenuItems() to add the menu items for the linked contact to the menu. Pass in the array of menu items, the unique ID of your application, the application group, and the application descriptor.

LinkedContactUtilities.registerMenuItems(items, APPLICATION_ID, 
    LinkedContactConstants.COMPOSE_SN_MENU_GROUP, appdesc);

To see an example of creating menu items for linked contacts, see the SampleMenuItem class and main() in the Contact Linking Demo sample application that is included in the .

Create an information provider for a linked contact

You can create a class that extends the abstract LinkedContactInfoProvider class to define information about a linked contact. This information appears in the Contacts application on the BlackBerry device when a user views a contact that is linked with a contact in your application.

Import the required classes and interfaces.

import net.rim.blackberry.api.pdap.contactlinking.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;

Create a class that extends LinkedContactInfoProvider.

public class SampleLinkedContactInfoProvider 
               extends LinkedContactInfoProvider
{
    private Image _image;
    private String _appName;
        
    public SampleLinkedContactInfoProvider(Image image, String appName)    
    {        
        _image = image;
        _appName = appName;                
    }

Implement getAppImage() and return the icon that represents your application. The method must return an image in order for any information to appear for your linked contact when a user views a contact in the Contacts application.

public Image getAppImage()
{
    return _image;        
}

Implement getAppName() and return the name of your application. The method must return a name in order for information about the linked contact to appear when a user edits a contact in the Contacts application.

public String getAppName()
{        
    return _appName;
}  

To indicate which LinkedContactInfoProvider fields (user name, availability, or status) that your application supports, implement isSupported(). By default, a field is not supported. You need to implement isSupported() only if your application supports any of the fields.

public boolean isSupported(int capability)
{
    switch(capability)
    {
        case LinkedContactInfoProvider.STATUS:
        case LinkedContactInfoProvider.AVAILABILITY:
        case LinkedContactInfoProvider.USER_NAME:
            return true;
        default:
            return false;
    }
}

Implement requestFields() to specify the information to display for the contact in the Contacts application. The method is invoked by the framework when it needs to display information for the linked contact in the Contacts application. Specify the contact's name, status, and current availability, depending on which fields you defined as supported in isSupported().

public void requestFields(
        String contactID, final LinkedContactCallback callback, int fields)
{        
    LinkableContact contact = ContactListScreen.getUserForID(contactID);
        
    if((fields & LinkedContactInfoProvider.AVAILABILITY) != 0)
    {
        callback.setAvailability(LinkedContactInfoProvider.AVAILABILITY_ONLINE);
    }
    if((fields & LinkedContactInfoProvider.STATUS) != 0)
    {            
        callback.setStatusString("<Sample contact status>");
    }       
    if((fields & LinkedContactInfoProvider.USER_NAME) != 0)
    {
        callback.setUserName(contact.toString());
    }
}    

Register the information provider with your application.

LinkedContactUtilities.registerLinkedContactInfoProvider(
    new SampleLinkedContactInfoProvider(imageBlue, "Demo App 1"), 
    APPLICATION_ID,
    LinkedContactConstants.COMPOSE_SN_MENU_GROUP);

This example registers the application as a social networking application, using the COMPOSE_SN_MENU_GROUP field in LinkedContactConstants.

When a user displays a contact in the Contacts application that is linked to one of your contacts, the information that you defined in your information provider displays on the contact screen. The framework determines the layout of the information. In this example, because the application was defined as a social networking application, the information displays in the Social Networks section of the contact.

To see an example of creating an information provider for a linked contact, see the SampleLinkedContactInfoProvider class in the Contact Linking Demo sample application that is included in the .