EPOC   SDK Home Glossary Indexes Previous   Up

Guide to the contacts model


Contents


Summary

A contact database contains a number of contact items. Each item contains a number of fields. Each field has storage for a single object. This object may be text, binary, or a date/time value.

It is important to note that future releases of the contacts model will break data, source and binary compatibility with this release. This documentation is current to the EPOC Release 5 version of the contacts model.


The contact database

The CContactDatabase class handles all interaction with a contact database. Most clients create an instance of the class during initialization, and destroy it on shutdown. The class allows clients to create a new contacts database, or open an existing one. Once opened, the database can be searched, sorted, and items within it can be edited or read, new items can be added, and existing ones can be deleted.

Client applications which need to be updated dynamically as the database is altered by other clients should derive from class MContactDbObserver. The observer's HandleDatabaseEventL() function will be called in response to each change to the database.


The view definition

A database can have a view definition (CContactItemViewDef). This is used when reading or opening contact items within the database. Only fields specified in the view definition will be included. The view definition is optional. If no view definition has been specified, every field is included in the view. The view definition does not persist so should be set each time the database is opened.


Contact items

A contact item (CContactItem) is an element in a contact database. 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 — a wrapper class for an array of contact item IDs).

Contact items are accessed through the contacts database. Opening a contact item (using CContactDatabase::OpenL()) 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. Template items (CContactTemplate class) and contact cards (CContactCard class) are concrete implementations of the abstract base class CContactItem.


Fields and field types

Each contact item is made up of a number of fields (CContactItemField). Each field has a content type (CContentType), and a storage type (TStorageType). The content type contains one or more UIDs. At least one UID must be specified to identify the field's type, another optional UID identifies a vCard property to which the field type maps. A field which does not define this second, optional UID may not be capable of being imported by another, non-EPOC device as part of a vCard. The storage type is used to specify how the data should be stored internally by the DBMS.

EPOC       SDK Home Glossary Indexes Previous   Up