<?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" />
<!-- contactsasync.qdoc -->
<title>Qt Mobility 1.2: Contacts Asynchronous API</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>Contacts Asynchronous API</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="#using-the-api">Using the API</a></li>
<li class="level2"><a href="#contact-manipulation">Contact Manipulation</a></li>
<li class="level3"><a href="#relationship-manipulation">Relationship Manipulation</a></li>
<li class="level2"><a href="#schema-manipulation">Schema Manipulation</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>
<h1 class="title">Contacts Asynchronous API</h1>
<span class="subtitle"></span>
<!-- $$$contactsasync.html-description -->
<div class="descr"> <a name="details"></a>
<a name="introduction"></a>
<h2>Introduction</h2>
<p>The Contacts Asynchronous API enables a client to asynchronously fetch, update, or remove contact, relationship or schema data from a contact manager. Use of the asynchronous API offers the programmer greater flexibility when requesting information from remote or slow local datastores.</p>
<a name="using-the-api"></a>
<h2>Using the API</h2>
<p>The asynchronous API offered by the Contacts module is available through classes derived from the <a href="qcontactabstractrequest.html">QContactAbstractRequest</a> class. It consists of three major sections:</p>
<ul>
<li>Contact Manipulation</li>
<li>Relationship Manipulation</li>
<li>Schema Manipulation</li>
</ul>
<p>The functionality offered by the synchronous API in these three categories is also available through the asynchronous API. There is one category of functionality which is not provided by the asynchronous API which is provided by the synchronous API: some information and reporting functionality is only provided through the synchronous API.</p>
<p>For detailed information about the information and reporting functionality provided, please refer to the documentation for the <a href="contactssync.html">Contacts Synchronous API</a>.</p>
<p>The functions to set and retrieve the id of the self-contact are also only provided by the synchronous API.</p>
<a name="contact-manipulation"></a>
<h3>Contact Manipulation</h3>
<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">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="qcontactlocalidfetchrequest.html">QContactLocalIdFetchRequest</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 <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactsortorder.html">QContactSortOrder</a>>& <a href="location-overview.html#sortorders">sortOrders</a> = <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactsortorder.html">QContactSortOrder</a>>()) const</li>
<li>contactIds(const <a href="qcontactfilter.html">QContactFilter</a>& filter, const <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactsortorder.html">QContactSortOrder</a>>& <a href="location-overview.html#sortorders">sortOrders</a> = <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactsortorder.html">QContactSortOrder</a>>()) const</li>
<li>contacts(const <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactsortorder.html">QContactSortOrder</a>>& <a href="location-overview.html#sortorders">sortOrders</a> = <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<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 <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactsortorder.html">QContactSortOrder</a>>& <a href="location-overview.html#sortorders">sortOrders</a> = <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactsortorder.html">QContactSortOrder</a>>(), const <a href="qcontactfetchhint.html">QContactFetchHint</a>& fetchHint = QContactFetchHint()) const</li>
<li>saveContacts(<a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontact.html">QContact</a>>* contacts, <a href="http://qt.nokia.com/doc/4.7/qmap.html">QMap</a><int, <a href="qcontactmanager.html#Error-enum">QContactManager::Error</a>>* errorMap)</li>
<li>removeContacts(<a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactid.html#QContactLocalId-typedef">QContactLocalId</a>>* contactIds, <a href="http://qt.nokia.com/doc/4.7/qmap.html">QMap</a><int, <a href="qcontactmanager.html#Error-enum">QContactManager::Error</a>>* errorMap)</li>
</ul>
<a name="relationship-manipulation"></a>
<h4>Relationship Manipulation</h4>
<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">Contacts Synchronous API</a>.</p>
<p>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 <a href="http://qt.nokia.com/doc/4.7/qstring.html">QString</a>& relationshipType = <a href="http://qt.nokia.com/doc/4.7/porting4.html">QString</a>(), 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(<a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactrelationship.html">QContactRelationship</a>>* relationships);</li>
<li>removeRelationship(const <a href="qcontactrelationship.html">QContactRelationship</a>& relationship);</li>
<li>removeRelationships(const <a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a><<a href="qcontactrelationship.html">QContactRelationship</a>>& relationships);</li>
</ul>
<a name="schema-manipulation"></a>
<h3>Schema Manipulation</h3>
<p>The schema supported by a plugin is the list of detail definitions which are supported by the plugin. For in-depth information about the schema, please refer to the <a href="contactssync.html">Contacts Synchronous API</a>.</p>
<p>There are three different types of operation which are supported by the asynchronous API:</p>
<ul>
<li>Fetch detail definitions</li>
<li>Save detail definitions (create or update, if supported by the backend)</li>
<li>Remove detail definitions (if supported by the backend)</li>
</ul>
<p>These operations are supported via the the <a href="qcontactdetaildefinitionfetchrequest.html">QContactDetailDefinitionFetchRequest</a>, <a href="qcontactdetaildefinitionsaverequest.html">QContactDetailDefinitionSaveRequest</a> and <a href="qcontactdetaildefinitionremoverequest.html">QContactDetailDefinitionRemoveRequest</a> classes, respectively.</p>
<p>The synchronous API offered by the <a href="qcontactmanager.html">QContactManager</a> class to allow manipulation of the schema consists of the following functions:</p>
<ul>
<li>detailDefinitions(const <a href="http://qt.nokia.com/doc/4.7/qstring.html">QString</a>& contactType = <a href="qcontacttype.html#TypeContact-var">QContactType::TypeContact</a>) const</li>
<li>detailDefinition(const <a href="http://qt.nokia.com/doc/4.7/qstring.html">QString</a>& definitionName, const <a href="http://qt.nokia.com/doc/4.7/qstring.html">QString</a>& contactType = <a href="qcontacttype.html#TypeContact-var">QContactType::TypeContact</a>) const</li>
<li>saveDetailDefinition(const <a href="qcontactdetaildefinition.html">QContactDetailDefinition</a>& def, const <a href="http://qt.nokia.com/doc/4.7/qstring.html">QString</a>& contactType = <a href="qcontacttype.html#TypeContact-var">QContactType::TypeContact</a>)</li>
<li>removeDetailDefinition(const <a href="http://qt.nokia.com/doc/4.7/qstring.html">QString</a>& definitionName, const <a href="http://qt.nokia.com/doc/4.7/qstring.html">QString</a>& contactType = <a href="qcontacttype.html#TypeContact-var">QContactType::TypeContact</a>)</li>
</ul>
<a name="examples-of-usage"></a>
<h2>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>setDetailDefinitionName(<span class="type"><a href="qcontactname.html">QContactName</a></span><span class="operator">::</span>DefinitionName<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()) {
<a href="http://qt.nokia.com/doc/4.7/qtglobal.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Unable to request contacts!"</span>;
<span class="type"><a href="http://qt.nokia.com/doc/4.7/qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>exit(<span class="number">0</span>);
} <span class="keyword">else</span> {
<a href="http://qt.nokia.com/doc/4.7/qtglobal.html#qDebug">qDebug</a>() <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"><a href="http://qt.nokia.com/doc/4.7/qlist.html">QList</a></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) {
<a href="http://qt.nokia.com/doc/4.7/qtglobal.html#qDebug">qDebug</a>() <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="operator">.</span>displayLabel();
}
}
<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) {
<a href="http://qt.nokia.com/doc/4.7/qtglobal.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Finished displaying asynchronously retrieved contacts!"</span>;
<span class="type"><a href="http://qt.nokia.com/doc/4.7/qcoreapplication.html">QCoreApplication</a></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 class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</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>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-release
>
by-pkgid
>
50facae208d4a6f280e44a513b104320
>
files
>
160
