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:

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 ).


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() .