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 ).
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() .
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.