Using Barcode drawer for iPhone Control to generate, create UCC.EAN - 128 image in iPhone applications.

www.OnBarcode.com

The basic fields shown in the previous section all support a single entry. An email address is a String, but any given user may have multiple addresses. BlackBerry devices support up to three addresses for any given contact. You may simply call addField() multiple times, as in the following example.

Using Barcode encoder for Font Control to generate, create GTIN - 12 image in Font applications.

www.OnBarcode.com

addresses, by calling the removeValue() method. The example below will remove the second item; if run after the preceding code, the two remaining addresses will be westley@example.com at index 0 and dread.pirate@example.com at index 1. contact.removeValue(Contact.EMAIL, 1); New email addresses will always be added to the end of the list. You can call setString() with the appropriate index to modify an existing email address slot.

Contact.NAME has the type PIMItem.STRING_ARRAY. It is helpful to be able to access individual components of a name; for example, John Smith can be easily sorted by first name, but you d like individual access to the Smith part in order to sort by the last name. PIM defines five potential elements that make up the name array. BlackBerry supports a subset of these, as shown in Table 6-2.

You can include as few name parts as you like, although, if neither a given nor a family name is included, BlackBerry will apply a default of Empty and Contact respectively. It is safe to include unsupported name parts such as NAME_SUFFIX. These will be silently discarded. If you d prefer to check at runtime whether a name is supported, use the method isSupportedArrayElement().

The phone number field is the first that supports attributes. As described previously, an attribute provides more detailed information about the data it contains. When you add multiple email addresses, there is no way to distinguish whether one email address will be more appropriate than another to use. For phone numbers, however, you can attach an attribute to each number describing its purpose, as the following code demonstrates.

As long as you stick to the defined attributes and don t repeat yourself, everything will work as expected. However, BlackBerry follows some unusual rules in other cases. If you try to add an attribute that isn t supported (such as Contact.AUTO), or one that already has a value assigned to it, then, rather than discarding the value or throwing an error, the number will be assigned to the next available slot. Therefore, it is possible for your code to add a mobile number to a contact, and have that number stored as a pager number. There is a limit of eight numbers per contact, and adding any more after that will result in a FieldFullException. To avoid this problem, you can use the countValues() method to determine how many entries are already stored in a field, and then a getAttributes() call to retrieve the attributes. Attributes are bit flags, so you can use a bitwise AND operator to determine whether a given attribute is set, as shown in the next example. This code will scan through all the telephone numbers already set on a contact and, if it finds a mobile number, update it.