qtpim5-doc-html 5.0~git20140515~29475884-0ubuntu24~7 / usr / share / qt5 / doc / qtcontacts / qtcontacts-overview.html

This file is indexed.

/usr/share/qt5/doc/qtcontacts/qtcontacts-overview.html is in qtpim5-doc-html 5.0~git20140515~29475884-0ubuntu24~7.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- contacts.qdoc -->
  <title>Qt Contacts Overview | Qt 5.0</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td >Qt 5.0</td><td >Qt Contacts Overview</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.0.0 Reference Documentation</td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#client-facing-api">Client-Facing API</a></li>
<li class="level2"><a href="#container-classes">Container Classes</a></li>
<li class="level2"><a href="#manager">Manager</a></li>
<li class="level2"><a href="#actions">Actions</a></li>
<li class="level1"><a href="#non-client-facing-api">Non-Client-Facing API</a></li>
<li class="level2"><a href="#manager-engine">Manager Engine</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Contacts Overview</h1>
<span class="subtitle"></span>
<!-- $$$qtcontacts-overview.html-description -->
<div class="descr"> <a name="details"></a>
<p>The Qt Contacts API enables a client to request contact data from local or remote backends in a platform-independent and datastore-agnostic manner. This is achieved by defining generic personal information data abstractions which can sufficiently describe contact data stored on any platform. Due to the cross-platform nature of the API, and the ability for developers to write platform-independent implementations of a <a href="qcontactmanager.html">QContactManager</a> which may unify one or more platform-specific contact backends, it is intended that the semantics and quirks of the underlying datastores on any platform may be entirely opaque from the perspective of Qt-based, cross-platform client applications.</p>
<p>Contact information is stored in datastores whose functionality is exposed via a <a href="qcontactmanager.html">manager</a>. The Qt Contacts API models a <a href="qcontact.html">contact</a> as a collection of distinct details. Individual contacts may be related to one other, and these <a href="qcontactrelationship.html">relationships</a> are stored separately from contacts themselves and may be manipulated directly by clients.</p>
<p><a href="qcontact.html">Contact</a>, and <a href="qcontactrelationship.html">relationship</a> information may all be retrieved, modified or deleted by clients using either the <a href="contactssync.html">synchronous</a> or <a href="contactsasync.html">asynchronous</a> API.</p>
<p>For a full list of classes, see <a href="qtcontacts-module.html">Qt Contacts C++ Classes</a>.</p>
<a name="client-facing-api"></a>
<h2 id="client-facing-api">Client-Facing API</h2>
<p>The client-facing API allows retrieval, modification and deletion of contacts, and relationships, as well as access to manager meta data and capability reporting.</p>
<a name="container-classes"></a>
<h3 >Container Classes</h3>
<p>Contact information is stored in container (value) classes. These classes are not derived from QObject, and hence can be used in lists. They do not have parents, do not emit signals, and so on. They represent data which may be manipulated and retrieved from a <a href="qtcontacts-overview.html#manager">manager</a>.</p>
<a name="contact"></a>
<h4 >Contact</h4>
<p>A <a href="qcontact.html">contact</a> is the digital representation of a person, group or entity, which is stored in a platform-specific manner. Information pertaining to a single contact may be located across several different datastores, and each datum (or detail) may or may not pertain to a particular context in which that information is valid. A contact may include semantically identical pieces of information that are relevant in different contexts. For example, a contact may have a phone number that is relevant to their <i>home</i> context, and another phone number that is relevant to their <i>work</i> context. It can be seen that the context of information defines its validity to the user, depending on the context of usage; and as such, the sum of information in a given context can be considered equivalent to a <i>contextual identity</i>. This allows great flexibility when consolidating data from various sources into a single, cohesive contact.</p>
<p>Each contact stored in a manager is identified by an <a href="qcontactid.html">id</a> which consists of a manager identifier (URI) and the <a href="qcontactid.html">QContactId</a> manager-local id which is used to identify the contact in that manager. Note that a contact stored in one manager may have the same local id as a different contact stored in another manager; please see the <a href="qcontactid.html">QContactId</a> documentation for more information.</p>
<a name="detail"></a>
<h4 >Detail</h4>
<p>A <a href="qcontactdetail.html">detail</a> is a single, cohesive unit of information that is stored in a contact. As explained previously, it is valid for a particular context or set of contexts. A detail may have specific metadata associated with it, such as its sub-type or context, as well as access constraints which may apply to the the detail (such as read-only, irremovable, etc).</p>
<p>There are a number of common details defined in the API which are intended for use by clients, as listed in <a href="contactsclasses.html#contact-details-leaf-classes">Contact Details Leaf Classes</a>.</p>
<a name="relationships"></a>
<h4 >Relationships</h4>
<p>Contacts may participate in <a href="qcontactrelationship.html">relationships</a> with other contacts. The details of any such relationship is stored by the manager which contains the contact. There are several standard relationship types supported by default, and arbitrary relationship types are also allowed if the manager supports that feature. One important relationship is that of group membership. Membership of a contact in a group can be modeled as that group contact participating in a <code>HasMember</code> relationship with the contact.</p>
<a name="manager"></a>
<h3 >Manager</h3>
<p>Access to contacts is provided by implementations of the Qt Contacts <a href="qcontactmanager.html">manager</a> API. A manager provides access to zero or more platform-specific datastores. Each datastore may support different capabilities (for example, the ability to store certain datatypes, the ability to natively filter on different details, 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 contacts and relationships stored in different datastores, in a platform and datastore independent manner.</p>
<a name="meta-data-api"></a>
<h4 >Meta Data API</h4>
<p>The API offered by the <a href="qcontactmanager.html">QContactManager</a> exposes functionality which is implemented by plugins. These plugins may be platform specific, and may be provided by Nokia or by third party developers. As described above, each plugin will have different capabilities and implement the functionality exposed by the Qt Contacts API to a different degree.</p>
<p>The <a href="qcontactmanager.html">QContactManager</a> class provides a static function <a href="qcontactmanager.html#availableManagers">QContactManager::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 (contact manager) are. The <a href="qcontactmanager.html">QContactManager</a> class provides an API to query the capabilities of a given manager with the following synchronous functions:</p>
<ul>
<li>isFilterSupported(const <a href="qcontactfilter.html">QContactFilter</a>&amp; filter) const</li>
<li>isRelationshipTypeSupported(const QString&amp; relationshipType, const QString&amp; contactType = QContactType::TypeContact) const</li>
<li>supportedDataTypes() const</li>
<li>supportedContactTypes() const</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 contact 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>managerName() const</li>
<li>managerParameters() const</li>
<li>managerUri() const</li>
<li>managerVersion() const;</li>
<li>(static) parseUri(const QString&amp; uri, QString* managerName, QMap&lt;QString, QString&gt;* params)</li>
<li>(static) buildUri(const QString&amp; managerName, const QMap&lt;QString, QString&gt;&amp; params, int implementationVersion = -1)</li>
</ul>
<p>The functionality that the above functions provide is only available through synchronous API.</p>
<a name="asynchronous-api"></a>
<h4 >Asynchronous API</h4>
<p>The asynchronous API provides a way to access or modify the contact 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.</p>
<p>The asynchronous API is offered through various classes derived from the <a href="qcontactabstractrequest.html">QContactAbstractRequest</a> class, including <a href="qcontactidfetchrequest.html">QContactIdFetchRequest</a>, <a href="qcontactfetchrequest.html">QContactFetchRequest</a>, <a href="qcontactsaverequest.html">QContactSaveRequest</a>, <a href="qcontactremoverequest.html">QContactRemoveRequest</a>, <a href="qcontactrelationshipfetchrequest.html">QContactRelationshipFetchRequest</a>, <a href="qcontactrelationshipsaverequest.html">QContactRelationshipSaveRequest</a>, and <a href="qcontactrelationshipremoverequest.html">QContactRelationshipRemoveRequest</a>.</p>
<p>The asynchronous API allows manipulation of <a href="qcontact.html">contacts</a> and <a href="qcontactrelationship.html">contact relationships</a>, but does not provide manager capability or meta data information reporting.</p>
<a name="synchronous-api"></a>
<h4 >Synchronous API</h4>
<p>The synchronous API provides the simplest way to access or modify the contact 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.</p>
<p>The synchronous API is offered through the <a href="qcontactmanager.html">QContactManager</a> class, and includes manipulation of <a href="qcontact.html">contacts</a> and <a href="qcontactrelationship.html">contact relationships</a>. As previously described, the meta data reporting and manipulation functions are also provided via synchronous API only.</p>
<a name="actions"></a>
<h3 >Actions</h3>
<p>Clients can perform <a href="qcontactaction.html">actions</a> on contacts which support them. Actions are things like <i>Send Email</i> or <i>Dial</i>, and can be provided from various sources including Qt Plugins or the Qt Service Framework. Every action implementation is uniquely identified by a combination of its name, the name of the service which provided the implementation, and the version of the implementation. These pieces of data may be encapsulated in a <a href="qcontactactiondescriptor.html">QContactActionDescriptor</a> which can be used to retrieve an instance of the implementation from a <a href="qcontactactionfactory.html">QContactActionFactory</a>.</p>
<p>Different actions will allow (or require) different parameters to invocation. For example, an action which allows clients to send emails to a contact may be able to accept attachments as a parameter to invocation. Each action must be invoked on an <a href="qcontactactiontarget.html">action target</a> or list of targets, where a target may be a contact or a specific detail of a particular contact.</p>
<a name="non-client-facing-api"></a>
<h2 id="non-client-facing-api">Non-Client-Facing API</h2>
<p>The non-client-facing API allows third party developers to implement a manager engine plugin from which clients may request data.</p>
<a name="manager-engine"></a>
<h3 >Manager Engine</h3>
<p>The functionality exposed by the <a href="qcontactmanager.html">QContactManager</a> class may be implemented by engine plugins which interface directly to a platform-specific backend or provide their own data storage backend. As such, the terms <i>manager</i>, <i>plugin</i> and <i>backend</i> are used interchangeably in this documentation to refer to any engine plugin which implements the functionality exposed by the <a href="qcontactmanager.html">QContactManager</a> interface. The plugin architecture allows dynamic loading of different manager engines at runtime.</p>
<p>A manager backend may be implemented by subclassing QContactManagerEngine, and providing a QContactManagerEngineFactory which can instantiate it when required.</p>
<p>For more information on the available engines and how to write your own engine, see <a href="contactsengines.html">Qt Contacts Manager Engines</a>.</p>
</div>
<p><b>See also </b><a href="contactsusage.html">Qt Contacts API Usage</a>, <a href="qml-contacts.html">Qt Contacts QML API</a>, <a href="contactsasync.html">Qt Contacts Asynchronous API</a>, <a href="contactssync.html">Qt Contacts Synchronous API</a>, and <a href="contactsactions.html">Qt Contacts Action API</a>.</p>
<!-- @@@qtcontacts-overview.html -->
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2017 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed 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.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>

APT Browse - Built by Thomas Orozco.