/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/


/*!

\page organizerschema.html

\title Qt Organizer Schema

\tableofcontents

\section1 Introduction

The \l{Organizer}{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.

\section1 Schema Definition

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.

\section1 Default Schema

The leaf details that form the default schema are as follows:
\annotatedlist organizer-details

\section2 Detail Definition Uniqueness

A uniqueness constraint on a detail definition means that for any \l{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:
\list
    \o \l{QOrganizerItemDisplayLabel}
    \o \l{QOrganizerItemDescription}
    \o \l{QOrganizerItemType}
    \o \l{QOrganizerItemGuid}
\endlist

\section2 Detail Access Constraints

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 \c QOrganizerItemDetail::Irremovable)
or updated (if the access constraint is \c 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 \l{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 \l{QOrganizerManager::saveItem()}.

Please see the documentation of \l{QOrganizerItemDetail} for more information on access constraints.

The leaf classes which have access constraints in the default schema are as follows:
\list
    \o \l{QOrganizerItemGuid} is \c QOrganizerItemDetail::ReadOnly and \c QOrganizerItemDetail::Irremovable
    \o \l{QOrganizerItemTimestamp} is \c QOrganizerItemDetail::ReadOnly and \c QOrganizerItemDetail::Irremovable
    \o \l{QOrganizerItemType} is \c QOrganizerItemDetail::Irremovable
\endlist

Furthermore, in the default schema, every item is required to have a \l{QOrganizerItemType} by default, which describes
the type of information which the item represents (for example, an event or an agenda).

\section2 Backend-provided Details

As described in the section on detail access constraints, some details are provided by the backend.
When the client attempts to save a \l{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
\l{QOrganizerItemTimestamp} detail to a \l{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.


*/