net.rim.blackberry.api.pdap
Interface BlackBerryContact

All Superinterfaces:
Contact, PIMItem

public interface BlackBerryContact
extends Contact

This interface represents a contact contained in the default RIM BlackBerry address book.

This interface defines extended fields in addition to the standard fields that are used to reference fields with the BlackBerryContact.

You can use any of the static field constants defined here in your code on any valid BlackBerryContact instance.

BlackBerryContact objects support the following fields and attributes:

Field Values Per Field Supported Attributes
Contact.BIRTHDAY 1 PIMItem.ATTR_NONE
Contact.NAME 1 PIMItem.ATTR_NONE
Contact.TITLE 1 PIMItem.ATTR_NONE
Contact.ORG 1 PIMItem.ATTR_NONE
BlackBerryContact.ORG_YOMI 1 PIMItem.ATTR_NONE
Contact.ADDR 1 Contact.ATTR_WORK, Contact.ATTR_HOME
Contact.NOTE 1 PIMItem.ATTR_NONE
Contact.TEL 8 Contact.ATTR_WORK, Contact.ATTR_HOME, Contact.ATTR_MOBILE, Contact.ATTR_PAGER, Contact.ATTR_FAX, Contact.ATTR_OTHER, Contact.ATTR_HOME2, Contact.ATTR_WORK2
Contact.EMAIL 3 PIMItem.ATTR_NONE
Contact.PHOTO 1 PIMItem.ATTR_NONE
Contact.UID 1 PIMItem.ATTR_NONE
BlackBerryContact.ANNIVERSARY 1 PIMItem.ATTR_NONE
BlackBerryContact.USER1 1 PIMItem.ATTR_NONE
BlackBerryContact.USER2 1 PIMItem.ATTR_NONE
BlackBerryContact.USER3 1 PIMItem.ATTR_NONE
BlackBerryContact.USER4 1 PIMItem.ATTR_NONE
BlackBerryContact.PIN 1 PIMItem.ATTR_NONE
BlackBerryContact.DCID 1 PIMItem.ATTR_NONE

Special Notes

The NAME array

The NAME_OTHER and NAME_SUFFIX entries of the NAME array are not supported. They will be silently dropped if present in the parameter passed in to the addStringArray() method.

On commit, if the NAME_GIVEN and NAME_LAST entries in the NAME array are null, and the ORG field is not assigned, then default values of "Empty" and "Contact" are assigned to NAME_GIVEN and NAME_LAST respectively.

The ADDR array

The ADDR_POBOX entry of the ADDR array is not supported. It will be silently dropped if present in the parameter passed in to the addStringArray() method.

The ADDR field supports at most 2 values, with each value having a distinct attribute. The getAttributes() method for the ADDR field will always return one of ATTR_WORK, or ATTR_HOME.

When adding an ADDR field, the attribute is chosen by examining the attributes parameter for the presence of one of the supported attributes in the following order: ATTR_HOME, ATTR_WORK, with the first one found that does not have a value already assigned to it being chosen. If no such attribute is found, then the first available attribute is used in the order: ATTR_WORK, ATTR_HOME, (even though the attribute is not present in the attributes parameter).

The TEL field

The TEL field supports at most 8 values, with each value having a distinct attribute. The getAttributes() method for the TEL field will always return one of ATTR_WORK, ATTR_HOME, ATTR_MOBILE, ATTR_PAGER, ATTR_FAX, ATTR_OTHER, ATTR_HOME2, or ATTR_WORK2.

When adding a TEL field, the attribute is chosen by examining the attributes parameter for the presence of one of the supported attributes in the following order: ATTR_FAX, ATTR_PAGER, ATTR_MOBILE, ATTR_HOME2, ATTR_HOME, ATTR_WORK2, ATTR_WORK, ATTR_OTHER with the first one found that does not have a value already assigned to it being chosen. If no such attribute is found, or there are no vacant fields for values of the given attribute type, then the first available attribute is used in the order: ATTR_OTHER, ATTR_WORK, ATTR_WORK2, ATTR_HOME, ATTR_HOME2, ATTR_MOBILE, ATTR_PAGER, ATTR_FAX (even though the attribute is not present in the attributes parameter).

The ORG field

Setting the ORG field to the empty string "" is equivalent to removing any value from the field.

The USER fields

The labels for the extended fields USER1-4 can be modified using setFieldLabel(). Changing a label affects all contacts in the list.

See Also:
Contact, PIMItem
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

Field Summary
Category: Signed static int ANNIVERSARY
          Anniversary date for a contact.
Category: Signed static int ATTR_HOME2
          Attribute used on values in the TEL field to indicate that the phone number is a secondary home number.
Category: Signed static int ATTR_WORK2
          Attribute used on values in the TEL field to indicate that the phone number is a secondary work number.
Category: Signed static int DCID
          Direct Connect ID field for communicating with devices on the iDEN network.
Category: Signed static int NAME_FAMILY_YOMI
          Index into the string array for a NAME field, where the data at this index represents the reading of the name in the NAME_FAMILY index.
Category: Signed static int NAME_GIVEN_YOMI
          Index into the string array for a NAME field, where the data at this index represents the reading of the name in the NAME_GIVEN index.
Category: Signed static int ORG_YOMI
          Field specifying the reading of the ORG field's value.
Category: Signed static int PIN
          Unique identifier for a BlackBerry device.
Category: Signed static int USER1
          User defined String field.
Category: Signed static int USER2
          User defined String field.
Category: Signed static int USER3
          User defined String field.
Category: Signed static int USER4
          User defined String field.
 
Fields inherited from interface javax.microedition.pim.Contact
ADDR, ADDR_COUNTRY, ADDR_EXTRA, ADDR_LOCALITY, ADDR_POBOX, ADDR_POSTALCODE, ADDR_REGION, ADDR_STREET, ATTR_ASST, ATTR_AUTO, ATTR_FAX, ATTR_HOME, ATTR_MOBILE, ATTR_OTHER, ATTR_PAGER, ATTR_PREFERRED, ATTR_SMS, ATTR_WORK, BIRTHDAY, CLASS, CLASS_CONFIDENTIAL, CLASS_PRIVATE, CLASS_PUBLIC, EMAIL, FORMATTED_ADDR, FORMATTED_NAME, NAME, NAME_FAMILY, NAME_GIVEN, NAME_OTHER, NAME_PREFIX, NAME_SUFFIX, NICKNAME, NOTE, ORG, PHOTO, PHOTO_URL, PUBLIC_KEY, PUBLIC_KEY_STRING, REVISION, TEL, TITLE, UID, URL
 
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
 
Methods inherited from interface javax.microedition.pim.Contact
getPreferredIndex
 
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

PIN

static final int PIN
Unique identifier for a BlackBerry device.

This field is of type String, but the value must be a valid hex number.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

USER1

static final int USER1
User defined String field.

The field can be named using the BlackBerryPIMList.setFieldLabel(int, java.lang.String) method.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

USER2

static final int USER2
User defined String field.

The field can be named using the BlackBerryPIMList.setFieldLabel(int, java.lang.String) method.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

USER3

static final int USER3
User defined String field.

The field can be named using the BlackBerryPIMList.setFieldLabel(int, java.lang.String) method.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

USER4

static final int USER4
User defined String field.

The field can be named using the BlackBerryPIMList.setFieldLabel(int, java.lang.String) method.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

DCID

static final int DCID
Direct Connect ID field for communicating with devices on the iDEN network.

This field is of type String and is only supported on iDEN devices. To check if this field is supported use the PIMList.isSupportedField(int) method.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.0.0

ANNIVERSARY

static final int ANNIVERSARY
Anniversary date for a contact.

This field is of type Date.

Note that in RIM's implementation any date specified for this field will be rounded down to midnight of the nearest day.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.3.0

ORG_YOMI

static final int ORG_YOMI
Field specifying the reading of the ORG field's value.

The value of the ORG_YOMI field must be set after setting the value of the ORG field. This is because the value of the ORG_YOMI field will be automatically removed if the value of the ORG field is removed or changed. Also, when a Contact is committed, if the ORG_YOMI field is set but the ORG field is not then the value of the ORG_YOMI field will NOT be saved, and will be removed by commit(). This logic is because the value of the ORG_YOMI field is directly related to the value in the ORG field and is not useful on its own.

This field is only present in the native BlackBerry Address Book application in languages where the pronunciation of the company name may be different from its spelling, such as in Japanese.

This field is of type String.

See Also:
BlackBerryContact.NAME_GIVEN_YOMI, BlackBerryContact.NAME_FAMILY_YOMI, Contact.ORG, Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

ATTR_HOME2

static final int ATTR_HOME2
Attribute used on values in the TEL field to indicate that the phone number is a secondary home number.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

ATTR_WORK2

static final int ATTR_WORK2
Attribute used on values in the TEL field to indicate that the phone number is a secondary work number.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

NAME_GIVEN_YOMI

static final int NAME_GIVEN_YOMI
Index into the string array for a NAME field, where the data at this index represents the reading of the name in the NAME_GIVEN index.

When a Contact is committed, if the NAME_GIVEN_YOMI index of the NAME field is set to a non-null value but the NAME_GIVEN field is null then the value of the NAME_GIVEN_YOMI index will NOT be saved, and will be removed by commit().

This field is only present in the native BlackBerry Address Book application in languages where the pronunciation of the company name may be different from its spelling, such as in Japanese.

See Also:
BlackBerryContact.NAME_FAMILY_YOMI, BlackBerryContact.ORG_YOMI, Contact.NAME, Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

NAME_FAMILY_YOMI

static final int NAME_FAMILY_YOMI
Index into the string array for a NAME field, where the data at this index represents the reading of the name in the NAME_FAMILY index.

When a Contact is committed, if the NAME_FAMILY_YOMI index of the NAME field is set to a non-null value but the NAME_FAMILY field is null then the value of the NAME_FAMILY_YOMI index will NOT be saved, and will be removed by commit().

This field is only present in the native BlackBerry Address Book application in languages where the pronunciation of the company name may be different from its spelling, such as in Japanese.

See Also:
BlackBerryContact.NAME_GIVEN_YOMI, BlackBerryContact.ORG_YOMI, Contact.NAME, Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.