SHOW Signed

net.rim.blackberry.api.pim
Interface Contact

All Superinterfaces:

PIMItem

All Known Subinterfaces:

BlackBerryContact

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.

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

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 the remove method. 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, the isSupportedField method 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_GIVEN)) {
                  contact.addString(Contact.NAME_GIVEN, "Robert");
          }
          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 the isSupportedAttribute method 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, the countValues method is invoked to determine whether or not the field is empty, and the removeValue method is used to remove the data from the field.

     if (contact.countValues(NAME_GIVEN) > 0) {
         contact.removeValue(NAME_GIVEN, 0);
      }
      contact.addString(NAME_GIVEN, ATTR_NONE, "Kate");

      if (contact.countValues(NAME_FAMILY) > 0) {
              contact.removeValue(NAME_FAMILY, 0);
      }
      contact.addString(NAME_FIRST, ATTR_NONE, "Demeter");

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

Saving a Contact object

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

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

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

See Also:

ContactList

Field Summary

	static int	ADDR Represents the address of the contact.
	static int	ADDR_COUNTRY Represents the country field of the contact's address array.
	static int	ADDR_EXTRA Represents an extra field of the contact's address array.
	static int	ADDR_LOCALITY Represents the locality (for example, city) field of the contact's address array.
	static int	ADDR_POBOX Represents the post office box number field of the contact's address array.
	static int	ADDR_POSTALCODE Represents the postal code field of the contact's address array.
	static int	ADDR_REGION Represents the region (for example, state or province) field of the contact's address array.
	static int	ADDR_STREET Represents the street address field of the contact's address.
	static int	ADDRSIZE Represents the size of an address array.
	static int	ATTR_ASST Represents the information (usually name or phone number) of a contact's assistant.
	static int	ATTR_AUTO Represents the automobile phone number of a contact.
	static int	ATTR_FAX Represents the fax number of a contact.
	static int	ATTR_HOME Represents the home phone number of a contact.
	static int	ATTR_MOBILE Represents the mobile phone number of a contact.
	static int	ATTR_OTHER Represents an "other" field for a contact.
	static int	ATTR_PAGER Represents a pager number for a contact.
	static int	ATTR_PREFERRED Indicates that a field is the preferred attribute for a contact.
	static int	ATTR_SMS Represents the SMS address of a contact.
	static int	ATTR_WORK Represents the work phone number of a contact.
	static int	BIRTHDAY Represents the birthday field of the contact.
	static int	CLASS Field specifying the class of this contact.
	static int	CLASS_CONFIDENTIAL Represents the constant for the "confidential" access class.
	static int	CLASS_PRIVATE Represents the constant for the "private" access class.
	static int	CLASS_PUBLIC Represents the constant for the "public" access class.
	static int	EMAIL Represents the contact's email address field(s).
	static int	FORMATTED_ADDR Represents the contact's formatted address.
	static int	FORMATTED_NAME Represents the contact's formatted name.
	static int	NAME Represents the contact's name.
	static int	NAME_FAMILY Represents the family name of the contact's name array.
	static int	NAME_GIVEN Represents the given name of the contact's name array.
	static int	NAME_OTHER Represents another name for the contact's name array.
	static int	NAME_PREFIX Represents a prefix, for example Mr. or Dr., of the contact's name array.
	static int	NAME_SUFFIX Represents a suffix, for example a degree, for the contact's name array.
	static int	NAMESIZE Represents the size of a name string array.
	static int	NICKNAME Represents the contact's nick name.
	static int	NOTE Represents a field used to store a note about the contact.
	static int	ORG Represents the name of a contact's organization.
	static int	PHOTO Represents a photo for the contact.
	static int	PHOTO_URL Represents a string URL to a photo of the contact.
	static int	PUBLIC_KEY Represents the public key of the contact.
	static int	PUBLIC_KEY_STRING Contains a string representation of the contact's public key.
	static int	REVISION Represents the last date and time that this contact's information was modified.
	static int	TEL Represents the contact's telephone number.
	static int	TITLE Represents the contact's title, for example Vice President.
	static int	UID Represents a Contact's unique ID.
	static int	URL Represents a uniform resource locator (URL) to a website.

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) Returns the index number of the preferred field.

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

Represents the size of an address array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NAMESIZE

public static final int NAMESIZE

Represents the size of a name string array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ADDR_POBOX

public static final int ADDR_POBOX

Represents the post office box number field of the contact's address array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ADDR_EXTRA

public static final int ADDR_EXTRA

Represents an extra field of the contact's address array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ADDR_STREET

public static final int ADDR_STREET

Represents the street address field of the contact's address.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ADDR_LOCALITY

public static final int ADDR_LOCALITY

Represents the locality (for example, city) field of the contact's address array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ADDR_REGION

public static final int ADDR_REGION

Represents the region (for example, state or province) field of the contact's address array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ADDR_POSTALCODE

public static final int ADDR_POSTALCODE

Represents the postal code field of the contact's address array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ADDR_COUNTRY

public static final int ADDR_COUNTRY

Represents the country field of the contact's address array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NAME_FAMILY

public static final int NAME_FAMILY

Represents the family name of the contact's name array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NAME_GIVEN

public static final int NAME_GIVEN

Represents the given name of the contact's name array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NAME_OTHER

public static final int NAME_OTHER

Represents another name for the contact's name array.

For example, the contact's middle name.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NAME_PREFIX

public static final int NAME_PREFIX

Represents a prefix, for example Mr. or Dr., of the contact's name array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NAME_SUFFIX

public static final int NAME_SUFFIX

Represents a suffix, for example a degree, for the contact's name array.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL

Represents the constant for the "confidential" access class.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CLASS_PRIVATE

public static final int CLASS_PRIVATE

Represents the constant for the "private" access class.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CLASS_PUBLIC

public static final int CLASS_PUBLIC

Represents the constant for the "public" access class.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ADDR

public static final int ADDR

Represents the address of the contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

BIRTHDAY

public static final int BIRTHDAY

Represents the birthday field of the contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CLASS

public static final int CLASS

Field specifying the class of this contact.

One of CLASS_PRIVATE, CLASS_PUBLIC, or CLASS_CONFIDENTIAL.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

EMAIL

public static final int EMAIL

Represents the contact's email address field(s).

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FORMATTED_ADDR

public static final int FORMATTED_ADDR

Represents the contact's formatted address.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

FORMATTED_NAME

public static final int FORMATTED_NAME

Represents the contact's formatted name.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NAME

public static final int NAME

Represents the contact's name.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NICKNAME

public static final int NICKNAME

Represents the contact's nick name.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NOTE

public static final int NOTE

Represents a field used to store a note about the contact.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ORG

public static final int ORG

Represents the name of a contact's organization.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

PHOTO

public static final int PHOTO

Represents a photo for the contact.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

PHOTO_URL

public static final int PHOTO_URL

Represents a string URL to a photo of the contact.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

PUBLIC_KEY

public static final int PUBLIC_KEY

Represents the public key of the contact.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

PUBLIC_KEY_STRING

public static final int PUBLIC_KEY_STRING

Contains a string representation of the contact's public key.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

REVISION

public static final int REVISION

Represents the last date and time that this contact's information was modified.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

TEL

public static final int TEL

Represents the contact's telephone number.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

TITLE

public static final int TITLE

Represents the contact's title, for example Vice President.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

UID

public static final int UID

Represents a Contact's unique ID.

The unique ID field is valid only if the Contact has been added to a ContactList atleast once in the past. If the Contact has not yet been added to a list, the UID returns Null.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

URL

public static final int URL

Represents a uniform resource locator (URL) to a website.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_ASST

public static final int ATTR_ASST

Represents the information (usually name or phone number) of a contact's assistant.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_AUTO

public static final int ATTR_AUTO

Represents the automobile phone number of a contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_FAX

public static final int ATTR_FAX

Represents the fax number of a contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_HOME

public static final int ATTR_HOME

Represents the home phone number of a contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_MOBILE

public static final int ATTR_MOBILE

Represents the mobile phone number of a contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_OTHER

public static final int ATTR_OTHER

Represents an "other" field for a contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_PAGER

public static final int ATTR_PAGER

Represents a pager number for a contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_PREFERRED

public static final int ATTR_PREFERRED

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. The getPreferredIndex(int) method returns the index of the preferred attribute.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_SMS

public static final int ATTR_SMS

Represents the SMS address of a contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

ATTR_WORK

public static final int ATTR_WORK

Represents the work phone number of a contact.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Detail

getPreferredIndex

public int getPreferredIndex(int field)

Returns the index number of the preferred field.

Parameters:

field - The field to check for a preferred value.

Returns:

An integer representing the index of the preferred value. -1 is returned if no value is marked as preferred.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.