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	10	Contact.ATTR_WORK, Contact.ATTR_HOME, Contact.ATTR_MOBILE, Contact.ATTR_PAGER, Contact.ATTR_FAX, Contact.ATTR_OTHER, BlackBerryContact.ATTR_HOME2, BlackBerryContact.ATTR_WORK2, BlackBerryContact.ATTR_MOBILE2, BlackBerryContact.ATTR_FAX2
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 10 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, ATTR_WORK2, ATTR_MOBILE2, ATTR_FAX2.

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_FAX2, ATTR_FAX, ATTR_PAGER, ATTR_MOBILE2, 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_MOBILE2, ATTR_PAGER, ATTR_FAX, ATTR_FAX2 (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
	static int	ANNIVERSARY Anniversary date for a contact.
	static int	ATTR_FAX2 Attribute used on values in the TEL field to indicate that the fax number is a secondary fax number.
	static int	ATTR_HOME2 Attribute used on values in the TEL field to indicate that the phone number is a secondary home number.
	static int	ATTR_MOBILE2 Attribute used on values in the TEL field to indicate that the mobile number is a secondary mobile number.
	static int	ATTR_WORK2 Attribute used on values in the TEL field to indicate that the phone number is a secondary work number.
	static int	DCID Direct Connect ID field for communicating with devices on the iDEN network.
	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.
	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.
	static int	ORG_YOMI Field specifying the reading of the ORG field's value.
	static int	PIN Unique identifier for a BlackBerry device.
	static int	USER1 User defined String field.
	static int	USER2 User defined String field.
	static int	USER3 User defined String field.
	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

ATTR_MOBILE2

static final int ATTR_MOBILE2

Attribute used on values in the TEL field to indicate that the mobile number is a secondary mobile 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 6.0.0

ATTR_FAX2

static final int ATTR_FAX2

Attribute used on values in the TEL field to indicate that the fax number is a secondary fax 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 6.0.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