Sophie

Sophie

distrib > Mageia > 5 > i586 > media > core-release > by-pkgid > 50facae208d4a6f280e44a513b104320 > files > 162

qt-mobility-doc-1.2.0-13.mga5.noarch.rpm

<?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" />
<!-- contactsschema.qdoc -->
  <title>Qt Mobility 1.2: Qt Contacts Schema</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>Qt Contacts Schema</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="level1"><a href="#schema-definition">Schema Definition</a></li>
<li class="level1"><a href="#default-schema">Default Schema</a></li>
<li class="level2"><a href="#detail-definition-uniqueness">Detail Definition Uniqueness</a></li>
<li class="level2"><a href="#detail-access-constraints">Detail Access Constraints</a></li>
<li class="level2"><a href="#backend-provided-details">Backend-provided Details</a></li>
</ul>
</div>
<h1 class="title">Qt Contacts Schema</h1>
<span class="subtitle"></span>
<!-- $$$contactsschema.html-description -->
<div class="descr"> <a name="details"></a>
<a name="introduction"></a>
<h2>Introduction</h2>
<p>The <a href="contacts.html">Qt Contacts API</a> 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 provided by the <a href="contacts.html">Qt Contacts API</a> is updated with every release of QtMobility, so the function which returns the default schema definitions can take an integer which identifies the schema version which the engine writer developed against. Engine writers should call <a href="qcontactmanagerengine.html#schemaDefinitions">schemaDefinitions()</a> in their code which generates the manager-specific schema (which is returned to clients when they call <a href="qcontactmanager.html#detailDefinitions">QContactManager::detailDefinitions</a>()).</p>
<p>The <a href="qcontactmanagerengine.html#schemaDefinitions">schemaDefinitions()</a> function should NOT be called by clients; rather, clients should call <a href="qcontactmanager.html#detailDefinitions">QContactManager::detailDefinitions</a>() instead.</p>
<a name="schema-definition"></a>
<h2>Schema Definition</h2>
<p>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 (for example, a logo field for organization details).</p>
<p>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 <a href="qcontactphonenumber.html">QContactPhoneNumber</a> type (that is, details whose definition name is &quot;<a href="qml-phonenumber.html">PhoneNumber</a>&quot;) with reasonable certainty that the data returned is a phone number.</p>
<p>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.</p>
<a name="default-schema"></a>
<h2>Default Schema</h2>
<p>The leaf details that form the current version of the default schema are as follows: <table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactaddress.html">QContactAddress</a></p></td><td class="tblDescr"><p>Contains an address of a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactanniversary.html">QContactAnniversary</a></p></td><td class="tblDescr"><p>Contains an anniversary of a contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactavatar.html">QContactAvatar</a></p></td><td class="tblDescr"><p>Contains avatar URLs of a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactbirthday.html">QContactBirthday</a></p></td><td class="tblDescr"><p>Contains a birthday of a contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a></p></td><td class="tblDescr"><p>The (possibly synthesized) display label of a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactemailaddress.html">QContactEmailAddress</a></p></td><td class="tblDescr"><p>Contains an email address of a contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactfamily.html">QContactFamily</a></p></td><td class="tblDescr"><p>Contains names of family members of a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactfavorite.html">QContactFavorite</a></p></td><td class="tblDescr"><p>Indicates if a contact is a favorite contact as well as the position it should appear in an ordered list of favorites</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactgender.html">QContactGender</a></p></td><td class="tblDescr"><p>Contains the gender of a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactgeolocation.html">QContactGeoLocation</a></p></td><td class="tblDescr"><p>Contains a global location coordinate associated with a contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactglobalpresence.html">QContactGlobalPresence</a></p></td><td class="tblDescr"><p>Aggregated presence information for a contact, synthesized or supplied by the backend</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactguid.html">QContactGuid</a></p></td><td class="tblDescr"><p>Contains a globally unique Id of a contact, for use in synchronization with other datastores</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontacthobby.html">QContactHobby</a></p></td><td class="tblDescr"><p>Contains a hobby of the contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactname.html">QContactName</a></p></td><td class="tblDescr"><p>Contains a name of a contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactnickname.html">QContactNickname</a></p></td><td class="tblDescr"><p>Contains a nickname of a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactnote.html">QContactNote</a></p></td><td class="tblDescr"><p>Contains a note associated with a contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactonlineaccount.html">QContactOnlineAccount</a></p></td><td class="tblDescr"><p>Online account, which the contact uses to communicate with friends and family</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactorganization.html">QContactOrganization</a></p></td><td class="tblDescr"><p>Details about an organization that the contact is either a part of, or stands for</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactphonenumber.html">QContactPhoneNumber</a></p></td><td class="tblDescr"><p>Phone number of a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactpresence.html">QContactPresence</a></p></td><td class="tblDescr"><p>Presence information for an online account of a contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontactringtone.html">QContactRingtone</a></p></td><td class="tblDescr"><p>Ringtone associated with a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactsynctarget.html">QContactSyncTarget</a></p></td><td class="tblDescr"><p>Sync target for a contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontacttag.html">QContactTag</a></p></td><td class="tblDescr"><p>Contains a tag associated with a contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontactthumbnail.html">QContactThumbnail</a></p></td><td class="tblDescr"><p>Contains a thumbnail used in display lists to represent the contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontacttimestamp.html">QContactTimestamp</a></p></td><td class="tblDescr"><p>Contains the creation and last-modified timestamp associated with the contact</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qcontacttype.html">QContactType</a></p></td><td class="tblDescr"><p>Describes the type of the contact</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qcontacturl.html">QContactUrl</a></p></td><td class="tblDescr"><p>Contains a url associated with a contact</p></td></tr>
</table>
</p>
<p>Note that the following leaf details were added to the default schema in version 1.1 of the QtMobility project:</p>
<ul>
<li><a href="qcontactfamily.html">QContactFamily</a></li>
<li><a href="qcontactfavorite.html">QContactFavorite</a></li>
</ul>
<a name="detail-definition-uniqueness"></a>
<h3>Detail Definition Uniqueness</h3>
<p>A uniqueness constraint on a detail definition means that for any <a href="qcontact.html">QContact</a>, only one detail of that definition may be saved.</p>
<p>The leaf classes which have a uniqueness constraint in the default schema are as follows:</p>
<ul>
<li><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a></li>
<li><a href="qcontacttype.html">QContactType</a></li>
<li><a href="qcontactsynctarget.html">QContactSyncTarget</a></li>
<li><a href="qcontactguid.html">QContactGuid</a></li>
</ul>
<a name="detail-access-constraints"></a>
<h3>Detail Access Constraints</h3>
<p>Some details in a contact 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 <tt>QContactDetail::Irremovable</tt>) or updated (if the access constraint is <tt>QContactDetail::ReadOnly</tt>) by the client. If the client attempts to save an updated version of a read-only detail in a contact, or remove a detail which is irremovable from a contact, the operation will succeed; however those updates to the contact will be ignored by the manager when the contact is saved there.</p>
<p>For example, the <a href="qcontactdisplaylabel.html">QContactDisplayLabel</a> is defined in the default schema as a read-only, irremovable detail, meaning that it may not be modified or deleted by the client, but are provided by the backend (in the case of <a href="qcontactdisplaylabel.html">QContactDisplayLabel</a>, automatically synthesized by the backend from various details of the contact, like the <a href="qcontactname.html">QContactName</a>, <a href="qcontactnickname.html">QContactNickname</a>, etc).</p>
<p>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 contact (that is, the contact 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 <a href="qcontacttype.html">QContactType</a> detail, which is irremovable but may be updated by clients as desired. Details with no constraint may be added, updated and removed as desired by the client. Changes to such details in a contact will be persisted in the manager when the client calls <a href="qcontactmanager.html#saveContact">QContactManager::saveContact</a>().</p>
<p>Please see the documentation of <a href="qcontactdetail.html">QContactDetail</a> for more information on access constraints.</p>
<p>The leaf classes which have access constraints in the default schema are as follows:</p>
<ul>
<li><a href="qcontactguid.html">QContactGuid</a> is <tt>QContactDetail::ReadOnly</tt> and <tt>QContactDetail::Irremovable</tt></li>
<li><a href="qcontactsynctarget.html">QContactSyncTarget</a> is <tt>QContactDetail::ReadOnly</tt> and <tt>QContactDetail::Irremovable</tt></li>
<li><a href="qcontacttimestamp.html">QContactTimestamp</a> is <tt>QContactDetail::ReadOnly</tt> and <tt>QContactDetail::Irremovable</tt></li>
<li><a href="qcontactpresence.html">QContactPresence</a> is <tt>QContactDetail::ReadOnly</tt> and <tt>QContactDetail::Irremovable</tt></li>
<li><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a> is <tt>QContactDetail::ReadOnly</tt> and <tt>QContactDetail::Irremovable</tt></li>
<li><a href="qcontacttype.html">QContactType</a> is <tt>QContactDetail::Irremovable</tt></li>
</ul>
<p>Furthermore, in the default schema, every contact is required to have at least two details by default: a <a href="qcontacttype.html">QContactType</a> which describes the type of entity that the contact represents (for example, a person or a group), and a <a href="qcontactdisplaylabel.html">QContactDisplayLabel</a> which holds the default display label for the contact.</p>
<a name="backend-provided-details"></a>
<h3>Backend-provided Details</h3>
<p>As described in the section on detail access constraints, some details are provided by the backend, such as <a href="qcontactdisplaylabel.html">QContactDisplayLabel</a> and <a href="qcontactpresence.html">QContactPresence</a>. When the client attempts to save a <a href="qcontact.html">QContact</a> 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 <a href="qcontactpresence.html">QContactPresence</a> detail to a <a href="qcontact.html">QContact</a>, it will not be persisted in the manager when the client attempts to save that contact.</p>
<p>Precisely which details are backend-provided is backend specific; some backends provide more details than others.</p>
</div>
<!-- @@@contactsschema.html -->
  <div class="ft">
    <span></span>
  </div>
</div> 
<div class="footer">
  <p>
     <acronym title="Copyright">&copy;</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>