Contacts Model Overview

Purpose

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.

Architectural Relationships

The Contacts Model is primarily used by messaging, telephony, synchronisation and vCard viewer clients on a device.

Description

The CContactDatabase class allows clients access to the contact data stored on the device and has the following functionality:

Contact database management

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.

Contact items management

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’.

Searching the database

Searching CContactDatabase 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.

Speed dial functionality

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.

Notification of changes

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 CContactDatabase instances.