Viadeo Twitter Google Bookmarks ! Facebook Digg del.icio.us MySpace Yahoo MyWeb Blinklist Netvouz Reddit Simpy StumbleUpon Bookmarks Windows Live Favorites 
Logo Documentation Qt ·  Page d'accueil  ·  Toutes les classes  ·  Toutes les fonctions  ·  Vues d'ensemble  · 

Contacts

The Contacts API enables a client to request contact data from local or remote backends. This is part of the Qt Mobility Project.

Introduction

The Contacts API provides clients with the ability to access contact data in a platform-independent and datastore-agnostic manner. This is achieved by defining generic personal information data abstractions which can sufficiently describe contact data stored on any platform. Due to the cross-platform nature of the API, and the ability for developers to write platform-independent implementations of a QContactManager which may unify one or more platform-specific contact backends, it is intended that the semantics and quirks of the underlying datastores on any platform may be entirely opaque from the perspective of Qt-based, cross-platform client applications.

Overview

The QtMobility APIs are placed into the QtMobility namespace. This is done to facilitate the future migration of Mobility APIs into Qt. See the Quickstart guide for an example on how the namespace impacts on application development.

Contact information is stored in datastores whose functionality is exposed via a manager. The Contacts API models a contact as a collection of distinct details. Each detail conforms to a particular definition (or template), which may be extensible or otherwise modifiable by clients. Individual contacts may be related to one other, and these relationships are stored separately from contacts themselves and may be manipulated directly by clients.

Contact, detail definition, and relationship information may all be retrieved, modified or deleted by clients using either synchronous or asynchronous API.

Client-Facing API

The client-facing API allows retrieval, modification and deletion of contacts, detail definitions and relationships, and access to manager meta data and capability reporting.

Container Classes

Contact information is stored in container (value) classes. These classes are not derived from QObject, and hence can be used in lists, do not have parents, do not emit signals, and so on. They represent data which may be manipulated and retrieved from a manager.

Contact

A contact is the digital representation of a person, group or entity, which is stored in a platform-specific manner. Information pertaining to a single contact may be located across several different datastores, and each datum (or detail) may or may not pertain to a particular context in which that information is valid. A contact may include semantically identical pieces of information that are relevant in different contexts. For example, a contact may have a phone number that is relevant to their "home" context, and another phone number that is relevant to their "work" context. It can be seen that the context of information defines its validity to the user, depending on the context of usage; and as such, the sum of information in a given context can be considered equivalent to a "contextual identity". This allows great flexibility when consolidating data from various sources into a single, cohesive contact.

Each contact stored in a manager is identified by an id which consists of a manager identifier (URI) and the manager-local id which is used to identify the contact in that manager. Note that a contact stored in one manager may have the same local id as a different contact stored in another manager; please see the QContactId documentation for more information.

Detail

A detail is a single, cohesive unit of information that is stored in a contact. As explained previously, it is valid for a particular context or set of contexts, and conforms to a particular definition. A detail may have specific metadata associated with it, such as its sub-type, context, and arbitrary, user-defined metadata, as well as access constraints which may apply to the the detail (such as read-only, irremovable, etc).

There are a number of common details defined in the API which are intended for use by clients, as listed here.

Detail Definition

Each detail stored in a contact has defined semantics of usage and storage. The Qt Contacts API allows per-datastore contact detail definitions, allowing a manager to provide clients with this information on demand, and allowing third-party developers to register detail definitions for use by clients. A detail definition includes the fields (and value-types of those fields) which make up the detail, and per-contact uniqueness constraints on details of the definition.

Most clients can safely ignore this class entirely, since they will most likely want to use the predefined details listed here. In some cases, however, a manager will not support all of the fields of a particular predefined detail leaf class; in that case, it may be necessary for the client to inspect the supported detail definition for that leaf class and modify its behavior accordingly (for example, if the CustomLabel field of the QContactName leaf detail is not supported in a particular manager).

Relationships

Contacts may participate in relationships with other contacts. The details of any such relationship is stored by the manager which contains the contact. There are several standard relationship types supported by the default schema, and arbitrary relationship types are also allowed if the manager supports that feature. One important relationship is that of group membership; membership of a contact in a group can be modeled as that group contact participating in a HasMember relationship with the contact.

Manager

Access to contacts is provided by implementations of the Qt Contacts manager API. A manager provides access to zero or more platform-specific datastores. Each datastore may support different capabilities (for example, the ability to store certain datatypes, the ability to natively filter on different details or details of different definitions, the provision of locking mechanisms, the provision of changelog information, etc) which are reported by the manager on request. The manager therefore provides access to detail definitions, contacts, and relationships stored in different datastores, in a platform and datastore independent manner.

Meta Data API

The API offered by the QContactManager exposes functionality which is implemented by plugins. These plugins may be platform specific, and may be provided by Nokia or by third party developers. As described above, each plugin will have different capabilities and implement the functionality exposed by the Contacts API to a different degree.

The QContactManager class provides a static function QContactManager::availableManagers() which allows clients of the API to determine (at run time) which plugins (managers) are available for use.

Clients of the API also need to be able to determine (at run time) what the capabilities of a given plugin (contact manager) are. The QContactManager class provides API to query the capabilities of a given manager with the following synchronous functions:

A given manager is identified by its URI. The URI consists of the manager's name, any relevant parameters which were used during instantiation of the manager, and the version of the manager. While the name of the manager identifies the plugin which provides the functionality, you cannot guarantee that the data available through one manager will be available through another with the same name (for example, if one parameter tells the plugin to store and retrieve contact information from a particular online service or local file).

The synchronous API offered to allow run-time querying of a manager's metadata includes:

  • managerName() const
  • managerParameters() const
  • managerUri() const
  • managerVersion() const;
  • (static) parseUri(const QString& uri, QString* managerName, QMap<QString, QString>* params)
  • (static) buildUri(const QString& managerName, const QMap<QString, QString>& params, int implementationVersion = -1)

The functionality that the above functions provide is only available through synchronous API.

Asynchronous API

The asynchronous API provides a way to access or modify the contact information managed by a particular backend via non-blocking, asynchronous requests. It is recommended for most applications that the asynchronous API be used where possible.

The asynchronous API is offered through various classes derived from the QContactAbstractRequest class, including QContactLocalIdFetchRequest, QContactFetchRequest, QContactSaveRequest, QContactRemoveRequest, QContactDetailDefinitionFetchRequest, QContactDetailDefinitionSaveRequest, QContactDetailDefinitionRemoveRequest, QContactRelationshipFetchRequest, QContactRelationshipSaveRequest, and QContactRelationshipRemoveRequest.

The asynchronous API allows manipulation of contacts, contact relationships, and schema definitions, but does not provide manager capability or meta data information reporting.

For more detailed documentation on the asynchronous API, see the Contacts Asynchronous API.

Synchronous API

The synchronous API provides the simplest way to access or modify the contact information managed by a particular backend. It has the disadvantage that calls block the current thread of execution until completion and is therefore most suitable only for applications which interact with local, high-speed datastores, or for applications which do not require a responsive user interface.

The synchronous API is offered through the QContactManager class, and includes manipulation of contacts, contact relationships, and schema definitions. As previously described, the meta data reporting and manipulation functions are also provided via synchronous API only.

For more detailed documentation on the synchronous API, see the Contacts Synchronous API.

Non-Client-Facing API

The non-client-facing API allows third party developers to implement a manager engine plugin from which clients may request data.

Manager Engine

The functionality exposed by the QContactManager class may be implemented by engine plugins which interface directly to a platform-specific backend or provide their own data storage backend. As such, the terms "manager", "plugin" and "backend" are used interchangeably in this documentation to refer to any engine plugin which implements the functionality exposed by the QContactManager interface. The plugin architecture allows dynamic loading of different manager engines at runtime.

A manager backend may be implemented by subclassing QContactManagerEngine, and providing a QContactManagerEngineFactory which can instantiate it when required.

See Qt Contacts Manager Engines for more information on available engines and how to write your own engine.

Using the API

Some examples of common usage of the API may be found here.

Building and compiling

This library requires Qt 4.6 to be installed.

To build the library, see the Qt Mobility installation instructions.

Reference documentation

Main classes

QContactRepresents an addressbook contact
QContactAbstractRequestMechanism for asynchronous requests to be made of a manager if it supports them
QContactDetailRepresents a single, complete detail about a contact
QContactFilterUsed to select contacts made available through a QContactManager
QContactManagerInterface which allows clients with access to contact information stored in a particular backend
QContactRelationshipDescribes a one-to-one relationship between a locally-stored contact and another (possibly remote) contact

"Contact Details" Leaf Classes

Several subclasses of QContactDetail are provided as part of the Qt Mobility Project Contacts API. They are general in design but are intended to fulfill specific use-cases. Please note that certain backends may choose not to support one or more of these subclasses as they appear here; they may offer their own which provide similar functionality.

QContactAddressContains an address of a contact
QContactAnniversaryContains an anniversary of a contact
QContactAvatarContains the avatar of a contact
QContactBirthdayContains a birthday of a contact
QContactDisplayLabelThe (possibly synthesized) display label of a contact
QContactEmailAddressContains an email address of a contact
QContactFamilyContains names of family members of a contact
QContactGenderContains the gender of a contact
QContactGeoLocationContains a global location coordinate associated with a contact
QContactGlobalPresenceAggregated presence information for a contact, synthesized or supplied by the backend
QContactGuidContains a globally unique Id of a contact, for use in synchronization with other datastores
QContactNameContains a name of a contact
QContactNicknameContains a nickname of a contact
QContactNoteContains a note associated with a contact
QContactOnlineAccountOnline 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
QContactPresencePresence information for an online account of a contact
QContactRingtoneRingtone associated with a contact
QContactSyncTargetSync target for a contact
QContactTagContains a tag associated with a contact
QContactThumbnailContains a thumbnail used in display lists to represent the 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

Each of these subclasses provide access to information stored in fields which may have certain constraints, as listed in the schema.

Asynchronous Requests

Clients may use either the synchronous or asynchronous API to access functionality provided by a manager backend. The asynchronous API is offered through subclasses of the QContactAbstractRequest class:

QContactDetailDefinitionFetchRequestAllows a client to asynchronously request detail definitions from a contacts store manager
QContactDetailDefinitionRemoveRequestAllows a client to asynchronously request that certain detail definitions be removed from a contacts store
QContactDetailDefinitionSaveRequestAllows a client to asynchronously request that certain detail definitions be saved in a contacts store
QContactFetchRequestAllows a client to asynchronously request contacts from a contacts store manager
QContactLocalIdFetchRequestAllows a client to asynchronously request a list of contact ids from a contacts store manager
QContactRelationshipFetchRequestAllows a client to asynchronously request relationships from a contacts store manager
QContactRelationshipRemoveRequestAllows a client to asynchronously request that certain relationships be removed from a contacts store
QContactRelationshipSaveRequestAllows a client to asynchronously request that certain groups be saved to a contacts store
QContactRemoveRequestAllows a client to asynchronously request that certain contacts be removed from a contacts store
QContactSaveRequestAllows a client to asynchronously request that certain contacts be saved to a contacts store

Contact Selection

Clients may select a contact by specifying a unique contact id, or by supplying a QContactFilter which matches the contact or contacts they wish to select. The various derivatives of QContactFilter allow for fine-grained and flexible selection of contacts according to various criteria:

QContactChangeLogFilterFilter based around a contact timestamp criterion
QContactDetailFilterFilter based around a detail value criterion
QContactDetailRangeFilterFilter based around a detail value range criterion
QContactIntersectionFilterFilter which intersects the results of other filters
QContactInvalidFilterMatches no contacts
QContactLocalIdFilterFilter based around a list of contact ids
QContactRelationshipFilterFilter based around relationship criteria
QContactUnionFilterFilter which unions the results of other filters

A client can also request that the results of such a selection be sorted, by passing a QContactSortOrder (or list of sort orders) to the manager.

Implementing Backends

A backend implementor must implement the following interfaces:

QContactManagerEngineThe interface for all implementations of the contact manager backend functionality
QContactManagerEngineFactoryThe interface for plugins that implement QContactManagerEngine functionality

For more information on this topic, see please see the documentation on implementing manager engines.

Synchronization and Serialization

The contacts API is used by another Qt Mobility module: the Versit* module. It allows serialization of a QContact into a vCard document, and vice versa.

[*] Versit ® is a trademark of the Internet Mail Consortium.

Examples

The following sample applications show examples of API usage:

See also: Contacts API Usage
Publicité

Best Of

Actualités les plus lues

Semaine
Mois
Année
  1. « Quelque chose ne va vraiment pas avec les développeurs "modernes" », un développeur à "l'ancienne" critique la multiplication des bibliothèques 85
  2. Apercevoir la troisième dimension ou l'utilisation multithreadée d'OpenGL dans Qt, un article des Qt Quarterly traduit par Guillaume Belz 0
  3. Les développeurs ignorent-ils trop les failles découvertes dans leur code ? Prenez-vous en compte les remarques des autres ? 17
  4. BlackBerry 10 : premières images du prochain OS de RIM qui devrait intégrer des widgets et des tuiles inspirées de Windows Phone 0
  5. Pourquoi les programmeurs sont-ils moins payés que les gestionnaires de programmes ? Manquent-ils de pouvoir de négociation ? 19
  6. Quelles nouveautés de C++11 Visual C++ doit-il rapidement intégrer ? Donnez-nous votre avis 10
  7. Adieu qmake, bienvenue qbs : Qt Building Suite, un outil déclaratif et extensible pour la compilation de projets Qt 17
Page suivante

Le blog Digia au hasard

Logo

Créer des applications avec un style Metro avec Qt, exemples en QML et C++, un article de Digia Qt traduit par Thibaut Cuvelier

Le blog Digia est l'endroit privilégié pour la communication sur l'édition commerciale de Qt, où des réponses publiques sont apportées aux questions les plus posées au support. Lire l'article.

Communauté

Ressources

Liens utiles

Contact

  • Vous souhaitez rejoindre la rédaction ou proposer un tutoriel, une traduction, une question... ? Postez dans le forum Contribuez ou contactez-nous par MP ou par email (voir en bas de page).

Qt dans le magazine
Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia. Qt qtmobility-1.0
Copyright © 2012 Developpez LLC. Tous droits réservés Developpez LLC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents et images sans l'autorisation expresse de Developpez LLC. Sinon, vous encourez selon la loi jusqu'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts. Cette page est déposée à la SACD.
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter ou par MP !
 
 
Developpez.com

Nous contacter

Participez

Informations légales

 
Services

Forum Qt

Blogs

Hébergement

 
Partenaires

Hébergement Web