+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

+\section1 Namespace

+

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+optimizes the interface's uptime.

+This API is a key enabler for HTTP level roaming in

+enables to user to create, edit or delete network configurations.

+WLAN access point details (e.g ESSID, encryption details) and user specific

+QNetworkSession provides two types of use cases. It enables the monitoring of

+active network sessions for the same network interface by maintaining the link

+lists the major QNetworkSession functions and how they fit into the session and

+The state of the session represents the state of the underlying access point

+whereas the session's openness implies the networking/connectivity state available

+applications which intend to monitor the connectivity state but do not engage

+Internet access point or the user instructs the platform to ask the user

+ // Set Internet Access Point

+ const bool canStartIAP = (manager.capabilities()

+ & QNetworkConfigurationManager::CanStartAndStopInterfaces);

+ // Is there default access point, use it

+ if (!cfg.isValid() || (!canStartIAP && cfg.state() != QNetworkConfiguration::Active)) {

+ QMessageBox::information(this, tr("Network"), tr(

+ "No Access Point found."));

+ session = new QNetworkSession(cfg, this);

+ session->open();

+ session->waitForOpened(-1);

+\l{QNetworkConfiguration::UserChoice}{UserChoice} configuration is only

+and an \l{QNetworkSession::isOpen()}{isOpen()} condition.

+stateful connections with other parties. In the most extreme cases applications

+platform APIs being used by this API. This may assist in the process of

+ \o This platform has full support by way of CoreWLAN offered in Mac OS 10.6. Previous

+ versions of Mac OS - 10.5 and 10.4 have limited support.

+The \l {bearercloud}{Bearer Cloud} example graphically represents the available access points to

+various networks and their respective configuration state.

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{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 \l{QContactManager}{manager}. The Contacts API models a

+\l{QContact}{contact} as a collection of distinct details. Each

+\l{QContactDetail}{detail} conforms to a particular

+\l{QContactDetailDefinition}{definition} (or template), which may be

+extensible or otherwise modifiable by clients. Individual contacts may be

+related to one other, and these \l{QContactRelationship}{relationships} are

+stored separately from contacts themselves and may be manipulated directly by

+clients.

+

+\l{QContact}{Contact}, \l{QContactDetailDefinition}{detail definition}, and

+\l{QContactRelationship}{relationship} information may all be

+retrieved, modified or deleted by clients using either

+\l{Contacts Asynchronous API}{synchronous} or

+\l{Contacts Asynchronous API}{asynchronous} API.

+

+\section1 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.

+

+\section2 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 \l{Manager}{manager}.

+

+\section3 Contact

+

+A \l{QContact}{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

+Each contact stored in a manager is identified by an \l{QContactId}{id} which

+consists of a manager identifier (URI) and the

+\l{QContactLocalId}{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.

+

+\section3 Detail

+

+A \l{QContactDetail}{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 \l{"Contact Details" Leaf Classes}{here}.

+

+\section3 Detail Definition

+

+Each detail stored in a contact has defined semantics of usage and storage.

+The Qt Contacts API allows per-datastore contact

+\l{QContactDetailDefinition}{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

+\l{"Contact Details" Leaf Classes}{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 behaviour

+accordingly (for example, if the \c CustomLabel field of the QContactName

+leaf detail is not supported in a particular manager).

+

+\section3 Relationships

+

+Contacts may participate in \l{QContactRelationship}{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 \c HasMember relationship with the contact.

+

+\section2 Manager

+

+Access to contacts is provided by implementations of the Qt Contacts

+\l{QContactManager}{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.

+

+\section3 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:

+\list

+ \o hasFeature(QContactManager::ManagerFeature feature, const QString& contactType = QContactType::TypeContact) const

+ \o isFilterSupported(const QContactFilter& filter) const

+ \o isRelationshipTypeSupported(const QString& relationshipType, const QString& contactType = QContactType::TypeContact) const

+ \o supportedDataTypes() const

+ \o supportedContactTypes() const

+\endlist

+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:

+\list

+ \o managerName() const

+ \o managerParameters() const

+ \o managerUri() const

+ \o managerVersion() const;

+ \o (static) parseUri(const QString& uri, QString* managerName, QMap<QString, QString>* params)

+ \o (static) buildUri(const QString& managerName, const QMap<QString, QString>& params, int implementationVersion = -1)

+\endlist

+The functionality that the above functions provide is only available through

+synchronous API.

+\section3 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 \l{QContact}{contacts},

+\l{QContactRelationship}{contact relationships}, and

+\l{QContactDetailDefinition}{schema definitions}, but does not provide manager

+capability or meta data information reporting.

+For more detailed documentation on the asynchronous API, see the \l{Contacts Asynchronous API}.

+\section3 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 UI.

+The synchronous API is offered through the QContactManager class, and includes

+manipulation of \l{QContact}{contacts},

+\l{QContactRelationship}{contact relationships}, and

+\l{QContactDetailDefinition}{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 \l{Contacts Synchronous API}.

+\section1 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.

+\section2 Manager Engine

+The functionality exposed by the QContactManager class may be implemented by

+\l{QContactManagerEngine}{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

+\l{QContactManagerEngine}, and providing a \l{QContactManagerEngineFactory}

+which can instantiate it when required.

+\section1 Using the API

+Some examples of common usage of the API may be found

+\l{Contacts API Usage}{here}.

+This library requires Qt 4.6 to be installed.

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

+Clients may use either the \l{Contacts Synchronous API}{synchronous}

+or \l{Contacts Asynchronous API}{asynchronous} API to access

+functionality provided by a manager backend. The

+\l{Contacts Asynchronous API}{asynchronous} API is

+A backend implementor must implement the following interfaces:

+\annotatedlist contacts-backends

+The contacts API is used by another Qt Mobility module: the \l {Versit API (technology preview)} {Versit}* module. It allows

+The following sample applications show examples of API usage:

+ \o \l{qmlcontacts}{QML-based Sample Phonebook}

+See also: \l{Contacts API Usage}

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+/*!

+

+\page contactsasync.html

+

+\title Contacts Asynchronous API

+

+\tableofcontents

+

+

+\section1 Introduction

+

+The Contacts Asynchronous API enables a client to asynchronously fetch, update, or remove

+contact, relationship or schema data from a contact manager. Use of the asynchronous API

+offers the programmer greater flexibility when requesting information from remote or

+slow local datastores.

+

+\section1 Using the API

+

+The asynchronous API offered by the Contacts module is available through classes

+derived from the QContactAbstractRequest class. It consists of three major sections:

+\list

+ \o Contact Manipulation

+ \o Relationship Manipulation

+ \o Schema Manipulation

+\endlist

+

+The functionality offered by the synchronous API in these three categories is also

+available through the asynchronous API. There is one category of functionality

+which is not provided by the asynchronous API which is provided by the synchronous

+API: some information and reporting functionality is only provided through the

+synchronous API.

+

+For detailed information about the information and reporting functionality provided,

+please refer to the documentation for the \l{Contacts Synchronous API}.

+

+The functions to set and retrieve the id of the self-contact are also only provided by

+the synchronous API.

+

+\section2 Contact Manipulation

+

+The most common type of operation that clients will perform involves retrieval or modification of contacts.

+For in-depth information about contact manipulation, please refer to the \l{Contacts Synchronous API}.

+

+There are four different types of operation which are supported by the asynchronous API:

+\list

+ \o Fetch contact ids

+ \o Fetch contacts

+ \o Save contacts (create or update)

+ \o Remove contacts

+\endlist

+

+These operations are supported via the QContactLocalIdFetchRequest, QContactFetchRequest,

+QContactSaveRequest and QContactRemoveRequest classes, respectively.

+

+The synchronous API offered by the QContactManager class to allow manipulation of contacts consists

+of the following functions:

+\list

+ \o contactIds(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const

+ \o contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const

+ \o contacts(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const

+ \o contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const

+ \o saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap)

+ \o removeContacts(QList<QContactLocalId>* contactIds, QMap<int, QContactManager::Error>* errorMap)

+\endlist

+

+\section3 Relationship Manipulation

+

+Contacts may be related in various ways. The contacts API allows clients to define relationships between contacts.

+For in-depth information about relationship manipulation, please refer to the \l{Contacts Synchronous API}.

+

+There are three different types of operation which are supported by the asynchronous API:

+\list

+ \o Fetch relationships

+ \o Save relationships (create or update, if supported by the backend)

+ \o Remove relationships (if supported by the backend)

+\endlist

+

+These operations are supported via the QContactRelationshipFetchRequest,

+QContactRelationshipSaveRequest and QContactRelationshipRemoveRequest classes respectively.

+

+The synchronous API offered by the QContactManager class to allow manipulation of relationships

+consists of the following functions:

+\list

+ \o relationships(const QContactId& participantId, QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;

+ \o relationships(const QString& relationshipType = QString(), const QContactId& participantId = QContactId(), QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;

+ \o saveRelationship(QContactRelationship* relationship);

+ \o saveRelationships(QList<QContactRelationship>* relationships);

+ \o removeRelationship(const QContactRelationship& relationship);

+ \o removeRelationships(const QList<QContactRelationship>& relationships);

+\endlist

+

+\section2 Schema Manipulation

+

+The schema supported by a plugin is the list of detail definitions which are supported by the plugin.

+For in-depth information about the schema, please refer to the \l{Contacts Synchronous API}.

+

+There are three different types of operation which are supported by the asynchronous API:

+\list

+ \o Fetch detail definitions

+ \o Save detail definitions (create or update, if supported by the backend)

+ \o Remove detail definitions (if supported by the backend)

+\endlist

+

+These operations are supported via the the QContactDetailDefinitionFetchRequest,

+QContactDetailDefinitionSaveRequest and QContactDetailDefinitionRemoveRequest classes,

+respectively.

+

+The synchronous API offered by the QContactManager class to allow manipulation of the schema consists

+of the following functions:

+\list

+ \o detailDefinitions(const QString& contactType = QContactType::TypeContact) const

+ \o detailDefinition(const QString& definitionName, const QString& contactType = QContactType::TypeContact) const

+ \o saveDetailDefinition(const QContactDetailDefinition& def, const QString& contactType = QContactType::TypeContact)

+ \o removeDetailDefinition(const QString& definitionName, const QString& contactType = QContactType::TypeContact)

+\endlist

+

+\section1 Examples Of Usage

+

+\section2 Fetching Contacts

+

+The client sets up a request for contacts matching a specific criteria

+from a particular manager.

+

+Results from the request will be displayed to the user as they are

+received.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Asynchronous contact request

+

+\section2 Other Asynchronous Operations

+

+All other asynchronous operations are performed in a similar manner to the

+previous example. A request of the desired type (which is derived from

+QContactAbstractRequest) is created, certain criteria are set which

+determine the intent of the request, and the signals of the request

+are connected to slots which deals with the results. The request can then

+be started.

+

+*/

+definition may be saved.

+\section2 Detail Access Constraints

+

+Some details in a contact retrieved from a manager may have access constraints set.

+An access constraint on a detail means that the detail may not be removed (if the access constraint is \c QContactDetail::Irremovable)

+or updated (if the access constraint is \c QContactDetail::ReadOnly) by the client. If the client attempts to save an updated

+version of a read-only detail in a contact, or remove a detail which is irremovable from a contact, the operation will succeed;

+however those updates to the contact will be ignored by the manager when the contact is saved there.

+For example, the \l{QContactDisplayLabel} is defined in the default schema as a read-only, irremovable detail,

+meaning that it may not be modified or deleted by the client, but are provided by the backend (in the case

+of \l{QContactDisplayLabel}, automatically synthesized by the backend from various details of the contact, like

+the \l{QContactName}, \l{QContactNickname}, etc).

+There are three possible detail access constraints: read-only, irremovable and no constraint.

+A read-only constraint ensures that clients cannot modify the values stored in such details in the persistent

+copy of the contact (that is, the contact as it is stored in the manager); the irremovable constaint ensures

+that a particular detail may not be removed by clients. In general, most details which are read only will

+also be irremovable, and vice versa. One exception to this is the \l{QContactType} detail, which is

+irremovable but may be updated by clients as desired.

+Details with no constraint may be added, updated and removed as desired by the client. Changes to such details

+in a contact will be persisted in the manager when the client calls \l{QContactManager::saveContact()}.

+Please see the documentation of \l{QContactDetail} for more information on access constraints.

+ \o \l{QContactGuid} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable

+ \o \l{QContactSyncTarget} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable

+ \o \l{QContactTimestamp} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable

+ \o \l{QContactPresence} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable

+ \o \l{QContactDisplayLabel} is \c QContactDetail::ReadOnly and \c QContactDetail::Irremovable

+ \o \l{QContactType} is \c QContactDetail::Irremovable

+\section2 Backend-provided Details

+As described in the section on detail access constraints, some details are provided by the backend,

+such as \l{QContactDisplayLabel} and \l{QContactPresence}. When the client attempts to save a \l{QContact}

+that contains these details, these details will be ignored by the backend (since any values in this field

+are synthesized by the backend). This means that while clients may (for example) add a

+\l{QContactPresence} detail to a \l{QContact}, it will not be persisted in the manager when the

+client attempts to save that contact.

+Precisely which details are backend-provided is backend specific; some backends provide more details

+than others.

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+/*!

+

+\page contactssync.html

+

+\title Contacts Synchronous API

+

+\tableofcontents

+

+

+\section1 Introduction

+

+The Contacts Synchronous API enables a client to synchronously fetch, update, or remove

+contact data from a contact manager. A synchronous API is of most use to clients who wish

+to perform simple requests where performance or UI responsiveness is not critical.

+Synchronous calls to a contact manager will block until they are completed, and therefore

+should not be performed in the GUI thread if the manager is a frontend to an online service

+or long-latency datastore. The main advantage of the synchronous API is its simplicity and

+convenience.

+

+Most operations which may be performed using the synchronous API may also be

+performed using the asynchronous API. It is recommended for most

+applications that the asynchronous API be used where possible.

+

+

+\section1 Using The API

+

+The synchronous API offered by the Contacts module is available through the QContactManager

+class. It consists of four major sections:

+\list

+ \o Error Reporting

+ \o Schema Manipulation

+ \o Contact Manipulation

+ \o Relationship Manipulation

+\endlist

+

+

+\section2 Error Reporting

+

+When a synchronous operation fails, clients need to be able to retrieve error information associated

+with that synchronous operation. The QContactManager::error() function provides this information to clients.

+

+For some synchronous operations (for example, batch save or remove operations) it is possible that

+multiple errors may occur during the operation. In those cases, the synchronous function will take

+a pointer to a map of input index to error, which will be filled by the function as required, and

+the QContactManager::error() function will report the overall operation error.

+

+Error reporting is handled slightly differently in the asynchronous API, in that each instance of

+an asynchronous request is able to report any overall operation error as well as the finer-grained

+map of errors, for the operation which it requested.

+

+

+\section2 Contact Manipulation

+

+The most common type of operation that clients will perform involves retrieval or modification of contacts.

+The QContactManager class offers synchronous API to retrieve, create, update and delete contacts. The create

+and update operations are provided through the same interface. Both singular and batch operations are offered

+by the API.

+

+A contact is identified by its QContactId. This id consists of two parts: a URI which identifies the contact manager

+which stores the contact, and the local id of the contact in that manager. Some operations which take a pointer

+to a contact as an argument may modify the contact during the operation; updating the contact id is a common example.

+

+The QContactManager class provides API for accessing the ids of contacts which are stored in the manager:

+\list

+ \o contactIds(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const

+ \o contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const

+\endlist

+

+The contact id retrieval functionality is also provided via asynchronous API through the QContactLocalIdFetchRequest class.

+

+The synchronous, singular contact manipulation functions offered by the QContactManager class are:

+\list

+ \o contact(const QContactLocalId& contactId, const QContactFetchHint& fetchHint = QContactFetchHint()) const

+ \o saveContact(QContact* contact)

+ \o removeContact(const QContactLocalId& contactId)

+\endlist

+

+The (optional) fetch argument to the contact accessor function allows clients to tell the plugin

+which types of information they wish to retrieve. This argument is a hint only, and may be ignored safely by the plugin,

+or used by the plugin to optimize the performance of the retrieve operation.

+

+The save operation entails a validation step, where the contact's details are checked against the supported schema.

+If the contact is valid, it will be saved. Note that if the contact already exists in the database (determined by

+the id of the contact) it will be replaced with the contact contained in the argument. This means that clients should

+not save any contact which was retrieved with a non-empty fetchHint defined, or data loss may occur.

+

+Any error which occurs during such singular contact manipulation functions may be accessed by calling QContactManager::error()

+directly after the original synchronous call.

+

+The synchronous, batch contact manipulation functions offered by the QContactManager class are:

+\list

+ \o contacts(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const

+ \o contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const

+ \o saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap)

+ \o removeContacts(QList<QContactLocalId>* contactIds, QMap<int, QContactManager::Error>* errorMap)

+\endlist

+

+The batch save and remove functions both take an (optional) pointer to a map of errors. If the pointer is non-null,

+this map will be filled out with any errors which occur. The overall operation error of any batch manipulation operation

+may be accessed by calling QContactManager::error() directly after the original synchronous call.

+

+The contact manipulation functionality is also provided via asynchronous API through the QContactFetchRequest,

+QContactSaveRequest, and QContactRemoveRequest classes.

+

+The "self" contact is a special concept, which has dedicated API. A client may instruct any backend which supports the

+concept of a self contact that a particular, previously saved contact is the self contact. Any backend which implements

+this functionality should report that it supports the QContactManager::SelfContact feature.

+

+The API which provides the self-contact functionality consists of:

+\list

+ \o setSelfContactId(const QContactLocalId& contactId)

+ \o selfContactId() const

+\endlist

+

+In order to unset the self contact, a client may either delete the contact which is currently set as the self contact,

+or set the self contact id to be the invalid, zero id (constructed via QContactLocalId(0)).

+The self-contact manipulation functionality is only available via the synchronous API.

+

+

+\section2 Relationship Manipulation

+

+Contacts may be related in various ways. The contacts API allows clients to define relationships between contacts

+if the plugin providing the functionality supports such relationships. Any plugin which supports relationships

+should report this functionality by reporting that it supports the QContactManager::Relationships feature.

+

+Some plugins support arbitrary relationship types. Clients can define custom relationships between contacts saved

+in such plugins. Any plugin which supports arbitrary relationship types should report this functionality by reporting

+that it supports the QContactManager::ArbitraryRelationshipTypes feature.

+

+The API which provides the relationship manipulation functionality consists of:

+\list

+ \o relationships(const QContactId& participantId, QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;

+ \o relationships(const QString& relationshipType = QString(), const QContactId& participantId = QContactId(), QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;

+ \o saveRelationship(QContactRelationship* relationship);

+ \o saveRelationships(QList<QContactRelationship>* relationships);

+ \o removeRelationship(const QContactRelationship& relationship);

+ \o removeRelationships(const QList<QContactRelationship>& relationships);

+\endlist

+

+The relationship manipulation functionality is also provided via asynchronous API through the QContactRelationshipFetchRequest,

+QContactRelationshipSaveRequest, and QContactRelationshipRemoveRequest classes.

+

+

+\section2 Schema Manipulation

+

+The schema supported by a plugin is the list of detail definitions which are supported by the plugin.

+A contact which contains a detail of a particular definition which is not supported by the plugin

+will fail to validate when the user attempts to save it in that manager. The schema also includes

+any access constraints which may apply to certain details or detail definitions (for example,

+a particular detail definition might be declared to be unique per-contact in a particular manager).

+

+Every plugin will support a slightly different schema, as the schema which can be supported will depend

+on the semantics and limitations of the underlying storage platform on which the plugin is based.

+The default schema is described in the \l {Qt Contacts Schema}{Qt Mobility Contacts schema documentation},

+and plugins should attempt to implement that schema; however no guarantees are given to clients as to

+the conformance of the schemas supported by various plugins to the default schema.

+

+Some plugins support extensible detail types. This means that third party developers can

+extend the schema of such plugins at run time (for example, to add a new field to a detail).

+Some plugins allow third party developers to define new detail types (that is, to

+add an entirely new detail type to the schema supported by that plugin).

+Plugins which support these types of operations must report to clients that they support the

+QContactManager::MutableDefinitions feature.

+

+The synchronous API offers several functions to retrieve or modify the schema supported by a plugin:

+\list

+ \o detailDefinitions(const QString& contactType = QContactType::TypeContact) const

+ \o detailDefinition(const QString& definitionName, const QString& contactType = QContactType::TypeContact) const

+ \o saveDetailDefinition(const QContactDetailDefinition& def, const QString& contactType = QContactType::TypeContact)

+ \o removeDetailDefinition(const QString& definitionName, const QString& contactType = QContactType::TypeContact)

+\endlist

+

+The schema manipulation functionality is also provided via asynchronous API through the

+QContactDetailDefinitionFetchRequest, QContactDetailDefinitionSaveRequest and QContactDetailDefinitionRemoveRequest

+classes.

+

+Note that the schema supported by a plugin may vary depending on the type of contact to which the schema applies.

+For example, a particular plugin might support name, address, phone number, email address, and gender details for

+normal contacts, but only name, address, and phone number details for a group contact.

+

+

+\section1 Examples Of Usage

+

+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 until completion and is therefore

+most suitable only for applications which interact with local, high-speed

+datastores.

+

+

+\section2 Saving a new contact to the default manager

+

+The client creates a new contact, adds a name and a phone number, and

+saves it to the default store of the default manager.

+

+We assume the existence of a specialised leaf-class that allows simple

+access to details of the definition identified by the "PhoneNumber"

+identifier, and another that allows simple access to details of the

+definition identified by the "Name" identifier. These specialised leaf

+classes may be written by anyone, and simply wrap the functionality

+provided by QContactDetail in order to allow simpler access to fields

+supported by a particular definition.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Creating a new contact

+

+\section2 Filtering by detail definition and value

+

+The client utilises a default manager and asks for any contacts with a

+particular phone number. The example assumes that the default manager

+supports the provided QContactPhoneNumber detail leaf class (which

+implements the default definition for phone number details).

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Filtering by definition and value

+

+

+\section2 Installing a plugin that modifies the definition of one type of detail

+

+The client installs a plugin, which requires a new field to be added to

+details of the "EmailAddress" definition. It loads the definition from the

+default manager, modifies it (by adding the new field - a label field), and

+saves it back.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Installing a plugin which modifies a definition

+

+\section3 Modifying an existing contact and saving the modifications

+

+The client retrieves a contact, modifies one of its details, adds a new

+detail, and then saves the contact back to the manager. Note that it uses

+the newly added field of the email address definition!

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Modifying an existing contact

+

+*/

+

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+/*!

+

+\page contactsusagehtml

+

+\title Contacts API Usage

+

+\tableofcontents

+

+\section1 Introduction

+

+This section provides some examples of common usage of the Qt Contacts API.

+

+\section1 Manager Settings And Configuration

+

+Users of the contacts API can define which backend they wish to access if a

+manager for that backend is available. The list of available managers can be

+queried programmatically at run-time, and the capabilities of different

+managers can be ascertained by inspecting a QContactManager instance.

+Furthermore, some managers can be constructed with parameters which affect the

+operation of the backend.

+

+\section2 Loading the default manager for the platform

+

+Most users of the API will want to use the default manager for the platform,

+which provides access to the system address book. Instantiating a manager by

+using the default constructor will result in the default manager for that

+platform being instantiated.

+

+The default constructor can either be used to create a manager on the stack,

+in which case it will be deleted automatically when it goes out of scope:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Loading the default manager for the platform

+

+or it can be used explicitly to create a manager on the heap, in which case

+the client must ensure that they delete the manager when they are finished

+with it in order to avoid a memory leak:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Loading the default manager for the platform on heap

+

+\section2 Querying a manager for capabilities

+

+Different managers will support different capabilities and details. Clients

+can use the meta data reporting functions of QContactManager to determine what

+the capabilities of the manager they have instantiated might be.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Querying a manager for capabilities

+

+\section2 Loading the manager for a specific backend

+

+In this example, the client loads a manager for a specific backend. While

+this could be found and retrieved using a more advanced plugin framework

+(such as the Qt Service Framework), this code assumes that the client has

+prior knowledge of the backend in question.

+

+Clients may wish to use this feature of the API if they wish to store or

+retrieve contact information to a particular manager (for example, one that

+interfaces with a particular online service).

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Loading a specific manager backend

+

+\section2 Loading a manager with specific parameters

+

+The client loads a manager with specific parameters defined. The

+parameters which are available are backend specific, and so the client had

+to know that the "Settings" parameter was valid for the particular backend,

+and what argument it took. In this example, the client tells the backend to

+load detail definitions saved in a particular settings file.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Loading a specific manager backend with parameters

+

+\section1 Contact Detail Manipulation

+

+Once a contact has been created (or retrieved from a manager), the client can

+retrieve, create, update or delete details from the contact. Since QContact

+and QContactDetail are both container (value) classes, the API offered for

+these operations is purely synchronous.

+

+A contact consists of the details it contains, as well as an id. Some details

+are read-only (such as the display label of a contact) or irremovable (like

+the type of a contact), but most are freely modifiable by clients.

+

+\section2 Adding a detail to a contact

+

+The client adds a name and a phone number to a contact.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Adding a detail to a contact

+

+\section2 Updating a detail in a contact

+

+The client updates the phone number of a contact.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Updating a detail in a contact

+

+\section2 Removing a detail from a contact

+

+The client removes the phone number of a contact.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Removing a detail from a contact

+

+\section2 Viewing a specific detail of a contact

+

+The client retrieves and displays the first phone number of a contact

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Viewing a specific detail of a contact

+

+\section2 Viewing all of the details of a contact

+

+The client retrieves all of the details of a contact, and displays them

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Viewing the details of a contact

+

+It is important to note that details are implicitly shared objects with

+particular semantics surrounding saving, removal and modification. The

+following example demonstrates these semantics

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Demonstration of detail sharing semantics

+

+\section1 Persistent Contact Information

+

+After instantiating a manager, clients will wish to retrieve or modify contact

+information (including relationships and possibly detail definitions) which

+is persistently stored in the manager (for example, in a database or online

+cloud).

+

+If the client wishes to use the asynchronous API, it is suggested that their

+class uses member variables for the manager and requests, similarly to:

+

+ \snippet snippets/qtcontactsdocsample/requestexample.h Class setup

+

+This allows them to define slots which deal with the data as required when the

+state of the request changes:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Example of an asynchronous request slot

+

+Note that if the client is interested in receiving the results of the request

+as they become available, rather than only the final set of results once the

+request changes state (to \c FinishedState, for example), the client should

+instead connect the QContactAbstractRequest::resultsAvailable() signal to the

+slot which deals with the results.

+

+\section2 Creating a new contact in a manager

+

+The client creates a new contact and saves it in a manager

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Creating a new contact in a manager

+

+Alternatively, the client can explicitly block execution until the request is

+complete, by doing something like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Creating a new contact in a manager waiting until finished

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously creating a new contact in a manager

+

+\section2 Retrieving contacts from a manager

+

+The client requests all contacts from the manager which match a particular

+filter.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Filtering contacts from a manager

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously filtering contacts from a manager

+

+The client can also retrieve a particular existing contact from a manager, by

+directly requesting the contact with a particular (previously known) id.

+With the asynchronous API, this takes the form of another filter:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Retrieving an existing contact from a manager

+

+The synchronous API provides a function specifically for this purpose:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously retrieving an existing contact from a manager

+

+\section2 Updating an existing contact in a manager

+

+The client updates a previously saved contact by saving the updated version of

+the contact. Any contact whose id is the same as that of the updated contact

+will be overwritten as a result of the save request.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Updating an existing contact in a manager

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously updating an existing contact in a manager

+

+\section2 Removing a contact from a manager

+

+The client removes a contact from the manager by specifying its local id.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Removing a contact from a manager

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously removing a contact from a manager

+

+\section2 Creating a new relationship between two contacts

+

+The client specifies a relationship between two contacts stored in the manager

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Creating a new relationship between two contacts

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously creating a new relationship between two contacts

+

+\section2 Retrieving relationships between contacts

+

+The client requests the relationships that a particular contact is involved in

+from the manager in which the contact is stored.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Retrieving relationships between contacts

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously retrieving relationships between contacts

+

+When a contact is retrieved, it will contain a cache of the relationships in

+which it is involved at the point in time at which it was retrieved.

+This provides clients with a simple way to retrieve the relationships in which

+a contact is involved, but carries the risk that the cache is stale.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Retrieving relationships from cache

+

+Clients can inform the manager that they do not require this cache of

+relationships to be populated when retrieving a contact, which can allow a

+manager to optimize contact retrieval. Other retrieval optimizations are also

+possible to specify, for example that they are only interested in certain types of details.

+The following code shows how the client can inform the manager that they are

+only interested in relationships of the \c HasMember type (groups):

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Providing a fetch hint

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously providing a fetch hint

+

+\section2 Removing a relationship between two contacts

+

+The client can remove a relationship directly from a manager.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Removing a relationship

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously removing a relationship

+

+Alternatively, when a contact which is involved in a relationship is removed,

+any relationships in which it is involved will be removed also.

+

+\section2 Querying the schema supported by a manager

+

+The client queries the schema supported by a manager, and checks to see if a

+particular detail definition supports a certain field.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Querying the schema supported by a manager

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously querying the schema supported by a manager

+

+\section2 Modifying the schema supported by a manager

+

+The client attempts to modify a particular detail definition by extending it

+so that it supports an extra field.

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsampleasync.cpp Modifying the schema supported by a manager

+

+The equivalent code using the synchronous API looks like:

+

+ \snippet snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Synchronously modifying the schema supported by a manager

+

+Note that some managers do not support mutable definitions, and hence

+attempting to modify or remove detail definitions in those managers will fail.

+

+*/

+ \o \l{qmlcontacts}{QML-based Sample Phonebook}

+ \o \l{servicebrowser}{Service Browser}\raisedaster

+ \o \l{notesmanagerplugin}{Notes Manager Plugin}

+ \o \l{sfw-notes}{Notes Manager}

+ \o \l{declarative-sfw-notes}{Declarative Notes Manager}

+ \o \l{declarative-sfw-dialer}{Declarative Dialer}

+

+ \section1 Registering the Service

+ The service can be registered by using the function \l{QServiceManager::}{addService()}, this takes a path to the XML file that describes the service, \i{bluetoothtransferservice.xml}.

+

+ \section1 Writing the Plugin

+ To implement a plugin it is necessary to create a new plugin class derived from QObject and QServicePluginInterface. The function QServicePluginInterface::createInstance() is implemented to return the appropriate instantiated object based on the interface name passed into the function. Since there is only one interface name for this example there is no test involved, so we can simply create the object implementing the service and return its pointer.

+

+ \snippet ../../examples/bluetoothtransferplugin/bluetoothtransferplugin.cpp createinstance

+

+ The implementation of the service BluetoothTransfer is simply a test function for this example. The BluetoothTransfer class is very simple, with only an empty constructor and the sendFile() function

+

+ \snippet ../../examples/bluetoothtransferplugin/bluetoothtransfer.cpp sendFile

+

+\example declarative-sfw-dialer

+access the services in a QMLContext. Currently there is a wrapper class

+which provides functionality for a single service as well as a list of

+services. In future releases this will be included as a plugin. Another

+example that demonstrates how to connect to a single service object to

+implement a simple note taking application can be found \l{declarative-sfw-notes}{here}.

+ \o Include the neccessary service framework type registrations

+ \o Include the QML canvas to be displayed

+Step is shown below:

+\snippet declarative-sfw-dialer/sfwexample/main.cpp 0

+

+Now to make our service framework wrappers known to QML as registered types we need the

+following inline method:

+\snippet declarative-sfw-dialer/sfwexample/main.cpp 1

+This allows us to import our new types in QML by:

+\snippet declarative-sfw-dialer/sfwexample/content/DialerList.qml 4

+We are using QDeclarativeView to load and show our QML content

+\snippet declarative-sfw-dialer/sfwexample/main.cpp 2

+declarative-sfw-dialer\\landlinedialer and declarative-sfw-dialer\\voipdialer.

+In our example this will be done in the function registerExampleServices in the registration class

+accompanying the main function:

+\snippet declarative-sfw-dialer/sfwexample/sfwexample.cpp 0

+

+\snippet declarative-sfw-dialer/voipdialer/voipdialerplugin.h 0

+\snippet declarative-sfw-dialer/voipdialer/voipdialerplugin.cpp 0

+\snippet declarative-sfw-dialer/voipdialer/voipdialer.h 0

+\snippet declarative-sfw-dialer/sfwexample/qdeclarativeservice.h 0

+Additionally, there is a QList of ServiceWrapper objects that is also available through QML which can be used to

+obtain a list of services and their details by supplying an interface with an optional minimum version number. QML

+can gain access to these details including the list using the QML-specific QDeclarativeListProperty with the

+following properties.

+\snippet declarative-sfw-dialer/sfwexample/qdeclarativeservice.h 1

+The ServiceWrapperList contains a list of all available services that contain the com.nokia.qt.examples.Dialer interface.

+In the setInterfaceName(..) function which is QML accessible, a QList of ServiceWrapper objects is populated for the

+dialer services (LandLineDialer and VoipDaler). Each ServiceWrapper object containts the QServiceInterfaceDescriptor and

+properties which allow QML to access the service library functions. This is done by utilising the code below:

+\snippet declarative-sfw-dialer/sfwexample/qdeclarativeservice.cpp 0

+QML context requires a special declarative list when declaring the property, in this case the property services will

+provide QML with the list of ServiceWrappers which can call serviceObject(..) to reference the service library functions.

+The first step is to use our ServiceWrapperList to specify the interface and minimum version (optional) through QML item

+context, which will produce a list of ServiceWrapper objects.

+

+\snippet declarative-sfw-dialer/sfwexample/content/DialerList.qml 5

+

+In the DialerList.qml file the services property is assigned to the ListView model property.

+\snippet declarative-sfw-dialer/sfwexample/content/DialerList.qml 0

+\snippet declarative-sfw-dialer/sfwexample/content/DialerList.qml 1

+\target DialerList_qml_2

+\snippet declarative-sfw-dialer/sfwexample/content/DialerList.qml 2

+\snippet declarative-sfw-dialer/sfwexample/content/DialerList.qml 3

+\snippet declarative-sfw-dialer/sfwexample/sfwexample.qml 0

+\snippet declarative-sfw-dialer/sfwexample/content/DialScreen.qml 1

+\snippet declarative-sfw-dialer/sfwexample/content/DialScreen.qml 2

+This is done in our main declarative file:

+\snippet declarative-sfw-dialer/sfwexample/sfwexample.qml 1

+\l {DialerList_qml_2}{ ServiceList.qml file}.

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+/*!

+\example declarative-sfw-notes

+

+\title Declarative Service Framework Notes Manager

+

+This example demonstrates how to use the \l{notesmanagerplugin}{Notes Manager service plugin}

+to implement a notes managing application with QML as the declarative user-interface. There

+is also a non-QML counterpart which demonstrates an identical application using standard Qt

+user-interface tool. See \l{sfw-notes}{Service Framework Notes Manager} for more details.

+

+

+\bold {Explanation}

+

+In general, QML requires external types and registrations to be provided via a plugin-based

+system, which the service framework does not currently provide. Instead, we have a wrapper

+class which provides access to the QServiceManager and QServiceInterfaceDescriptor API that

+needs to be included in the project and declared in the main funciton of the application. The

+wrapper is referred to as QDeclarativeService.

+

+This example demonstrates how QML can be used to completely control the logic of the

+application, using a combination of declarative elements and Javascript in the QML file. The

+main function is used to produce an application binary but once service framework supports

+a QML plugin, only the QML file will be needed. Also contained is a class that registers our

+Notes Manager service to supply the plugin library, which can also be done using the

+servicefw tool.

+

+There is another service framework example that demonstrates how to use the wrapper to

+browse a list of services to select for dialing usage. See

+\l{declarative-sfw-dialer}{Declarative Service Framework Dialer} for a detailed explanation.

+

+The secion belows explains how QML can be used to emulate to exact functionality of the

+alternate Qt/C++ example.

+

+

+\bold {QML File}

+

+The very first step is to import our registered types with the following:

+\snippet declarative-sfw-notes/declarative-sfw-notes.qml 0

+

+Now to obtain the default service with a specific interface name from within QML we can

+use the Service wrapper item as follows:

+\snippet declarative-sfw-notes/declarative-sfw-notes.qml 6

+

+In most cases we will need the service to be avaiable to all parts of the QML file, meaning

+the actual QObject returned from the service wrapper needs to be a global property.

+\snippet declarative-sfw-notes/declarative-sfw-notes.qml 1

+

+The interfaceName property of the Service item has READ and WRITE methods which can be used

+to obtain a new service instance and check if there was a valid default service.

+\snippet declarative-sfw-notes/declarative-sfw-notes.qml 2

+

+With a valid reference which points to the service plugin class we can now invoke methods

+directly from the Notes Manager plugin. The example below shows how to obtain a list of

+notes and delete one from the notes manager database through QML.

+\snippet declarative-sfw-notes/declarative-sfw-notes.qml 3

+

+The Notes Manager plugin also provides readable functions which return the values of a

+single note and can be utilized to display on the UI as follows:

+\snippet declarative-sfw-notes/declarative-sfw-notes.qml 4

+\snippet declarative-sfw-notes/declarative-sfw-notes.qml 5

+

+*/

+

+ \section1 Registering the Service

+ The service can be registered by using the function \l{QServiceManager::}{addService()} which takes a path to the XML file that describes the service, \i{filemanagerservice.xml}.

+

+ \section1 Writing the Plug-In

+ A Service plug-in is made by deriving a new plugin class from the QServicePluginInterface class then implementing the function QServicePluginInterface::createInstance().

+

+ The FileManager plugin example has a simple \l {QServicePluginInterface::}{createInstance()}. It

+ only needs to create the appropriate object based on the interface name

+ and return a pointer to it.

+

+ \snippet ../../examples/filemanagerplugin/filemanagerplugin.cpp createinstance

+

+ The functionality of the FileManager and the FileTransfer classes are

+ in the separate classes FileManagerStorage and FileManagerTransfer respectively. The existing functions are merely test stubs to demonstrate

+ the concept.

+

+

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+/*!

+ \example notesmanagerplugin

+ \title Notes Manager Plugin Example

+

+ This example shows how to write a service plugin that manages textual notes by using a

+ database to add, delete and store note objects. This plugin is QML compatible and is

+ therefore used in the example \l{declarative-sfw-notes}{Declarative Notes Manager} as

+ well as its non-QML counterpart \l{sfw-notes}{Notes Manager} which uses standard

+ user-interface files (*.ui).

+*/

+ \example qmlcontacts

+ \title Sample QML-based Phonebook Example

+ \section1 Phone Book

+ This example shows how to write a simple read-only phonebook with the \l{Contacts}{Contacts API},

+ with a user interface declared with the QML declarative language.

+ This application was written to provide an example to developers of how to use the Qt Mobility Contacts API,

+ and an example of integration with QML.

+ The interface is simplistic and merely provides an example that may provide a starting point

+ for developers interested in designing QML-based interfaces for projects which use Qt Mobility APIs.

+ The example is not intended to be feature complete. Only a very limited subset of detail types are

+ supported by the application. It exercises only a very small portion of the Qt Contacts API.

+ The example is read-only and not performant.

+ \o Use the QTM_USE_NAMESPACE macro (defined in qmobilityglobal.h but implicitly included from any Qt Mobility header)

+within a Qt Mobility namespace and thus developers

+need to use the QTM_USE_NAMESPACE macro.

+

+When developing on Symbian we will also need to add the required capabilites to the project file in order to satisfy the Symbian security model:

+

+\snippet quickstart/quickstart.pro 1

+

+\table

+\header

+ \o Domain

+ \o Symbian Capabilities

+\row

+ \o \l {Bearer Management}

+ \o ReadUserData NetworkServices (NetworkControl for QNetworkSession::stop())

+\row

+ \o \l {Contacts}

+ \o ReadUserData WriteUserData SwEvent ReadDeviceData WriteDeviceData

+\row

+ \o \l {Location}

+ \o Location

+\row

+ \o \l {Multimedia}

+ \o UserEnvironment ReadUserData WriteUserData ReadDeviceData WriteDeviceData

+\row

+ \o \l {Messaging}

+ \o LocalServices ReadUserData WriteUserData NetworkServices UserEnvironment ReadDeviceData WriteDeviceData

+\row

+ \o \l {Publish And Subscribe}

+ \o ReadDeviceData WriteDeviceData

+\row

+ \o \l {Qt Service Framework} {Service Framework}

+ \o No capabilities requried by itself, the plugins may have capability requirements.

+\row

+ \o \l {System Information}

+ \o LocalServices ReadUserData WriteUserData NetworkServices UserEnvironment Location TrustedUI ReadDeviceData

+\row

+\endtable

+

+If you are developing for Symbian, to make a debug build for the emulator run:

+This assumes that qmake is in your %PATH% and Qt has been built for the emulator already.

+Symbian see \l {http://qt.nokia.com/doc/4.6/symbian-with-qt-introduction.html}

+{The Symbian Platform - Introduction to Qt} and \l {http://developer.symbian.org/wiki/index.php/Qt_Quick_Start}

+{Qt Quick Start}

+ This application was written to provide an example to developers of how to use the QtContacts and

+ QtVersit APIs.

+

+ It provides an example of how to use the QtMobility libraries to:

+ \list

+ \o select a backend for persistent storage

+ \o list the stored contacts

+ \o add contacts

+ \o edit contacts

+ \o use filters to find contacts matching certain criteria

+ \o import and export contact lists as vCards\reg *

+ \endlist

+ of people that they know. This sample application provides a simple phone book that allows users

+ to store certain pieces of information about their contacts, and save them to the contacts database of

+ their device.

+ The application is designed to work on desktop and mobile platforms with

+ minimal differences in code between the platforms. The interface is

+ organized into a paged view, showing the \i {Contact List} by default.

+ Contacts can be added, edited or deleted using the buttons at the bottom

+ of the contact list.

+ To search for a contact in the list, a filter can be applied using the

+ \i {Apply Filter} item in the \i Contacts menu.

+

+ Here we see the \i {Contact List} with some names added.

+

+ \image sample-phonebook-1.png

+

+ When adding a new contact a new page is shown, with a \i{Set Picture}

+ button to import an image. It is a good idea to use smaller images if

+ you intend to export the contacts to a file later.

+

+ \image sample-phonebook-2.png

+

+ From the main menu, \i{Contacts}, you can select \i{Apply Filter}. This

+ will display a new page which enables the user to specify filter criteria.

+ In the screenshot below, we are selecting based on the first two characters

+ of the Name,

+

+ \image sample-phonebook-3.png

+

+ which gives us a subset of the list of contacts.

+

+ \image sample-phonebook-4.png

+ To reset this, just select \i{Clear Filter} from the \i {Contacts} menu.

+ The contact list can also be imported and exported to the vCard format

+ through the \i {Import Contacts} and \i {Export Contacts} items in the

+ \i Contacts menu. This functionality can be used to populate the

+ list from another device or application.

+ In particular:

+ \o The example only exercises the synchronous API of QtContacts. For most real applications, the

+ asynchronous API is the preferred interface to use as it does not block the UI while a query

+ is made to the contacts backend.

+ \o Detail subtypes and contexts are not supported by the interface.

+ \o Duplicate contacts are not filtered out - importing the same contact twice results in two

+ identical contacts appearing in the list. In a real application, more complex synchronization

+ code may be required.

+ \o Contact groups are not supported. The QtContacts API supports two methods of grouping contacts.

+ One way is to use contacts of type \l{QContactType::TypeGroup}{TypeGroup}, along with the

+ \l{QContactRelationship::HasMember}{HasMember} QContactRelationship. The other way is to use

+ the QContactTag detail by giving related contacts the same tag. A real application may support

+ grouping via one or both of these methods.

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+/*!

+ \example sfw-notes

+

+ \title Service Framework Notes Manager

+

+ This example demonstrates how to use the Service Framework to obtain a single

+ default service at a specified interface address provided by the Notes

+ Manager service \l{notesmanagerplugin}{plugin}, which can be used to implement

+ a notes managing application.

+

+ There is also a declarative example which implements identical functionality

+ using QML as the main user-interface context. This example is called the

+ \l{declarative-sfw-notes}{Declarative Notes Manager}

+*/

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+/*!

+ \example sysinfo

+ \title System Information Example

+

+

+ \image sysinfo.png

+

+

+ The System Information example uses a tabbed dialog, with each tab

+ representing a particular type of data: versions, network and so on.

+

+ To access the information, the example creates objects belonging to the System Information classes

+

+ \annotatedlist systeminfo

+

+ Here are some examples that show how the example application reads the

+ device information.

+

+ The current language

+

+ \snippet ../../examples/sysinfo/dialog.cpp lang

+

+ Device information, starting with the battery level

+

+ \snippet ../../examples/sysinfo/dialog.cpp createdi

+ \dots

+ \snippet ../../examples/sysinfo/dialog.cpp batteryLevel

+

+ The manufacturer id and the product name

+

+ \snippet ../../examples/sysinfo/dialog.cpp manuf-id

+ \dots

+ \snippet ../../examples/sysinfo/dialog.cpp productName

+

+ And there are signals that can be used to update progress bars and other

+ indicators. An example is when the battery level changes, the batteryLevelChanged() signal is emitted

+

+ \snippet ../../examples/sysinfo/dialog.cpp sig batteryLevelChanged

+

+

+ Other information is stored as bitwise flags. The following code shows

+ the input methods being determined using flags.

+

+ \snippet ../../examples/sysinfo/dialog.cpp inputMethod flags

+

+ Various capabilities of the device can be found by testing for features.

+ In the example a Feature combo box, on the General tab, has a hard coded

+ list of features. When a listed featue is selected the getFeature()

+ function is called with the index which is handled by applying a test to

+ the corresponding feaure.

+

+ \snippet ../../examples/sysinfo/dialog.cpp feature

+ \dots

+ \snippet ../../examples/sysinfo/dialog.cpp feature-bluetooth

+ \dots

+ \snippet ../../examples/sysinfo/dialog.cpp feature test

+

+

+*/

+

+

+

+ \example declarative-sfw-dialer

+ \title Declarative Service Framework Example

+\l{Versit API (technology preview)}{Versit API Documentation}

+ audio recording, and the playing of music or video clips.

+ <table cellpadding="2" cellspacing="1" border="0">

+ <tbody>

+

+ </tr>

+ <tr>

+ <td bgcolor="green"></td>

+ <td>A functional backend for the API on the platform is complete.</td>

+ </tr>

+ <tr>

+ <td bgcolor="yellow"></td>

+ <td>A functional backend for the API on the platform is being worked however it is not functionally complete.</td>

+

+ </tr>

+ <tr>

+ <td>A functional backend for the API on the platform is being worked on. At this point it is far from functionally complete or there is no platform specific code inside QDF source code.</td>

+ <td>A functional backend for the API on the platform is not being worked on. It is possible for others to implement and integrate support.</td>

+ </tbody>

+

+ <b>Tier 1 Platforms</b><br>

+ Primary platforms are the main focus of Mobility API. There platforms are frequently tested by our unit test suite and other internal testing tools. However, the timeline of availability for each backend is subject to change.

+ <br>

+ <b>Tier 2 Platforms</b><br>

+ Secondary platforms include future direction of Qt Mobility API. Contributions to these platforms are welcome.

+ <br>

+ <br>

+ <table align="center" cellpadding="2" cellspacing="1" border="1">

+ <tbody>

+ <td rowspan="2">&nbsp;</td>

+ <td rowspan="2"><b>API Maturity Level</b></td>

+ <td colspan="5" align="center" bgcolor="#96E066"><b>Tier 1 Platforms</b></td>

+

+ <td colspan="4" align="center" bgcolor="#96E066"><b>Tier 2 Platforms</b></td>

+ </tr>

+ <tr>

+ <td width="9%"><b>S60 3rd Edition, Feature Pack 1</b></td>

+ <td width="9%"><b>S60 3rd Edition, Feature Pack 2</b></td>

+ <td width="9%"><b>S60 5th Edition</b></td>

+ <td width="9%"><b>Symbian^3</b></td>

+ <td width="9%"><b>Maemo 5</b></td>

+ <td width="9%"><b>Windows CE/Mobile<b></b></b></td>

+ <td width="9%"><b>Windows XP/Vista</b></td>

+

+ <td width="9%"><b>Linux</b></td>

+ <td width="9%"><b>Mac OS X</b></td>

+ <td>FINAL</td>

+

+ <td>FINAL</td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+

+ <td>FINAL</td>

+

+ <td>FINAL</td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+

+ <td>FINAL</td>

+ <td bgcolor="yellow"></td>

+ <td>FINAL</td>

+

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="gray"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td>FINAL</td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+

+ <tr>

+ <td>BETA</td>

+ <td bgcolor="yellow"></td>

+ <td bgcolor="green"></td>

+

+ <tr>

+ <td>FINAL</td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+ <td bgcolor="green"></td>

+

+ <td bgcolor="green"></td>

+ <p></p>

+ <p></p>

+ </tbody>

+a copy. Furthermore perl must be installed and available in the environment path.

+Windows environments may require the installation of a perl interpreter such as

+\l {http://www.activestate.com/activeperl} {ActivePerl}. On the Maemo 5 (Fremantle)

+platform PR1.2 firmware release or newer is required.

+

+ \o The Maemo 5 backend depends on \l {http://maemo.org/packages/view/libosso-abook/}{libosso-abook}.

+ The Maemo 6 backend depends on \l {http://maemo.gitorious.org/maemo-af/libqttracker}{libqttracker}.

+ will be updated when the library is released.

+ provides SMS/MMS facilities. Email functionality requires that an email

+ MediaPlayerEngine (MediaPlayerUtilityAPI for 3rd FP2), AudioRoutingAPI , Tuner Utility (only for 3rd FP1) Radio Utility API (for 3rd FP2 and 5th ed).

+\section1 Namespace

+

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+\section1 Namespace

+

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+\section1 Examples

+

+\section2 Keep In Touch

+

+The \l {keepintouch}{Keep In Touch} example shows how to extract useful

+information from the messages stored by the system.

+

+

+\section2 Service Actions

+

+The \l {serviceactions}{Service Actions} example is a program to demonstrate

+how to compose, send, show, query and retrieve messages, and also react to

+message store events using the Qt Mobility Messaging API.

+

+\section1 Namespace

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+\l{Versit API (technology preview)}{Versit API Documentation}

+\section1 Namespace

+

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+ \row

+ \o \l{GConf Layer}

+ \o The GConf Layer provides a permanent Value Space backing store using the

+ GConf configuration system designed for the GNOME desktop environment.

+ The GConf Layer has an order of 0 and it's the only available layer in Maemo 5.

+\section2 GConf Layer

+

+Publish and Subscribe API can be used to access the GConf configuration system.

+

+\section3 Limitations

+

+GConf can natively store only a limited set of QVariant data types. These types are Bool, Int, Double,

+String, StringList and List. When publishing other data types the values are automatically serialized

+and stored to GConf as BASE64 encoded strings. When reading these values they are automatically

+converted back to the original data types. The serialization/deserialization is transparent operation

+to the API user but may cause interoperatibility issues with native applications that access the same

+data directly.

+

+\section1 Namespace

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+

+

+\snippet snippets/sensors/creating.cpp Creating a sensor

+\snippet snippets/sensors/start.cpp Starting a sensor

+The Sensors API has a front end, for application developers to use and a back end,

+developer you do not need to access the back end though it may be useful to understand

+More information about the back end can be found in \l{Sensors Backend}.

+it may even talk to another sensor.

+\snippet snippets/sensors/plugin.cpp Plugin

+\section1 Namespace

+

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+

+Its disdvantage is that client and service must share the implementation of the service object via a library

+they link against or via a common header file. Note that such sharing breaks the fundamental ServiceFramework

+principle of separating clients from service as changes of the service type may require changes to both, services and clients.

+\section1 Namespace

+

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+

+\section1 Examples

+\section2 System Information Example

+The \l{sysinfo}{System Information} example demonstrates how an application can very easily access the system information of the device.

+ //qDebug() << "update metadata" << player->metaData(QtMediaServices::Title).toString();

+ .arg(player->metaData(QtMediaServices::AlbumArtist).toString())

+ .arg(player->metaData(QtMediaServices::Title).toString()));

+ QUrl url = player->metaData(QtMediaServices::CoverArtUrlLarge).value<QUrl>();

+#include "qmobilityglobal.h"

+QTM_USE_NAMESPACE

+

+static void loadDefault();

+static void queryManagerCapabilities();

+static void contactDetailManipulation();

+static void contactManipulation();

+int stopCompilerWarnings()

+ // more doc snippet examples

+ loadDefault();

+ queryManagerCapabilities();

+ contactDetailManipulation();

+ contactManipulation();

+

+ // async doc snippet examples

+ AsyncRequestExample example;

+ QTimer::singleShot(10, &example, SLOT(performRequests()));

+

+

+void loadDefault()

+{

+//! [Loading the default manager for the platform]

+ QContactManager stackDefaultContactManager;

+//! [Loading the default manager for the platform]

+

+//! [Loading the default manager for the platform on heap]

+ QContactManager *heapDefaultContactManager = new QContactManager;

+ // ... perform contact manipulation

+ delete heapDefaultContactManager;

+//! [Loading the default manager for the platform on heap]

+}

+

+void queryManagerCapabilities()

+{

+//! [Querying a manager for capabilities]

+ QContactManager cm;

+ qDebug() << "The default manager for the platform is:" << cm.managerName();

+ qDebug() << "It" << (cm.isRelationshipTypeSupported(QContactRelationship::HasAssistant) ? "supports" : "does not support") << "assistant relationships.";

+ qDebug() << "It" << (cm.supportedContactTypes().contains(QContactType::TypeGroup) ? "supports" : "does not support") << "groups.";

+ qDebug() << "It" << (cm.hasFeature(QContactManager::MutableDefinitions) ? "supports" : "does not support") << "mutable detail definitions.";

+//! [Querying a manager for capabilities]

+}

+

+void contactDetailManipulation()

+{

+//! [Adding a detail to a contact]

+ QContact exampleContact;

+

+ QContactName nameDetail;

+ nameDetail.setFirstName("Adam");

+ nameDetail.setLastName("Unlikely");

+

+ QContactPhoneNumber phoneNumberDetail;

+ phoneNumberDetail.setNumber("+123 4567");

+

+ exampleContact.saveDetail(&nameDetail);

+ exampleContact.saveDetail(&phoneNumberDetail);

+//! [Adding a detail to a contact]

+

+//! [Updating a detail in a contact]

+ phoneNumberDetail.setNumber("+123 9876");

+ exampleContact.saveDetail(&phoneNumberDetail); // overwrites old value on save

+//! [Updating a detail in a contact]

+

+//! [Removing a detail from a contact]

+ exampleContact.removeDetail(&phoneNumberDetail);

+//! [Removing a detail from a contact]

+}

+

+void contactManipulation()

+{

+ QContactManager m_manager("memory");

+//! [Synchronously creating a new contact in a manager]

+ QContact exampleContact;

+

+ QContactName nameDetail;

+ nameDetail.setFirstName("Adam");

+ nameDetail.setLastName("Unlikely");

+

+ QContactPhoneNumber phoneNumberDetail;

+ phoneNumberDetail.setNumber("+123 4567");

+

+ exampleContact.saveDetail(&nameDetail);

+ exampleContact.saveDetail(&phoneNumberDetail);

+

+ // save the newly created contact in the manager

+ if (!m_manager.saveContact(&exampleContact))

+ qDebug() << "Error" << m_manager.error() << "occurred whilst saving contact!";

+//! [Synchronously creating a new contact in a manager]

+

+//! [Synchronously filtering contacts from a manager]

+ QList<QContact> results = m_manager.contacts(QContactPhoneNumber::match("+123 4567"));

+//! [Synchronously filtering contacts from a manager]

+

+//! [Synchronously retrieving an existing contact from a manager]

+ QContact existing = m_manager.contact(exampleContact.localId());

+//! [Synchronously retrieving an existing contact from a manager]

+

+//! [Synchronously updating an existing contact in a manager]

+ phoneNumberDetail.setNumber("+123 9876");

+ exampleContact.saveDetail(&phoneNumberDetail);

+ m_manager.saveContact(&exampleContact);

+//! [Synchronously updating an existing contact in a manager]

+

+//! [Synchronously removing a contact from a manager]

+ m_manager.removeContact(exampleContact.localId());

+//! [Synchronously removing a contact from a manager]

+

+//! [Synchronously creating a new relationship between two contacts]

+ // first, create the group and the group member

+ QContact exampleGroup;

+ exampleGroup.setType(QContactType::TypeGroup);

+ QContactNickname groupName;

+ groupName.setNickname("Example Group");

+ exampleGroup.saveDetail(&groupName);

+

+ QContact exampleGroupMember;

+ QContactName groupMemberName;

+ groupMemberName.setFirstName("Member");

+ exampleGroupMember.saveDetail(&groupMemberName);

+

+ // second, save those contacts in the manager

+ QMap<int, QContactManager::Error> errorMap;

+ QList<QContact> saveList;

+ saveList << exampleGroup << exampleGroupMember;

+ m_manager.saveContacts(&saveList, &errorMap);

+

+ // third, create the relationship between those contacts

+ QContactRelationship groupRelationship;

+ groupRelationship.setFirst(exampleGroup.id());

+ groupRelationship.setRelationshipType(QContactRelationship::HasMember);

+ groupRelationship.setSecond(exampleGroupMember.id());

+

+ // finally, save the relationship in the manager

+ m_manager.saveRelationship(&groupRelationship);

+//! [Synchronously creating a new relationship between two contacts]

+

+//! [Synchronously retrieving relationships between contacts]

+ QList<QContactRelationship> groupRelationships = m_manager.relationships(QContactRelationship::HasMember, exampleGroup.id(), QContactRelationship::First);

+ QList<QContactRelationship> result;

+ for (int i = 0; i < groupRelationships.size(); i++) {

+ if (groupRelationships.at(i).second() == exampleGroupMember.id()) {

+ result.append(groupRelationships.at(i));

+ }

+ }

+//! [Synchronously retrieving relationships between contacts]

+

+//! [Retrieving relationships from cache]

+ exampleGroup = m_manager.contact(exampleGroup.localId()); // refresh the group contact

+ groupRelationships = exampleGroup.relationships(QContactRelationship::HasMember);

+ for (int i = 0; i < groupRelationships.size(); i++) {

+ if (groupRelationships.at(i).second() == exampleGroupMember.id()) {

+ result.append(groupRelationships.at(i));

+ }

+ }

+//! [Retrieving relationships from cache]

+

+//! [Synchronously providing a fetch hint]

+ QContactFetchHint hasMemberRelationshipsOnly;

+ hasMemberRelationshipsOnly.setRelationshipTypesHint(QStringList(QContactRelationship::HasMember));

+

+ // retrieve all contacts, with no specified sort order, requesting that

+ // HasMember relationships be included in the cache of result contacts

+ QList<QContact> allContacts = m_manager.contacts(QContactFilter(), QList<QContactSortOrder>(), hasMemberRelationshipsOnly);

+//! [Synchronously providing a fetch hint]

+

+//! [Synchronously removing a relationship]

+ m_manager.removeRelationship(groupRelationship);

+//! [Synchronously removing a relationship]

+

+//! [Synchronously querying the schema supported by a manager]

+ QMap<QString, QContactDetailDefinition> definitions = m_manager.detailDefinitions();

+ qDebug() << "This manager"

+ << (definitions.value(QContactName::DefinitionName).fields().contains(QContactName::FieldCustomLabel) ? "supports" : "does not support")

+ << "the custom label field of QContactName";

+//! [Synchronously querying the schema supported by a manager]

+

+//! [Synchronously modifying the schema supported by a manager]

+ // modify the name definition, adding a patronym field

+ QContactDetailDefinition nameDefinition = definitions.value(QContactName::DefinitionName);

+ QContactDetailFieldDefinition fieldPatronym;

+ fieldPatronym.setDataType(QVariant::String);

+ nameDefinition.insertField("Patronym", fieldPatronym);

+

+ // save the updated definition in the manager if supported...

+ if (m_manager.hasFeature(QContactManager::MutableDefinitions)) {

+ m_manager.saveDetailDefinition(nameDefinition, QContactType::TypeContact);

+ }

+//! [Synchronously modifying the schema supported by a manager]

+}

+

+ QMap<QString, QContactDetailFieldDefinition> fields = currentDefinition.fields();

+ QContactDetailFieldDefinition newField;

+ QMap<QString, QContactDetailFieldDefinition> fields = modified.fields();

+void displayLabel()

+{

+ QContactManager *manager = new QContactManager();

+ QContactLocalId myId;

+//! [Updating the display label of a contact]

+ /* Retrieve a contact */

+ QContact c = manager->contact(myId);

+ qDebug() << "Current display label" << c.displayLabel();

+

+ /* Update some fields that might influence the display label */

+ QContactName name = c.detail<QContactName>();

+ name.setFirstName("Abigail");

+ name.setLastName("Arkansas");

+ c.saveDetail(&name);

+

+ /* Update the display label */

+ manager->synthesizeContactDisplayLabel(&c);

+ qDebug() << "Now the label is:" << c.displayLabel();

+//! [Updating the display label of a contact]

+}

+

+ connect(m_fetchRequest, SIGNAL(resultsAvailable()), this, SLOT(printContacts()));

+ connect(m_fetchRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)),

+ this, SLOT(stateChanged(QContactAbstractRequest::State)));

+void RequestExample::printContacts()

+ QList<QContact> results = m_fetchRequest->contacts();

+ for (m_previousLastIndex = 0; m_previousLastIndex < results.size(); ++m_previousLastIndex) {

+ qDebug() << "Found an Alice:" << results.at(m_previousLastIndex).displayLabel();

+}

+void RequestExample::stateChanged(QContactAbstractRequest::State state)

+{

+ if (state == QContactAbstractRequest::FinishedState

+ || state == QContactAbstractRequest::CanceledState) {

+

+void shortsnippets()

+ QContact contact;

+ QContact groupContact;

+ {

+ //! [0]

+ QContactDetail detail = contact.detail(QContactName::DefinitionName);

+ //! [0]

+ //! [1]

+ QContactName name = contact.detail<QContactName>();

+ //! [1]

+ //! [2]

+ QList<QContactDetail> details = contact.details(QContactPhoneNumber::DefinitionName);

+ //! [2]

+ //! [3]

+ QList<QContactPhoneNumber> phoneNumbers = contact.details<QContactPhoneNumber>();

+ //! [3]

+ //! [4]

+ QList<QContactPhoneNumber> homePhones = contact.details<QContactPhoneNumber>("Context", "Home");

+ //! [4]

+ //! [5]

+ QList<QContactRelationship> spouseRelationships = contact.relationships(QContactRelationship::HasSpouse);

+ // For each relationship in spouseRelationships, contact.id() will either be first() or second()

+ //! [5]

+ //! [6]

+ // Who are the members of a group contact?

+ QList<QContactId> groupMembers = groupContact.relatedContacts(QContactRelationship::HasMember, QContactRelationship::Second);

+ // What groups is this contact in?

+ QList<QContactId> contactGroups = contact.relatedContacts(QContactRelationship::HasMember, QContactRelationship::First);

+ // An alternative to QContact::relationships()

+ QList<QContactId> spouses = contact.relatedContacts(QContactRelationship::HasSpouse, QContactRelationship::Either);

+ if (spouses.count() > 1) {

+ // Custom relationship type

+ QList<QContactId> therapists = contact.relatedContacts("HasTherapist", QContactRelationship::Second);

+ }

+ //! [6]

+

+void loadManager()

+{

+//! [Loading a specific manager backend]

+ QContactManager contactManager("KABC");

+}

+//! [Loading a specific manager backend with parameters]

+ QContactManager contactManager("KABC", parameters);

+}

+TEMPLATE = lib

+INCLUDEPATH += ../../../../src/global \

+ ../../../../src/contacts \

+ ../../../../src/contacts/requests \

+ ../../../../src/contacts/filters \

+ ../../../../src/contacts/details

+DESTDIR = $$QT_MOBILITY_BUILD_TREE/lib

+CONFIG += mobility console

+SOURCES += qtcontactsdocsample.cpp qtcontactsdocsampleasync.cpp

+

+symbian {

+ TARGET.EPOCALLOWDLLDATA = 1

+}

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+#include "qmobilityglobal.h"

+#include "qtcontacts.h"

+#include "requestexample.h"

+

+#include <QDebug>

+#include <QCoreApplication>

+#include <QObject>

+#include <QTimer>

+

+QTM_USE_NAMESPACE

+

+AsyncRequestExample::AsyncRequestExample()

+ : QObject()

+{

+ m_manager = new QContactManager("memory");

+}

+

+AsyncRequestExample::~AsyncRequestExample()

+{

+ delete m_manager;

+}

+

+//! [Example of an asynchronous request slot]

+void AsyncRequestExample::contactFetchRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState) {

+ QContactFetchRequest *request = qobject_cast<QContactFetchRequest*>(QObject::sender());

+ if (request->error() != QContactManager::NoError) {

+ qDebug() << "Error" << request->error() << "occurred during fetch request!";

+ return;

+ }

+

+ QList<QContact> results = request->contacts();

+ for (int i = 0; i < results.size(); i++) {

+ qDebug() << "Retrieved contact:" << results.at(i).displayLabel();

+ }

+ } else if (newState == QContactAbstractRequest::CanceledState) {

+ qDebug() << "Fetch operation canceled!";

+ }

+}

+//! [Example of an asynchronous request slot]

+

+void AsyncRequestExample::contactSaveRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState)

+ qDebug() << "Finished saving the contacts!";

+ else if (newState == QContactAbstractRequest::CanceledState)

+ qDebug() << "Save operation canceled!";

+}

+

+void AsyncRequestExample::contactRemoveRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState)

+ qDebug() << "Finished removing the contacts!";

+ else if (newState == QContactAbstractRequest::CanceledState)

+ qDebug() << "Remove operation canceled!";

+}

+

+void AsyncRequestExample::relationshipFetchRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState)

+ qDebug() << "Finished fetching the contacts!";

+ else if (newState == QContactAbstractRequest::CanceledState)

+ qDebug() << "Fetch operation canceled!";

+}

+

+void AsyncRequestExample::relationshipSaveRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState)

+ qDebug() << "Finished saving the contacts!";

+ else if (newState == QContactAbstractRequest::CanceledState)

+ qDebug() << "Save operation canceled!";

+}

+

+void AsyncRequestExample::relationshipRemoveRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState)

+ qDebug() << "Finished removing the contacts!";

+ else if (newState == QContactAbstractRequest::CanceledState)

+ qDebug() << "Remove operation canceled!";

+}

+

+void AsyncRequestExample::definitionFetchRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState)

+ qDebug() << "Finished fetching the contacts!";

+ else if (newState == QContactAbstractRequest::CanceledState)

+ qDebug() << "Fetch operation canceled!";

+}

+

+void AsyncRequestExample::definitionSaveRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState)

+ qDebug() << "Finished saving the contacts!";

+ else if (newState == QContactAbstractRequest::CanceledState)

+ qDebug() << "Save operation canceled!";

+}

+

+void AsyncRequestExample::definitionRemoveRequestStateChanged(QContactAbstractRequest::State newState)

+{

+ if (newState == QContactAbstractRequest::FinishedState)

+ qDebug() << "Finished removing the contacts!";

+ else if (newState == QContactAbstractRequest::CanceledState)

+ qDebug() << "Remove operation canceled!";

+}

+

+void AsyncRequestExample::performRequests()

+{

+//! [Creating a new contact in a manager]

+ QContact exampleContact;

+

+ QContactName nameDetail;

+ nameDetail.setFirstName("Adam");

+ nameDetail.setLastName("Unlikely");

+

+ QContactPhoneNumber phoneNumberDetail;

+ phoneNumberDetail.setNumber("+123 4567");

+

+ exampleContact.saveDetail(&nameDetail);

+ exampleContact.saveDetail(&phoneNumberDetail);

+

+ // save the newly created contact in the manager

+ connect(&m_contactSaveRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(contactSaveRequestStateChanged(QContactAbstractRequest::State)));

+ m_contactSaveRequest.setManager(m_manager);

+ m_contactSaveRequest.setContacts(QList<QContact>() << exampleContact);

+ m_contactSaveRequest.start();

+//! [Creating a new contact in a manager]

+

+ m_contactSaveRequest.waitForFinished();

+

+//! [Creating a new contact in a manager waiting until finished]

+ m_contactSaveRequest.setManager(m_manager);

+ m_contactSaveRequest.setContacts(QList<QContact>() << exampleContact);

+ m_contactSaveRequest.start();

+ m_contactSaveRequest.waitForFinished();

+ QList<QContact> savedContacts = m_contactSaveRequest.contacts();

+//! [Creating a new contact in a manager waiting until finished]

+

+//! [Filtering contacts from a manager]

+ connect(&m_contactFetchRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(contactFetchRequestStateChanged(QContactAbstractRequest::State)));

+ m_contactFetchRequest.setManager(m_manager);

+ m_contactFetchRequest.setFilter(QContactPhoneNumber::match("+123 4567"));

+ m_contactFetchRequest.start();

+//! [Filtering contacts from a manager]

+

+ m_contactFetchRequest.waitForFinished();

+

+//! [Retrieving an existing contact from a manager]

+ QContactLocalIdFilter idListFilter;

+ idListFilter.setIds(QList<QContactLocalId>() << exampleContact.localId());

+ m_contactFetchRequest.setManager(m_manager);

+ m_contactFetchRequest.setFilter(idListFilter);

+ m_contactFetchRequest.start();

+//! [Retrieving an existing contact from a manager]

+

+ m_contactFetchRequest.waitForFinished();

+

+//! [Updating an existing contact in a manager]

+ phoneNumberDetail.setNumber("+123 9876");

+ exampleContact.saveDetail(&phoneNumberDetail);

+ m_contactSaveRequest.setManager(m_manager);

+ m_contactSaveRequest.setContacts(QList<QContact>() << exampleContact);

+ m_contactSaveRequest.start();

+//! [Updating an existing contact in a manager]

+

+ m_contactFetchRequest.waitForFinished();

+

+//! [Removing a contact from a manager]

+ connect(&m_contactRemoveRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(contactRemoveRequestStateChanged(QContactAbstractRequest::State)));

+ m_contactRemoveRequest.setManager(m_manager);

+ m_contactRemoveRequest.setContactIds(QList<QContactLocalId>() << exampleContact.localId());

+ m_contactRemoveRequest.start();

+//! [Removing a contact from a manager]

+

+ m_contactFetchRequest.waitForFinished();

+

+//! [Creating a new relationship between two contacts]

+ // first, create the group and the group member

+ QContact exampleGroup;

+ exampleGroup.setType(QContactType::TypeGroup);

+ QContactNickname groupName;

+ groupName.setNickname("Example Group");

+ exampleGroup.saveDetail(&groupName);

+

+ QContact exampleGroupMember;

+ QContactName groupMemberName;

+ groupMemberName.setFirstName("Member");

+ exampleGroupMember.saveDetail(&groupMemberName);

+

+ // second, save those contacts in the manager

+ QList<QContact> saveList;

+ saveList << exampleGroup << exampleGroupMember;

+ m_contactSaveRequest.setContacts(saveList);

+ m_contactSaveRequest.start();

+ m_contactSaveRequest.waitForFinished();

+

+ // third, create the relationship between those contacts

+ QContactRelationship groupRelationship;

+ groupRelationship.setFirst(exampleGroup.id());

+ groupRelationship.setRelationshipType(QContactRelationship::HasMember);

+ groupRelationship.setSecond(exampleGroupMember.id());

+

+ // finally, save the relationship in the manager

+ connect(&m_relationshipSaveRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(relationshipSaveRequestStateChanged(QContactAbstractRequest::State)));

+ m_relationshipSaveRequest.setManager(m_manager);

+ m_relationshipSaveRequest.setRelationships(QList<QContactRelationship>() << groupRelationship);

+ m_relationshipSaveRequest.start();

+//! [Creating a new relationship between two contacts]

+

+ m_contactFetchRequest.waitForFinished();

+

+//! [Retrieving relationships between contacts]

+ connect(&m_relationshipFetchRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(relationshipFetchRequestStateChanged(QContactAbstractRequest::State)));

+ m_relationshipFetchRequest.setManager(m_manager);

+ // retrieve the list of relationships between the example group contact and the example member contact

+ // where the group contact is the first contact in the relationship, and the member contact is the

+ // second contact in the relationship. In order to fetch all relationships between them, another

+ // relationship fetch must be performed with their roles reversed, and the results added together.

+ m_relationshipFetchRequest.setFirst(exampleGroup.id());

+ m_relationshipFetchRequest.setSecond(exampleGroupMember.id());

+ m_relationshipFetchRequest.start();

+//! [Retrieving relationships between contacts]

+

+ m_contactFetchRequest.waitForFinished();

+

+//! [Providing a fetch hint]

+ QContactFetchHint hasMemberRelationshipsOnly;

+ hasMemberRelationshipsOnly.setRelationshipTypesHint(QStringList(QContactRelationship::HasMember));

+

+ m_contactFetchRequest.setManager(m_manager);

+ m_contactFetchRequest.setFilter(QContactFilter()); // all contacts

+ m_contactFetchRequest.setFetchHint(hasMemberRelationshipsOnly);

+ m_contactFetchRequest.start();

+//! [Providing a fetch hint]

+

+//! [Removing a relationship]

+ connect(&m_relationshipRemoveRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(relationshipRemoveRequestStateChanged(QContactAbstractRequest::State)));

+ m_relationshipRemoveRequest.setManager(m_manager);

+ m_relationshipRemoveRequest.setRelationships(QList<QContactRelationship>() << groupRelationship);

+ m_relationshipRemoveRequest.start();

+//! [Removing a relationship]

+

+ connect(&m_definitionFetchRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(definitionFetchRequestStateChanged(QContactAbstractRequest::State)));

+//! [Querying the schema supported by a manager]

+ m_definitionFetchRequest.setManager(m_manager);

+ m_definitionFetchRequest.setDefinitionNames(QStringList(QContactName::DefinitionName));

+ m_definitionFetchRequest.start();

+ m_definitionFetchRequest.waitForFinished();

+ QMap<QString, QContactDetailDefinition> definitions = m_definitionFetchRequest.definitions();

+ qDebug() << "This manager"

+ << (definitions.value(QContactName::DefinitionName).fields().contains(QContactName::FieldCustomLabel) ? "supports" : "does not support")

+ << "the custom label field of QContactName";

+//! [Querying the schema supported by a manager]

+

+ connect(&m_definitionSaveRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(definitionSaveRequestStateChanged(QContactAbstractRequest::State)));

+ connect(&m_definitionRemoveRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)), this, SLOT(definitionRemoveRequestStateChanged(QContactAbstractRequest::State)));

+//! [Modifying the schema supported by a manager]

+ // modify the name definition, adding a patronym field

+ QContactDetailDefinition nameDefinition = definitions.value(QContactName::DefinitionName);

+ QContactDetailFieldDefinition fieldPatronym;

+ fieldPatronym.setDataType(QVariant::String);

+ nameDefinition.insertField("Patronym", fieldPatronym);

+

+ // save the updated definition in the manager if supported...

+ if (m_manager->hasFeature(QContactManager::MutableDefinitions)) {

+ m_definitionSaveRequest.setManager(m_manager);

+ m_definitionSaveRequest.setContactType(QContactType::TypeContact);

+ m_definitionSaveRequest.setDefinitions(QList<QContactDetailDefinition>() << nameDefinition);

+ m_definitionSaveRequest.start();

+ }

+//! [Modifying the schema supported by a manager]

+

+ QCoreApplication::exit(0);

+}

+#include "qmobilityglobal.h"

+#include "qcontactrequests.h"

+//! [Class setup]

+class AsyncRequestExample : public QObject

+{

+ Q_OBJECT

+

+public:

+ AsyncRequestExample();

+ ~AsyncRequestExample();

+

+public slots:

+ void performRequests();

+

+private slots:

+ void contactFetchRequestStateChanged(QContactAbstractRequest::State newState);

+ void contactSaveRequestStateChanged(QContactAbstractRequest::State newState);

+ void contactRemoveRequestStateChanged(QContactAbstractRequest::State newState);

+ void relationshipFetchRequestStateChanged(QContactAbstractRequest::State newState);

+ void relationshipSaveRequestStateChanged(QContactAbstractRequest::State newState);

+ void relationshipRemoveRequestStateChanged(QContactAbstractRequest::State newState);

+ void definitionFetchRequestStateChanged(QContactAbstractRequest::State newState);

+ void definitionSaveRequestStateChanged(QContactAbstractRequest::State newState);

+ void definitionRemoveRequestStateChanged(QContactAbstractRequest::State newState);

+

+private:

+ QContactManager *m_manager;

+ QContactFetchRequest m_contactFetchRequest;

+ QContactSaveRequest m_contactSaveRequest;

+ QContactRemoveRequest m_contactRemoveRequest;

+ QContactRelationshipFetchRequest m_relationshipFetchRequest;

+ QContactRelationshipSaveRequest m_relationshipSaveRequest;

+ QContactRelationshipRemoveRequest m_relationshipRemoveRequest;

+ QContactDetailDefinitionFetchRequest m_definitionFetchRequest;

+ QContactDetailDefinitionSaveRequest m_definitionSaveRequest;

+ QContactDetailDefinitionRemoveRequest m_definitionRemoveRequest;

+};

+//! [Class setup]

+ void printContacts();

+ void stateChanged(QContactAbstractRequest::State state);

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+#include "qmobilityglobal.h"

+#include "qtcontacts.h"

+#include "qcontacttag.h"

+#include "qversitreader.h"

+#include "qversitcontactimporter.h"

+#include "qversitwriter.h"

+#include "qversitcontactexporter.h"

+#include "qversitdocument.h"

+#include "qversitproperty.h"

+#include "qversitresourcehandler.h"

+#include <QCoreApplication>

+#include <QBuffer>

+#include <QList>

+#include <QFile>

+

+QTM_USE_NAMESPACE

+

+void completeExample();

+void exportExample();

+void importExample();

+

+//! [Detail handler]

+class MyDetailHandler : public QVersitContactExporterDetailHandler {

+public:

+ bool preProcessDetail(const QContact& contact, const QContactDetail& detail,

+ QVersitDocument* document) {

+ Q_UNUSED(contact) Q_UNUSED(detail) Q_UNUSED(document)

+ return false;

+ }

+ bool postProcessDetail(const QContact& contact, const QContactDetail& detail,

+ bool alreadyProcessed, QVersitDocument* document) {

+ Q_UNUSED(contact) Q_UNUSED(document)

+ if (!alreadyProcessed)

+ mUnknownDetails.append(detail);

+ return false;

+ }

+ QList<QContactDetail> mUnknownDetails;

+};

+//! [Detail handler]

+

+//! [Property handler]

+class MyPropertyHandler : public QVersitContactImporterPropertyHandler {

+public:

+ bool preProcessProperty(const QVersitDocument& document, const QVersitProperty& property,

+ int contactIndex, QContact* contact) {

+ Q_UNUSED(document) Q_UNUSED(property) Q_UNUSED(contactIndex) Q_UNUSED(contact)

+ return false;

+ }

+ bool postProcessProperty(const QVersitDocument& document, const QVersitProperty& property,

+ bool alreadyProcessed, int contactIndex, QContact* contact) {

+ Q_UNUSED(document) Q_UNUSED(contactIndex) Q_UNUSED(contact)

+ if (!alreadyProcessed)

+ mUnknownProperties.append(property);

+ return false;

+ }

+ QList<QVersitProperty> mUnknownProperties;

+};

+//! [Property handler]

+

+//! [Resource handler]

+class MyResourceHandler : public QVersitDefaultResourceHandler {

+public:

+ bool saveResource(const QByteArray& contents, const QVersitProperty& property,

+ QString* location) {

+ Q_UNUSED(property)

+ *location = QString::number(qrand());

+ QFile file(*location);

+ file.open(QIODevice::WriteOnly);

+ file.write(contents); // In a real implementation, consider when this file will be deleted.

+ return true;

+ }

+ bool loadResource(const QString& location, QByteArray* contents, QString* mimeType)

+ {

+ return QVersitDefaultResourceHandler::loadResource(location, contents, mimeType);

+ }

+};

+//! [Resource handler]

+

+#if 0

+int main(int argc, char *argv[])

+{

+ Q_UNUSED(argc)

+ Q_UNUSED(argv)

+ completeExample();

+ exportExample();

+ importExample();

+}

+#endif

+

+void completeExample()

+{

+ //! [Complete example]

+ // Create the input vCard

+ QBuffer input;

+ input.open(QBuffer::ReadWrite);

+ QByteArray inputVCard =

+ "BEGIN:VCARD\r\nVERSION:2.1\r\nFN:John Citizen\r\nN:Citizen;John;Q;;\r\nEND:VCARD\r\n";

+ input.write(inputVCard);

+ input.seek(0);

+

+ // Parse the input into QVersitDocuments

+ // Note: we could also use the more convenient QVersitReader(QByteArray) constructor.

+ QVersitReader reader;

+ reader.setDevice(&input);

+ reader.startReading(); // Remember to check the return value

+ reader.waitForFinished();

+

+ // Convert the QVersitDocuments to QContacts

+ QList<QVersitDocument> inputDocuments = reader.results();

+ QVersitContactImporter importer;

+ if (!importer.importDocuments(inputDocuments))

+ return;

+ QList<QContact> contacts = importer.contacts();

+ // Note that the QContacts are not saved yet.

+ // Use QContactManager::saveContacts() for saving if necessary

+

+ // Export the QContacts back to QVersitDocuments

+ QVersitContactExporter exporter;

+ if (!exporter.exportContacts(contacts, QVersitDocument::VCard30Type))

+ return;

+ QList<QVersitDocument> outputDocuments = exporter.documents();

+

+ // Encode the QVersitDocument back to a vCard

+ // Note: we could also use the more convenient QVersitWriter(QByteArray*) constructor.

+ QBuffer output;

+ output.open(QBuffer::ReadWrite);

+ QVersitWriter writer;

+ writer.setDevice(&output);

+ writer.startWriting(outputDocuments); // Remember to check the return value

+ writer.waitForFinished();

+

+ // Read the vCard back to a QByteArray

+ output.seek(0);

+ QByteArray outputVCard(output.readAll());

+ //! [Complete example]

+}

+

+void exportExample()

+{

+ //! [Export example]

+ QVersitContactExporter contactExporter;

+

+ MyDetailHandler detailHandler;

+ contactExporter.setDetailHandler(&detailHandler);

+

+ QContact contact;

+ // Create a name

+ QContactName name;

+ name.setFirstName(QString::fromAscii("John"));

+ contact.saveDetail(&name);

+

+ if (!contactExporter.exportContacts(QList<QContact>() << contact, QVersitDocument::VCard30Type))

+ return;

+ QList<QVersitDocument> versitDocuments = contactExporter.documents();

+

+ // detailHandler.mUnknownDetails now contains the list of unknown details

+ //! [Export example]

+}

+

+void importExample()

+{

+ //! [Import example]

+ QVersitContactImporter importer;

+

+ MyPropertyHandler propertyHandler;

+ importer.setPropertyHandler(&propertyHandler);

+

+ QVersitDocument document;

+

+ QVersitProperty property;

+ property.setName(QString::fromAscii("N"));

+ property.setValue("Citizen;John;Q;;");

+ document.addProperty(property);

+

+ property.setName(QString::fromAscii("X-UNKNOWN-PROPERTY"));

+ property.setValue("some value");

+ document.addProperty(property);

+

+ if (importer.importDocuments(QList<QVersitDocument>() << document)) {

+ QList<QContact> contactList = importer.contacts();

+ // contactList.first() now contains the "N" property as a QContactName

+ // propertyHandler.mUnknownProperties contains the list of unknown properties

+ }

+ //! [Import example]

+}

+

+//! [Import relationship example]

+/*! Adds contacts in \a newContacts into \a manager, converting categories specified

+ with tags into group membership relationships. Note that this implementation uses the

+ synchronous API of QContactManager for clarity. It is recommended that the asynchronous

+ API is used in practice.

+

+ Relationships are added so that if a contact, A, has a tag "b", then a HasMember relationship is

+ created between a group contact in the manager, B with display label "b", and contact A. If there

+ does not exist a group contact with display label "b", one is created.

+ */

+void insertWithGroups(const QList<QContact>& newContacts, QContactManager* manager)

+{

+ // Cache map from group names to QContactIds

+ QMap<QString, QContactId> groupMap;

+

+ foreach (QContact contact, newContacts) {

+ if (!manager->saveContact(&contact))

+ continue; // In practice, better error handling may be required

+ foreach (const QContactTag& tag, contact.details<QContactTag>()) {

+ QString groupName = tag.tag();

+ QContactId groupId;

+ if (groupMap.contains(groupName)) {

+ // We've already seen a group with the right name

+ groupId = groupMap.value(groupName);

+ } else {

+ QContactDetailFilter groupFilter;

+ groupFilter.setDetailDefinitionName(QContactType::DefinitionName);

+ groupFilter.setValue(QLatin1String(QContactType::TypeGroup));

+ groupFilter.setMatchFlags(QContactFilter::MatchExactly);

+ // In practice, some detail other than the display label could be used

+ QContactDetailFilter nameFilter = QContactDisplayLabel::match(groupName);

+ QList<QContactLocalId> matchingGroups = manager->contactIds(groupFilter & nameFilter);

+ if (!matchingGroups.isEmpty()) {

+ // Found an existing group in the manager

+ QContactId groupId;

+ groupId.setManagerUri(manager->managerUri());

+ groupId.setLocalId(matchingGroups.first());

+ groupMap.insert(groupName, groupId);

+ }

+ else {

+ // Make a new group

+ QContact groupContact;

+ QContactName name;

+ name.setCustomLabel(groupName);

+ // Beware that not all managers support custom label

+ groupContact.saveDetail(&name);

+ if (!manager->saveContact(&groupContact))

+ continue; // In practice, better error handling may be required

+ groupId = groupContact.id();

+ groupMap.insert(groupName, groupId);

+ }

+ }

+ // Add the relationship

+ QContactRelationship rel;

+ rel.setFirst(groupId);

+ rel.setRelationshipType(QContactRelationship::HasMember);

+ rel.setSecond(contact.id());

+ manager->saveRelationship(&rel);

+ }

+ }

+}

+//! [Import relationship example]

+

+//! [Export relationship example]

+/*! Adds QContactTag details to the \a contacts, based on the \a relationships.

+

+ Tags are created such that if a group contact, B with display label "b", has a HasMember

+ relationship with a contact, A, then a QContactTag, "b", is added to A.

+

+ Group contacts can be passed in with the \a contacts list. If a contact is part of a group which

+ is not in \a contacts, the \a manager is queried to find them.

+ */

+void createTagsFromGroups(QList<QContact>* contacts,

+ const QList<QContactRelationship>& relationships,

+ const QContactManager* manager)

+{

+ // Map from QContactIds to group names

+ QMap<QContactId, QString> groupMap;

+

+ // Map from QContactIds to indices into the contacts list

+ QMap<QContactId, int> indexMap;

+ // Build up groupMap and indexMap

+ for (int i = 0; i < contacts->size(); ++i) {

+ QContact contact = contacts->at(i);

+ if (contact.type() == QContactType::TypeGroup) {

+ // In practice, you may want to check that there aren't two distinct groups with the

+ // same name, and you may want to use a field other than display label.

+ groupMap.insert(contact.id(), contact.displayLabel());

+ }

+ indexMap.insert(contact.id(), i);

+ }

+

+ // Now add all the tags specified by the group relationships

+ foreach (const QContactRelationship& rel, relationships) {

+ if (rel.relationshipType() == QContactRelationship::HasMember

+ && indexMap.contains(rel.second())) {

+ QString groupName = groupMap.value(rel.first()); // Have we seen the group before?

+ if (groupName.isEmpty()) {

+ // Try and find the group in the manager

+ QContactId groupId = rel.second();

+ QContactFetchHint fetchHint;

+ fetchHint.setDetailDefinitionsHint(QStringList(QContactDisplayLabel::DefinitionName));

+ QContact contact = manager->contact(groupId.localId(), fetchHint);

+ if (!contact.isEmpty()) {

+ groupName = contact.displayLabel();

+ groupMap.insert(groupId, groupName); // Cache the group id/name

+ }

+ }

+ if (!groupName.isEmpty()) {

+ // Add the tag

+ QContactTag tag;

+ tag.setTag(groupName);

+ (*contacts)[indexMap.value(rel.second())].saveDetail(&tag);

+ }

+ }

+ }

+}

+//! [Export relationship example]

+######################################################################

+#

+# Simple example of how to use the versit API

+#

+######################################################################

+

+TEMPLATE = lib

+TARGET = qtversitdocsample

+include(../../../../common.pri)

+INCLUDEPATH += ../../../../src/global \

+ ../../../../src/contacts \

+ ../../../../src/contacts/requests \

+ ../../../../src/contacts/filters \

+ ../../../../src/contacts/details \

+ ../../../../src/versit

+

+DESTDIR = $$QT_MOBILITY_BUILD_TREE/lib

+QMAKE_RPATHDIR+=$$OUTPUT_DIR/lib

+

+CONFIG += mobility console

+MOBILITY = contacts versit

+

+SOURCES += qtversitdocsample.cpp

+

+symbian {

+ TARGET.EPOCALLOWDLLDATA = 1

+}

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+#include <QWidget>

+#include <qaccelerometer.h>

+#include <qorientationsensor.h>

+

+QTM_USE_NAMESPACE

+

+class MyWidget : public QWidget

+{

+ void create();

+};

+

+void MyWidget::create()

+{

+//! [Creating a sensor]

+// On the heap (deleted when this object is deleted)

+QAccelerometer *sensor = new QAccelerometer(this);

+

+// On the stack (deleted when the current scope ends)

+QOrientationSensor orient_sensor;

+//! [Creating a sensor]

+

+ Q_UNUSED(sensor)

+ Q_UNUSED(orient_sensor);

+}

+

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+int main(int /*argc*/, char ** /*argv*/)

+{

+ return 0;

+}

+

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+#ifndef MYBACKEND_H

+#define MYBACKEND_H

+

+#include <qaccelerometer.h>

+#include <qsensorbackend.h>

+

+QTM_USE_NAMESPACE

+

+class MyBackend : public QSensorBackend

+{

+public:

+ MyBackend(QSensor *sensor) : QSensorBackend(sensor) {}

+ void stop() {}

+ void start() {}

+ void poll() {}

+

+ static const char *id;

+};

+

+#endif

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+#include "mybackend.h"

+#include <qsensorplugin.h>

+#include <qsensormanager.h>

+

+const char *MyBackend::id = "mybackend";

+

+//! [Plugin]

+class MyPluginClass : public QObject, QSensorPluginInterface, public QSensorBackendFactory

+{

+ Q_OBJECT

+ Q_INTERFACES(QtMobility::QSensorPluginInterface)

+public:

+ void registerSensors()

+ {

+ QSensorManager::registerBackend(QAccelerometer::type, MyBackend::id, this);

+ }

+

+ QSensorBackend *createBackend(QSensor *sensor)

+ {

+ if (sensor->identifier() == MyBackend::id)

+ return new MyBackend(sensor);

+ return 0;

+ }

+};

+//! [Plugin]

+

+//Q_EXPORT_PLUGIN2(libmy_plugin_file_name, MyPluginClass);

+#include "plugin.moc"

+TEMPLATE=app

+TARGET=sensors

+include(../../../../common.pri)

+INCLUDEPATH += ../../../../src/sensors

+SOURCES+=main.cpp\

+ creating.cpp\

+ start.cpp\

+ plugin.cpp

+HEADERS+=mybackend.h

+LIBS+=-rdynamic

+CONFIG+=mobility

+MOBILITY+=sensors

+CONFIG+=strict_flags

+/****************************************************************************

+**

+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

+** All rights reserved.

+** Contact: Nokia Corporation (qt-info@nokia.com)

+**

+** This file is part of the Qt Mobility Components.

+**

+** $QT_BEGIN_LICENSE:LGPL$

+** No Commercial Usage

+** This file contains pre-release code and may not be distributed.

+** You may use this file in accordance with the terms and conditions

+** contained in the Technology Preview License Agreement accompanying

+** this package.

+**

+** GNU Lesser General Public License Usage

+** Alternatively, this file may be used under the terms of the GNU Lesser

+** General Public License version 2.1 as published by the Free Software

+** Foundation and appearing in the file LICENSE.LGPL included in the

+** packaging of this file. Please review the following information to

+** ensure the GNU Lesser General Public License version 2.1 requirements

+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

+**

+** In addition, as a special exception, Nokia gives you certain additional

+** rights. These rights are described in the Nokia Qt LGPL Exception

+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

+**

+** If you have questions regarding the use of this file, please contact

+** Nokia at qt-info@nokia.com.

+**

+**

+**

+**

+**

+**

+**

+**

+** $QT_END_LICENSE$

+**

+****************************************************************************/

+

+#include <qsensor.h>

+

+QTM_USE_NAMESPACE

+

+void start()

+{

+//! [Starting a sensor]

+// start the sensor

+QSensor sensor("QAccelerometer");

+sensor.start();

+

+// later

+QSensorReading *reading = sensor.reading();

+qreal x = reading->property("x").value<qreal>();

+qreal y = reading->value(1).value<qreal>();

+//! [Starting a sensor]

+

+ Q_UNUSED(x)

+ Q_UNUSED(y)

+}

+contains(mobility_modules,versit): SUBDIRS += qtversitdocsample

+contains(mobility_modules,sensors): SUBDIRS += sensors

+\section1 Namespace

+

+The QtMobility API's are placed into the \i{QtMobility} namespace. This is done

+to facilitate the future migration of Mobility API's into Qt. See the

+\l {Quickstart Example}{Quickstart guide} for an example on how the

+namespace impacts on application development.

+

+\section1 Overview

+QContacts from Versit documents and export (\l{QVersitContactExporter})

+QContacts to Versit documents.

+\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example

+\snippet ../../src/versit/qversitdefs_p.h Property name mappings

+\snippet ../../src/versit/qversitdefs_p.h Property type parameter mappings