|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Contact.
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.
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 |
public static final int ADDRSIZE
PIMList.stringArraySize(int) instead
public static final int NAMESIZE
PIMList.stringArraySize(int) instead
public static final int ADDR_POBOX
public static final int ADDR_EXTRA
public static final int ADDR_STREET
public static final int ADDR_LOCALITY
public static final int ADDR_REGION
public static final int ADDR_POSTALCODE
public static final int ADDR_COUNTRY
public static final int NAME_FAMILY
public static final int NAME_GIVEN
public static final int NAME_OTHER
For example, this could be used to contain this contact's middle name.
public static final int NAME_PREFIX
For example, this could be used to contain a title, such as 'Dr.' or 'Ms.'
public static final int NAME_SUFFIX
For example, this could be used to contain an educational or professional entitlement, such as 'Phd' or 'QC'.
public static final int CLASS_CONFIDENTIAL
public static final int CLASS_PRIVATE
public static final int CLASS_PUBLIC
public static final int BIRTHDAY
public static final int CLASS
One of CLASS_PRIVATE, CLASS_PUBLIC, or
CLASS_CONFIDENTIAL.
public static final int EMAIL
public static final int FORMATTED_ADDR
The formatted address consists of the various fields that make up an address.
public static final int FORMATTED_NAME
The formatted name represents the fields that make up a full name.
public static final int NOTE
The data associated with this field conforms to the X.520 Description data format.
public static final int PHOTO
The photo is stored in inline binary format and is directly related
to the PHOTO_URL field.
public static final int PHOTO_URL
The photo URL is stored in the same memory location as the photo.
public static final int PUBLIC_KEY
Manipulation of this field may affect data stored in the
PUBLIC_KEY_STRING field since both are stored in the same memory
location.
public static final int PUBLIC_KEY_STRING
Manipulation of this field may affect data stored in the PUBLIC_KEY
field since both are stored in the same memory location.
public static final int REVISION
public static final int TEL
This data is stored as a string. Any valid string will be acceptable.
public static final int TITLE
This title is based on the X.520 Title attribute.
public static final int UID
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.
public static final int ATTR_ASST
public static final int ATTR_AUTO
public static final int ATTR_HOME
public static final int ATTR_MOBILE
public static final int ATTR_OTHER
public static final int ATTR_PAGER
public static final int ATTR_PREFERRED
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.
public static final int ATTR_WORK
| Method Detail |
public int getPreferredIndex(int field)
field - Field to check for a preferred value.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.