Contents
Organizer Asynchronous API
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.
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:
- Organizer Item Manipulation
- Schema Manipulation
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 Organizer Synchronous API.
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 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:
- Fetch item ids
- Fetch items
- Save items (create or update)
- Remove items
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:
- itemIds(const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>()) const
- itemIds(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>()) const
- items(const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>(), const QOrganizerItemFetchHint& fetchHint = QOrganizerItemFetchHint()) const
- items(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders = QList<QOrganizerItemSortOrder>(), const QOrganizerItemFetchHint& fetchHint = QOrganizerItemFetchHint()) const
- saveItems(QList<QOrganizerItem>* items, QMap<int, QOrganizerItemManager::Error>* errorMap)
- removeItems(QList<QOrganizerItemLocalId>& itemIds, QMap<int, QOrganizerItemManager::Error>* errorMap)
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 Organizer Synchronous API.
There are three different types of operation which are supported by the asynchronous API:
- Fetch detail definitions
- Save detail definitions (create or update, if supported by the backend)
- Remove detail definitions (if supported by the backend)
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:
- detailDefinitions(const QString& itemType = QOrganizerItemType::TypeEvent) const
- detailDefinition(const QString& definitionName, const QString& itemType = QOrganizerItemType::TypeEvent) const
- saveDetailDefinition(const QOrganizerItemDetailDefinition& def, const QString& itemType = QOrganizerItemType::TypeEvent)
- removeDetailDefinition(const QString& definitionName, const QString& itemType = QOrganizerItemType::TypeEvent)
Examples Of Usage
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.
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.