/usr/share/qt5/doc/qtcontacts/contactsengines.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 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- contactsengines.qdoc -->
<title>Qt Contacts Manager Engines | 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 Manager Engines</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="#information-for-clients">Information for Clients</a></li>
<li class="level2"><a href="#where-is-the-data-stored">Where Is the Data Stored?</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="level1"><a href="#information-for-engine-implementors">Information For Engine Implementors</a></li>
<li class="level2"><a href="#which-functions-do-i-need-to-implement">Which Functions Do I Need to Implement?</a></li>
<li class="level2"><a href="#which-signals-do-i-need-to-emit">Which Signals Do I Need to Emit?</a></li>
<li class="level2"><a href="#other-considerations">Other Considerations</a></li>
<li class="level2"><a href="#example-implementation">Example Implementation</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Contacts Manager Engines</h1>
<span class="subtitle"></span>
<!-- $$$contactsengines.html-description -->
<div class="descr"> <a name="details"></a>
<p>The <a href="qcontactmanager.html">QContactManager</a> interface provided to clients to allow access to contact information depends on an implementation of QContactManagerEngine existing. This engine provides the methods which are called by the manager. An engine is identified by its URI, which is the name reported to clients through the <a href="qcontactmanager.html#managerUri">QContactManager::managerUri</a>() function. The URI of a manager is built by combining its name, version and relevant construction parameters.</p>
<a name="information-for-clients"></a>
<h2 id="information-for-clients">Information for Clients</h2>
<p>While clients never interact directly with instances of QContactManagerEngine, they may need to be aware of limitations of individual engines, or differences between engines. The API offered through <a href="qcontactmanager.html">QContactManager</a> allows clients to retrieve this information for the engine which provides the functionality exposed through a particular <a href="qcontactmanager.html">QContactManager</a>.</p>
<a name="where-is-the-data-stored"></a>
<h3 >Where Is the Data Stored?</h3>
<p>A QContactManagerEngine may provide an aggregated view of multiple physical datastores, zero or more of which may be remote datastores. Clients of the API are aware only that the data is managed by a QContactManagerEngine 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, it is recommended that clients use the asynchronous client API to access contact information from any <a href="qcontactmanager.html">QContactManager</a>.</p>
<a name="schema-differences"></a>
<h3 >Schema Differences</h3>
<p>Each engine may support a different schema. All engines should attempt to support the default schema, described in the default schema documentation, however clients should never assume that any engine does support the default schema fully.</p>
<p>Some engines support different types of contacts. Clients can retrieve the contact types supported by an engine by calling <a href="qcontactmanager.html#supportedContactTypes">QContactManager::supportedContactTypes</a>().</p>
<a name="provided-engines"></a>
<h3 >Provided Engines</h3>
<p>The Qt PIM AddOn includes the Contacts module which includes several backends already, some of which are designed to interface with the default addressbook 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 <i>memory</i> engine. It is available on all platforms which are supported by the Qt PIM AddOn.</p>
<p>The in-memory engine supports the default schema, and provides all functionality available through the Contacts API; however, all data is stored in-memory and is not persisted in any way.</p>
<a name="information-for-engine-implementors"></a>
<h2 id="information-for-engine-implementors">Information For Engine Implementors</h2>
<p>Some developers may wish to provide implementations of QContactManagerEngine for use by clients. The engine that they provide may aggregate multiple datastores, or access a remote datastore, or provide some other functionality to clients. An engine is distributed as a Qt Plugin, and will be detected automatically by the plugin loading code in the <a href="qcontactmanager.html">QContactManager</a>, so long as the plugin is located in the correct path ($QT_PLUGINS_DIR/contacts/).</p>
<a name="which-functions-do-i-need-to-implement"></a>
<h3 >Which Functions Do I Need to Implement?</h3>
<p>Different engines provide different functionality and support different features. Depending on the feature set of the engine, it will need to implement a particular subset of the API. The default implementation for most functions will set the error to <code>QContactManager::NotSupportedError</code> and return the value which indicates that an error has occurred.</p>
<a name="mandatory-functions"></a>
<h4 >Mandatory Functions</h4>
<p>All engines must implement the following functions:</p>
<ul>
<li>QContactManagerEngine::managerName()</li>
<li>QContactManagerEngine::managerVersion()</li>
<li>QContactManagerEngine::supportedContactTypes()</li>
<li>QContactManagerEngine::supportedDataTypes()</li>
<li>QContactManagerEngine::contactIds()</li>
<li>QContactManagerEngine::contacts()</li>
</ul>
<p>Every engine implementation must also come with an implementation of QContactManagerEngineFactory for that engine.</p>
<p>Note that you do not need to implement filtering and sorting natively in an engine; the default implementation offers the following static functions to perform filtering and sorting respectively, in memory:</p>
<ul>
<li>QContactManagerEngine::testFilter()</li>
<li>QContactManagerEngine::sortContacts()</li>
</ul>
<p>However, engine implementors should be aware that the default implementation is naive and will have greatly reduced performance compared to a native implementation (e.g., SQL queries, if the contact data exposed by the engine implementation is stored in an SQL database).</p>
<p>Similarly, any <a href="qcontactfetchhint.html">QContactFetchHint</a> parameter may be ignored by an engine implementation, but if it does so it must return all information available for the contact.</p>
<p>All engines must also implement the following functions to implement asynchronous requests:</p>
<ul>
<li>QContactManagerEngine::requestDestroyed()</li>
<li>QContactManagerEngine::startRequest()</li>
<li>QContactManagerEngine::cancelRequest()</li>
<li>QContactManagerEngine::waitForRequestFinished()</li>
</ul>
<p>If the engine does not support asynchronous requests, it should always return false in the last three of those functions, and do nothing in the first. If the engine does support asynchronous requests, it must ensure that all information required to perform the request is saved in the engine within QContactManagerEngine::startRequest(), as the client owns the request object and may delete it at any time. In general, engine implementors should be aware of this ownership semantic, and never attempt an unsafe operation on a request pointer.</p>
<p>It is recommended that all engine implementations support asynchronous requests, even if they use a "dummy" implementation which services the request synchronously during startRequest, and then emit the appropriate signals from the request via a zero-millisecond timeout timer.</p>
<a name="optional-functionality"></a>
<h4 >Optional Functionality</h4>
<p>The rest of the virtual functions are optional, and should be implemented only if the engine supports the operations.</p>
<p>If the engine can be constructed with different parameters, which affects the operation of the engine (for example, a parameter might define which file to read contact information from, or it might be an access token to prove that the client has the access rights to read contact information from the engine, etc), it must report which parameters it was constructed with via the</p>
<ul>
<li>QContactManagerEngine::managerParameters()</li>
</ul>
<p>function.</p>
<p>If the engine supports native filtering of any kind, it must report to clients which filters are supported natively by implementing:</p>
<ul>
<li>QContactManagerEngine::isFilterSupported()</li>
</ul>
<p>If the engine supports saving or removing contact information, as well as retrieval, it must implement:</p>
<ul>
<li>QContactManagerEngine::saveContacts()</li>
<li>QContactManagerEngine::removeContacts()</li>
</ul>
<p>It may also choose to implement the "single contact" functions:</p>
<ul>
<li>QContactManagerEngine::saveContact()</li>
<li>QContactManagerEngine::removeContact()</li>
</ul>
<p>If it does not, the default implementation of those functions will use the batch (plural) versions of those functions to implement the required behavior.</p>
<p>Support for relationships are backend specific, see below convenience methods for more information.</p>
<ul>
<li>QContactManagerEngine::isRelationshipTypeSupported()</li>
<li>QContactManagerEngine::relationships()</li>
<li>QContactManagerEngine::saveRelationships()</li>
<li>QContactManagerEngine::removeRelationships()</li>
</ul>
<p>Specifically, if the engine supports group contacts, it must support the <code>QContactRelationship::HasMember</code> relationship, and report this as a supported relationship type. It must then also report that it supports the <code>QContactType::TypeGroup</code> contact type as a supported contact type in QContactManagerEngine::supportedContactTypes().</p>
<p>Support for saving a "self" contact (that is, a contact which contains information about the owner of the device or online service account from which the engine provides contact information) is backend specific</p>
<ul>
<li>QContactManagerEngine::setSelfContactId()</li>
<li>QContactManagerEngine::selfContactId()</li>
</ul>
<a name="optional-implementation"></a>
<h4 >Optional Implementation</h4>
<p>Apart from areas of functionality which may be optionally implemented by the engine or not, the default implementation provides several functions which operate in a naive, in-memory manner. An engine implementation can override this default implementation with its own, if it wishes, in order to obtain performance gains, or to more accurately implement the function.</p>
<p>As previously mentioned it may implement its own sorting or filtering, in functions such as QContactManagerEngine::contacts(). An engine may also implement:</p>
<ul>
<li>QContactManagerEngine::validateContact()</li>
<li>QContactManagerEngine::synthesizedDisplayLabel()</li>
</ul>
<a name="which-signals-do-i-need-to-emit"></a>
<h3 >Which Signals Do I Need to Emit?</h3>
<p>An engine implementation must emit the appropriate signals for the subset of functionality that it supports.</p>
<p>If the engine supports reading or saving contacts, it must emit the:</p>
<ul>
<li>QContactManagerEngine::contactsAdded()</li>
<li>QContactManagerEngine::contactsChanged()</li>
<li>QContactManagerEngine::contactsRemoved()</li>
</ul>
<p>signals as appropriate. Alternatively, it can emit the <a href="qcontactmanager.html#dataChanged">QContactManager::dataChanged</a>() signal instead.</p>
<p>If the engine supports reading or saving relationships, it must emit the:</p>
<ul>
<li>QContactManagerEngine::relationshipsAdded()</li>
<li>QContactManagerEngine::relationshipsRemoved()</li>
</ul>
<p>signals as appropriate. Alternatively, it can emit the <a href="qcontactmanager.html#dataChanged">QContactManager::dataChanged</a>() signal instead.</p>
<p>If the engine supports the <code>QContactManager::SelfContact</code> feature, it must emit the:</p>
<ul>
<li>QContactManagerEngine::selfContactIdChanged()</li>
</ul>
<p>signal as appropriate. Alternatively, it can emit the <a href="qcontactmanager.html#dataChanged">QContactManager::dataChanged</a>() signal instead.</p>
<a name="other-considerations"></a>
<h3 >Other Considerations</h3>
<p>There are several other considerations that engine writers must be aware of:</p>
<ul>
<li>Most batch functions take an OPTIONAL error map as a parameter. This parameter may be null, in which case the client is not interested in fine-grained error reporting. Engines must check the pointer before attempting to dereference it.</li>
<li>Every function takes a mandatory <code>QContactManager::Error</code> pointer argument. This argument is NEVER null, since it exists in the private implementation of <a href="qcontactmanager.html">QContactManager</a>. Testing this argument for null is, therefore, superfluous.</li>
<li>The single-item functions for contact and relationship retrieval, removal and save already have a default implementation which merely wraps the batch retrieval, removal or save function appropriately. This default implementation may not be as performant as a hand-rolled function. Engine implementations MUST implement the batch functions for each area of functionality supported by the engine.</li>
<li>Most clients will prefer to use the asynchronous API to access contact information from the engine. It is therefore suggested that asynchronous requests be serviced, even if it is implemented in a similar manner to the (provided) memory engine's naive implementation.</li>
</ul>
<a name="example-implementation"></a>
<h3 >Example Implementation</h3>
<p>There are several implementations of QContactManagerEngine available in the Qt PIM AddOn source code repository. In particular, the "memory" engine provides an implementation of an in-memory, anonymous datastore which supports every feature in the API, and therefore is useful for demonstration purposes. Be aware, however, that the implementation of all functionality in the "memory" engine is naive and not performant, and should not be copied in any real engine implementation (e.g., to perform filtering, it reads all contacts from the (in-memory) database, and checks one by one for matches; a real engine, on the other hand, might perform a database query to return the results directly, rather than performing n-reads).</p>
</div>
<!-- @@@contactsengines.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</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>
|