/usr/share/qt5/doc/qtcontacts/contactssync.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 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- contactssync.qdoc -->
<title>Qt Contacts Synchronous 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 Synchronous 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="#reporting-errors">Reporting Errors</a></li>
<li class="level1"><a href="#manipulating-contacts">Manipulating Contacts</a></li>
<li class="level2"><a href="#adding-contacts">Adding Contacts</a></li>
<li class="level2"><a href="#filtering-by-detail-definition-and-value">Filtering by Detail Definition and Value</a></li>
<li class="level2"><a href="#modifying-contact-details">Modifying Contact Details</a></li>
<li class="level1"><a href="#manipulating-relationships">Manipulating Relationships</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Contacts Synchronous API</h1>
<span class="subtitle"></span>
<!-- $$$contactssync.html-description -->
<div class="descr"> <a name="details"></a>
<p>The Qt Contacts 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 until completion and is therefore most suitable only for applications which interact with local, high-speed datastores.</p>
<p>Most operations that may be performed using the synchronous API may also be performed using the Qt Contacts Asynchronous API. It is recommended for most applications that the asynchronous API be used where possible.</p>
<p>The Qt Contacts Synchronous API is available through the <a href="qcontactmanager.html">QContactManager</a> class. It has the following main use cases:</p>
<ul>
<li>Reporting Errors</li>
<li>Manipulating Contacts</li>
<li>Manipulating Relationships</li>
</ul>
<a name="reporting-errors"></a>
<h2 id="reporting-errors">Reporting Errors</h2>
<p>When a synchronous operation fails, clients need to be able to retrieve error information associated with that synchronous operation. The <a href="qcontactmanager.html#error">QContactManager::error</a>() function provides this information to clients.</p>
<p>For some synchronous operations (for example, batch save or remove operations) it is possible that multiple errors may occur during the operation. In those cases, the synchronous function takes a pointer to a map of input index to error, which is filled by the function as required. The <a href="qcontactmanager.html#error">QContactManager::error</a>() function then reports the overall operation error.</p>
<p>Error reporting is handled slightly differently in the asynchronous API, in that each instance of an asynchronous request is able to report any overall operation error as well as the finer-grained map of errors, for the operation which it requested.</p>
<a name="manipulating-contacts"></a>
<h2 id="manipulating-contacts">Manipulating Contacts</h2>
<p>The most common type of operation that clients perform involves retrieval or modification of contacts. The <a href="qcontactmanager.html">QContactManager</a> class offers synchronous API to retrieve, create, update and delete contacts. The create and update operations are provided through the same interface. Both singular and batch operations are offered by the API.</p>
<p>A contact is identified by its <a href="qcontactid.html">QContactId</a>. This id consists of two parts: a URI which identifies the contact manager which stores the contact, and the local id of the contact in that manager. Some operations which take a pointer to a contact as an argument may modify the contact during the operation; updating the contact id is a common example.</p>
<p>The <a href="qcontactmanager.html">QContactManager</a> class provides API for accessing the IDs of contacts which are stored in the manager:</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>
</ul>
<p>The contact id retrieval functionality is also provided via asynchronous API through the <a href="qcontactidfetchrequest.html">QContactIdFetchRequest</a> class.</p>
<p>The synchronous, singular contact manipulation functions offered by the <a href="qcontactmanager.html">QContactManager</a> class are:</p>
<ul>
<li>contact(const <a href="qcontactid.html">QContactId</a>& contactId, const <a href="qcontactfetchhint.html">QContactFetchHint</a>& fetchHint = QContactFetchHint()) const</li>
<li>saveContact(<a href="qcontact.html">QContact</a>* contact)</li>
<li>removeContact(const <a href="qcontactid.html">QContactId</a>& contactId)</li>
</ul>
<p>The (optional) fetch argument to the contact accessor function allows clients to tell the plugin which types of information they wish to retrieve. This argument is a hint only, and may be ignored safely by the plugin, or used by the plugin to optimize the performance of the retrieve operation.</p>
<p>The save operation entails a validation step, where the contact's details are checked against the supported schema. If the contact is valid, it is saved. Note that if the contact already exists in the database (determined by the id of the contact) it is replaced with the contact contained in the argument. This means that clients should not save any contact which was retrieved with a non-empty fetchHint defined, or data loss may occur.</p>
<p>Any error which occurs during such singular contact manipulation functions may be accessed by calling <a href="qcontactmanager.html#error">QContactManager::error</a>() directly after the original synchronous call.</p>
<p>The synchronous, batch contact manipulation functions offered by the <a href="qcontactmanager.html">QContactManager</a> class are:</p>
<ul>
<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>
<p>The batch save and remove functions both take an (optional) pointer to a map of errors. If the pointer is non-null, this map is filled out with any errors which occur. The overall operation error of any batch manipulation operation may be accessed by calling <a href="qcontactmanager.html#error">QContactManager::error</a>() directly after the original synchronous call.</p>
<p>The contact manipulation functionality is also provided via asynchronous API through the <a href="qcontactfetchrequest.html">QContactFetchRequest</a>, <a href="qcontactsaverequest.html">QContactSaveRequest</a>, and <a href="qcontactremoverequest.html">QContactRemoveRequest</a> classes.</p>
<p>The <i>self</i> contact is a special concept, which has dedicated API. A client may instruct any backend which supports the concept of a self contact that a particular, previously saved contact is the self contact. Any backend which implements this functionality should report that it supports the QContactManager::SelfContact feature.</p>
<p>The API which provides the self-contact functionality consists of:</p>
<ul>
<li>setSelfContactId(const <a href="qcontactid.html">QContactId</a>& contactId)</li>
<li>selfContactId() const</li>
</ul>
<p>In order to unset the self contact, a client may either delete the contact which is currently set as the self contact, or set the self contact id to be null id (constructed via QContactId()). The self-contact manipulation functionality is only available via the synchronous API.</p>
<a name="adding-contacts"></a>
<h3 >Adding Contacts</h3>
<p>The client creates a new contact, adds a name and a phone number, and saves it to the default store of the default manager.</p>
<p>We assume the existence of a specialized leaf-class that allows simple access to details of the definition identified by the "<a href="qml-qtcontacts-phonenumber.html">PhoneNumber</a>" identifier, and another that allows simple access to details of the definition identified by the "Name" identifier. These specialized leaf classes may be written by anyone, and simply wrap the functionality provided by <a href="qcontactdetail.html">QContactDetail</a> in order to allow simpler access to fields supported by a particular definition.</p>
<pre class="cpp">
<span class="type">void</span> addContact(<span class="type"><a href="qcontactmanager.html">QContactManager</a></span><span class="operator">*</span> cm)
{
<span class="type"><a href="qcontact.html">QContact</a></span> alice;
<span class="type"><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a></span> displayLabel;
displayLabel<span class="operator">.</span>setLabel(<span class="string">"Ally Jones"</span>);
alice<span class="operator">.</span>saveDetail(<span class="operator">&</span>displayLabel);
<span class="comment">/* Set the contact's name */</span>
<span class="type"><a href="qcontactname.html">QContactName</a></span> aliceName;
aliceName<span class="operator">.</span>setFirstName(<span class="string">"Alice"</span>);
aliceName<span class="operator">.</span>setLastName(<span class="string">"Jones"</span>);
alice<span class="operator">.</span>saveDetail(<span class="operator">&</span>aliceName);
<span class="comment">/* Add a phone number */</span>
<span class="type"><a href="qcontactphonenumber.html">QContactPhoneNumber</a></span> number;
<span class="type">QList</span><span class="operator"><</span><span class="type">int</span><span class="operator">></span> subTypeMobile;
subTypeMobile <span class="operator"><</span><span class="operator"><</span> <span class="type"><a href="qcontactphonenumber.html">QContactPhoneNumber</a></span><span class="operator">::</span>SubTypeMobile;
number<span class="operator">.</span>setSubTypes(subTypeMobile);
number<span class="operator">.</span>setContexts(<span class="type"><a href="qcontactdetail.html">QContactDetail</a></span><span class="operator">::</span>ContextHome);
number<span class="operator">.</span>setSubTypes(subTypeMobile);
number<span class="operator">.</span>setNumber(<span class="string">"12345678"</span>);
alice<span class="operator">.</span>saveDetail(<span class="operator">&</span>number);
alice<span class="operator">.</span>setPreferredDetail(<span class="string">"DialAction"</span><span class="operator">,</span> number);
<span class="comment">/* Add a second phone number */</span>
<span class="type"><a href="qcontactphonenumber.html">QContactPhoneNumber</a></span> number2;
<span class="type">QList</span><span class="operator"><</span><span class="type">int</span><span class="operator">></span> subTypeLandline;
subTypeLandline <span class="operator"><</span><span class="operator"><</span> <span class="type"><a href="qcontactphonenumber.html">QContactPhoneNumber</a></span><span class="operator">::</span>SubTypeMobile;
number<span class="operator">.</span>setSubTypes(subTypeLandline);
number2<span class="operator">.</span>setContexts(<span class="type"><a href="qcontactdetail.html">QContactDetail</a></span><span class="operator">::</span>ContextWork);
number2<span class="operator">.</span>setSubTypes(subTypeLandline);
number2<span class="operator">.</span>setNumber(<span class="string">"555-4444"</span>);
alice<span class="operator">.</span>saveDetail(<span class="operator">&</span>number2);
<span class="comment">/* Save the contact */</span>
cm<span class="operator">-</span><span class="operator">></span>saveContact(<span class="operator">&</span>alice) <span class="operator">?</span> qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Successfully saved"</span>
: qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Failed to save"</span>;
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"The display label for the contact:"</span> <span class="operator"><</span><span class="operator"><</span> alice<span class="operator">.</span>details(<span class="type"><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a></span><span class="operator">::</span>Type)<span class="operator">.</span>value(<span class="number">1</span>)<span class="operator">.</span>value(<span class="type"><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a></span><span class="operator">::</span>FieldLabel);
}
</pre>
<a name="filtering-by-detail-definition-and-value"></a>
<h3 >Filtering by Detail Definition and Value</h3>
<p>The client utilizes a default manager and asks for any contacts with a particular phone number. The example assumes that the default manager supports the provided <a href="qcontactphonenumber.html">QContactPhoneNumber</a> detail leaf class (which implements the default definition for phone number details).</p>
<pre class="cpp">
<span class="type">void</span> matchCall(<span class="type"><a href="qcontactmanager.html">QContactManager</a></span><span class="operator">*</span> cm<span class="operator">,</span> <span class="keyword">const</span> <span class="type">QString</span><span class="operator">&</span> incomingCallNbr)
{
<span class="type"><a href="qcontactdetailfilter.html">QContactDetailFilter</a></span> phoneFilter;
phoneFilter<span class="operator">.</span>setDetailType(<span class="type"><a href="qcontactphonenumber.html">QContactPhoneNumber</a></span><span class="operator">::</span>Type<span class="operator">,</span> <span class="type"><a href="qcontactphonenumber.html">QContactPhoneNumber</a></span><span class="operator">::</span>FieldNumber);
phoneFilter<span class="operator">.</span>setValue(incomingCallNbr);
phoneFilter<span class="operator">.</span>setMatchFlags(<span class="type"><a href="qcontactfilter.html">QContactFilter</a></span><span class="operator">::</span>MatchExactly);
<span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qcontactid.html">QContactId</a></span><span class="operator">></span> matchingContacts <span class="operator">=</span> cm<span class="operator">-</span><span class="operator">></span>contactIds(phoneFilter);
<span class="keyword">if</span> (matchingContacts<span class="operator">.</span>size() <span class="operator">=</span><span class="operator">=</span> <span class="number">0</span>) {
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Incoming call from unknown contact ("</span> <span class="operator"><</span><span class="operator"><</span> incomingCallNbr <span class="operator"><</span><span class="operator"><</span> <span class="string">")"</span>;
} <span class="keyword">else</span> {
<span class="type"><a href="qcontact.html">QContact</a></span> match <span class="operator">=</span> cm<span class="operator">-</span><span class="operator">></span>contact(matchingContacts<span class="operator">.</span>at(<span class="number">0</span>));
<span class="type"><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a></span> displayLabel;
displayLabel<span class="operator">.</span>setLabel(<span class="string">"Match"</span>);
match<span class="operator">.</span>saveDetail(<span class="operator">&</span>displayLabel);
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Incoming call from"</span>
<span class="operator"><</span><span class="operator"><</span> match<span class="operator">.</span>details(<span class="type"><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a></span><span class="operator">::</span>Type)<span class="operator">.</span>value(<span class="number">0</span>)<span class="operator">.</span>value(<span class="type"><a href="qcontactdisplaylabel.html">QContactDisplayLabel</a></span><span class="operator">::</span>FieldLabel)
<span class="operator"><</span><span class="operator"><</span> <span class="string">"("</span> <span class="operator"><</span><span class="operator"><</span> incomingCallNbr <span class="operator"><</span><span class="operator"><</span> <span class="string">")"</span>;
}
}
</pre>
<a name="modifying-contact-details"></a>
<h3 >Modifying Contact Details</h3>
<p>The client retrieves a contact, modifies one of its details, adds a new detail, and then saves the contact back to the manager.</p>
<pre class="cpp">
<span class="type">void</span> editView(<span class="type"><a href="qcontactmanager.html">QContactManager</a></span><span class="operator">*</span> cm)
{
<span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qcontactid.html">QContactId</a></span><span class="operator">></span> contactIds <span class="operator">=</span> cm<span class="operator">-</span><span class="operator">></span>contactIds();
<span class="type"><a href="qcontact.html">QContact</a></span> a <span class="operator">=</span> cm<span class="operator">-</span><span class="operator">></span>contact(contactIds<span class="operator">.</span>first());
<span class="comment">/* Change the first phone number */</span>
<span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qcontactdetail.html">QContactDetail</a></span><span class="operator">></span> numbers <span class="operator">=</span> a<span class="operator">.</span>details(<span class="type"><a href="qcontactphonenumber.html">QContactPhoneNumber</a></span><span class="operator">::</span>Type);
<span class="type"><a href="qcontactphonenumber.html">QContactPhoneNumber</a></span> phone <span class="operator">=</span> numbers<span class="operator">.</span>value(<span class="number">0</span>);
phone<span class="operator">.</span>setNumber(<span class="string">"123-4445"</span>);
<span class="comment">/* Add an email address */</span>
<span class="type"><a href="qcontactemailaddress.html">QContactEmailAddress</a></span> email;
email<span class="operator">.</span>setEmailAddress(<span class="string">"alice.jones@example"</span>);
email<span class="operator">.</span>setContexts(<span class="type"><a href="qcontactdetail.html">QContactDetail</a></span><span class="operator">::</span>ContextHome);
<span class="type">int</span> emailField <span class="operator">=</span> <span class="type"><a href="qcontactemailaddress.html">QContactEmailAddress</a></span><span class="operator">::</span>FieldEmailAddress;
email<span class="operator">.</span>setValue(emailField<span class="operator">,</span> <span class="string">"Alice's Work Email Address"</span>);
<span class="comment">/* Save the updated details to the contact. */</span>
a<span class="operator">.</span>saveDetail(<span class="operator">&</span>phone);
a<span class="operator">.</span>saveDetail(<span class="operator">&</span>email);
<span class="comment">/* Now we must save the updated contact back to the database. */</span>
cm<span class="operator">-</span><span class="operator">></span>saveContact(<span class="operator">&</span>a);
viewDetails(cm);
}
</pre>
<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 if the plugin providing the functionality supports such relationships. Some plugins support arbitrary relationship types. Clients can define custom relationships between contacts saved in such plugins.</p>
<p>The API which provides the relationship manipulation functionality consists of:</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>
<p>The relationship manipulation functionality is also provided via asynchronous API through the <a href="qcontactrelationshipfetchrequest.html">QContactRelationshipFetchRequest</a>, <a href="qcontactrelationshipsaverequest.html">QContactRelationshipSaveRequest</a>, and <a href="qcontactrelationshipremoverequest.html">QContactRelationshipRemoveRequest</a> classes.</p>
</div>
<!-- @@@contactssync.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>
|