|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface Contact
Represents a single Contact entry in a PIM Contact database. The supported field list for a Contact is also a subset of the fields defined by the vCard specification from the Internet Mail Consortium (http://www.imc.org). This set of fields included in this Contact class represents those necessary to provide the relevant information about a contact without compromising platform portability.
The Contact class has many different fields that it can support. However,
each individual Contact object supports only fields valid for its associated
list. Its ContactList restricts what fields in a Contact are retained. This
reflects that some native Contact databases do not support all of the fields
available in a Contact item. The methods
PIMList.isSupportedField(int) and
PIMList.getSupportedAttributes(int) can be used to determine if
particular Contact fields and types are supported by a ContactList and
therefore persisted when the Contact is committed to its list. Attempts to
add or get data based on fields not supported in the Contact's ContactList
result in a UnsupportedFieldException.
| Fields | Type of Data Associated with Field |
|---|---|
NAME, ADDR |
PIMItem.STRING_ARRAY |
EMAIL, FORMATTED_NAME, NICKNAME, NOTE, ORG, TEL, TITLE, UID, URL |
PIMItem.STRING |
BIRTHDAY, REVISION |
PIMItem.DATE |
PHOTO, PUBLIC_KEY |
PIMItem.BINARY |
PHOTO_URL, PUBLIC_KEY_STRING |
PIMItem.STRING |
CLASS |
PIMItem.INT |
All Contact fields may or may not be supported by a particular list. This is
due to the fact that underlying native databases may not support all of the
fields defined in this API. Support for any of the fields can be determined
by the method PIMList.isSupportedField(int).
Native Contact databases may require some of the fields to have values assigned to them in order to be persisted. If an application does not provide values for these fields, default values are provided for the Contact by the VM when the Contact is persisted.
ContactList contacts = null;
try {
contacts = (ContactList) PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
} catch (PIMException e) {
// An error occurred
return;
}
Contact contact = contacts.createContact();
String[] addr = new String[contacts.stringArraySize(Contact.ADDR)];
String[] name = new String[contacts.stringArraySize(Contact.NAME)];
if (contacts.isSupportedField(Contact.FORMATTED_NAME)
contact.addString(Contact.FORMATTED_NAME, PIMItem.ATTR_NONE, "Mr. John Q. Public, Esq.");
if (contacts.isSupportedArrayElement(Contact.NAME, Contact.NAME_FAMILY))
name[Contact.NAME_FAMILY] = "Public";
if (contacts.isSupportedArrayElement(Contact.NAME, Contact.NAME_GIVEN))
name[Contact.NAME_GIVEN] = "John";
contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);
if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_COUNTRY))
addr[Contact.ADDR_COUNTRY] = "USA";
if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_LOCALITY))
addr[Contact.ADDR_LOCALITY] = "Coolsville";
if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_POSTALCODE))
addr[Contact.ADDR_POSTALCODE] = "91921-1234";
if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_STREET))
addr[Contact.ADDR_STREET] = "123 Main Street";
if (contacts.isSupportedField(Contact.ADDR))
contact.addStringArray(Contact.ADDR, Contact.ATTR_HOME, addr);
if (contacts.isSupportedField(Contact.TEL))
contact.addString(Contact.TEL, Contact.ATTR_HOME, "613-123-4567");
if (contacts.maxCategories() != 0
&& contacts.isCategory("Friends"))
contact.addToCategory("Friends");
if (contacts.isSupportedField(Contact.BIRTHDAY))
contact.addDate(Contact.BIRTHDAY, PIMItem.ATTR_NONE, new Date().getTime());
if (contacts.isSupportedField(Contact.EMAIL)) {
contact.addString(Contact.EMAIL, Contact.ATTR_HOME | Contact.ATTR_PREFERRED, "jqpublic@xyz.dom1.com");
}
try {
contact.commit();
} catch (PIMException e) {
// An error occurred
}
try {
contacts.close();
} catch (PIMException e) {
}
UnsupportedFieldException. In this case, the setting of the
whole Contact is rejected if any of the fields are not supported in the
particular list implementation.
ContactList contacts = null;
try {
contacts = (ContactList) PIM.getInstance().openPIMList( PIM.CONTACT_LIST,
PIM.READ_WRITE );
} catch( PIMException e ) {
// An error occurred
return;
}
Contact contact = contacts.createContact();
String[] name = new String[ contacts.stringArraySize( Contact.NAME ) ];
name[ Contact.NAME_GIVEN ] = "John";
name[ Contact.NAME_FAMILY ] = "Public";
String[] addr = new String[ contacts.stringArraySize( Contact.ADDR ) ];
addr[ Contact.ADDR_COUNTRY ] = "USA";
addr[ Contact.ADDR_LOCALITY ] = "Coolsville";
addr[ Contact.ADDR_POSTALCODE ] = "91921-1234";
addr[ Contact.ADDR_STREET ] = "123 Main Street";
try {
contact.addString( Contact.FORMATTED_NAME, PIMItem.ATTR_NONE,
"Mr. John Q. Public, Esq." );
contact.addStringArray( Contact.NAME, PIMItem.ATTR_NONE, name );
contact.addStringArray( Contact.ADDR, Contact.ATTR_HOME, addr );
contact.addString( Contact.TEL, Contact.ATTR_HOME, "613-123-4567" );
contact.addToCategory( "Friends" );
contact.addDate( Contact.BIRTHDAY, PIMItem.ATTR_NONE, new Date().getTime() );
contact.addString( Contact.EMAIL, Contact.ATTR_HOME
| Contact.ATTR_PREFERRED, "jqpublic@xyz.dom1.com" );
} catch( UnsupportedFieldException e ) {
// In this case, we choose not to save the contact at all if any of the
// fields are not supported on this platform.
System.out.println( "Contact not saved" );
return;
}
try {
contact.commit();
} catch( PIMException e ) {
// An error occurred
}
try {
contacts.close();
} catch( PIMException e ) {
}
The RIM extension fields and attributes for Contacts are all defined in
BlackBerryContact. Any instance of
Contact that is retrieved from a
BlackBerryContactList will be an instance
of BlackBerryContact and will support all RIM extension fields
and attributes defined therein. Casting such a Contact to a
BlackBerryContact is possible if use of any RIM extension
methods defined therein is desired.
Contact.PHOTO field, which is supported by RIM's implementation, is
a binary field whose value is the bytes of the image to use for the contact's
photo. Supported image formats are those supported by
EncodedImage.
Note that the javadocs for addBinary(),
setBinary(), and getBinary() all state
that the binary data must be encoded "in a "B" binary encoded string as
defined by [IETF RFC 2047]". This means that the photo data returned
from getBinary() will be Base64-encoded. Also, data may be
specified to setBinary() and addBinary() in
either raw bytes or Base64-encoded; if raw bytes are specified then they are
converted to Base64. To encode or decode Base64 data you may use
Base64OutputStream or
Base64InputStream, respectively.
Also note that in addBinary() and setBinary()
the offset and length parameters apply to the
unencoded array and not the encoded array. Therefore,
addBinary() and setBinary() decode the entire
Base64 data and then apply the offset and length to get a subset of
the data.
If the PHOTO field has an invalid value, such as the bytes of an unrecognized
image format or corrupt bytes of a known image format, then both
addBinary() and setBinary() will complete successfully,
but commit() will throw PIMException. In order to
ensure that an image's bytes will be accepted by commit() invoke
EncodedImage.createEncodedImage(byte[], int, int) with the raw bytes
of the image; if the method returns normally then the image will be accepted by
commit() and if it throws IllegalArgumentException then
the bytes will be rejected by commit(), causing it to throw
PIMException.
The code below shows how to work with the PHOTO field using
Base64 encoding. Note the invocations of addBinary() and
setBinary() that specify the length of the unencoded
array.
import java.io.IOException;
import javax.microedition.pim.Contact;
import javax.microedition.pim.ContactList;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;
import javax.microedition.pim.PIMItem;
import net.rim.device.api.io.Base64InputStream;
import net.rim.device.api.io.Base64OutputStream;
public class PhotoExample
{
private Contact _contact;
public PhotoExample() throws PIMException
{
ContactList contactList = (ContactList) PIM.getInstance().openPIMList(
PIM.CONTACT_LIST, PIM.READ_WRITE );
_contact = contactList.createContact();
}
public void setPhoto() throws IOException
{
byte[] photo = getSamplePhoto();
byte[] photoEncoded = Base64OutputStream.encode( photo, 0,
photo.length, false, false );
if( _contact.countValues( Contact.PHOTO ) > 0 ) {
_contact.setBinary( Contact.PHOTO, 0, PIMItem.ATTR_NONE,
photoEncoded, 0, photo.length );
} else {
_contact.addBinary( Contact.PHOTO, PIMItem.ATTR_NONE, photoEncoded,
0, photo.length );
}
}
public byte[] getPhoto() throws IOException
{
if( _contact.countValues( Contact.PHOTO ) > 0 ) {
byte[] photoEncoded = _contact.getBinary( Contact.PHOTO, 0 );
return Base64InputStream.decode( photoEncoded, 0,
photoEncoded.length );
} else {
return null;
}
}
private static byte[] getSamplePhoto()
{
// return the raw bytes of the photo to use
}
public static void main( String[] args ) throws Throwable
{
PhotoExample example = new PhotoExample();
example.setPhoto();
example.getPhoto();
}
}
ContactList,
BlackBerryContact,
Internet Mail Consortium PDI| Field Summary | ||
|---|---|---|
static int |
ADDR
Field specifying an address for this Contact. |
|
static int |
ADDR_COUNTRY
Index into the string array for an ADDR field, where the
data at this index represents the country of a particular address. |
|
static int |
ADDR_EXTRA
Index into the string array for an ADDR field, where the
data at this index represents any extra info of a particular address. |
|
static int |
ADDR_LOCALITY
Index into the string array for an ADDR field, where the
data at this index represents the locality (for example, a city) of a
particular address. |
|
static int |
ADDR_POBOX
Index into the string array for an ADDR field, where the
data at this index represents the post office box of a particular
address. |
|
static int |
ADDR_POSTALCODE
Index into the string array for an ADDR field, where the
data at this index represents the postal code (for example, a zip code)
of a particular address. |
|
static int |
ADDR_REGION
Index into the string array for an ADDR field, where the
data at this index represents the region (for example, a province, state,
or territory) of a particular address. |
|
static int |
ADDR_STREET
Index into the string array for an ADDR field, where the
data at this index represents the street information of a particular
address. |
|
static int |
ATTR_ASST
Attribute classifying a data value as related to an ASSISTANT. |
|
static int |
ATTR_AUTO
Attribute classifying a data value as related to an AUTOMOBILE. |
|
static int |
ATTR_FAX
Attribute classifying a data value as related to FAX. |
|
static int |
ATTR_HOME
Attribute classifying a data value as related to HOME contact information. |
|
static int |
ATTR_MOBILE
Attribute classifying a data value as related to MOBILE contact information. |
|
static int |
ATTR_OTHER
Attribute classifying a data value as "OTHER". |
|
static int |
ATTR_PAGER
Attribute classifying a data value as related to PAGER. |
|
static int |
ATTR_PREFERRED
Attribute classifying a data value with preferred status for retrieval or display purposes (platform specific). |
|
static int |
ATTR_SMS
Attribute classifying a data value as related to SMS (short message service) contact information. |
|
static int |
ATTR_WORK
Attribute classifying a data value as related to WORK contact information. |
|
static int |
BIRTHDAY
Field for the birthday of the Contact. |
|
static int |
CLASS
Field specifying the desired access class for this contact. |
|
static int |
CLASS_CONFIDENTIAL
Constant indicating this contact's class of access is confidential. |
|
static int |
CLASS_PRIVATE
Constant indicating this contact's class of access is private. |
|
static int |
CLASS_PUBLIC
Constant indicating this contact's class of access is public. |
|
static int |
EMAIL
Field for an e-mail address. |
|
static int |
FORMATTED_ADDR
Field represents a formatted version of a complete address for the Contact entry. |
|
static int |
FORMATTED_NAME
Field represents a formatted version of a name for the Contact entry. |
|
static int |
NAME
Field specifying the name for this contact. |
|
static int |
NAME_FAMILY
Index into the string array for a NAME field, where the
data at this index represents the family name. |
|
static int |
NAME_GIVEN
Index into the string array for a NAME field, where the
data at this index represents the given name. |
|
static int |
NAME_OTHER
Index into the string array for a NAME field, where the
data at this index represents other alternate name or names, such as a
"middle" name. |
|
static int |
NAME_PREFIX
Index into the string array for a NAME field, where the
data at this index represents a prefix to a name. |
|
static int |
NAME_SUFFIX
Index into the string array for a NAME field, where the
data at this index represents a suffix to a name. |
|
static int |
NICKNAME
Field where the data represents a nickname. |
|
static int |
NOTE
Field specifying supplemental information or a comment associated with a Contact. |
|
static int |
ORG
Field specifying the organization name or units associated with a Contact. |
|
static int |
PHOTO
Field specifying a photo for a Contact. |
|
static int |
PHOTO_URL
Field specifying a photo of a Contact. |
|
static int |
PUBLIC_KEY
Field specifying the public encryption key for a Contact. |
|
static int |
PUBLIC_KEY_STRING
Field specifying the public encryption key for a Contact. |
|
static int |
REVISION
Field specifying the last modification date and time of a Contact item. |
|
static int |
TEL
Field for a voice telephone number. |
|
static int |
TITLE
Field specifying the job title for a Contact. |
|
static int |
UID
Field specifying a unique ID for a Contact. |
|
static int |
URL
Field specifying the uniform resource locator for a Contact. |
|
| 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 of the value marked with the attribute ATTR_PREFERRED for the given 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 |
|---|
static final int ADDR
static final int ADDR_COUNTRY
ADDR field, where the
data at this index represents the country of a particular address. Data
for this field is of String type.
static final int ADDR_EXTRA
ADDR field, where the
data at this index represents any extra info of a particular address.
Data for this field is of String type.
static final int ADDR_LOCALITY
ADDR field, where the
data at this index represents the locality (for example, a city) of a
particular address. Data for this field is of String type.
static final int ADDR_POBOX
ADDR field, where the
data at this index represents the post office box of a particular
address. Data for this field is of String type.
static final int ADDR_POSTALCODE
ADDR field, where the
data at this index represents the postal code (for example, a zip code)
of a particular address. Data for this field is of String type.
static final int ADDR_REGION
ADDR field, where the
data at this index represents the region (for example, a province, state,
or territory) of a particular address. Data for this field is of String
type.
static final int ADDR_STREET
ADDR field, where the
data at this index represents the street information of a particular
address. Data for this field is of String type.
static final int ATTR_ASST
static final int ATTR_AUTO
static final int ATTR_FAX
static final int ATTR_HOME
static final int ATTR_MOBILE
static final int ATTR_OTHER
static final int ATTR_PAGER
static final int ATTR_PREFERRED
static final int ATTR_SMS
static final int ATTR_WORK
static final int BIRTHDAY
Date, which is
milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native Contact database only support contact date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.
RIM Implementation Note: Note that in RIM's implementation any date specified for this field will be rounded down to midnight of the nearest day. Also, if the specified date has a year that is out of range then it will be snapped to the nearest valid year.
static final int CLASS
Contact.CLASS_PRIVATE, Contact.CLASS_PUBLIC, or
Contact.CLASS_CONFIDENTIAL.
static final int CLASS_CONFIDENTIAL
static final int CLASS_PRIVATE
static final int CLASS_PUBLIC
static final int EMAIL
static final int FORMATTED_ADDR
static final int FORMATTED_NAME
static final int NAME
static final int NAME_FAMILY
NAME field, where the
data at this index represents the family name. For example: "Stevenson"
static final int NAME_GIVEN
NAME field, where the
data at this index represents the given name. For example: "Chris"
static final int NAME_OTHER
NAME field, where the
data at this index represents other alternate name or names, such as a
"middle" name. For example: "John, Johnny"
static final int NAME_PREFIX
NAME field, where the
data at this index represents a prefix to a name. For example: "Dr."
static final int NAME_SUFFIX
NAME field, where the
data at this index represents a suffix to a name. For example: "M.D.,
A.C.P."
static final int NICKNAME
static final int NOTE
static final int ORG
static final int PHOTO
RIM Implementation Note: For details about the PHOTO
field please see the RIM Implementation
Notes.
static final int PHOTO_URL
static final int PUBLIC_KEY
static final int PUBLIC_KEY_STRING
static final int REVISION
Date, which is milliseconds since
the epoch (00:00:00 GMT, January 1, 1970).
Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native Contact database only support contact date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.
static final int TEL
static final int TITLE
static final int UID
String.equals(Object). UID is read only
if the Contact has been committed to a ContactList at least once in its
lifetime. The UID is not set if the Contact has never been committed to a
ContactList; countValues(UID) returns 0 before a newly created Contact
object is committed to its list. The attribute is valid for the
persistent life of the Contact and may be reused by the platform once
this particular Contact is deleted. Data for this field is of String data
type.
static final int URL
| Method Detail |
|---|
int getPreferredIndex(int field)
ATTR_PREFERRED for the given field. Only one value per
field may be marked as preferred. PIMList.isSupportedField(int)
should be used to verify the field validity for this item prior to
invoking this method. PIMList.isSupportedAttribute(int, int)
should be used to verify the attribute validity for this item prior to
invoking this method.
field - The field to check for a preferred value.
IllegalArgumentException - if the specified field is not a valid
field for a Contact.
UnsupportedFieldException - if the specified field is not supported by
the implementing class.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal