|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.
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.
Adding data to a Contact
Before adding data to a contact, invoke ContactList.IsSupportedField() to check
that the field you are adding is supported by the list.
If you try to add data to a field that does not exist, a PIMException is thrown.
ContactList contactList = (ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.WRITE_ONLY);
if (contactList.isSupportedField(Contact.NAME)) {
Contact contact = contactList.createContact();
String[] name = new String[ contactList.stringArraySize( Contact.NAME ) ];
name[Contact.NAME_GIVEN] = "Kate";
name[Contact.NAME_FAMILY] = "Turner";
contact.addStringArray(Contact.NAME, Contact.ATTR_NONE, new String[] {"Kate Turner"});
contact.commit();
return true;
} else {
return false;
}
Similarly, to add a new attribute to a contact, invoke
ContactList.isSupportedAttribute() to check that the attribute is
supported by the field. If a specified field or attribute are not supported,
an PIMException is 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, invoke countValues()
to determine whether the field is empty. If the field is not empty, invoke
removeValue() to remove the data from the field.
String[] name = new String[contactList.stringArraySize(Contact.NAME)];
if (contact.countValues(Contact.NAME) > 0) {
contact.removeValue(Contact.NAME, 0);
}
name[Contact.NAME_GIVEN] = "Kate";
name[Contact.NAME_FAMILY] = "Turner";
contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, nameArray);
Removing a contact
To remove a Contact, invoke removeContact(). The
following example removes a contact from a contact list:
contactList.removeContact(contact);
Saving a Contact object
The commit() method must be used to save the object to a
list. In the following example, isModified() is called to determine whether
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
See BlackBerryContact for more information
on the behavior of Contacts on RIM devices.
For more information about this class or about the personal information management (PIM) API, see The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.
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 |
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 |
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 javax.microedition.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 javax.microedition.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 ADDR_COUNTRY
public static final int ADDR_EXTRA
public static final int ADDR_LOCALITY
public static final int ADDR_POBOX
public static final int ADDR_POSTALCODE
public static final int ADDR_REGION
public static final int ADDR_STREET
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. The getPreferredIndex(int)
method returns the index of the preferred attribute.
public static final int ATTR_WORK
public static final int BIRTHDAY
public static final int CLASS
One of CLASS_PRIVATE, CLASS_PUBLIC, or CLASS_CONFIDENTIAL.
public static final int CLASS_CONFIDENTIAL
public static final int CLASS_PRIVATE
public static final int CLASS_PUBLIC
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 NAME_FAMILY
public static final int NAME_GIVEN
public static final int NAME_OTHER
For example, the contact's middle name.
public static final int NAME_PREFIX
public static final int NAME_SUFFIX
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 atleast once in the past. If the
Contact has not yet been added to a list, the UID returns Null.
public static final int URL
| Method Detail |
public int getPreferredIndex(int field)
field - The 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-2007 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.