net.rim.blackberry.api.pim
Interface Contact

All Superinterfaces:
PIMItem
All Known Subinterfaces:
BlackBerryContact

Deprecated. In favour of Contact.

public interface Contact
extends PIMItem

Represents a PIM contact.

A PIM contact consists of the fields, such as phone number, and address, that represent the personal information of a contact.

While the Contact object contains support for many different fields, the fields supported by a given instance of a Contact object are defined in the ContactList object associated with the contact. The ContactList restricts which fields are retained by a Contact database. If a ContactList encounters a Contact object that contains unsupported fields, those fields are dropped.

isSupportedField is invoked to determine if a field (as specified by the integer argument) is supported by a ContactList. Similarly, getSupportedAttributes is invoked to return an integer array representing all fields supported by the list.

Data
The following table details the explicitly defined fields that may by in a Contact. Implementations may extend the field set using extended fields as defined in PIMItem.
Fields Type of Data Associated with Field
NAME, ADDR PIMItem.STRING_ARRAY
EMAIL, FORMATTED_NAME, NICKNAME, PHOTO_URL, PUBLIC_KEY_STRING, FORMATTED_ADDR, NOTE, ORG, TEL, TITLE, UID, URL PIMItem.STRING
BIRTHDAY, REVISION PIMItem.DATE
PHOTO, PUBLIC_KEY PIMItem.BINARY
CLASS PIMItem.INT

Working with the Contact object
The following examples demonstrate how to use the Contact object.

Below, a new contact is created and given the category "Work":

     try {
        Contact contact = contacts.createContact();
        contact.addToCategory("Work");
     } catch(PIMException e) {
        // contact was not be created, exception thrown
     }
 

To remove a Contact, use ContactList.remove. The following example removes a contact from a contact list:

    contacts.removeContact(contact);
 

Adding data to a Contact
When adding data to a contact, you first need to ensure that the field and attribute you are adding are supported by the list. Below, isSupportedField is used to return whether or not the specified field is supported. If the specified field is supported, in this case the given name of the contact, the new name will be added to the contact:

          if (contacts.isSupportedField(Contact.NAME)) {
              String[] nameArray = new String[Contact.NAMESIZE];
              nameArray[Contact.NAME_GIVEN] = "Robert";
              contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, nameArray);
          }
          if (contacts.isSupportedField(Contact.TEL) &&
                  (contacts.isSupportedAttribute(Contact.TEL, TYPE_HOME)) {
                  contact.addString(Contact.TEL, Contact.TYPE_HOME, 
                          "613-123-4567");
          )
 

Similarly, to add a new attribute to a contact, invoke isSupportedAttribute to ensure that the attribute is supported by the field. If a specified field or attribute are not supported, an UnsupportedFieldException will be thrown.

Updating data in an existing Contact
The previous example added new data to an empty field. Since you can not add data to a field that already contains data, countValues is invoked to determine whether or not the field is empty, and removeValue is used to remove the data from the field:

       String[] nameArray = new String[Contact.NAMESIZE];
       if (contact.countValues(Contact.NAME) > 0) {
         contact.removeValue(Contact.NAME, 0);
       }
       nameArray[Contact.NAME_GIVEN] = "Kate";
       nameArray[Contact.NAME_FAMILY] = "Demeter";
       contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, nameArray);

 

Above, countValues and removeValue are invoked before the contact's first and last name are modified using addString.

Saving a Contact object
The commit method must be used to save the object to a list. Below, isModified is called to indicate whether or not the contact's information has been modified. If so, commit method is invoked and the contact is saved:

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

RIM Implementation Notes
For further details on the behaviour of Contacts on RIM devices see BlackBerryContact.

For more information about this class or about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Since:
JDE 3.6.0
See Also:
BlackBerryContact, ContactList

Field Summary
static int ADDR
          Deprecated. Address of this contact.
static int ADDR_COUNTRY
          Deprecated. Country field of this contact's address array.
static int ADDR_EXTRA
          Deprecated. Extra field of this contact's address array.
static int ADDR_LOCALITY
          Deprecated. Locality (for example, city) field of this contact's address array.
static int ADDR_POBOX
          Deprecated. Post office box number field of this contact's address array.
static int ADDR_POSTALCODE
          Deprecated. Postal code field of this contact's address array.
static int ADDR_REGION
          Deprecated. Region (for example, state or province) field of this contact's address array.
static int ADDR_STREET
          Deprecated. Street address field of this contact's address.
static int ADDRSIZE
          Deprecated. Use PIMList.stringArraySize(int) instead
static int ATTR_ASST
          Deprecated. Information (usually name or phone number) for an assistant to a contact.
static int ATTR_AUTO
          Deprecated. Automobile phone number for a contact.
static int ATTR_FAX
          Deprecated. Fax number for a contact.
static int ATTR_HOME
          Deprecated. Home phone number for a contact.
static int ATTR_MOBILE
          Deprecated. Mobile phone number for a contact.
static int ATTR_OTHER
          Deprecated. Other information for a contact.
static int ATTR_PAGER
          Deprecated. Pager number for a contact.
static int ATTR_PREFERRED
          Deprecated. Indicates that a field is the preferred attribute for a contact.
static int ATTR_SMS
          Deprecated. SMS address for a contact.
static int ATTR_WORK
          Deprecated. Work phone number of a contact.
static int BIRTHDAY
          Deprecated. Birthday field for this contact.
static int CLASS
          Deprecated. Access class for this contact.
static int CLASS_CONFIDENTIAL
          Deprecated. "Confidential" access class.
static int CLASS_PRIVATE
          Deprecated. "Private" access class.
static int CLASS_PUBLIC
          Deprecated. "Public" access class.
static int EMAIL
          Deprecated. Email address field(s) for this contact.
static int FORMATTED_ADDR
          Deprecated. Contact's formatted address.
static int FORMATTED_NAME
          Deprecated. Contact's formatted name.
static int NAME
          Deprecated. Contact's name.
static int NAME_FAMILY
          Deprecated. Family name of this contact's name array.
static int NAME_GIVEN
          Deprecated. Given name of this contact's name array.
static int NAME_OTHER
          Deprecated. Another name for this contact's name array.
static int NAME_PREFIX
          Deprecated. A prefix for this contact's name array.
static int NAME_SUFFIX
          Deprecated. A suffix for this contact's name array.
static int NAMESIZE
          Deprecated. Use PIMList.stringArraySize(int) instead
static int NICKNAME
          Deprecated. Contact's nick name.
static int NOTE
          Deprecated. Represents a field used to store a note about this contact.
static int ORG
          Deprecated. Name of this contact's organization.
static int PHOTO
          Deprecated. Photo for this contact.
static int PHOTO_URL
          Deprecated. URL leading to a photo for this contact.
static int PUBLIC_KEY
          Deprecated. Public encryption key of this contact.
static int PUBLIC_KEY_STRING
          Deprecated. String representation of this contact's public encryption key.
static int REVISION
          Deprecated. Last-modification date and time for this contact's information.
static int TEL
          Deprecated. Telephone number for this contact.
static int TITLE
          Deprecated. Title for this contact, for example 'Vice President'.
static int UID
          Deprecated. Unique ID for this contact.
static int URL
          Deprecated. Website URL for this contact.
 
Fields inherited from interface net.rim.blackberry.api.pim.PIMItem
ATTR_NONE, BINARY, BOOLEAN, DATE, EXTENDED_ATTRIBUTE_MIN_VALUE, EXTENDED_FIELD_MIN_VALUE, INT, STRING, STRING_ARRAY
 
Method Summary
 int getPreferredIndex(int field)
          Deprecated. Retrieves the index number for this contact's preferred attribute.
 
Methods inherited from interface net.rim.blackberry.api.pim.PIMItem
addBinary, addBoolean, addDate, addInt, addString, addStringArray, addToCategory, commit, countValues, getAttributes, getBinary, getBoolean, getCategories, getDate, getFields, getInt, getPIMList, getString, getStringArray, isModified, maxCategories, removeFromCategory, removeValue, setBinary, setBoolean, setDate, setInt, setString, setStringArray
 

Field Detail

ADDRSIZE

public static final int ADDRSIZE
Deprecated. Use PIMList.stringArraySize(int) instead

Size of an address array.
Since:
JDE 3.6.0

NAMESIZE

public static final int NAMESIZE
Deprecated. Use PIMList.stringArraySize(int) instead

Size of a name string array.
Since:
JDE 3.6.0

ADDR_POBOX

public static final int ADDR_POBOX
Deprecated. 
Post office box number field of this contact's address array.
Since:
JDE 3.6.0

ADDR_EXTRA

public static final int ADDR_EXTRA
Deprecated. 
Extra field of this contact's address array.
Since:
JDE 3.6.0

ADDR_STREET

public static final int ADDR_STREET
Deprecated. 
Street address field of this contact's address.
Since:
JDE 3.6.0

ADDR_LOCALITY

public static final int ADDR_LOCALITY
Deprecated. 
Locality (for example, city) field of this contact's address array.
Since:
JDE 3.6.0

ADDR_REGION

public static final int ADDR_REGION
Deprecated. 
Region (for example, state or province) field of this contact's address array.
Since:
JDE 3.6.0

ADDR_POSTALCODE

public static final int ADDR_POSTALCODE
Deprecated. 
Postal code field of this contact's address array.
Since:
JDE 3.6.0

ADDR_COUNTRY

public static final int ADDR_COUNTRY
Deprecated. 
Country field of this contact's address array.
Since:
JDE 3.6.0

NAME_FAMILY

public static final int NAME_FAMILY
Deprecated. 
Family name of this contact's name array.
Since:
JDE 3.6.0

NAME_GIVEN

public static final int NAME_GIVEN
Deprecated. 
Given name of this contact's name array.
Since:
JDE 3.6.0

NAME_OTHER

public static final int NAME_OTHER
Deprecated. 
Another name for this contact's name array.

For example, this could be used to contain this contact's middle name.

Since:
JDE 3.6.0

NAME_PREFIX

public static final int NAME_PREFIX
Deprecated. 
A prefix for this contact's name array.

For example, this could be used to contain a title, such as 'Dr.' or 'Ms.'

Since:
JDE 3.6.0

NAME_SUFFIX

public static final int NAME_SUFFIX
Deprecated. 
A suffix for this contact's name array.

For example, this could be used to contain an educational or professional entitlement, such as 'Phd' or 'QC'.

Since:
JDE 3.6.0

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL
Deprecated. 
"Confidential" access class.
Since:
JDE 3.6.0

CLASS_PRIVATE

public static final int CLASS_PRIVATE
Deprecated. 
"Private" access class.
Since:
JDE 3.6.0

CLASS_PUBLIC

public static final int CLASS_PUBLIC
Deprecated. 
"Public" access class.
Since:
JDE 3.6.0

ADDR

public static final int ADDR
Deprecated. 
Address of this contact.
Since:
JDE 3.6.0

BIRTHDAY

public static final int BIRTHDAY
Deprecated. 
Birthday field for this contact.
Since:
JDE 3.6.0

CLASS

public static final int CLASS
Deprecated. 
Access class for this contact.

One of CLASS_PRIVATE, CLASS_PUBLIC, or CLASS_CONFIDENTIAL.

Since:
JDE 3.6.0

EMAIL

public static final int EMAIL
Deprecated. 
Email address field(s) for this contact.
Since:
JDE 3.6.0

FORMATTED_ADDR

public static final int FORMATTED_ADDR
Deprecated. 
Contact's formatted address.

The formatted address consists of the various fields that make up an address.

Since:
JDE 3.6.0

FORMATTED_NAME

public static final int FORMATTED_NAME
Deprecated. 
Contact's formatted name.

The formatted name represents the fields that make up a full name.

Since:
JDE 3.6.0

NAME

public static final int NAME
Deprecated. 
Contact's name.
Since:
JDE 3.6.0

NICKNAME

public static final int NICKNAME
Deprecated. 
Contact's nick name.
Since:
JDE 3.6.0

NOTE

public static final int NOTE
Deprecated. 
Represents a field used to store a note about this contact.

The data associated with this field conforms to the X.520 Description data format.

Since:
JDE 3.6.0

ORG

public static final int ORG
Deprecated. 
Name of this contact's organization.
Since:
JDE 3.6.0

PHOTO

public static final int PHOTO
Deprecated. 
Photo for this contact.

The photo is stored in inline binary format and is directly related to the PHOTO_URL field.

Since:
JDE 3.6.0

PHOTO_URL

public static final int PHOTO_URL
Deprecated. 
URL leading to a photo for this contact.

The photo URL is stored in the same memory location as the photo.

Since:
JDE 3.6.0

PUBLIC_KEY

public static final int PUBLIC_KEY
Deprecated. 
Public encryption key of this contact.

Manipulation of this field may affect data stored in the PUBLIC_KEY_STRING field since both are stored in the same memory location.

Since:
JDE 3.6.0

PUBLIC_KEY_STRING

public static final int PUBLIC_KEY_STRING
Deprecated. 
String representation of this contact's public encryption key.

Manipulation of this field may affect data stored in the PUBLIC_KEY field since both are stored in the same memory location.

Since:
JDE 3.6.0

REVISION

public static final int REVISION
Deprecated. 
Last-modification date and time for this contact's information.
Since:
JDE 3.6.0

TEL

public static final int TEL
Deprecated. 
Telephone number for this contact.

This data is stored as a string. Any valid string will be acceptable.

Since:
JDE 3.6.0

TITLE

public static final int TITLE
Deprecated. 
Title for this contact, for example 'Vice President'.

This title is based on the X.520 Title attribute.

Since:
JDE 3.6.0

UID

public static final int UID
Deprecated. 
Unique ID for this contact.

The unique ID field is valid only if the Contact has been added to a ContactList at least once in the past. If this contact has not yet been added to a list, the UID returns contains null.

Since:
JDE 3.6.0

URL

public static final int URL
Deprecated. 
Website URL for this contact.
Since:
JDE 3.6.0

ATTR_ASST

public static final int ATTR_ASST
Deprecated. 
Information (usually name or phone number) for an assistant to a contact.
Since:
JDE 3.6.0

ATTR_AUTO

public static final int ATTR_AUTO
Deprecated. 
Automobile phone number for a contact.
Since:
JDE 3.6.0

ATTR_FAX

public static final int ATTR_FAX
Deprecated. 
Fax number for a contact.
Since:
JDE 3.6.0

ATTR_HOME

public static final int ATTR_HOME
Deprecated. 
Home phone number for a contact.
Since:
JDE 3.6.0

ATTR_MOBILE

public static final int ATTR_MOBILE
Deprecated. 
Mobile phone number for a contact.
Since:
JDE 3.6.0

ATTR_OTHER

public static final int ATTR_OTHER
Deprecated. 
Other information for a contact.
Since:
JDE 3.6.0

ATTR_PAGER

public static final int ATTR_PAGER
Deprecated. 
Pager number for a contact.
Since:
JDE 3.6.0

ATTR_PREFERRED

public static final int ATTR_PREFERRED
Deprecated. 
Indicates that a field is the preferred attribute for a contact.

This attribute will be used for retrieval and display. Only one field can be designated as preferred. getPreferredIndex(int) retrieves the index of the preferred attribute.

Since:
JDE 3.6.0

ATTR_SMS

public static final int ATTR_SMS
Deprecated. 
SMS address for a contact.
Since:
JDE 3.6.0

ATTR_WORK

public static final int ATTR_WORK
Deprecated. 
Work phone number of a contact.
Since:
JDE 3.6.0
Method Detail

getPreferredIndex

public int getPreferredIndex(int field)
Deprecated. 
Retrieves the index number for this contact's preferred attribute.
Parameters:
field - Field to check for a preferred value.
Returns:
Index of the preferred value, or -1 if no value is marked as preferred.
Since:
JDE 4.0.2


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.