|
PDAP Public Review Draft | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 IETF vCard 3.0 specification [RFC 2426]. 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 field IDs 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 element.
The methods PIMList.isSupportedField(int)
and PIMList.getSupportedTypes(int)
can be used to determine if a particular Contact field is supported by a ContactList
and therefore persisted when the Contact is committed to its list. Attempts to set
or get data based on field IDs not supported in the Contact's ContactList result
in a PIMException
.
A contact contains three types of data:
PIMElement.getString(int)
and PIMElement.setString(int, String)
are used for Contact.FORMATTED_NAME
since a String value is associated with formatted names).
Some named fields also have a further defining type ID associated with them.
This allows for the appearance of more than one instance of a field. For instance,
a contact entry may have more than one telephone number by storing mulitple phone numbers with
different type IDs (e.g. for the Contact.TEL
field ID, use different type ids
such as Contact.TYPE_HOME
and Contact.TYPE_WORK
.
The specific combination of field and type ID must only appear once in the Contact entry
(e.g. only one Work phone number may be present in the Contact entry).
Extended fields are fields that does not have a specific field explicitly predefined
in the API, but do have field ids assigned by the contact list. These fields
are implementation dependent and can vary. Users can find out a field id is
is extended field through the method PIMList.isExtendedField(int)
. Users
can also find out the data type for the field (PIMElement.getFieldDataType(int)
)
and the human readable label for the field (PIMElement.getFieldLabel(int)
).
Extended fields use the same get and set methods as named fields.
Categories are string items. There is no limit to the number of categories that a Contact can be associated with.
Field IDs | Allowed Type IDs | Type of Data Associated with Field |
---|---|---|
FORMATTED_NAME, NAME_FAMILY, NAME_GIVEN, NAME_OTHER, NAME_PREFIX,
NAME_SUFFIX, NICKNAME, NOTE, ORG, TITLE, UID, URL |
- | PIMElement.STRING |
BIRTHDAY, REVISION |
- | PIMElement.DATE |
PHOTO, PUBLIC_KEY |
- | PIMElement.BINARY or PIMElement.STRING |
EMAIL, FAX, TEL |
TYPE_ASSISTANT, TYPE_AUTO, TYPE_HOME, TYPE_MOBILE, TYPE_OTHER,
TYPE_PAGER, TYPE_WORK |
PIMElement.TYPED_STRING |
ADDR_COUNTRY, ADDR_EXTRA, ADDR_LOCALITY, ADDR_POBOX, ADDR_POSTALCODE,
ADDR_REGION, ADDR_STREET |
TYPE_HOME, TYPE_OTHER, TYPE_WORK |
PIMElement.TYPED_STRING |
Note that the FORMATTED_NAME
field and the NAME_FAMILY,
NAME_GIVEN, NAME_OTHER, NAME_PREFIX and NAME_SUFFIX
fields may be related
in some Contact implementations. In other words, some implementations may intepret
or store the FORMATTED_NAME
field in such a way that associating data
with the FORMATTED_NAME
field changes the associated values in
NAME_FAMILY, NAME_GIVEN, NAME_OTHER, NAME_PREFIX, or NAME_SUFFIX
.
FORMATTED_NAME
is the only field that is required to be supported
in a Contact and its List. All other fields may or may not be required by the list. Support
for all fields can be determined by the method PIMList.isSupportedField(int)
.
PIMElement.fromSerialFormat(java.io.Reader)
initializes a Contact from vCard 3.0 information contained
in the given Reader object. The Unicode character stream starting from the Reader's
current character position must be a complete vCard 3.0 entry or else a
PIMException
is thrown. This method reads one complete vCard
entry at a time, leaving the Reader object character position on the character
after the end of the vCard entry. It is the responsibility of the application
to perform any character decoding prior to providing the Reader object with
the vCard entry.PIMElement.toSerialFormat(java.io.Writer)
writes the data from this Contact
to the given Writer object as Unicode characters in a vCard 3.0 format as
defined in [RFC 2426]. The character stream is a complete vCard entry and
suitable for exchange with other implementations of vCard. It is the
responsibility of the application to perform any necessary character encoding
needed for further transportation of the vCard entry. This method is
equivalent to invoking PIMElement.toSerialFormat(java.io.Writer, String)
with
a version parameter of "3.0".
PIMElement.toSerialFormat(java.io.Writer, String)
writes the data from this Contact
to the given Writer object as Unicode characters in a vCard format whose
version is indicated by the String parameter. The value of the String must
be a valid vCard VERSION
value as defined by the appropriate
vCard specifications or else an IllegalArgumentException
is thrown.
The character stream is a complete vCard entry and suitable for exchange with
other implementations of vCard. It is the responsibility of the application
to perform any necessary character encoding needed for further transportation
of the vCard entry.
PIMElement.setString(int, String)
If the field ID is ADDR_*
, TEL
,
FAX
or EMAIL
then the behavior
is the same as setString(fieldID, TYPE_OTHER, value)
.
ContactList contacts = null; try { contacts = PIM.openContactList(PIM.READ_WRITE); } catch (PIMException e) { // An error occurred return; } Contact contact = contacts.createContact(); contact.setString(Contact.FORMATTED_NAME, "Mr. John Q. Public\, Esq"); contact.setString(Contact.NAME_FAMILY, "Public"); contact.setString(Contact.NAME_GIVEN, "John"); contact.setString(Contact.TEL, Contact.TYPE_HOME, "613-123-4567"); contact.setString(Contact.ADDR_COUNTRY, Contact.TYPE_HOME, "USA"); contact.setString(Contact.ADDR_LOCALITY, Contact.TYPE_HOME, "Coolsville"); contact.setString(Contact.ADDR_POSTALCODE, Contact.TYPE_HOME, "91921-1234"); contact.setString(Contact.ADDR_STREET, Contact.TYPE_HOME, "123 Main Street"); contact.addToCategory("Friends"); contact.setDate(Contact.BIRTHDAY, new Date().getTime()); contact.setString(Contact.EMAIL, Contact.TYPE_HOME, "jqpublic@xyz.dom1.com"); contact.setPreferredType(Contact.EMAIL, Contact.TYPE_HOME); try { contact.commit(); } catch (PIMException e) { // An error occured } try { contacts.close(); } catch (PIMException e) { }
ContactList
Field Summary | |
static int |
ADDR_COUNTRY
Field ID for the country of a particular address. |
static int |
ADDR_EXTRA
Field ID for the extra info of a particular address. |
static int |
ADDR_LOCALITY
Field ID for the locality (for example, a city) of a particular address. |
static int |
ADDR_POBOX
Field ID for the post office box of a particular address. |
static int |
ADDR_POSTALCODE
Field ID for the postal code (for example, a zip code) of a particular address. |
static int |
ADDR_REGION
Field ID for the region (for example, a province, state, or territory) of a particular address. |
static int |
ADDR_STREET
Field ID for the street information of a particular address. |
static int |
BIRTHDAY
Field ID for the birthday of the Contact. |
static int |
EMAIL
Field ID for an e-mail address. |
static int |
FAX
Field ID for a facsimile machine telephone number. |
static int |
FORMATTED_NAME
Field ID for data corresponding to the name of the Contact. |
static int |
NAME_FAMILY
Field ID for the family name of the Contact. |
static int |
NAME_GIVEN
Field ID for the given name of the Contact. |
static int |
NAME_OTHER
Field ID for another name for the Contact. |
static int |
NAME_PREFIX
Field ID for a name prefix for the Contact. |
static int |
NAME_SUFFIX
Field ID for a name suffix for the Contact. |
static int |
NICKNAME
Field ID corresponding to the Nickname of the contact. |
static int |
NOTE
Field ID specifying supplemental information or a comment associated with a Contact. |
static int |
ORG
Field ID specifying the organization name or units associated with a Contact. |
static int |
PHOTO
Field ID specifying the photo of a Contact. |
static int |
PUBLIC_KEY
Field ID specifying the public encryption key for a Contact. |
static int |
REVISION
Field ID specifying the last modification time of a Contact. |
static int |
TEL
Field ID for a voice telephone number. |
static int |
TITLE
Field ID specifying the job title for a Contact. |
static int |
TYPE_ASSISTANT
Type "assistant" for TEL, FAX and EMAIL entries. |
static int |
TYPE_AUTO
Type "auto" for TEL, FAX and EMAIL entries. |
static int |
TYPE_HOME
Type "home" for ADDR_*, TEL, FAX and EMAIL entries. |
static int |
TYPE_MOBILE
Type "mobile" for TEL, FAX and EMAIL entries. |
static int |
TYPE_OTHER
Type "other" for ADDR_*, TEL, FAX and EMAIL entries. |
static int |
TYPE_PAGER
Type "pager" for TEL, FAX and EMAIL entries. |
static int |
TYPE_WORK
Type "work" for ADDR_*, TEL, FAX and EMAIL entries. |
static int |
UID
Field ID specifying a unique ID for a Contact. |
static int |
URL
Field ID specifying the uniform resource locator for a Contact. |
Fields inherited from interface javax.microedition.pim.PIMElement |
BINARY, DATE, INT, STRING, TYPED_STRING |
Method Summary | |
int |
getPreferredType(int fieldID)
Returns the preferred type ID for the given field, as set by setPreferredType. |
void |
setPreferredType(int fieldID,
int typeID)
Sets the preferred type for the given field. |
Methods inherited from interface javax.microedition.pim.PIMElement |
addToCategory, commit, fromSerialFormat, getBinary, getCategories, getDate, getFieldDataType, getFieldLabel, getFields, getInt, getPIMList, getString, getTypedString, isModified, maxCategories, removeFromCategory, setBinary, setDate, setInt, setString, setTypedString, supportedSerialVersions, toSerialFormat, toSerialFormat |
Field Detail |
public static final int ADDR_COUNTRY
Value 1 is assigned to ADDR_COUNTRY.
public static final int ADDR_EXTRA
Value 2 is assigned to ADDR_EXTRA
.
public static final int ADDR_LOCALITY
Value 3 is assigned to ADDR_LOCALITY
.
public static final int ADDR_POBOX
Value 4 is assigned to ADDR_POBOX
.
public static final int ADDR_POSTALCODE
Value 5 is assigned to ADDR_POSTALCODE
.
public static final int ADDR_REGION
Value 6 is assigned to ADDR_REGION
.
public static final int ADDR_STREET
Value 7 is assigned to ADDR_STREET
.
public static final int TEL
Value 8 is assigned to TEL
.
public static final int FAX
Value 9 is assigned to FAX
.
public static final int EMAIL
Value 10 is assigned to EMAIL
.
public static final int BIRTHDAY
Value 11 is assigned to BIRTHDAY
.
public static final int FORMATTED_NAME
Value 12 is assigned to FORMATTED_NAME
.
public static final int NAME_FAMILY
Value 13 is assigned to NAME_FAMILY
.
public static final int NAME_GIVEN
Value 14 is assigned to NAME_GIVEN
.
public static final int NAME_OTHER
Value 15 is assigned to NAME_OTHER
.
public static final int NAME_PREFIX
Value 16 is assigned to NAME_PREFIX
.
public static final int NAME_SUFFIX
Value 17 is assigned to NAME_SUFFIX
.
public static final int NICKNAME
Value 18 is assigned to NICKNAME
.
public static final int NOTE
Value 19 is assigned to NOTE
.
public static final int ORG
Value 20 is assigned to ORG
.
public static final int TITLE
Value 21 is assigned to TITLE
.
public static final int PUBLIC_KEY
PIMElement.getFieldDataType(int)
should be used
to determine the type of the data associated with this field.
Value 22 is assigned to PUBLIC_KEY
.
public static final int URL
Value 23 is assigned to URL
.
public static final int UID
getString(UID)
returns null
before
the Contact object is added to a list.
Value 24 is assigned to UID
.
public static final int REVISION
Value 25 is assigned to REVISION
.
public static final int PHOTO
PIMElement.getFieldDataType(int)
should be used
to determine the type of the data associated with this field.
Value 26 is assigned to PHOTO
.
PIMList.isSupportedField(int)
public static final int TYPE_OTHER
ADDR_*, TEL, FAX and EMAIL
entries.
This is for address, telephone, fax, and e-mail entries that have
no specific association assigned to them. This is the default type
for those fields that have no type specified.
Value 256 is assigned to TYPE_OTHER
.
public static final int TYPE_HOME
ADDR_*, TEL, FAX and EMAIL
entries.
Value 257 is assigned to
public static final int TYPE_WORK
ADDR_*, TEL, FAX and EMAIL
entries.
Value 258 is assigned to TYPE_WORK
.
public static final int TYPE_MOBILE
TEL, FAX and EMAIL
entries.
Value 259 is assigned to TYPE_MOBILE
.
public static final int TYPE_PAGER
TEL, FAX and EMAIL
entries.
Value 260 is assigned to TYPE_PAGER
.
public static final int TYPE_AUTO
TEL, FAX and EMAIL
entries.
Value 261 is assigned to TYPE_AUTO
.
public static final int TYPE_ASSISTANT
TEL, FAX and EMAIL
entries.
Value 262 is assigned to TYPE_ASSISTANT
.
Method Detail |
public int getPreferredType(int fieldID) throws PIMException
fieldID
- the field ID to find the preferred type forjava.lang.IllegalArgumentException
- if fieldID is not a valid field ID for
a ContactPIMException
- if the field ID does not have types associated with it.public void setPreferredType(int fieldID, int typeID) throws PIMException
fieldID
- the field ID to set the preferred type fortypeID
- the type ID to be the default for field ID.
The type ID must be one of TYPE_*
.java.lang.IllegalArgumentException
- if fieldID is not a valid field ID for
a Contact or typeID is not a value Contact type ID.PIMException
- if the typeID is not a valid type ID for the given
field ID, or data for the given fieldID/typeID combination does
not exist in the Contact.
|
PDAP 1.0 Spec, Rev. 0.16 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |