<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-36FD1F9A-FA1C-5822-A95F-720600E8F418"><title>Contact Items Management</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>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: </p> <ul><li id="GUID-39BF4108-CFC9-54CD-BC88-81C41984601E"><p>a contact card - either generic cards (<xref href="GUID-CCE5DB7C-AD68-3F8C-8720-14CD1FC3D164.dita"><apiname>CContactCard</apiname></xref>) or the device owner's card (<xref href="GUID-942BB679-256F-3DD3-A027-6A40E1DE9C40.dita"><apiname>CContactOwnCard</apiname></xref>) </p> </li> <li id="GUID-06168476-8C2F-5944-A5FD-B37BB2ABB032"><p>a template card (<xref href="GUID-D144F6EE-B50D-3EC8-BAD7-A0E7590CD512.dita"><apiname>CContactTemplate</apiname></xref>) - a card that sets the initial fields for other Contact Items </p> </li> <li id="GUID-7C15AAFE-A236-5036-9C55-E647B6DF46C6"><p>a collection of Contact Items (<xref href="GUID-98A3BF93-A1EF-32C3-B98C-680A515D9985.dita"><apiname>CContactItemPlusGroup</apiname></xref>) - a group that holds a set of associated Contact Item IDs </p> </li> <li id="GUID-21FAB277-889F-52F7-941C-06F803983319"><p>a contact which maps to the device's ICC (<xref href="GUID-BEC62AFD-2CDA-387D-A290-2221D88FD2B8.dita"><apiname>CContactICCEntry</apiname></xref>) or SIM (<xref href="GUID-CCE5DB7C-AD68-3F8C-8720-14CD1FC3D164.dita"><apiname>CContactCard</apiname></xref>). </p> </li> </ul> <p>Each Contact Item is uniquely identified in the database by a Contact Item ID (<xref href="GUID-B1F75A76-9F02-3D88-B76F-1489319B7108.dita"><apiname>TContactItemId</apiname></xref>). More than one Contact Item ID is referred to using a Contact Item ID array (<xref href="GUID-7CACA76F-00E5-3A69-966E-1D40E64F0E27.dita"><apiname>CContactIdArray</apiname></xref>). </p> <fig id="GUID-10046728-05A3-5A02-B9C0-A3AAF33AD8D5"><title>

          CONTACT ITEM HIERARCHY 

        </title> <image href="GUID-16C323DC-B43F-5621-B617-C31FBB25379B_d0e612496_href.png" placement="inline"/></fig> <p>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. </p> <p>Note: Fields in a Contact Item also have attributes. Attribute values specified in the Contact Item override those in the contained fields. </p> <p>Contact Items are accessed through the <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita"><apiname>CContactDatabase</apiname></xref> class. Opening a Contact Item (using <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita#GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E/GUID-05A0BF3B-6F83-300C-A70D-3FEB069A3964"><apiname>CContactDatabase::OpenContactL()</apiname></xref>) locks it so that it cannot be edited by another client. Closing the Contact Item (using <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita#GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E/GUID-0D90CADE-D766-3A39-9928-F4E8936B52FB"><apiname>CContactDatabase::CloseContactL()</apiname></xref>) releases the lock on the item without saving any changes made to it. Committing the Contact Item (using <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita#GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E/GUID-35AD302C-659C-3705-961A-3730F2975B25"><apiname>CContactDatabase::CommitContactL()</apiname></xref>) releases the lock and saves any changes made to it. </p> <section id="GUID-D41E051D-CA35-559C-803B-811008FD4089"><title>Contact Item Fields</title> <p>Each Contact Item contains a number of fields (<xref href="GUID-8ECF9E69-5102-37C6-BF4F-E4C543026304.dita"><apiname>CContactItemFieldSet</apiname></xref>). Each field (<xref href="GUID-6466EF81-CAFC-3098-8E2F-D55AB77F2B99.dita"><apiname>CContactItemField</apiname></xref>) in <xref href="GUID-8ECF9E69-5102-37C6-BF4F-E4C543026304.dita"><apiname>CContactItemFieldSet</apiname></xref> has a content type, (<xref href="GUID-96249829-E053-3DB5-ABEC-77C9C8A0BB69.dita"><apiname>CContentType</apiname></xref>), and a storage type, (<xref href="GUID-35235317-4E31-3ED4-9798-1B2621F89265.dita"><apiname>TStorageType</apiname></xref>) and the field data (<xref href="GUID-429B1D62-189C-3DE1-AABD-C162B0593992.dita"><apiname>CContactTextField</apiname></xref>, <xref href="GUID-C44B4C53-417E-330F-A651-FEB97B3FE75F.dita"><apiname>CContactStoreField</apiname></xref>, <xref href="GUID-ABBBE7AC-F837-3039-B2A3-6A7B4E11F82D.dita"><apiname>CContactAgentField</apiname></xref> or <xref href="GUID-F7BC1DB1-C8AA-371A-B930-1DB9B7360949.dita"><apiname>CContactDateField</apiname></xref>). </p> <p>A content type contains at least one UID, using <xref href="GUID-84023E98-6C2C-31CE-9DDC-15D92650AC23.dita"><apiname>TFieldType</apiname></xref>. 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. </p> <p>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. </p> </section> <section id="GUID-C8B3F417-57B3-548B-8247-9171ABAECED9"><title>Contact Groups</title> <p>A Contact Group (<xref href="GUID-F823D586-386F-300B-82D2-8365695BA7A0.dita"><apiname>CContactGroup</apiname></xref> 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 <xref href="GUID-7770D130-465B-3360-8BB4-0870F81EC8C9.dita"><apiname>KUidContactGroup</apiname></xref>, as returned by <xref href="GUID-F823D586-386F-300B-82D2-8365695BA7A0.dita#GUID-F823D586-386F-300B-82D2-8365695BA7A0/GUID-BE8C8EBC-4402-3E04-ADD4-7843B65AB8A6"><apiname>CContactGroup::Type()</apiname></xref>. </p> <p>It is possible to construct a group using <xref href="GUID-F823D586-386F-300B-82D2-8365695BA7A0.dita#GUID-F823D586-386F-300B-82D2-8365695BA7A0/GUID-61DCBD98-BF07-3DB0-A02B-603A99C7DA58"><apiname>CContactGroup::CreateContactGroupL()</apiname></xref>. 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 <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita#GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E/GUID-38EEDF68-F1F8-3286-8525-24822B75FEBC"><apiname>CContactDatabase::AddContactToGroupL()</apiname></xref>. To remove the association, use <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita#GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E/GUID-981C88EC-2089-3CE0-8DDF-03F228EC75F7"><apiname>CContactDatabase::RemoveContactFromGroupL()</apiname></xref>. To find out which groups a card belongs to, use <xref href="GUID-CCE5DB7C-AD68-3F8C-8720-14CD1FC3D164.dita#GUID-CCE5DB7C-AD68-3F8C-8720-14CD1FC3D164/GUID-C67AAC3C-6925-3CE4-9F4D-C7B955A95A9A"><apiname>CContactCard::GroupsJoinedLC()</apiname></xref> or <xref href="GUID-942BB679-256F-3DD3-A027-6A40E1DE9C40.dita#GUID-942BB679-256F-3DD3-A027-6A40E1DE9C40/GUID-4162EB84-E4D1-387B-B92D-DFD4738C5734"><apiname>CContactOwnCard::GroupsJoinedLC()</apiname></xref>. </p> </section> </conbody></concept>