Java Reference
In-Depth Information
A datum for a field with multiple values such as
Contact.TEL
may have an attribute
indicating what
kind
it is. For example, a contact may have multiple telephone numbers,
one each for home, mobile, office, and fax phones. While you use the field index to obtain
each of these numbers, you use the attribute of a given field to determine
which
number
is which. You do this using the
getAttributes
method of a
PIMItem
instance, which returns
a bit mask of attributes for the given field and index, like so:
int attrs = item.getAttributes( Contact.TEL, i );
As I write this, attributes are only used for
Contact
items, and Table 7-4 shows the list
of attributes for
Contact
items. Of course, this may change in future versions of the PIM
package.
Table 7-4.
Attributes of Contact Fields
Attribute
Purpose
ATTR_ASST
Field datum related to an administrative assistant
ATTR_AUTO
Field datum related to auto
ATTR_FAX
Field datum related to facsimile
ATTR_HOME
Field datum related to home
ATTR_MOBILE
Field datum related to mobile
ATTR_OTHER
Field datum related to other information
ATTR_PAGER
Field datum related to pager
ATTR_PREFERRED
Field datum related to preferred contact (may only be on one datum)
ATTR_SMS
Field datum related to SMS
ATTR_WORK
Field datum related to work
Two fields—
Contact.NAME
and
Contact.ADDR
—return an array of strings. This is
because different implementations may have differing numbers of fields for a single
name or address. For example, does an address consist of one line for the street and one
for the suite or apartment, or two? Consequently, you can access each portion of these
fields as a single string within the returned array of strings. The
Contact
class provides
constants that let you index these arrays to obtain specific parts of a field, such as the
city, street, or postal code of an address. Table 7-5 shows the indexes you can use when
accessing elements of these
String
arrays. You can also determine the size of these arrays
by invoking a
ContactList
's
stringArraySize
, passing either
Contact.NAME
or
Contact.ADDR
to obtain the maximum number of permissible elements in either array.
