Qt Mobility Reference Documentation

Organizer

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.

Note: This API and documentation is a Technology Preview and is still subject to change.

Namespace

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

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.

Overview

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

Organizer information is stored in datastores whose functionality is exposed via a manager. The Organizer API models organizer information as an item which consists of a collection of distinct details. Each detail conforms to a particular 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.

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

Client-Facing API

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

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

Item

An 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 id which consists of a manager identifier (URI) and the 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.

Detail

A 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 here.

Detail Definition

Each detail stored in an item has defined semantics of usage and storage. The Qt Organizer API allows per-datastore organizer item 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 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.

Manager

Access to organizer items is provided by implementations of the Qt Organizer 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.

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:

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:

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

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

Asynchronous API

The asynchronous API provides a way to access or modify the 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 items and schema definitions, but does not provide manager capability or meta data information reporting.

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

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 items and schema definitions. As previously described, the meta data reporting and manipulation functions are also provided via synchronous API only.

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

Non-Client-Facing API

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

Manager Engine

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

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

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

On-going Development

There are several areas of API which are actively being developed, which are not included in the Technical Preview. These include:

  • Multiple Calendar Support
  • Timezone Support
  • Result Pagination Support
  • All-day and Multiple-day Event Support

Each of these areas is complex and may have important ramifications to related areas of the API, and so are discussed separately below.

Multiple Calendar Support

One aspect of the Qt Mobility Organizer API which is still under discussion and active development is the ability to support multiple "calendars" for different contexts. Currently, no API is offered to support multiple calendars. It is still undecided how multiple calendars should be supported by the API (some possibilities, in no particular order, include: each calendar is modeled as a separate manager; each calendar is modeled as a top-level item, and API for manipulating these calendars is offered via QOrganizerItemManager and through various subclasses of QOrganizerItemAbstractRequest; calendars are supported only as a QOrganizerItemTag detail in each item; etc).

The semantics of events stored in multiple calendars is also under discussion. Multiple calendar support has the potential to introduce possibly confusing semantics (for example: sharing of event data versus duplication of event data) and so we need to carefully consider how current calendar and scheduling backends work, in order to determine what is technically feasible and what is most intuitive for the application developer, before mandating some particular set of semantics related to multiple calendar support.

Timezone Support

A critical part of the API which is still under development is support for different time zones. In general, dates are considered to be timezone-independent (that is, floating dates), whereas datetimes should include timezone information. The exact manner in which timezone information should be offered to clients in the API is still under discussion.

One possible solution would be to offer a QOrganizerTimezone class which provides API to allow clients to transform a particular datetime into another datetime in a different timezone. A more complete solution might be to add timezone support to QDateTime directly, however this would require extensive modifications to Qt and so may not be possible due to technical reasons (e.g., binary compatibility promises, release scheduling, etc).

Result Pagination

Often, clients will want a single "page" of results from a single filtering operation at a time. The advantage of an API to allow this is that memory use decreases, and results may be returned faster (since there are less of them to instantiate).

We see two main use cases for pagination:

  • Limiting results to a single offset plus a count
  • Limiting results to a single count (implied offset of zero)

The first is more general, and support on some platforms is limited or even non-existent. Emulation of such a feature obviates any potential benefits which might be derived from offering the API in the first place (as emulating the feature would use more memory and be less performant that simply returning all results of the filtering operation). Paging of results is possible to achieve manually using the current API (by retrieving a list of ids, and then manually retrieving pages of items manually by id) but may be suboptimal.

The second is supported on most platforms, and is the more common use case. It may be implemented by extending QOrganizerItemFetchHint to include a maximum count parameter, which may be ignored by backends if the backend does not support the feature.

In short, discussion about result pagination is still on-going, as it is a complex topic with far-reaching ramifications given that we must maintain consistency between the various modules of the Qt Mobility project.

All-day and Multiple-day Event Support

Several options for supporting all-day and multiple-day events have been considered. One possible method of supporting all-day events is to allow the start date time of the event to be set to a date without a time component, while another might be to explicitly set the start and end date times to cover an entire 24 hour period (the currently supported solution). We envision that multiple-day events will be supported in the same manner as all-day events.

Finally, the way in which all-day and multiple-day events are supported may depend on the way in which timezone support is implemented. As such, this aspect of the API will be considered iteratively as support for timezone information matures.

Using the API

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

Building and compiling

This library requires Qt 4.6 to be installed.

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

Reference documentation

Main classes

QOrganizerItem

Represents an addressbook organizeritem

QOrganizerItemAbstractRequest

Mechanism for asynchronous requests to be made of a manager if it supports them

QOrganizerItemDetail

Represents a single, complete detail about a organizeritem

QOrganizerItemFilter

Used to select organizer items made available through a QOrganizerItemManager

QOrganizerItemManager

Interface which allows clients with access to organizer item information stored in a particular backend

"Organizer Item Details" Leaf Classes

Several subclasses of 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.

QOrganizerEventTimeRange

Contains the start and end dates and times of a recurring event series, or occurrence of an event

QOrganizerItemComment

Contains some arbitrary information which is relevant to the organizer item

QOrganizerItemDescription

Contains some arbitrary information which is relevant to the organizer item

QOrganizerItemDisplayLabel

Contains the backend-synthesized display label of the organizer item

QOrganizerItemGuid

Contains the globally unique identifier of the organizer item, which can be used for synchronization purposes

QOrganizerItemInstanceOrigin

Contains information about when and from where or whom the organizer item originated

QOrganizerItemLocation

Contains information about a location which is related to the organizer item in some manner

QOrganizerItemPriority

Contains the priority of the organizer item, which may be used to resolve scheduling conflicts

QOrganizerItemRecurrence

Contains a list of rules and dates on which the recurrent item occurs, and a list of rules and dates on which exceptions occur

QOrganizerItemTimestamp

Contains the creation and last-modified timestamp associated with the organizer item. XXX TODO: what about last accessed?

QOrganizerItemType

Describes the type of the organizer item. This detail may be automatically synthesized by the backend depending on other details in the organizer item

QOrganizerJournalTimeRange

Contains information about the date and time for which a journal entry has been created

QOrganizerTodoProgress

Contains information about the progress of a todo item

QOrganizerTodoTimeRange

Contains information about the time range of a todo item

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

Asynchronous Requests

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

QOrganizerItemDetailDefinitionFetchRequest

Allows a client to asynchronously request detail definitions from a organizeritems store manager

QOrganizerItemDetailDefinitionRemoveRequest

Allows a client to asynchronously request that certain detail definitions be removed from a organizeritems store

QOrganizerItemDetailDefinitionSaveRequest

Allows a client to asynchronously request that certain detail definitions be saved in a organizeritems store

QOrganizerItemFetchRequest

Allows a client to asynchronously request organizeritems from a organizeritems store manager

QOrganizerItemInstanceFetchRequest

Allows a client to asynchronously request organizeritems from a organizeritems store manager

QOrganizerItemLocalIdFetchRequest

Allows a client to asynchronously request a list of organizeritem ids from a organizeritems store manager

QOrganizerItemRemoveRequest

Allows a client to asynchronously request that certain organizeritems be removed from a organizeritems store

QOrganizerItemSaveRequest

Allows a client to asynchronously request that certain organizeritems be saved to a organizeritems store

Organizer Item Selection And Sorting

Clients may select an organizer item by specifying a unique item id, or by supplying a QOrganizerItemFilter which matches the item or items they wish to select. The various derivatives of QOrganizerItemFilter allow for fine-grained and flexible selection of organizer data according to various criteria:

QOrganizerItemChangeLogFilter

Filter based around a organizeritem timestamp criterion

QOrganizerItemDateTimePeriodFilter

Filter based around a datetime period between start and end datetime

QOrganizerItemDetailFilter

Filter based around a detail value criterion

QOrganizerItemDetailRangeFilter

Filter based around a detail value range criterion

QOrganizerItemIntersectionFilter

Filter which intersects the results of other filters

QOrganizerItemInvalidFilter

Matches no organizeritems

QOrganizerItemLocalIdFilter

Filter based around a list of organizeritem ids

QOrganizerItemUnionFilter

Filter which unions the results of other filters

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

Implementing Backends

A backend implementor must implement the following interfaces:

QOrganizerItemManagerEngine

The interface for all implementations of the organizer item manager backend functionality

QOrganizerItemManagerEngineFactory

The interface for plugins that implement QOrganizerItemManagerEngine functionality

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

Synchronization and Serialization

The organizer API is used by another Qt Mobility module: the Versit* module. It allows serialization of a QOrganizerItem into an iCalendar document, and vice versa.

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

Examples

The following sample applications show examples of API usage:

  • Example Calendar Application

See Organizer API Usage for more examples of API usage.


Copyright © 2009-2010 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Mobility Project 1.1.0