The 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.
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).
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 QOrganizerManager::MutableDefinitions feature.
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 location, description, priority and recurrence details for events, but only description, display label and comments for journal items.
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.
The leaf details that form the default schema are as follows:
Contains the start and end dates and times of a recurring event series, or occurrence of an event | |
Contains information about an audible reminder of an item | |
Contains some arbitrary information which is relevant to the organizer item | |
Contains some arbitrary information which is relevant to the organizer item | |
Contains the backend-synthesized display label of the organizer item | |
Contains information about an email reminder of an item | |
Contains the globally unique identifier of the organizer item, which can be used for synchronization purposes | |
Contains information about a location which is related to the organizer item in some manner | |
Contains information about the event or todo that generated this item | |
Contains the priority of the organizer item, which may be used to resolve scheduling conflicts | |
Contains a list of rules and dates on which the recurrent item occurs, and a list of rules and dates on which exceptions occur | |
Contains information about when and how the user wants to reminded of the item | |
Contains some arbitrary tag which is relevant to the organizer item | |
Contains the creation and last-modified timestamp associated with the organizer item. XXX TODO: what about last accessed? | |
Describes the type of the organizer item. This detail may be automatically synthesized by the backend depending on other details in the organizer item | |
Contains information about a visual reminder of an item | |
Contains information about the date and time for which a journal entry has been created | |
Contains information about the progress of a todo item | |
Contains information about the time range of a todo item |
A uniqueness constraint on a detail definition means that for any 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:
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 QOrganizerItemDetail::Irremovable) or updated (if the access constraint is 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 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 QOrganizerManager::saveItem().
Please see the documentation of QOrganizerItemDetail for more information on access constraints.
The leaf classes which have access constraints in the default schema are as follows:
Furthermore, in the default schema, every item is required to have a QOrganizerItemType by default, which describes the type of information which the item represents (for example, an event or an agenda).
As described in the section on detail access constraints, some details are provided by the backend. When the client attempts to save a 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 QOrganizerItemTimestamp detail to a 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.