ContactList

ContactList provides access to the Phonebook on-device database but the current S60 implementation does not provide access to SIM contacts. The supported Contact fields and their attribute combinations are specified in the table below:

**Table 6:** The supported `Contact` fields and their attribute combinations
PIM API Field	PIM API Attributes	Corresponding Phonebook Field
`Contact.FORMATTED_NAME`*	`PIMItem.ATTR_NONE`	Name
`Contact.NAME`	`PIMItem.ATTR_NONE`	Name (See element table)
`Contact.NICKNAME`	`PIMItem.ATTR_NONE`	Nick name
`Contact.ORG`	`PIMItem.ATTR_NONE`	Company
`Contact.TITLE`	`PIMItem.ATTR_NONE`	Job title
`Contact.ADDR`	`PIMItem.ATTR_NONE`	Address (See element table)
`Contact.ADDR`	`Contact.ATTR_HOME`	Address (home)
`Contact.ADDR`	`Contact.ATTR_WORK`	Address (business)
`Contact.TEL`	`PIMItem.ATTR_NONE`	Telephone
`Contact.TEL`	`Contact.ATTR_HOME`	Telephone (home)
`Contact.TEL`	`Contact.ATTR_WORK`	Telephone (business)
`Contact.TEL`	`Contact.ATTR_MOBILE`	Mobile
`Contact.TEL`	`Contact.ATTR_MOBILE + Contact.ATTR_HOME`	Mobile (home)
`Contact.TEL`	`Contact.ATTR_MOBILE + Contact.ATTR_WORK`	Mobile (business)
`Contact.TEL`	`Contact.ATTR_FAX`	Fax
`Contact.TEL`	`Contact.ATTR_FAX + Contact.ATTR_HOME`	Fax (home)
`Contact.TEL`	`Contact.ATTR_FAX + Contact.ATTR_WORK`	Fax (business)
`Contact.TEL`	`Contact.ATTR_PAGER`	Pager
`Contact.TEL`	`Contact.ATTR_ASST`	Assistant phone
`Contact.TEL`	`Contact.ATTR_AUTO`	Car phone
`Contact.TEL`	`Contact.ATTR_SMS`	Default SMS number
`Contact.TEL`	`Contact.ATTR_OTHER`	N/A
`Contact.EMAIL`	`PIMItem.ATTR_NONE`	E-mail
`Contact.EMAIL`	`Contact.ATTR_HOME`	E-mail (home)
`Contact.EMAIL`	`Contact.ATTR_WORK`	E-mail (business)
`Contact.BIRTHDAY`	`PIMItem.ATTR_NONE`	Birthday
`Contact.URL`	`PIMItem.ATTR_NONE`	URL
`Contact.URL`	`Contact.ATTR_HOME`	URL (home)
`Contact.URL`	`Contact.ATTR_WORK`	URL (business)
`Contact.NOTE`	`PIMItem.ATTR_NONE`	Note
`Contact.PHOTO`**	`PIMItem.ATTR_NONE`	Photo
`Contact.CLASS`	`PIMItem.ATTR_NONE`	Synchronization
`Contact.UID`	`PIMItem.ATTR_NONE`	(Internal unique identifier)
`Contact.REVISION`	`PIMItem.ATTR_NONE`	(Internal last modification date)

*) The values set in the Contact.FORMATTED_NAME field through the API are not written to the database. The value in the Contact.FORMATTED_NAME field is set by the API from the values in Contact.NAME string array field elements whenever a Contact is committed or refreshed from the database.

**) New Contact.PHOTO values may be scaled down during PIMItem.commit() to fit in the Phonebook UI.

The PIM API S60 3rd Edition Feature Pack 1 implementation provides access to so called "extended" fields which are not included in the standard PIM API fields. The extended fields are the following:

**Table 7:** The supported extended fields and their attribute combinations
PIM API Field	Numeric extended field ID	PIM API Attributes	Corresponding Phonebook Field
`USER ID`	0x1005001	`PIMItem.ATTR_NONE`	No correspondence shown in the native side
`SIP`	0x1005002	`PIMItem.ATTR_NONE`	SIP
`DTMF`	0x1005003	`PIMItem.ATTR_NONE`	DTMF
`Department`	0x1005004	`PIMItem.ATTR_NONE`	Department
`Assistant Name`	0x1005005	`PIMItem.ATTR_NONE`	Assistant name
`Children`	0x1005006	`PIMItem.ATTR_NONE`	Children
`Spouse`	0x1005007	`PIMItem.ATTR_NONE`	Spouse
`Anniversary`	0x1005008	`PIMItem.ATTR_NONE`	Anniversary
`VOIP`	0x1005009	`PIMItem.ATTR_NONE`	Tel. Internet
`VOIP`	0x1005009	`Contact.ATTR_HOME`	Tel. Internet (home)
`VOIP`	0x1005009	`Contact.ATTR_WORK`	Tel. Internet (work)
`Contact.TEL`*	(This is a standard PIM API field)	`ATTR_VIDEO_CALL`	Video number
`Contact.TEL`*	(This is a standard PIM API field)	`ATTR_VIDEO_CALL + Contact.ATTR_HOME`	Video number (home)
`PTT` (from S60 5th Edition)	0x100500A	`PIMItem.ATTR_NONE`	Push to Talk
`SWIS` (from S60 5th Edition)	0x100500B	`PIMItem.ATTR_NONE`	Share View

*) The Contact.TEL field has a specific extended attribute for Video number, which extends the functionality of the standard Telephone number field. The Video call attribute is not a standard Contact.TEL field attribute, and therefore it does not have its own constant defined. See the table below about extended attributes.

The PIM API S60 3rd Edition Feature Pack 1 includes new extended attributes which do not have specific constants defined, so they must be used with certain identifiers. The new extended attributes are listed in the following table:

**Table 8:** Extended attributes
Extended attribute	Numeric attribute ID	Note
`ATTR_VIDEO_CALL`	0x1000000	`Contact.TEL` field video call attribute

The supported Contact.NAME string array elements are the following:

**Table 9:** The supported `Contact.NAME` string array elements
Contact.NAME element	Corresponding Phonebook field
`Contact.NAME_FAMILY`	Last name
`Contact.NAME_GIVEN`	First name
`Contact.NAME_OTHER`	Middle
`Contact.NAME_PREFIX`	Prefix
`Contact.NAME_SUFFIX`	Suffix
Last name reading* (element id 5)	Last name reading
First name reading* (element id 6)	First name reading

*) The Contact.NAME field has extended string array elements in S60 3rd Edition Feature Pack 1. These elements are not included in the standard PIM API string array elements, and therefore they do not have their own constants defined. These name reading elements correspond to Japanese name pronunciations which are in accordance to the East Asian system of personal names.

The supported Contact.ADDR string array elements are the following:

**Table 10:** The supported `Contact.ADDR` string array elements
Contact.NAME element	Corresponding Phonebook field
`Contact.ADDR_POBOX`	P.O. Box
`Contact.ADDR_EXTRA`	Extension
`Contact.ADDR_STREET`	Street
`Contact.ADDR_LOCALITY`	City
`Contact.ADDR_REGION`	State/province
`Contact.ADDR_POSTALCODE`	Postal/ZIP
`Contact.ADDR_COUNTRY`	County/region

The ContactList supports an unlimited number of categories. Categories represent caller groups in the Phonebook.

ContactList performance improvement

The ContactList performance is improved in the S60 3rd Edition Feature Pack 1. The API is improved by loading items partially. Only the essential fields are loaded from the native database during the initialization when invocating PIMList.items() or its variations for the first time. The initialized fields are Contact.NAME and Contact.FORMATTED_NAME. Care should be taken when other fields are acquired from an item because it is performance critical.

Invocating PIMList.items( PIMItem aMatchingItem ) causes the PIM API to load fields which are included in the matching item. The item is fully loaded when PIMItem.getFields() has been invocated. The function should be used only when the whole item needs to be displayed.

Unsupported in S60

Unsupported Contact fields:

Contact.PUBLIC_KEY
Contact.PHOTO_URL
Contact.PUBLIC_KEY_STRING
Contact.FORMATTED_ADDR