<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- organizeradvanced.qdoc -->
<title>Qt Mobility 1.2: Advanced Organizer API Usage</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>QtMobility Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Advanced Organizer API Usage</li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#introduction">Introduction</a></li>
<li class="level2"><a href="#the-detail-model">The Detail Model</a></li>
<li class="level2"><a href="#optimization-in-item-retrieval">Optimization in item retrieval</a></li>
<li class="level3"><a href="#detail-definitions">Detail Definitions</a></li>
<li class="level1"><a href="#the-organizer-manager-and-manager-engines">The Organizer Manager and Manager Engines</a></li>
<li class="level2"><a href="#the-organizer-manager">The Organizer Manager</a></li>
<li class="level2"><a href="#storage-considerations">Storage considerations</a></li>
<li class="level2"><a href="#schema-differences">Schema Differences</a></li>
<li class="level2"><a href="#provided-engines">Provided Engines</a></li>
<li class="level3"><a href="#in-memory-example-engine">In-Memory Example Engine</a></li>
<li class="level3"><a href="#symbian-engine">Symbian Engine</a></li>
<li class="level3"><a href="#maemo-5-fremantle-engine">Maemo 5 (Fremantle) Engine</a></li>
<li class="level1"><a href="#manager-settings-and-configuration">Manager Settings And Configuration</a></li>
<li class="level2"><a href="#querying-a-manager-for-capabilities">Querying a manager for capabilities</a></li>
<li class="level2"><a href="#loading-the-manager-for-a-specific-backend">Loading the manager for a specific backend</a></li>
<li class="level2"><a href="#loading-a-manager-with-specific-parameters">Loading a manager with specific parameters</a></li>
<li class="level2"><a href="#querying-the-schema-supported-by-a-manager">Querying the schema supported by a manager</a></li>
<li class="level2"><a href="#modifying-the-schema-supported-by-a-manager">Modifying the schema supported by a manager</a></li>
<li class="level2"><a href="#meta-data-api">Meta Data API</a></li>
</ul>
</div>
<h1 class="title">Advanced Organizer API Usage</h1>
<span class="subtitle"></span>
<!-- $$$organizeradvanced.html-description -->
<div class="descr"> <a name="details"></a>
<a name="introduction"></a>
<h2>Introduction</h2>
<p>This section provides some detailed information on more advanced topics regarding the Qt Organizer API.</p>
<a name="the-detail-model"></a>
<h3>The Detail Model</h3>
<p>While <a href="qorganizeritem.html">QOrganizerItem</a> and its subclasses provide methods for data access and manipulation which should be sufficient for most purposes, it is actually a generic container that can hold arbitrary data in the form of <i>details</i>. In fact, functions for manipulating items, such as <a href="qorganizeritem.html#displayLabel">QOrganizerItem::displayLabel</a>() or <a href="qorganizerevent.html#setRecurrenceRule">QOrganizerEvent::setRecurrenceRule</a>() are merely convenience functions that perform operations on the underlying details of an item. A <a href="qorganizeritem.html">QOrganizerItem</a> consists of nothing more than the details it contains, as well as an id and the id of its collection.</p>
<p>A <a href="qorganizeritemdetail.html">QOrganizerItemDetail</a> 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).</p>
<p>A list of all standard details defined by this API are listed <a href="organizer.html#qorganizeritemdetail-leaf-classes">here</a>.</p>
<p>Some details are read-only (such as the modification timestamp of an item) or irremovable (like the type of an item), but most are freely modifiable by clients. The <a href="qorganizeritem.html#details">QOrganizerItem::details</a>(), <a href="qorganizeritem.html#detail">QOrganizerItem::detail</a>(), <a href="qorganizeritem.html#saveDetail">QOrganizerItem::saveDetail</a>() and <a href="qorganizeritem.html#removeDetail">QOrganizerItem::removeDetail</a>() functions can be used to manipulate these details.</p>
<p>It is important to note that details are implicitly shared objects with particular semantics surrounding saving, removal and modification.</p>
<a name="optimization-in-item-retrieval"></a>
<h3>Optimization in item retrieval</h3>
<p>Clients can inform the manager that they do not require certain details from an item, which can allow a manager to optimize item retrieval. In this way, the client can inform the manager that they are not interested in any binary blob data (e.g., images) in retrieved items. These restrictions can be specified by providing a <a href="qorganizeritemfetchhint.html">QOrganizerItemFetchHint</a> as an argument to the retrieval operation.</p>
<p>Note that if the item already exists in the database, it will be completely replaced. This means that clients should not save any item which was retrieved with a non-empty fetchHint defined, or data loss may occur.</p>
<a name="detail-definitions"></a>
<h4>Detail Definitions</h4>
<p>Each detail stored in an item has defined semantics of usage and storage. The Qt Organizer API allows per-manager organizer item <a href="qorganizeritemdetaildefinition.html">detail definitions</a>, 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.</p>
<p><b>Most clients can safely ignore this class entirely</b>, since they will most likely want to use the predefined details listed <a href="organizer.html#qorganizeritemdetail-leaf-classes">here</a>. 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.</p>
<a name="the-organizer-manager-and-manager-engines"></a>
<h2>The Organizer Manager and Manager Engines</h2>
<a name="the-organizer-manager"></a>
<h3>The Organizer Manager</h3>
<p>Access to organizer items is provided by implementations of the Qt Organizer <a href="qorganizermanager.html">manager</a> API. Each manager 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 collections of organizer items stored in different datastores, in a platform and datastore independent manner.</p>
<p>The <a href="qorganizermanager.html">QOrganizerManager</a> is in fact a client-facing interface through to a platform-specific manager engine (which is implemented as a Qt plugin). While clients never interact directly with the manager engine, they may need to be aware of limitations of individual engines, or differences between engines. The API offered through <a href="qorganizermanager.html">QOrganizerManager</a> allows clients to retrieve this information for the engine which provides the functionality exposed through a particular <a href="qorganizermanager.html">QOrganizerManager</a>.</p>
<a name="storage-considerations"></a>
<h3>Storage considerations</h3>
<p>A <a href="qorganizermanagerengine.html">QOrganizerManagerEngine</a> may provide an aggregated view of multiple physical datastores, some of which may be remote datastores. Clients of the API are aware only that the data is managed by a <a href="qorganizermanagerengine.html">QOrganizerManagerEngine</a> with a particular URI. It is possible that multiple different engines will have overlap in the datastores which they aggregate, and in that case the way in which those engines were implemented will determine whether operations are thread-safe or not.</p>
<p>Since the data may physically be stored in a remote datastore, any operations may be dominated by the return-trip-time of communications with the remote datastore. As such, <b>it is recommended that clients use the asynchronous client API to access organizer information from any <a href="qorganizermanager.html">QOrganizerManager</a>.</b></p>
<a name="schema-differences"></a>
<h3>Schema Differences</h3>
<p>Please see the documentation on <a href="organizerschema.html">Qt Organizer Schema</a> model for background on this topic.</p>
<p>The save operation includes a validation step, where the item's details are checked against the supported schema. If the item is valid, it will be saved; otherwise, an error will occur.</p>
<p>Each engine may support a different schema (but that schema should be consistent within a manager - ie. it should be collection independent). All engines should attempt to support the default schema, described in the <a href="organizerschema.html">default schema</a> documentation, however clients should never assume that any engine does support the default schema fully.</p>
<p>Clients are able to retrieve the schema supported by a particular engine at run-time by calling <a href="qorganizermanager.html#detailDefinitions">QOrganizerManager::detailDefinitions</a>(). Some engines support different detail definitions (that is, a different schema) for different types of organizer items (events, todos, journals, notes and so forth). Clients can retrieve the organizer item types supported by an engine by calling <a href="qorganizermanager.html#supportedItemTypes">QOrganizerManager::supportedItemTypes</a>().</p>
<a name="provided-engines"></a>
<h3>Provided Engines</h3>
<p>The Organizer module of the QtMobility project includes several backends already, some of which are designed to interface with the default calendar on their particular platform.</p>
<a name="in-memory-example-engine"></a>
<h4>In-Memory Example Engine</h4>
<p>The in-memory engine identifies itself as the "memory" engine. It is available on all platforms which are supported by the QtMobility project.</p>
<p>The in-memory engine supports the default schema, and provides almost all functionality available through the QtMobility Organizer API; however, all data is stored in-memory and is not persisted in any way.</p>
<a name="symbian-engine"></a>
<h4>Symbian Engine</h4>
<p>The Symbian engine identifies itself as the "symbian" engine, and is only available on the Symbian S60 3.1, S60 3.2, S60 5.0 and Symbian^3 platforms.</p>
<p>The Symbian engine supports a modified version of the default schema. The schema supported by the Symbian engine depends on which version of the platform is being used.</p>
<p>The Symbian engine allows clients to use both the asynchronous and synchronous interfaces, and persists all saved data to the system calendar.</p>
<a name="maemo-5-fremantle-engine"></a>
<h4>Maemo 5 (Fremantle) Engine</h4>
<p>The Maemo 5 (Fremantle) engine identifies itself as the "maemo5" engine, but is only available on the Maemo 5 (Fremantle) platform which has the correct libraries installed (including calendar-backend).</p>
<p>The Maemo 5 (Fremantle) engine supports a modified version of the default schema, and persists all saved information to the system calendar.</p>
<a name="manager-settings-and-configuration"></a>
<h2>Manager Settings And Configuration</h2>
<p>Users of the items API can define which backend they wish to access if a manager for that backend is available. The list of available managers can be queried programmatically at run-time, and the capabilities of different managers can be ascertained by inspecting a <a href="qorganizermanager.html">QOrganizerManager</a> instance. Furthermore, some managers can be constructed with parameters which affect the operation of the backend.</p>
<a name="querying-a-manager-for-capabilities"></a>
<h3>Querying a manager for capabilities</h3>
<p>Different managers will support different capabilities and details. Clients can use the meta data reporting functions of <a href="qorganizermanager.html">QOrganizerManager</a> to determine what the capabilities of the manager they have instantiated might be.</p>
<a name="loading-the-manager-for-a-specific-backend"></a>
<h3>Loading the manager for a specific backend</h3>
<p>The client can choose to load a manager for a specific backend. While the engine could be found and retrieved using a more advanced plugin framework (such as the Qt Service Framework), this code assumes that the client has prior knowledge of the backend in question:</p>
<pre class="cpp"> <span class="type"><a href="qorganizermanager.html">QOrganizerManager</a></span> specificManager(<span class="string">"symbian"</span>);</pre>
<p>Clients may wish to use this feature of the API if they wish to store or retrieve item information to a particular manager (for example, one that interfaces with a particular online service).</p>
<a name="loading-a-manager-with-specific-parameters"></a>
<h3>Loading a manager with specific parameters</h3>
<p>The client can load a manager with specific parameters defined. The parameters which are available are backend specific, and so the client has to know which parameters are valid for a particular backend, and what argument it takes.</p>
<a name="querying-the-schema-supported-by-a-manager"></a>
<h3>Querying the schema supported by a manager</h3>
<p>A client may query the schema supported by a manager, and check to see if a particular detail definition supports a certain field.</p>
<a name="modifying-the-schema-supported-by-a-manager"></a>
<h3>Modifying the schema supported by a manager</h3>
<p>A client may attempt to modify a particular detail definition by extending it so that it supports an extra field, or add a new detail definition, or remove an existing one. These operations are not necessarily supported on various backends, and even those backends which do support a mutable schema may not allow modification of the default detail definitions.</p>
<p>Note that some managers do not support mutable definitions, and hence attempting to modify or remove detail definitions in those managers will fail.</p>
<a name="meta-data-api"></a>
<h3>Meta Data API</h3>
<p>The <a href="qorganizermanager.html">QOrganizerManager</a> class provides a static function <a href="qorganizermanager.html#availableManagers">QOrganizerManager::availableManagers</a>() which allows clients of the API to determine (at run time) which plugins (managers) are available for use.</p>
<p>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 <a href="qorganizermanager.html">QOrganizerManager</a> class provides API to query the capabilities of a given manager with the following synchronous functions:</p>
<ul>
<li><a href="qorganizermanager.html#hasFeature">hasFeature()</a></li>
<li><a href="qorganizermanager.html#isFilterSupported">isFilterSupported()</a></li>
<li><a href="qorganizermanager.html#supportedItemTypes">supportedItemTypes()</a></li>
</ul>
<p>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).</p>
<p>The synchronous API offered to allow run-time querying of a manager's metadata includes:</p>
<ul>
<li><a href="qorganizermanager.html#managerName">managerName</a></li>
<li><a href="qorganizermanager.html#managerParameters">managerParameters</a></li>
<li><a href="qorganizermanager.html#managerUri">managerUri</a></li>
<li><a href="qorganizermanager.html#managerVersion">managerVersion</a></li>
<li><a href="qorganizermanager.html#parseUri">parseUri</a></li>
<li><a href="qorganizermanager.html#buildUri">buildUri</a></li>
</ul>
<p>The functionality that the above functions provide is only available through synchronous API.</p>
</div>
<!-- @@@organizeradvanced.html -->
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2008-2011 Nokia Corporation and/or its
subsidiaries. Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide.</p>
<p>
All other trademarks are property of their respective owners. <a title="Privacy Policy"
href="http://qt.nokia.com/about/privacy-policy">Privacy Policy</a></p>
<br />
<p>
Licensees holding valid Qt Commercial licenses may use this document in accordance with the Qt Commercial License Agreement provided with the Software or, alternatively, in accordance with the terms contained in a written agreement between you and Nokia.</p>
<p>
Alternatively, this document may be used under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU
Free Documentation License version 1.3</a>
as published by the Free Software Foundation.</p>
</div>
</body>
</html>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-release
>
by-pkgid
>
50facae208d4a6f280e44a513b104320
>
files
>
539
