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

+**

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

+** All rights reserved.

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

+**

+** This file is part of the documentation of the Qt Toolkit.

+**

+** $QT_BEGIN_LICENSE:FDL$

+** Commercial Usage

+** Licensees holding valid Qt Commercial licenses may use this file in

+** accordance with the Qt Commercial License Agreement provided with the

+** Software or, alternatively, in accordance with the terms contained in a

+** written agreement between you and Nokia.

+**

+** GNU Free Documentation License

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

+** Documentation License version 1.3 as published by the Free Software

+** Foundation and appearing in the file included in the packaging of this

+** file.

+**

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

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

+** $QT_END_LICENSE$

+**

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

+

+

+

+

+/*!

+

+\page organizer.html

+

+\title Organizer

+\brief An API enabling clients to request calendar, schedule and personal data

+from local or remote backends.

+

+\ingroup mobility

+

+The Organizer API enables a client to request calendar, schedule and personal

+data from local or remote backends. This is part of the Qt Mobility Project.

+

+\tableofcontents

+

+\section1 Introduction

+

+The Organizer API provides clients with the ability to access calendar,

+schedule and personal data in a platform-independent and datastore-agnostic

+manner. This is achieved by defining generic personal information data

+abstractions which can sufficiently describe calendar and scheduling data

+stored on any platform. Due to the cross-platform nature of the API, and the

+ability for developers to write platform-independent implementations of a

+QOrganizerItemManager which may unify one or more platform-specific calendar

+or scheduling backends, it is intended that the semantics and quirks of the

+underlying datastores on any platform may be entirely opaque from the

+perspective of Qt-based, cross-platform client applications.

+

+\section1 Overview

+

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

+to facilitate the future migration of Mobility APIs into Qt. See the

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

+namespace impacts on application development.

+

+Organizer information is stored in datastores whose functionality is exposed

+via a \l{QOrganizerItemManager}{manager}. The Organizer API models organizer

+information as an \l{QOrganizerItem}{item} which consists of a collection of

+distinct details. Each \l{QOrganizerItemDetail}{detail} conforms to a

+particular \l{QOrganizerItemDetailDefinition}{definition} (or template), which

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

+items may be recurrent, and occurrences of such items are also items, but are

+linked to the "parent" item.

+

+\l{QOrganizerItem}{Item} and

+\l{QOrganizerItemDetailDefinition}{detail definition} information may be

+retrieved, modified or deleted by clients using either

+\l{Organizer Synchronous API}{synchronous} or

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

+

+\section1 Client-Facing API

+

+The client-facing API allows retrieval, modification and deletion of organizer

+items and detail definitions, and access to manager meta data and capability

+reporting.

+

+\section2 Container Classes

+

+Organizational data 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{QOrganizerItemManager}{manager}.

+

+\section3 Item

+

+An \l{QOrganizerItem}{item} is the digital representation of an event, journal,

+todo, or note which is stored in a platform-specific manner. Information

+pertaining to a single item may be located across several different datastores.

+

+Each item stored in a manager is identified by an \l{QOrganizerItemId}{id}

+which consists of a manager identifier (URI) and the

+\l{QOrganizerItemLocalId}{manager-local id} which is used to identify the item

+within that manager. Note that an item stored in one manager may have the

+same local id as a different item stored in another manager; please see the

+QOrganizerItemId documentation for more information.

+

+\section3 Detail

+

+A \l{QOrganizerItemDetail}{detail} is a single, cohesive unit of information

+that is stored in an item. Any detail stored in an item which is saved in a

+manager will conform to a particular detail definition which that manager

+supports. A detail may have specific meta-data associated with it, such as

+its sub-type and arbitrary, user-defined meta-data, as well as access

+constraints which may apply to the detail (e.g., 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{"Organizer Item Details" Leaf Classes}{here}.

+

+\section3 Detail Definition

+

+Each detail stored in an item has defined semantics of usage and storage.

+The Qt Organizer API allows per-datastore organizer item

+\l{QOrganizerItemDetailDefinition}{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-item 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{"Organizer Item 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 behavior

+accordingly.

+

+\section2 Manager

+

+Access to organizer items is provided by implementations of the Qt Organizer

+\l{QOrganizerItemManager}{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 and organizer items stored in different

+datastores, in a platform and datastore independent manner.

+

+\section3 Meta Data API

+

+The API offered by the QOrganizerItemManager 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 Qt Organizer API to a different degree.

+

+The QOrganizerItemManager class provides a static function

+QOrganizerItemManager::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 (organizer item manager) are. The

+QOrganizerItemManager class provides API to query the capabilities of a given

+manager with the following synchronous functions:

+\list

+ \o hasFeature(QOrganizerItemManager::ManagerFeature feature, const QString& itemType = QOrganizerItemType::TypeEvent) const

+ \o isFilterSupported(const QOrganizerItemFilter& filter) const

+ \o supportedDataTypes() const

+ \o supportedItemTypes() 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 organizer 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

+organizer item 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

+QOrganizerItemAbstractRequest class, including

+QOrganizerItemLocalIdFetchRequest, QOrganizerItemFetchRequest,

+QOrganizerItemSaveRequest, QOrganizerItemRemoveRequest,

+QOrganizerItemDetailDefinitionFetchRequest,

+QOrganizerItemDetailDefinitionSaveRequest, and

+QOrganizerItemDetailDefinitionRemoveRequest.

+

+The asynchronous API allows manipulation of \l{QOrganizerItem}{items} and

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

+manager capability or meta data information reporting.

+

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

+

+\section3 Synchronous API

+

+The synchronous API provides the simplest way to access or modify the

+organizer item information managed by a particular backend. It has the

+disadvantage that calls block the current thread of execution until completion

+and is therefore most suitable only for applications which interact with

+local, high-speed datastores, or for applications which do not require a

+responsive user interface.

+

+The synchronous API is offered through the QOrganizerItemManager class, and

+includes manipulation of \l{QOrganizerItem}{items} and

+\l{QOrganizerItemDetailDefinition}{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{Organizer 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 QOrganizerItemManager class may be implemented

+by \l{QOrganizerItemManagerEngine}{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 QOrganizerItemManager interface. The plugin

+architecture allows dynamic loading of different manager engines at runtime.

+

+A manager backend may be implemented by subclassing

+\l{QOrganizerItemManagerEngine}, and providing a

+\l{QOrganizerItemManagerEngineFactory} which can instantiate it when required.

+

+See \l{Qt Organizer Manager Engines} for more information on available engines

+and how to write your own engine.

+

+\section1 Using the API

+

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

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

+

+\section1 Building and compiling

+

+This library requires Qt 4.6 to be installed.

+

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

+

+\section1 Reference documentation

+

+\section2 Main classes

+

+\annotatedlist organizer-main

+

+\section2 "Organizer Item Details" Leaf Classes

+

+Several subclasses of \l{QOrganizerItemDetail} are provided as part of the

+Qt Mobility Organizer API. They are general in design but are intended

+to fulfill specific use-cases. Please note that certain backends may

+choose not to support one or more of these subclasses as they appear here;

+they may offer their own which provide similar functionality.

+

+\annotatedlist organizer-details

+

+Each of these subclasses provide access to information stored in fields which

+may have certain constraints, as listed in the \l{Qt Organizer Schema}{schema}.

+

+\section2 Asynchronous Requests

+

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

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

+functionality provided by a manager backend. The

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

+offered through subclasses of the \l{QOrganizerItemAbstractRequest} class:

+

+\annotatedlist organizer-requests

+

+\section2 Organizer Item Selection And Sorting

+

+Clients may select an organizer item by specifying a unique item id, or by

+supplying a \l{QOrganizerItemFilter} which matches the item or items they

+wish to select. The various derivatives of \l{QOrganizerItemFilter} allow for

+fine-grained and flexible selection of organizer data according to various

+criteria:

+

+\annotatedlist organizer-filters

+

+

+A client can also request that the results of such a selection be sorted,

+by passing a \l{QOrganizerItemSortOrder} (or list of sort orders) to the

+manager.

+

+\section2 Implementing Backends

+

+A backend implementor must implement the following interfaces:

+

+\annotatedlist organizer-backends

+

+For more information on this topic, see please see the documentation on

+\l{Qt Organizer Manager Engines}{implementing manager engines}.

+

+\section2 Synchronization and Serialization

+

+The organizer API is used by another Qt Mobility module: the

+\l {Versit API} {Versit}* module. It allows

+serialization of a QOrganizerItem into an iCalendar document, and vice versa.

+

+[*] Versit \reg is a trademark of the Internet Mail Consortium.

+

+\section2 Examples

+

+There are no examples at this point in time.

+

+See \l{Organizer API Usage} instead.

+

+*/

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

+**

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

+** All rights reserved.

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

+**

+** This file is part of the documentation of the Qt Toolkit.

+**

+** $QT_BEGIN_LICENSE:FDL$

+** Commercial Usage

+** Licensees holding valid Qt Commercial licenses may use this file in

+** accordance with the Qt Commercial License Agreement provided with the

+** Software or, alternatively, in accordance with the terms contained in a

+** written agreement between you and Nokia.

+**

+** GNU Free Documentation License

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

+** Documentation License version 1.3 as published by the Free Software

+** Foundation and appearing in the file included in the packaging of this

+** file.

+**

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

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

+** $QT_END_LICENSE$

+**

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

+

+

+/*!

+

+\page organizerasync.html

+

+\title Organizer Asynchronous API

+

+\tableofcontents

+

+

+\section1 Introduction

+

+The Organizer Asynchronous API enables a client to asynchronously fetch,

+update, or remove calendar, scheduling and personal data from an organizer

+item 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 Organizer module is available through classes

+derived from the QOrganizerAbstractRequest class. It consists of two major sections:

+\list

+ \o Organizer Item Manipulation

+ \o Schema Manipulation

+\endlist

+

+The functionality offered by the synchronous API in these two 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{Organizer Synchronous API}.

+

+\section2 Organizer Item Manipulation

+

+The most common type of operation that clients will perform involves retrieval

+or modification of organizer items. For in-depth information about item

+manipulation, please refer to the \l{Organizer Synchronous API}, as the data

+semantics of such operations are the same.

+

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

+\list

+ \o Fetch item ids

+ \o Fetch items

+ \o Save items (create or update)

+ \o Remove items

+\endlist

+

+These operations are supported via the QOrganizerItemLocalIdFetchRequest,

+QOrganizerItemFetchRequest, QOrganizerItemSaveRequest and

+QOrganizerItemRemoveRequest classes, respectively.

+

+The synchronous API offered by the QOrganizerItemManager class to allow

+manipulation of organizer items consists of the following functions:

+\list

+ \o itemIds(const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>()) const

+ \o itemIds(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>()) const

+ \o items(const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>(), const QOrganizerItemFetchHint& fetchHint = QOrganizerItemFetchHint()) const

+ \o items(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>(), const QOrganizerItemFetchHint& fetchHint = QOrganizerItemFetchHint()) const

+ \o saveItems(QList<QOrganizerItem>* items, QMap<int, QOrganizerItemManager::Error>* errorMap)

+ \o removeItems(QList<QOrganizerItemLocalId>& itemIds, QMap<int, QOrganizerItemManager::Error>* errorMap)

+\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{Organizer 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 QOrganizerItemDetailDefinitionFetchRequest,

+QOrganizerItemDetailDefinitionSaveRequest and QOrganizerItemDetailDefinitionRemoveRequest classes,

+respectively.

+

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

+of the following functions:

+\list

+ \o detailDefinitions(const QString& itemType = QOrganizerItemType::TypeEvent) const

+ \o detailDefinition(const QString& definitionName, const QString& itemType = QOrganizerItemType::TypeEvent) const

+ \o saveDetailDefinition(const QOrganizerItemDetailDefinition& def, const QString& itemType = QOrganizerItemType::TypeEvent)

+ \o removeDetailDefinition(const QString& definitionName, const QString& itemType = QOrganizerItemType::TypeEvent)

+\endlist

+

+\section1 Examples Of Usage

+

+\section2 Fetching Items

+

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

+from a particular manager.

+

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

+received.

+

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

+QOrganizerItemAbstractRequest) 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.

+

+*/

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

+**

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

+** All rights reserved.

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

+**

+** This file is part of the documentation of the Qt Toolkit.

+**

+** $QT_BEGIN_LICENSE:FDL$

+** Commercial Usage

+** Licensees holding valid Qt Commercial licenses may use this file in

+** accordance with the Qt Commercial License Agreement provided with the

+** Software or, alternatively, in accordance with the terms contained in a

+** written agreement between you and Nokia.

+**

+** GNU Free Documentation License

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

+** Documentation License version 1.3 as published by the Free Software

+** Foundation and appearing in the file included in the packaging of this

+** file.

+**

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

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

+** $QT_END_LICENSE$

+**

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

+

+

+/*!

+

+\page organizerengines.html

+

+\title Qt Organizer Manager Engines

+

+\tableofcontents

+

+\section1 Introduction

+

+The QOrganizerItemManager interface provided to clients to allow access to organizer information depends

+on an implementation of QOrganizerItemManagerEngine existing. This engine provides the methods

+which are called by the manager. An engine is identified by its URI, which is the name

+reported to clients through the QOrganizerItemManager::managerUri() function. The URI of a manager

+is built by combining its name, version and relevant construction parameters.

+

+\section1 Information For Clients

+

+While clients never interact directly with instances of QOrganizerItemManagerEngine, they may need to

+be aware of limitations of individual engines, or differences between engines. The API offered

+through QOrganizerItemManager allows clients to retrieve this information for the engine which provides

+the functionality exposed through a particular QOrganizerItemManager.

+

+\section2 Where Is The Data Stored?

+

+A QOrganizerItemManagerEngine may provide an aggregated view of multiple physical datastores, zero or

+more of which may be remote datastores. Clients of the API are aware only that the data is managed

+by a QOrganizerItemManagerEngine with a particular URI. It is possible that multiple different engines

+will have overlap in the datastores which they aggregate, and in that case the way in which those

+engines were implemented will determine whether operations are thread-safe or not.

+

+Since the data may physically be stored in a remote datastore, any operations may be dominated by

+the return-trip-time of communications with the remote datastore. As such, it is recommended

+that clients use the asynchronous client API to access organizer information from any QOrganizerItemManager.

+

+\section2 Schema Differences

+

+Each engine may support a different schema. All engines should attempt to support the default

+schema, described in the \l{Qt Organizer Schema}{default schema} documentation, however clients

+should never assume that any engine does support the default schema fully.

+

+Clients are able to retrieve the schema supported by a particular engine at run-time by calling

+QOrganizerItemManager::detailDefinitions(). Some engines support different detail definitions (that is,

+a different schema) for different types of organizer items (events, todos, journals, notes and so

+forth). Clients can retrieve the organizer item types supported by an engine by calling QOrganizerItemManager::supportedItemTypes().

+

+\section2 Provided Engines

+

+The Organizer module of the Qt Mobility project includes several backends already, some of which

+are designed to interface with the default calendar on their particular platform.

+

+\section3 In-Memory Example Engine

+

+The in-memory engine identifies itself as the "memory" engine. It is available on all platforms

+which are supported by the Qt Mobility project.

+

+The in-memory engine supports the default schema, and provides almost all functionality available through

+the Qt Mobility Organizer API; however, all data is stored in-memory and is not persisted in any

+way.

+

+\section3 Symbian Engine

+

+The Symbian engine identifies itself as the "symbian" engine, and is only available on the

+Symbian S60 3.1, S60 3.2, S60 5.0 and Symbian^3 platforms.

+

+The Symbian engine supports a modified version of the default schema. The schema supported

+by the Symbian engine depends on which version of the platform is being used.

+

+The Symbian engine allows clients to use both the asynchronous and synchronous interfaces,

+and persists all saved data to the system calendar.

+

+\section3 Maemo 5 (Fremantle) Engine

+

+The Maemo 5 (Fremantle) engine identifies itself as the "maemo5" engine, but is only available

+on the Maemo 5 (Fremantle) platform which has the correct libraries installed (including

+calendar-backend).

+

+The Maemo 5 (Fremantle) engine supports a modified version of the default schema, and

+persists all saved information to the system calendar.

+

+\section1 Information For Engine Implementors

+

+Some developers may wish to provide implementations of QOrganizerItemManagerEngine for use by clients.

+The engine that they provide may aggregate multiple datastores, or access a remote datastore,

+or provide some other functionality to clients. An engine is distributed as a Qt Plugin, and

+will be detected automatically by the plugin loading code in the QOrganizerItemManager, so long as the

+plugin is located in the correct path ($QT_PLUGINS_DIR/organizer/).

+

+\section2 Which Functions Do I Need To Implement

+

+Different engines provide different functionality and support different features. Depending on

+the feature set of the engine, it will need to implement a particular subset of the API.

+The default implementation for most functions will set the error to

+\c QOrganizerItemManager::NotSupportedError and return the value which indicates that an error has

+occurred.

+

+\section3 Mandatory Functions

+

+All engines must implement the following functions:

+

+\list

+ \o QOrganizerItemManagerEngine::managerName()

+ \o QOrganizerItemManagerEngine::managerVersion()

+ \o QOrganizerItemManagerEngine::supportedItemTypes()

+ \o QOrganizerItemManagerEngine::supportedDataTypes()

+ \o QOrganizerItemManagerEngine::hasFeature()

+ \o QOrganizerItemManagerEngine::detailDefinitions()

+ \o QOrganizerItemManagerEngine::itemIds()

+ \o QOrganizerItemManagerEngine::items()

+\endlist

+

+Every engine implementation must also come with an implementation of QOrganizerItemManagerEngineFactory

+for that engine.

+

+Note that you do not need to implement filtering and sorting natively in an engine; the default

+implementation offers the following static functions to perform filtering and sorting respectively,

+in memory:

+\list

+ \o QOrganizerItemManagerEngine::testFilter()

+ \o QOrganizerItemManagerEngine::sortItems()

+\endlist

+

+However, engine implementors should be aware that the default implementation is naive and will

+have greatly reduced performance compared to a native implementation (e.g., SQL queries, if

+the calendar or personal data exposed by the engine implementation is stored in an SQL database).

+

+Similarly, any QOrganizerItemFetchHint parameter may be ignored by an engine implementation, but if

+it does so it must return all information available for the item.

+

+All engines must also implement the following functions to implement asynchronous requests:

+\list

+ \o QOrganizerItemManagerEngine::requestDestroyed()

+ \o QOrganizerItemManagerEngine::startRequest()

+ \o QOrganizerItemManagerEngine::cancelRequest()

+ \o QOrganizerItemManagerEngine::waitForRequestFinished()

+\endlist

+If the engine does not support asynchronous requests, it should always return false in the

+last three of those functions, and do nothing in the first. If the engine does support

+asynchronous requests, it must ensure that all information required to perform the request

+is saved in the engine within QOrganizerItemManagerEngine::startRequest(), as the client owns the

+request object and may delete it at any time. In general, engine implementors should be aware

+of this ownership semantic, and never attempt an unsafe operation on a request pointer.

+

+It is recommended that all engine implementations support asynchronous requests, even if they

+use a "dummy" implementation which services the request synchronously during startRequest, and then

+emit the appropriate signals from the request via a zero-millisecond timeout timer.

+

+\section3 Optional Functionality

+

+The rest of the virtual functions are optional, and should be implemented only if the engine

+supports the operations.

+

+If the engine can be constructed with different parameters, which affects the operation of the

+engine (for example, a parameter might define which file to read schedule or calendar information from, or

+it might be an access token to prove that the client has the access rights to read organizer information

+from the engine, etc), it must report which parameters it was constructed with via the

+\list

+ \o QOrganizerItemManagerEngine::managerParameters()

+\endlist

+function.

+

+If the engine supports native filtering of any kind, it must report to clients which filters

+are supported natively by implementing:

+\list

+ \o QOrganizerItemManagerEngine::isFilterSupported()

+\endlist

+

+If the engine supports saving or removing organizer item information, as well as retrieval, it must

+implement:

+\list

+ \o QOrganizerItemManagerEngine::saveItems()

+ \o QOrganizerItemManagerEngine::removeItems()

+\endlist

+It may also choose to implement the "single item" functions:

+\list

+ \o QOrganizerItemManagerEngine::saveItem()

+ \o QOrganizerItemManagerEngine::removeItem()

+\endlist

+If it does not, the default implementation of those functions will use the batch (plural) versions

+of those functions to implement the required behavior.

+

+If the engine supports modification of its schema (that is, extension of its definitions at

+run-time), it must report that it supports the \c QOrganizerItemManager::MutableDefinitions feature

+via QOrganizerItemManagerEngine::hasFeature(), and must also implement:

+\list

+ \o QOrganizerItemManagerEngine::saveDetailDefinition()

+ \o QOrganizerItemManagerEngine::removeDetailDefinition()

+\endlist

+

+

+\section3 Optional Implementation

+

+Apart from areas of functionality which may be optionally implemented by the engine or not,

+the default implementation provides several functions which operate in a naive, in-memory

+manner. An engine implementation can override this default implementation with its own,

+if it wishes, in order to obtain performance gains, or to more accurately implement the

+function.

+

+As previously mentioned it may implement its own sorting or filtering, in functions such as

+QOrganizerItemManagerEngine::items(). An engine may also implement:

+\list

+ \o QOrganizerItemManagerEngine::validateItem()

+ \o QOrganizerItemManagerEngine::validateDefinition()

+ \o QOrganizerItemManagerEngine::compatibleItem()

+\endlist

+

+

+\section2 Which Signals Do I Need To Emit

+

+An engine implementation must emit the appropriate signals for the subset of functionality

+that it supports.

+

+If the engine supports reading or saving items, it must emit the:

+\list

+ \o QOrganizerItemManagerEngine::itemsAdded()

+ \o QOrganizerItemManagerEngine::itemsChanged()

+ \o QOrganizerItemManagerEngine::itemsRemoved()

+\endlist

+signals as appropriate. Alternatively, it can emit the QOrganizerItemManager::dataChanged()

+signal instead.

+

+\section2 Other Considerations

+

+There are several other considerations that engine writers must be aware of:

+\list

+ \o Most batch functions take an OPTIONAL error map as a parameter. This parameter

+may be null, in which case the client is not interested in fine-grained error reporting.

+Engines must check the pointer before attempting to dereference it.

+ \o Every function takes a mandatory \c QOrganizerItemManager::Error pointer argument. This argument

+is NEVER null, since it exists in the private implementation of QOrganizerItemManager. Testing this

+argument for null is, therefore, superfluous.

+ \o The single-item functions for item retrieval, removal and save

+already have a default implementation which merely wraps the batch retrieval, removal or save

+function appropriately. This default implementation may not be as performant as a hand-rolled

+function. Engine implementations MUST implement the batch functions for each area of

+functionality supported by the engine.

+ \o Most clients will prefer to use the asynchronous API to access information from the

+engine. It is therefore suggested that asynchronous requests be serviced, even if it is

+implemented in a similar manner to the (provided) memory engine's naive implementation.

+\endlist

+

+\section2 Example Implementation

+

+There are several implementations of QOrganizerItemManagerEngine available in the Qt Mobility

+source code repository. In particular, the "memory" engine provides an implementation of

+an in-memory, anonymous datastore which supports almost every feature in the API, and therefore

+is useful for demonstration purposes. Be aware, however, that the implementation of all

+functionality in the "memory" engine is naive and not performant, and should not be copied

+in any real engine implementation (e.g., to perform filtering, it reads all items from the

+(in-memory) database, and checks one by one for matches; a real engine, on the other hand,

+might perform a database query to return the results directly, rather than performing n-reads).

+

+*/

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

+**

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

+** All rights reserved.

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

+**

+** This file is part of the documentation of the Qt Toolkit.

+**

+** $QT_BEGIN_LICENSE:FDL$

+** Commercial Usage

+** Licensees holding valid Qt Commercial licenses may use this file in

+** accordance with the Qt Commercial License Agreement provided with the

+** Software or, alternatively, in accordance with the terms contained in a

+** written agreement between you and Nokia.

+**

+** GNU Free Documentation License

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

+** Documentation License version 1.3 as published by the Free Software

+** Foundation and appearing in the file included in the packaging of this

+** file.

+**

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

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

+** $QT_END_LICENSE$

+**

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

+

+

+/*!

+

+\page organizerschema.html

+

+\title Qt Organizer Schema

+

+\tableofcontents

+

+\section1 Introduction

+

+The \l{Organizer}{Qt Organizer API} makes use of detail leaf classes

+which provide certain well-known functionality. In order to develop a backend engine which

+can service clients or provide synchronization to other backends, the schema must be

+known.

+

+\section1 Schema Definition

+

+Different backends have different capabilities. Some backends may not be able to implement

+certain definitions in the default schema (for example, some backends might not have support for

+storing location information), while other backends may not be able to implement some aspects

+of a particular definition in the default schema.

+

+In order to be useful for clients, however, all backends should attempt to support the default

+schema. Furthermore, no backend should support a schema definition of a modified form where

+those modifications change the semantics of the data. A client should be able to request details

+of the QOrganizerItemDescription type (that is, details whose definition name is "Description") with

+reasonable certainty that the data returned describes the item in which it is saved.

+

+By implementing the default schema, the backend developer ensures that client code written against

+the default schema will work without source modification against their backend.

+

+\section1 Default Schema

+

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

+\annotatedlist organizer-details

+

+

+\section2 Detail Definition Uniqueness

+

+A uniqueness constraint on a detail definition means that for any \l{QOrganizerItem}, only one detail of that

+definition may be saved.

+

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

+\list

+ \o \l{QOrganizerItemDisplayLabel}

+ \o \l{QOrganizerItemDescription}

+ \o \l{QOrganizerItemType}

+ \o \l{QOrganizerItemGuid}

+\endlist

+

+\section2 Detail Access Constraints

+

+Some details in an item 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 QOrganizerItemDetail::Irremovable)

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

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

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

+

+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 item (that is, the item 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{QOrganizerItemType} detail, which is

+irremovable but may be updated by clients as desired in the default schema.

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

+in an item will be persisted in the manager when the client calls \l{QOrganizerItemManager::saveItem()}.

+

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

+

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

+\list

+ \o \l{QOrganizerItemGuid} is \c QOrganizerItemDetail::ReadOnly and \c QOrganizerItemDetail::Irremovable

+ \o \l{QOrganizerItemTimestamp} is \c QOrganizerItemDetail::ReadOnly and \c QOrganizerItemDetail::Irremovable

+ \o \l{QOrganizerItemDisplayLabel} is \c QOrganizerItemDetail::Irremovable

+ \o \l{QOrganizerItemDescription} is \c QOrganizerItemDetail::Irremovable

+ \o \l{QOrganizerItemType} is \c QOrganizerItemDetail::Irremovable

+\endlist

+

+Furthermore, in the default schema, every item is required to have at least three details by default: a \l{QOrganizerItemType} which describes

+the type of information which the item represents (for example, an event or an agenda), a \l{QOrganizerItemDisplayLabel} which holds

+the display label of the item, and a \l{QOrganizerItemDescription} which describes the item in a human-readable manner.

+

+\section2 Backend-provided Details

+

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

+When the client attempts to save a \l{QOrganizerItem}

+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{QOrganizerItemTimestamp} detail to a \l{QOrganizerItem}, it will not be persisted in the manager when the

+client attempts to save that item.

+

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

+than others.

+

+

+*/

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

+**

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

+** All rights reserved.

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

+**

+** This file is part of the documentation of the Qt Toolkit.

+**

+** $QT_BEGIN_LICENSE:FDL$

+** Commercial Usage

+** Licensees holding valid Qt Commercial licenses may use this file in

+** accordance with the Qt Commercial License Agreement provided with the

+** Software or, alternatively, in accordance with the terms contained in a

+** written agreement between you and Nokia.

+**

+** GNU Free Documentation License

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

+** Documentation License version 1.3 as published by the Free Software

+** Foundation and appearing in the file included in the packaging of this

+** file.

+**

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

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

+** $QT_END_LICENSE$

+**

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

+

+

+

+/*!

+

+\page itemssync.html

+

+\title Organizer Synchronous API

+

+\tableofcontents

+

+

+\section1 Introduction

+

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

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

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

+Synchronous calls to an item 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 Organizer Items module is available through the QOrganizerItemManager

+class. It consists of three major sections:

+\list

+ \o Error Reporting

+ \o Schema Manipulation

+ \o Organizer Item 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 QOrganizerItemManager::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 QOrganizerItemManager::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 Organizer Item Manipulation

+

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

+The QOrganizerItemManager class offers synchronous API to retrieve, create, update and delete items. The create

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

+by the API.

+

+An item is identified by its QOrganizerItemId. This id consists of two parts: a URI which identifies the item manager

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

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

+

+The QOrganizerItemManager class provides API for accessing the IDs of items which are stored in the manager:

+\list

+ \o itemIds(const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>()) const

+ \o itemIds(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>()) const

+\endlist

+

+The item id retrieval functionality is also provided via asynchronous API through the QOrganizerItemLocalIdFetchRequest class.

+

+The synchronous, singular item manipulation functions offered by the QOrganizerItemManager class are:

+\list

+ \o item(const QOrganizerItemLocalId& itemId, const QOrganizerItemFetchHint& fetchHint = QOrganizerItemFetchHint()) const

+ \o saveOrganizer Item(QOrganizerItem* item)

+ \o removeOrganizer Item(const QOrganizerItemLocalId& itemId)

+\endlist

+

+The (optional) fetch argument to the item 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 item's details are checked against the supported schema.

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

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

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

+

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

+directly after the original synchronous call.

+

+The synchronous, batch item manipulation functions offered by the QOrganizerItemManager class are:

+\list

+ \o items(const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>(), const QOrganizerItemFetchHint& fetchHint = QOrganizerItemFetchHint()) const

+ \o items(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>(), const QOrganizerItemFetchHint& fetchHint = QOrganizerItemFetchHint()) const

+ \o saveOrganizer Items(QList<QOrganizerItem>* items, QMap<int, QOrganizerItemManager::Error>* errorMap)

+ \o removeOrganizer Items(QList<QOrganizerItemLocalId>* itemIds, QMap<int, QOrganizerItemManager::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 QOrganizerItemManager::error() directly after the original synchronous call.

+

+The item manipulation functionality is also provided via asynchronous API through the QOrganizerItemFetchRequest,

+QOrganizerItemSaveRequest, and QOrganizerItemRemoveRequest classes.

+

+\section2 Schema Manipulation

+

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

+An item 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-item 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 Organizer Schema}{Qt Mobility Organizer 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

+QOrganizerItemManager::MutableDefinitions feature.

+

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

+\list

+ \o detailDefinitions(const QString& itemType = QOrganizerItemType::TypeEvent) const

+ \o detailDefinition(const QString& definitionName, const QString& itemType = QOrganizerItemType::TypeEvent) const

+ \o saveDetailDefinition(const QOrganizerItemDetailDefinition& def, const QString& itemType = QOrganizerItemType::TypeEvent)

+ \o removeDetailDefinition(const QString& definitionName, const QString& itemType = QOrganizerItemType::TypeEvent)

+\endlist

+

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

+QOrganizerItemDetailDefinitionFetchRequest, QOrganizerItemDetailDefinitionSaveRequest and QOrganizerItemDetailDefinitionRemoveRequest

+classes.

+

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

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

+normal items, but only name, address, and phone number details for a group item.

+

+

+\section1 Examples Of Usage

+

+The synchronous API provides the simplest way to access or modify the

+item 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 item to the default manager

+

+The client creates a new non-recurring item, adds some, and

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

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Creating a non-recurrent entry

+

+We assume the existence of various specialized leaf-classes that allow simple

+access to details of the item, such as priority, description and display label.

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

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

+supported by a particular definition.

+

+\section2 Filtering by detail definition and value

+

+The client utilizes a default manager and asks for any items which match

+a particular search criteria:

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Retrieving any entry (not occurrence) which matches a search criteria

+

+

+\section3 Modifying an existing item and saving the modifications

+

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

+detail, and then saves the item back to the manager.

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Editing a non-recurrent entry

+

+*/

+

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

+**

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

+** All rights reserved.

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

+**

+** This file is part of the documentation of the Qt Toolkit.

+**

+** $QT_BEGIN_LICENSE:FDL$

+** Commercial Usage

+** Licensees holding valid Qt Commercial licenses may use this file in

+** accordance with the Qt Commercial License Agreement provided with the

+** Software or, alternatively, in accordance with the terms contained in a

+** written agreement between you and Nokia.

+**

+** GNU Free Documentation License

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

+** Documentation License version 1.3 as published by the Free Software

+** Foundation and appearing in the file included in the packaging of this

+** file.

+**

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

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

+** $QT_END_LICENSE$

+**

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

+

+/*!

+

+\page organizerusage.html

+

+\title Organizer API Usage

+

+\tableofcontents

+

+\section1 Introduction

+

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

+

+\section1 Manager Settings And Configuration

+

+Users of the items 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 QOrganizerItemManager instance.

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

+operation of the backend. In this example, the client constructs a particular

+backend, but does not construct it with any special parameters:

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Instantiating a specific manager

+

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

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Instantiating the default manager for the platform

+

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

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

+

+\section2 Querying a manager for capabilities

+

+Different managers will support different capabilities and details. Clients

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

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

+

+\section2 Loading the manager for a specific backend

+

+The client can choose to load a manager for a specific backend. While

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

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Instantiating a specific manager

+

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

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

+interfaces with a particular online service).

+

+\section2 Loading a manager with specific parameters

+

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

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

+to know which parameters are valid for a particular backend,

+and what argument it takes.

+

+\section1 Organizer Item Detail Manipulation

+

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

+retrieve, create, update or delete details from the item. Since QOrganizerItem

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

+these operations is purely synchronous.

+

+An item consists of the details it contains, as well as an id. Some details

+are read-only (such as the modification timestamp of an item) or irremovable (like

+the type of an item), but most are freely modifiable by clients. The

+QOrganizerItem::details(), QOrganizerItem::detail(),

+QOrganizerItem::saveDetail() and QOrganizerItem::removeDetail() functions can be

+used to manipulate these details.

+

+To aid in the manipulation of common details, convenience functions are provided

+in QOrganizerItem like setDisplayLabel() and setDescription() which set and

+access the details directly. Many details are specific to particular types of

+items, and convenience functions for these are provided in the subclasses of

+QOrganizerItem. For example, the QOrganizerEvent class provides the function

+setStartDateTime(), which is equivalent to getting the QOrganizerEventTimeRange

+detail, setting the StartDateTime field and resaving it.

+

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

+particular semantics surrounding saving, removal and modification.

+

+\section1 Persistent Organizer Item Information

+

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

+information (detail definitions) which is persistently stored in the manager

+(for example, in a database or online cloud). This may be done synchronously

+or asynchronously. And example of synchronous usage is as follows:

+

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

+class uses member variables for the manager and requests. This allows them

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

+state of the request changes.

+

+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 QOrganizerItemAbstractRequest::resultsAvailable() signal to the

+slot which deals with the results.

+

+\section2 Creating a new item in a manager

+

+Clients can create a new item simply by instantiating one and saving it a manager.

+The save operation will succeed if the item initially had a zero-id, and

+if the manager supports the details in the item. The item may be saved

+either synchronously by directly calling QOrganizerItemManager::saveItem() or

+asynchronously using a QOrganizerItemSaveRequest and connecting to that request's

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

+complete, by calling waitForFinished().

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Creating a non-recurrent entry

+

+\section2 Retrieving items from a manager

+

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

+filter, sorted according to a particular sort order.

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Retrieving any entry (not occurrence) which matches a search criteria

+

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

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

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

+The synchronous API provides the QOrganizerItemManager::item() function specifically for this purpose.

+

+Some items which clients are interested in may not be explicitly stored in the manager,

+but rather dynamically generated given a recurrence rule which is saved in a particular

+item. These are known as occurrences and may be retrieved by calling itemInstances().

+Once retrieved, a generated occurrence may be saved into the manager, at which point it

+becomes an exception to the original item.

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Creating an exception to a particular recurrent event

+

+\section2 Updating an existing item in a manager

+

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

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

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

+

+ \snippet snippets/qtorganizerdocsample/qtorganizerdocsample.cpp Editing a non-recurrent entry

+

+\section2 Removing an item from a manager

+

+The client may remove an item from the manager by specifying its local id.

+

+\section2 Optimization in item retrieval

+

+Clients can inform the manager that they do not require certain details from

+an item, which can allow a manager to optimize item retrieval.

+In this way, the client can inform the manager that they are

+not interested in any binary blob data (e.g., images) in retrieved items.

+

+\section2 Querying the schema supported by a manager

+

+A client may query the schema supported by a manager, and check to see if a

+particular detail definition supports a certain field.

+

+\section2 Modifying the schema supported by a manager

+

+A client may attempt to modify a particular detail definition by extending it

+so that it supports an extra field, or add a new detail definition, or

+remove an existing one. These operations are not necessarily supported on

+various backends, and even those backends which do support a mutable schema

+may not allow modification of the default detail definitions.

+

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

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

+

+\section1 Recurring items

+

+A recurring item is an item that occurs more than once; for example, a meeting

+that occurs every week for the next 10 weeks. A recurring item is created by

+creating a QOrganizerEvent or QOrganizerTodo and adding a

+QOrganizerItemRecurrence detail to it to specify the rules for when it should

+recur. While the item occurs multiple times, the client only has to create it

+once and save it once. When QOrganizerItemManager::itemInstances() is called,

+any recurring items are expanded into multiple QOrganizerEventOccurrence and

+QOrganizerTodoOccurrence items by the manager. Each generated occurrence item

+has a local id of zero.

+

+The client is able to make an exception for an occurrence by taking a generated

+item occurrence from the manager, making the necessary modifications, and

+resaving it. When the manager is then queried with

+QOrganizerItemManager::itemInstances(), it will return the list of occurrences

+as before, but with the modifications in place. The modified item will be given

+a non-zero local id, and replaces the generated one in the list.

+

+The client can also query the manager for a list of unexpanded items by calling

+QOrganizerItemManager::items(). The list of returned items will contain all

+items that have been saved to the manager with a call to saveItem() (of course,

+without any items removed with removeItem()). That is, recurring events will be

+returned as is, and event occurrences will not appear unless they are exceptions

+(ie. have a non-zero local id). Fetching the list in this way can be useful for

+transfering items to other managers or for exporting to iCalendar with QtVersit.

+

+\section1 Multiple organizers

+

+It may be useful for clients to separate their organizer items into different

+organizers (eg. Personal and Work) and work with different views that show items

+from one, some or all of these organizers. This is functionality has not been

+implemented in this technical preview, but we currently are investigating the

+best model to use to offer this.

+

+*/

+ ../../src/organizer \

+ ../../src/organizer \