Contact Items Management

A Contact Item is an element in a Contact Database. Contact Items can be added, read, edited and removed from the database. As the diagram below shows, a Contact Item can be:

a contact card - either generic cards (CContactCard) or the device owner's card (CContactOwnCard)
a template card (CContactTemplate) - a card that sets the initial fields for other Contact Items
a collection of Contact Items (CContactItemPlusGroup) - a group that holds a set of associated Contact Item IDs
a contact which maps to the device's ICC (CContactICCEntry) or SIM (CContactCard).

Each Contact Item is uniquely identified in the database by a Contact Item ID (TContactItemId). More than one Contact Item ID is referred to using a Contact Item ID array (CContactIdArray).

Figure: CONTACT ITEM HIERARCHY

Contact Items have an access count and attributes ('hidden', for example). The access count is a record of the number of objects referencing a Contact Item. A Contact Item cannot be fully deleted until its access count is zero.

Note: Fields in a Contact Item also have attributes. Attribute values specified in the Contact Item override those in the contained fields.

Contact Items are accessed through the CContactDatabase class. Opening a Contact Item (using CContactDatabase::OpenContactL()) locks it so that it cannot be edited by another client. Closing the Contact Item (using CContactDatabase::CloseContactL()) releases the lock on the item without saving any changes made to it. Committing the Contact Item (using CContactDatabase::CommitContactL()) releases the lock and saves any changes made to it.

Contact Item Fields

Each Contact Item contains a number of fields (CContactItemFieldSet). Each field (CContactItemField) in CContactItemFieldSet has a content type, (CContentType), and a storage type, (TStorageType) and the field data (CContactTextField, CContactStoreField, CContactAgentField or CContactDateField).

A content type contains at least one UID, using TFieldType. A storage type identifies the type of data (text, binary, contact agent ID, date/time) stored in a Contact Item field. As numeric field data is not supported all numbers are stored as text.

Each field can also have a label which identifies the field to a user, for example, first name, last name. Fields can have attributes assigned to them such as hidden, disabled, synchronised, read only, user added, template and speed dial.

Contact Groups

A Contact Group (CContactGroup class) is a Contact Item which holds a set of associated Contact Item IDs. The members of the group may be contact cards, own cards, or even other groups. The group has a label which identifies the group such as 'family', or 'colleagues' to users. The type of a Contact Group is KUidContactGroup, as returned by CContactGroup::Type().

It is possible to construct a group using CContactGroup::CreateContactGroupL(). These functions create the group, optionally with a label, add it to the database, and return a pointer to it. To create an association between a card and a group, use CContactDatabase::AddContactToGroupL(). To remove the association, use CContactDatabase::RemoveContactFromGroupL(). To find out which groups a card belongs to, use CContactCard::GroupsJoinedLC() or CContactOwnCard::GroupsJoinedLC().