Qt Organizer Asynchronous API

The Qt 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.

The asynchronous API is available through classes derived from the QOrganizerAbstractRequest class that enable clients to:

  • Manipulate organizer items
  • Manipulate item collections

Manipulating Organizer Items

The most common type of operation that clients will perform involves retrieval or modification of organizer items. For in-depth information about item manipulation, see Qt Organizer C++ API.

The asynchronous API supports the following operations:

  • Fetch item ids
  • Fetch persistent items (for export)
  • Fetch items (including generated occurrences) in a time period
  • Fetch the occurrences of a specific item
  • Save items (create or update)
  • Remove items

These operations are supported via the following classes:

  • QOrganizerItemIdFetchRequest
  • QOrganizerItemFetchForExportRequest
  • QOrganizerItemFetchRequest
  • QOrganizerItemOccurrenceFetchRequest
  • QOrganizerItemSaveRequest
  • QOrganizerItemRemoveRequest

Manipulating Item Collections

Each item is saved in a collection in a manager. Each collection has various properties which, if the manager supports such operations, may be modified by clients. For in-depth information about collections, see Qt Organizer C++ API.

The asynchronous API supports the following operations:

  • Fetch collections (that is, the object which defines the properties of a collection)
  • Save collections (create or update)
  • Remove collections

These operations are supported via the following classes:

  • QOrganizerCollectionFetchRequest
  • QOrganizerCollectionSaveRequest
  • QOrganizerCollectionRemoveRequest

Performing Asynchronous Operations

All asynchronous operations are performed in a similar way:

  • A request of the desired type (which is derived from QOrganizerAbstractRequest) is created
  • Certain criteria are set which determine the intent of the request
  • QOrganizerAbstractRequest::stateChanged() signal of the request is connected to a slot which deals with the results.
  • The request is started.

Note: To receive the results of the request as they become available, rather than only the final set of results once the request changes state (to FinishedState, for example), the client should instead connect the QOrganizerAbstractRequest::resultsAvailable() signal to the slot which deals with the results.

Reporting Errors

When a asynchronous operation fails, clients need to be able to retrieve error information associated with that asynchronous operation. It is possible to retrieve this error information by calling the QOrganizerAbstractRequest::error() function on the corresponding request.

For some asynchronous operations (for example, batch save or remove operations) it is possible that multiple errors may occur during the operation. In those cases, clients can call the errorMap() function on the request object to retrieve a map of input index to error. See, for instance, QOrganizerItemSaveRequest::errorMap().