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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-40E64445-CBA3-59E4-A777-937609B311C9" xml:lang="en"><title>Contacts

    13 Model Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section><title>Purpose</title> <p>The purpose of this document is to give

    15 guidelines on how to use the Contacts Model API most efficiently for a range

    16 of typical operations. The Contacts Model is an engine component that provides

    17 access to contact information stored on a Symbian OS device. Just like a real-world

    18 address book it stores and organises names, telephone numbers, addresses and

    19 other details of individuals and companies. It can be used to add, delete

    20 and edit data as well as providing information to clients, and sorting and

    21 searching contacts. </p> </section>

    22 <section><title>Architectural Relationships</title> <p>The Contacts Model

    23 is primarily used by messaging, telephony, synchronisation and vCard viewer

    24 clients on a Symbian OS device. </p> <fig id="GUID-79192704-415D-530B-8FEB-F73A5C93D0C2">

    25 <title>              CONTACTS MODEL CLIENTS            </title>

    26 <image href="GUID-5B6634EA-EB78-504E-BC5D-ABA67EEA06DF_d0e351317_href.png" placement="inline"/>

    27 </fig> </section>

    28 <section><title>Description</title> <p>The <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita"><apiname>CContactDatabase</apiname></xref> class

    29 allows clients access to the contact data stored on the device and has the

    30 following functionality: </p> <p><b>Contact database management </b> </p> <p>More than one Contact Database

    31 can exist on a phone, but a default Contact Database is used if no other is

    32 specified. Clients can open, close, alter and delete the Contact Database.

    33 Extra databases can be added as required. The Contact Database can be moved

    34 between drives, and can be compressed in order to save space. </p> <p><b>Contact items management </b> </p> <p>Contact Items are made up of Contact

    35 Fields and can be added to and removed from the database. Items in the database

    36 can be opened, read, sorted and deleted. An item must be opened before it

    37 can be edited. Editing an item often means altering data in one or more fields,

    38 such as name or telephone number. To provide different sorting views Contact

    39 Items can be grouped in categories such as ‘colleagues’ or ‘family’. </p> <p><b>Searching the database </b> </p> <p>Searching <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita"><apiname>CContactDatabase</apiname></xref> implements

    40 searching and sorting and also provides separate phone number matching functions.

    41 These provide a fast way of indexing and looking up phone numbers, for example,

    42 for looking up caller IDs on incoming calls. </p> <p><b>Speed dial functionality </b> </p> <p>The database owns speed dial information.

    43 This is a mapping between a single digit integer and a telephone number. There

    44 may be up to nine speed dial telephone numbers. If a Contact Item is deleted,

    45 its speed dial mapping is removed. </p> <p><b>Notification of changes </b> </p> <p>The database needs to be informed

    46 of data changes made to it. Sometimes a UI-level application may need to respond

    47 to updates made by other clients. The Contacts Model provides an observer

    48 to transmit this information between <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita"><apiname>CContactDatabase</apiname></xref> instances. </p> </section>

    49 </conbody></concept>