<?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 id="GUID-40E64445-CBA3-59E4-A777-937609B311C9" xml:lang="en"><title>Contacts

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

<section id="GUID-C4F81B43-D09B-45AE-A616-B77398345918"><title>Purpose</title> <p>The purpose of this document is to give

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

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

access to contact information stored on a device. Just like a real-world address

book it stores and organises names, telephone numbers, addresses and other

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

data as well as providing information to clients, and sorting and searching

contacts. </p> </section>

<section id="GUID-FE10E5CD-4F10-400D-AFDC-A00DDC22F6C7"><title>Architectural Relationships</title> <p>The Contacts Model

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

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

<title>              CONTACTS MODEL CLIENTS            </title>

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

</fig> </section>

<section id="GUID-DF37BEEF-CF1D-42B4-A5E2-B3C8F69B33BD"><title>Description</title> <p>The <xref href="GUID-6A6C7B3B-1E44-3731-956D-590A1122FF6E.dita"><apiname>CContactDatabase</apiname></xref> class

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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