MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Organizer

The Organizer API enables a client to request calendar, schedule and personal data from local or remote backends. This is part of the QtMobility Project.

Namespace

The QtMobility APIs are placed into the QtMobility namespace. This is done to facilitate the future migration of QtMobility 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 a platform's native calendaring system. Through the plugin architecture, it can be used as a front-end API for any calenaring system (eg. an online calendar).

Basic Usage

The Qt Organizer API provides both a synchronous and an asynchronous API. Note that for clarity, the short examples on this page demonstrate the synchronous API. While these code snippets might be useful for non-GUI applications, it is highly recommended that the asynchronous API is used for GUI applications.

The Organizer Manager

Organizer information is stored in datastores whose functionality is exposed via the QOrganizerManager class.

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:

 QOrganizerManager defaultManager;

Creating a New Item

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

 // a default constructed journal will have it's date/time set to the current date/time.
 QOrganizerJournal journal;
 journal.setDescription("The conference went well.  We all agree that marshmallows are awesome, "\
                 "but we were unable to reach any agreement as to how we could possibly "\
                 "increase our intake of marshmallows.  Several action points were assigned "\
                 "to various members of the group; I have been tasked with finding a good "\
                 "recipe that combines both marshmallows and chocolate, by next Wednesday.");
 defaultManager.saveItem(&journal);

Retrieving Items

You can request all items from the manager that occur in a given time range.

 QList<QOrganizerItem> entries =
     defaultManager.items(QDateTime(QDate(2010, 1, 1), QTime(0, 0, 0)),
                          QDateTime(QDate(2010, 1, 31), QTime(23, 59, 59)));

It is also possible filter the items on the value of a detail.

 entries = defaultManager.items(QOrganizerItemLocation::match("Meeting Room 8"));

The above code will retrieve both items that have been saved to the manager and items which are generated based on recurrence rules. Given a recurring item, it is possible to retrieve a list of items that it generates; that is, to get a list of the upcoming occurrences of a single recurring item. This can be done using QOrganizerManager::itemOccurrences():

You can also retrieve a particular existing item from a manager, by directly requesting the item with a particular (previously known) id. The synchronous API provides the QOrganizerManager::item() function to retrieve a single item by its id. With the asynchronous API, this can be done using a QOrganizerItemFetchRequest and a QOrganizerItemIdFilter.

Updating an Existing Item

You can update a previously saved item retrieving the item, modifying it, and saving it back to the manager. The manager uses the id of the item to match up the provided item with the one in the database.

 journal.addComment("Serves: 8.  Ingredients: 500g Milk Chocolate, 500g Marshmallows."\
                 "  Step 1: Put the marshmallows into 8 separate bowls."\
                 "  Step 2: Melt the chocolate."\
                 "  Step 3: Pour the chocolate over the marshmallows in the bowls."\
                 "  Step 4: Put the bowls into the refrigerator for 20 minutes; serve chilled.");
 if (!defaultManager.saveItem(&journal))
     qDebug() << "Unable to save updated journal!  Error:" << defaultManager.error();

Removing an item from a manager

You can remove an item from the manager by using its id.

 defaultManager.removeItem(journal.id());

The Organizer Item Model

Items

A QOrganizerItem represents an event, todo, journal or note.

Each item stored in a manager is identified by a QOrganizerItemId. The id is the means by which the manager can:

  • Determine whether a save operation should make a new item or update an existing one. (If an item has a null id, it should be saved as a new item)
  • Match an item to an existing one for updating.
  • Link between items (for example, in QOrganizerItemParent).

The QOrganizerItem class provides a generic interface for accessing events, todos, journals and notes. To actually access specific fields of an item, convenience subclasses of QOrganizerItem are offered. These are QOrganizerEvent, QOrganizerTodo, QOrganizerJournal and QOrganizerNote. Additionally, QOrganizerEventOccurrence and QOrganizerTodoOccurrence can be used for manipulating occurrences of event or todos (see the Recurring Items section). Here is an example of how to retrieve details specific to an item:

 QList<QOrganizerItem> items = defaultManager.items();
 foreach (QOrganizerItem item, entries) {
     if (item.type() == QOrganizerItemType::TypeEvent) {
         QOrganizerEvent event(item);
         qDebug() << "Event:" << event.startDateTime() << ", " << event.displayLabel();
     } else if (item.type() == QOrganizerItemType::TypeEventOccurrence) {
         QOrganizerEventOccurrence event(item);
         qDebug() << "Event:" << event.startDateTime() << ", " << event.displayLabel();
     } else if (item.type() == QOrganizerItemType::TypeTodo) {
         // process todos
     } else if (item.type() == QOrganizerItemType::TypeTodoOccurrence) {
         // process recurring todos
     } else if (item.type() == QOrganizerItemType::TypeJournal) {
         // process journals
     } else if (item.type() == QOrganizerItemType::TypeNote) {
         // process notes
     }
 }

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 setting a QOrganizerRecurrenceRule on it to specify the rules for when it should recur. When QOrganizerManager::items() is called, recurring items are not returned. Rather, they expanded into multiple QOrganizerEventOccurrence and QOrganizerTodoOccurrence items. Each generated occurrence item has a null id.

You can 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 QOrganizerManager::items(), it will return the list of occurrences as before, but with the modifications in place. The modified item will be given a non-null id, and replaces the generated one in the list.

Here is an example of changing a single occurrence of an item:

 QOrganizerEventOccurrence nextMarshmallowMeeting = defaultManager.itemOccurrences(marshmallowMeeting).value(0);
 nextMarshmallowMeeting.setStartDateTime(QDateTime::fromString("13.05.2010 18:00:00", "dd.MM.yy hh:mm:ss"));
 nextMarshmallowMeeting.setEndDateTime(QDateTime::fromString("13.05.2010 20:00:00", "dd.MM.yy hh:mm:ss"));
 nextMarshmallowMeeting.addComment("The next meeting will go for an hour longer (starting one "\
                                   "hour earlier than usual), since we have scheduled one hour"\
                                   "to taste the results of the recipe that I will be presenting "\
                                   "at the meeting.");
 defaultManager.saveItem(&nextMarshmallowMeeting);

You can also query the manager for a list of unexpanded items by calling QOrganizerManager::itemsForExport(). The list of returned items will contain all items that have been saved to the manager with a call to QOrganizerManager::saveItem() That is, recurring events will be returned as is, and event occurrences will not appear unless they are exceptions (ie. have a non-null id). Fetching the list in this way can be useful for transfering items to other managers or for exporting to iCalendar with QtVersit.

Collections

Every item stored in a manager belongs to exactly one collection. A collection can have properties such as a name, a "color", a specified icon, a description, and so on. Collections may be added or removed if the manager supports those operations, or modified. There will always be at least one collection in a manager, and the manager will always have a default collection into which items are saved if no other collection is specified.

Some managers will allow users to create collections (for example, a "football fixtures" collection) while others may have built-in collections (for example, "work" and "home" collections).

A list of all collections can be retrieved from a manager with one function call:

 QList<QOrganizerCollection> collections = defaultManager.collections();

To save an item to a collection, set the collection ID on the item object. If the collection id is the null id, the item will be saved in the collection in which it is currently saved (if the item already exists) or into the manager's default collection (if it is a new item).

 marshmallowMeeting.setCollectionId(collection.id());
 defaultManager.saveItem(&marshmallowMeeting);

To retrieve all items in a collection, a QOrganizerItemCollectionFilter should be used.

 QOrganizerItemCollectionFilter collectionFilter;
 collectionFilter.setCollectionId(collection.id());
 items = defaultManager.items(collectionFilter);

All-day Events

Events and Todos can be specified as all-day or multi-day by setting the AllDay field to true (using QOrganizerEvent::setAllDay()). When this field is set to true, it means that the time portion of the StartDateTime and EndDateTime should be ignored. An event or todo marked as all-day should be considered to start and end roughly on its given start and end dates (inclusive), but without specifying exact times. For example, a birthday could be specified as an all-day QOrganizerEvent where the StartDateTime and EndDateTime have the same value.

API Usage

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 QOrganizerAbstractRequest class, including QOrganizerItemIdFetchRequest, QOrganizerItemFetchRequest, QOrganizerItemFetchForExportRequest, QOrganizerItemSaveRequest, QOrganizerItemRemoveRequest, QOrganizerItemOccurrenceFetchRequest, QOrganizerCollectionFetchRequest, QOrganizerCollectionRemoveRequest, QOrganizerCollectionSaveRequest, QOrganizerItemDetailDefinitionFetchRequest, QOrganizerItemDetailDefinitionSaveRequest, and QOrganizerItemDetailDefinitionRemoveRequest.

The asynchronous API allows manipulation of items, collections 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 QOrganizerManager class, and includes manipulation of items, collections 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.

More information

While the information on this page should be sufficient for the common use-cases, please see the discussion on Advanced Organizer API Usage for more details on the intricacies of the API.

It is possible for third party developers to implement a manager engine plugin from which clients may request data. For more information on this topic (for example, if you intend to implement a manager backend) please see Qt Organizer Manager Engines.

Reference documentation

Main Classes

QOrganizerAbstractRequest

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

QOrganizerCollection

Represents a collection of items in a manager

QOrganizerItem

Represents an event, todo, note, or journal entry

QOrganizerItemDetail

Represents a single, complete detail about an organizer item

QOrganizerItemFilter

Used to select organizer items made available through a QOrganizerManager

QOrganizerItemObserver

Simple class that emits a signal when a single particular item is updated or deleted

QOrganizerManager

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

QOrganizerItemDetail Leaf Classes

Several subclasses of QOrganizerItemDetail are provided as part of the QtMobility 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.

QOrganizerEventTime

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

QOrganizerItemAudibleReminder

Contains information about an audible reminder of an item

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

QOrganizerItemEmailReminder

Contains information about an email reminder of an item

QOrganizerItemGuid

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

QOrganizerItemLocation

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

QOrganizerItemParent

Contains information about the event or todo that generated this item

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

QOrganizerItemReminder

Contains information about when and how the user wants to reminded of the item

QOrganizerItemTag

Contains some arbitrary tag which is relevant to the organizer item

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

QOrganizerItemVisualReminder

Contains information about a visual reminder of an item

QOrganizerJournalTime

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

QOrganizerTodoTime

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

You 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 QOrganizerAbstractRequest class:

QOrganizerItemDetailDefinitionFetchRequest

Allows a client to asynchronously request detail definitions from an organizer item store manager

QOrganizerItemDetailDefinitionRemoveRequest

Allows a client to asynchronously request that certain detail definitions be removed from an organizer item manager

QOrganizerItemDetailDefinitionSaveRequest

Allows a client to asynchronously request that certain detail definitions be saved in an organizer item store manager

QOrganizerItemFetchByIdRequest

Allows a client to asynchronously request items from a items store manager, given a list of item IDs

QOrganizerItemFetchForExportRequest

Allows a client to asynchronously request organizer items from an organizer item store manager

QOrganizerItemFetchRequest

Allows a client to asynchronously request organizer items from an organizer item store manager

QOrganizerItemIdFetchRequest

Allows a client to asynchronously request a list of organizer item ids from a organizer item store manager

QOrganizerItemOccurrenceFetchRequest

Allows a client to asynchronously request occurrences generated by a recurring item

QOrganizerItemRemoveRequest

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

QOrganizerItemSaveRequest

Allows a client to asynchronously request that certain organizer items be saved to an organizer item store

Organizer Item Selection And Sorting

You 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 organizer item timestamp criterion

QOrganizerItemDetailFilter

Filter based around a detail value criterion

QOrganizerItemDetailRangeFilter

Filter based around a detail value range criterion

QOrganizerItemIdFilter

Filter based around a list of organizer item ids

QOrganizerItemIntersectionFilter

Filter which intersects the results of other filters

QOrganizerItemInvalidFilter

Matches no organizeritems

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:

QOrganizerCollectionEngineId

Uniquely identifies an item within a particular engine plugin

QOrganizerItemEngineId

Uniquely identifies an item within a particular engine plugin

QOrganizerManagerEngine

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

QOrganizerManagerEngineFactory

The interface for plugins that implement QOrganizerManagerEngine 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 QtMobility 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:

QML Elements

For details on the QML support provided for the Organizer API see the documentation for the Organizer QML Plugin.