Home · All Classes · All Functions ·

Qt Contacts Schema

Introduction

The Qt Contacts API makes use of detail leaf classes which provide certain well-known functionality. In order to develop a backend engine which can service clients or provide synchronisation to other backends, the schema must be known.

Schema Definition

Different backends have different capabilities. Some backends may not be able to implement certain definitions in the default schema (for example, some backends might not have support for storing location information), while other backends may not be able to implement some aspects of a particular definition in the default schema (for example, a logo field for organisation details).

In order to be useful for clients, however, all backends should attempt to support the default schema. Furthermore, no backend should support a schema definition of a modified form where those modifications change the semantics of the data. A client should be able to request details of the QContactPhoneNumber type (that is, details whose definition name is "PhoneNumber") with reasonable certainty that the data returned is a phone number.

By implementing the default schema, the backend developer ensures that client code written against the default schema will work without source modification against their backend.

Default Schema

The leaf details that form the default schema are as follows:

QContactAddressContains an address of a contact
QContactAnniversaryContains the anniversary of a contact
QContactAvatarContains the avatar of a contact
QContactBirthdayContains the birthday of a contact
QContactDisplayLabelThe (possibly synthesized) display label of a contact
QContactEmailAddressContains the email address of a contact
QContactFamilyContains the names of the family members of a contact
QContactGenderContains the gender of a contact
QContactGeoLocationContains the global location coordinate associated with a contact
QContactGuidContains the globally unique Id of a contact
QContactNameContains the name of a contact
QContactNicknameContains a nickname of a contact
QContactNoteContains a note associated with a contact
QContactOnlineAccountThe online account, which the contact uses to communicate with friends and family
QContactOrganizationDetails about an organization that the contact is either a part of, or stands for
QContactPhoneNumberPhone number of a contact
QContactSyncTargetSync target for a contact
QContactTimestampContains the creation and last-modified timestamp associated with the contact
QContactTypeDescribes the type of the contact
QContactUrlContains a url associated with a contact

In the default schema, each of these definitions have various access and uniqueness constraints. Additionally, fields of the definitions may have an access constraint of read-only defined for them.

Detail Definition Uniqueness

A uniqueness constraint on a detail definition means that for any QContact, only one detail of that definition may be saved. Generally, it is information for which a contradicting detail would mean inability to identify the contact. Please note that some details, such as QContactBirthday or QContactName, do not have a uniqueness constraint, since in different contexts, different information may be valid.

The leaf classes which have a uniqueness constraint in the default schema are as follows:

Detail Definition Access Constraints

An access constraint on a detail definition means that for any detail of that definition in a QContact, the specified access constraints apply. For example, the QContactDisplayLabel is defined in the default schema as a read-only detail definition; meaning that details of that type in a contact cannot be created, modified or deleted by the client, but are provided by the backend (in the case of QContactDisplayLabel, automatically synthesized by the backend from various details of the contact).

There are three possible detail definition-level access constraints: read-only, create-only and no-constraint. A read-only constraint ensures that clients cannot create, delete or modify details of that definition; a create-only constraint ensures that clients cannot modify details of that definition, but can create them (with whichever values they see fit); if no constraint is specified, details of that definition may be created, modified or deleted as required.

Please see the documentation of QContactDetailDefinition for more information on access constraints.

The leaf classes which have access constraints in the default schema are as follows:

Furthermore, in the default schema, every contact is required to have at least two details by default: a QContactType which describes the type of entity that the contact represents (for example, a person or a group), and a QContactDisplayLabel which holds the default display label for the contact.

Field Access Constraints

Furthermore, some fields of some definitions are also constrained to be read-only. This is information which is generated or automatically provided by the backend, which is related to user-provided information that is also stored in the detail.

The eponymous example of this is the QContactOnlineAccount leaf detail, which has unconstrained fields which store the URI and service provider of the account, and several read-only fields in which are stored presence information, status messages, and service availability.

Currently, the QContactOnlineAccount is the only leaf detail with field-level access constraints. Every field in details of this type are QContactDetailDefinition::ReadOnly except for QContactOnlineAccount::FieldAccountUri and QContactOnlineAccount::FieldServiceProvider, which have no constraint.


Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Mobility Project 1.0.0