/usr/share/qt5/doc/qtcontacts/contactsasync.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 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- contactsasync.qdoc -->
<title>Qt Contacts Asynchronous API | 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 Asynchronous API</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="#manipulating-contacts">Manipulating Contacts</a></li>
<li class="level1"><a href="#manipulating-relationships">Manipulating Relationships</a></li>
<li class="level1"><a href="#examples-of-usage">Examples of Usage</a></li>
<li class="level2"><a href="#fetching-contacts">Fetching Contacts</a></li>
<li class="level2"><a href="#other-asynchronous-operations">Other Asynchronous Operations</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Contacts Asynchronous API</h1>
<span class="subtitle"></span>
<!-- $$$contactsasync.html-description -->
<div class="descr"> <a name="details"></a>
<p>The Qt Contacts Asynchronous API enables a client to asynchronously fetch, update, or remove contact and relationship data from a contact manager. It offers mostly the same functionality as the <a href="contactssync.html">Qt Contacts Synchronous API</a>, but with greater flexibility when requesting information from remote datastores or slow local datastores. However, some information and reporting functionality, as well as the functions to set and retrieve the id of the self-contact are only provided through the synchronous API.</p>
<p>The Qt Contacts Asynchronous API is available through classes derived from the <a href="qcontactabstractrequest.html">QContactAbstractRequest</a> class. It has the following main use cases:</p>
<ul>
<li>Manipulating contacts</li>
<li>Manipulating relationships</li>
</ul>
<a name="manipulating-contacts"></a>
<h2 id="manipulating-contacts">Manipulating Contacts</h2>
<p>The most common type of operation that clients will perform involves retrieval or modification of contacts. For in-depth information about contact manipulation, please refer to the <a href="contactssync.html">Qt Contacts Synchronous API</a>.</p>
<p>There are four different types of operation which are supported by the asynchronous API:</p>
<ul>
<li>Fetch contact ids</li>
<li>Fetch contacts</li>
<li>Save contacts (create or update)</li>
<li>Remove contacts</li>
</ul>
<p>These operations are supported via the <a href="qcontactidfetchrequest.html">QContactIdFetchRequest</a>, <a href="qcontactfetchrequest.html">QContactFetchRequest</a>, <a href="qcontactsaverequest.html">QContactSaveRequest</a> and <a href="qcontactremoverequest.html">QContactRemoveRequest</a> classes, respectively.</p>
<p>The synchronous API offered by the <a href="qcontactmanager.html">QContactManager</a> class to allow manipulation of contacts consists of the following functions:</p>
<ul>
<li>contactIds(const QList<<a href="qcontactsortorder.html">QContactSortOrder</a>>& sortOrders = QList<<a href="qcontactsortorder.html">QContactSortOrder</a>>()) const</li>
<li>contactIds(const <a href="qcontactfilter.html">QContactFilter</a>& filter, const QList<<a href="qcontactsortorder.html">QContactSortOrder</a>>& sortOrders = QList<<a href="qcontactsortorder.html">QContactSortOrder</a>>()) const</li>
<li>contacts(const QList<<a href="qcontactsortorder.html">QContactSortOrder</a>>& sortOrders = QList<<a href="qcontactsortorder.html">QContactSortOrder</a>>(), const <a href="qcontactfetchhint.html">QContactFetchHint</a>& fetchHint = QContactFetchHint()) const</li>
<li>contacts(const <a href="qcontactfilter.html">QContactFilter</a>& filter, const QList<<a href="qcontactsortorder.html">QContactSortOrder</a>>& sortOrders = QList<<a href="qcontactsortorder.html">QContactSortOrder</a>>(), const <a href="qcontactfetchhint.html">QContactFetchHint</a>& fetchHint = QContactFetchHint()) const</li>
<li>saveContacts(QList<<a href="qcontact.html">QContact</a>>* contacts, QMap<int, <a href="qcontactmanager.html#Error-enum">QContactManager::Error</a>>* errorMap)</li>
<li>removeContacts(QList<<a href="qcontactid.html">QContactId</a>>* contactIds, QMap<int, <a href="qcontactmanager.html#Error-enum">QContactManager::Error</a>>* errorMap)</li>
</ul>
<a name="manipulating-relationships"></a>
<h2 id="manipulating-relationships">Manipulating Relationships</h2>
<p>Contacts may be related in various ways. The contacts API allows clients to define relationships between contacts. For in-depth information about relationship manipulation, please refer to the <a href="contactssync.html">Qt Contacts Synchronous API</a>. Support for relationships is backend specific. There are three different types of operation which are supported by the asynchronous API:</p>
<ul>
<li>Fetch relationships</li>
<li>Save relationships (create or update, if supported by the backend)</li>
<li>Remove relationships (if supported by the backend)</li>
</ul>
<p>These operations are supported via the <a href="qcontactrelationshipfetchrequest.html">QContactRelationshipFetchRequest</a>, <a href="qcontactrelationshipsaverequest.html">QContactRelationshipSaveRequest</a> and <a href="qcontactrelationshipremoverequest.html">QContactRelationshipRemoveRequest</a> classes respectively.</p>
<p>The synchronous API offered by the <a href="qcontactmanager.html">QContactManager</a> class to allow manipulation of relationships consists of the following functions:</p>
<ul>
<li>relationships(const <a href="qcontactid.html">QContactId</a>& participantId, QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;</li>
<li>relationships(const QString& relationshipType = QString(), const <a href="qcontactid.html">QContactId</a>& participantId = QContactId(), QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;</li>
<li>saveRelationship(<a href="qcontactrelationship.html">QContactRelationship</a>* relationship);</li>
<li>saveRelationships(QList<<a href="qcontactrelationship.html">QContactRelationship</a>>* relationships);</li>
<li>removeRelationship(const <a href="qcontactrelationship.html">QContactRelationship</a>& relationship);</li>
<li>removeRelationships(const QList<<a href="qcontactrelationship.html">QContactRelationship</a>>& relationships);</li>
</ul>
<a name="examples-of-usage"></a>
<h2 id="examples-of-usage">Examples of Usage</h2>
<a name="fetching-contacts"></a>
<h3 >Fetching Contacts</h3>
<p>The client sets up a request for contacts matching a specific criteria from a particular manager.</p>
<p>Results from the request will be displayed to the user as they are received.</p>
<pre class="cpp">
<span class="type">void</span> RequestExample<span class="operator">::</span>performRequest()
{
<span class="comment">// retrieve any contact whose first name is "Alice"</span>
<span class="type"><a href="qcontactdetailfilter.html">QContactDetailFilter</a></span> dfil;
dfil<span class="operator">.</span>setDetailType(<span class="type"><a href="qcontactname.html">QContactName</a></span><span class="operator">::</span>Type<span class="operator">,</span> <span class="type"><a href="qcontactname.html">QContactName</a></span><span class="operator">::</span>FieldFirstName);
dfil<span class="operator">.</span>setValue(<span class="string">"Alice"</span>);
dfil<span class="operator">.</span>setMatchFlags(<span class="type"><a href="qcontactfilter.html">QContactFilter</a></span><span class="operator">::</span>MatchExactly);
<span class="comment">// m_fetchRequest was created with m_fetchRequest = new QContactFetchRequest() in the ctor.</span>
m_fetchRequest<span class="operator">-</span><span class="operator">></span>setManager(<span class="keyword">this</span><span class="operator">-</span><span class="operator">></span>m_manager); <span class="comment">// m_manager is a QContactManager*.</span>
m_fetchRequest<span class="operator">-</span><span class="operator">></span>setFilter(dfil);
connect(m_fetchRequest<span class="operator">,</span> SIGNAL(resultsAvailable())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(printContacts()));
connect(m_fetchRequest<span class="operator">,</span> SIGNAL(stateChanged(<span class="type"><a href="qcontactabstractrequest.html">QContactAbstractRequest</a></span><span class="operator">::</span>State))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(stateChanged(<span class="type"><a href="qcontactabstractrequest.html">QContactAbstractRequest</a></span><span class="operator">::</span>State)));
<span class="keyword">if</span> (<span class="operator">!</span>m_fetchRequest<span class="operator">-</span><span class="operator">></span>start()) {
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Unable to request contacts!"</span>;
<span class="type">QCoreApplication</span><span class="operator">::</span>exit(<span class="number">0</span>);
} <span class="keyword">else</span> {
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Requested contacts; awaiting results..."</span>;
}
}
<span class="type">void</span> RequestExample<span class="operator">::</span>printContacts()
{
<span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qcontact.html">QContact</a></span><span class="operator">></span> results <span class="operator">=</span> m_fetchRequest<span class="operator">-</span><span class="operator">></span>contacts();
<span class="keyword">for</span> (m_previousLastIndex <span class="operator">=</span> <span class="number">0</span>; m_previousLastIndex <span class="operator"><</span> results<span class="operator">.</span>size(); <span class="operator">+</span><span class="operator">+</span>m_previousLastIndex) {
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Found an Alice:"</span> <span class="operator"><</span><span class="operator"><</span> results<span class="operator">.</span>at(m_previousLastIndex);
}
}
<span class="type">void</span> RequestExample<span class="operator">::</span>stateChanged(<span class="type"><a href="qcontactabstractrequest.html">QContactAbstractRequest</a></span><span class="operator">::</span>State state)
{
<span class="comment">// once we've finished retrieving results, stop processing events.</span>
<span class="keyword">if</span> (state <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qcontactabstractrequest.html">QContactAbstractRequest</a></span><span class="operator">::</span>FinishedState
<span class="operator">|</span><span class="operator">|</span> state <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qcontactabstractrequest.html">QContactAbstractRequest</a></span><span class="operator">::</span>CanceledState) {
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Finished displaying asynchronously retrieved contacts!"</span>;
<span class="type">QCoreApplication</span><span class="operator">::</span>exit(<span class="number">0</span>);
}
}
</pre>
<a name="other-asynchronous-operations"></a>
<h3 >Other Asynchronous Operations</h3>
<p>All other asynchronous operations are performed in a similar manner to the previous example. A request of the desired type (which is derived from <a href="qcontactabstractrequest.html">QContactAbstractRequest</a>) is created, certain criteria are set which determine the intent of the request, and the signals of the request are connected to slots which deals with the results. The request can then be started.</p>
</div>
<!-- @@@contactsasync.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>
|