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