/usr/share/qt5/doc/qtlocation/location-places-backend.html is in qtlocation5-doc-html 5.2.1-1ubuntu2.
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 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.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" />
<!-- places-backend.qdoc -->
<title>Places Backend | QtLocation 5.2</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.2</li>
<li><a href="qtlocation-index.html">Qt Location</a></li>
<li>Places Backend</li>
<li id="buildversion">
Qt 5.2.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level1"><a href="#implementing-inheriting-reply-objects">Implementing/Inheriting Reply Objects</a></li>
<li class="level1"><a href="#icon-urls">Icon URLs</a></li>
<li class="level1"><a href="#categories">Categories</a></li>
<li class="level1"><a href="#saving-places-to-the-manager">Saving Places to the Manager</a></li>
<li class="level1"><a href="#cross-referencing-places-between-managers">Cross-Referencing Places Between Managers.</a></li>
<li class="level2"><a href="#alternative-identifier-cross-referencing">Alternative Identifier Cross-Referencing</a></li>
<li class="level3"><a href="#other-methods-of-linking">Other Methods of Linking</a></li>
<li class="level3"><a href="#user-readable-vs-non-user-readable-extended-attributes">User Readable vs Non-User Readable Extended Attributes</a></li>
</ul>
</div>
<h1 class="title">Places Backend</h1>
<span class="subtitle"></span>
<!-- $$$location-places-backend.html-description -->
<div class="descr"> <a name="details"></a>
<a name="overview"></a>
<h2>Overview</h2>
<p>The <a href="qplacemanager.html">QPlaceManager</a> interface, provided to clients to allow access to place information, depends directly on an implementation of <a href="qplacemanagerengine.html">QPlaceManagerEngine</a>. The engine provides the backend function implementations which are called by the manager.</p>
<p>A places backend implementer needs to derive from <a href="qplacemanagerengine.html">QPlaceManagerEngine</a> and provide implementations for the virtual functions relevant for their backend. Most of these functions are asynchronous and so implementers will also need to derive the appropriate <a href="location-places-cpp.html#places-reply-classes">reply classes</a>. The reply objects are responsible for managing an asynchronous request; they are used to notify when a request is complete and hold the results of that request. <a href="qplacemanagerengine.html">QPlaceManagerEngine</a> provides a default implementation for all virtual functions. The default implementations for the asynchronous functions return a reply that will emit the error() and finished() signals at the next iteration through the event loop.</p>
<a name="implementing-inheriting-reply-objects"></a>
<h2>Implementing/Inheriting Reply Objects</h2>
<p>A reply object would be inherited as follows:</p>
<pre class="cpp"><span class="keyword">class</span> SearchReply : <span class="keyword">public</span> <span class="type"><a href="qplacesearchreply.html">QPlaceSearchReply</a></span>
{
<span class="keyword">public</span>:
<span class="keyword">explicit</span> SearchReply(ManagerEngine <span class="operator">*</span>engine)
: <span class="type"><a href="qplacesearchreply.html">QPlaceSearchReply</a></span>(engine)<span class="operator">,</span> m_engine(engine){}
<span class="operator">~</span>SearchReply();
<span class="type">void</span> setResults(<span class="keyword">const</span> <span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qplacesearchresult.html">QPlaceSearchResult</a></span><span class="operator">></span> <span class="operator">&</span>results);
<span class="type">void</span> setRequest(<span class="keyword">const</span> <span class="type"><a href="qplacesearchrequest.html">QPlaceSearchRequest</a></span> <span class="operator">&</span>request);
...
<span class="type">void</span> triggerDone(<span class="type"><a href="qplacereply.html">QPlaceReply</a></span><span class="operator">::</span>Error error <span class="operator">=</span> <span class="type"><a href="qplacereply.html">QPlaceReply</a></span><span class="operator">::</span>NoError<span class="operator">,</span>
<span class="keyword">const</span> <span class="type">QString</span> <span class="operator">&</span>errorString <span class="operator">=</span> <span class="type">QString</span>());
ManagerEngine <span class="operator">*</span>m_engine;
};</pre>
<p>The implementation of a <a href="qplacemanagerengine.html">QPlaceManagerEngine</a> must ensure that any signals emitted by the reply objects are delayed until the request functions have returned and the application code has a chance to connect those signals to slots. The typical approach is to use QMetaObject::invokeMethod() with a Qt::QueuedConnection to emit the signals.</p>
<pre class="cpp"><span class="type">void</span> SearchSuggestionReply<span class="operator">::</span>triggerDone(<span class="type"><a href="qplacereply.html">QPlaceReply</a></span><span class="operator">::</span>Error error<span class="operator">,</span>
<span class="keyword">const</span> <span class="type">QString</span> <span class="operator">&</span>errorString)
{
<span class="keyword">if</span> (error <span class="operator">!</span><span class="operator">=</span> <span class="type"><a href="qplacereply.html">QPlaceReply</a></span><span class="operator">::</span>NoError) {
<span class="keyword">this</span><span class="operator">-</span><span class="operator">></span>setError(error<span class="operator">,</span>errorString);
<span class="type">QMetaObject</span><span class="operator">::</span>invokeMethod(m_engine<span class="operator">,</span> <span class="string">"error"</span><span class="operator">,</span> <span class="type">Qt</span><span class="operator">::</span>QueuedConnection<span class="operator">,</span>
Q_ARG(<span class="type"><a href="qplacereply.html">QPlaceReply</a></span> <span class="operator">*</span><span class="operator">,</span><span class="keyword">this</span>)<span class="operator">,</span>
Q_ARG(<span class="type"><a href="qplacereply.html">QPlaceReply</a></span><span class="operator">::</span>Error<span class="operator">,</span> error)<span class="operator">,</span>
Q_ARG(<span class="type">QString</span><span class="operator">,</span> errorString));
<span class="type">QMetaObject</span><span class="operator">::</span>invokeMethod(<span class="keyword">this</span><span class="operator">,</span> <span class="string">"error"</span><span class="operator">,</span> <span class="type">Qt</span><span class="operator">::</span>QueuedConnection<span class="operator">,</span>
Q_ARG(<span class="type"><a href="qplacereply.html">QPlaceReply</a></span><span class="operator">::</span>Error<span class="operator">,</span> error)<span class="operator">,</span>
Q_ARG(<span class="type">QString</span><span class="operator">,</span> errorString));
}
<span class="keyword">this</span><span class="operator">-</span><span class="operator">></span>setFinished(<span class="keyword">true</span>);
<span class="type">QMetaObject</span><span class="operator">::</span>invokeMethod(m_engine<span class="operator">,</span> <span class="string">"finished"</span><span class="operator">,</span> <span class="type">Qt</span><span class="operator">::</span>QueuedConnection<span class="operator">,</span>
Q_ARG(<span class="type"><a href="qplacereply.html">QPlaceReply</a></span> <span class="operator">*</span><span class="operator">,</span><span class="keyword">this</span>));
<span class="type">QMetaObject</span><span class="operator">::</span>invokeMethod(<span class="keyword">this</span><span class="operator">,</span> <span class="string">"finished"</span><span class="operator">,</span> <span class="type">Qt</span><span class="operator">::</span>QueuedConnection);
}</pre>
<p>Note that the <tt>finished</tt> signals should always be emitted when a reply is complete, even if an error has been encountered, that is, if there is an error, both the <tt>error</tt> and <tt>finished</tt> signals should be emitted while if there is no error, only the <tt>finished</tt> signals are emitted.</p>
<p>The protected functions of <a href="qplacesearchreply.html#setResults">QPlaceSearchReply::setResults</a>() and <a href="qplacesearchreply.html#setRequest">QPlaceSearchReply::setRequest</a>() are made publicly accessible so the plugin can assign results and requests. Because these functions are not publically exported, accessibility is not so much of an issue. An alternative would have been to declare a friend class in SearchReply.</p>
<p>Typically the engine instance would be made the <tt>parent</tt> of the reply. If the developer fails to discard the replies when finished, the engine can clean those upon destruction. Commonly, the reply also has a pointer reference back to the engine, which may be used to emit the <a href="qplacemanagerengine.html#finished">QPlaceManagerEngine::finished</a>() and <a href="qplacemanagerengine.html#error">QPlaceManagerEngine::error</a>() signals. This is just one of many ways the reply could be implemented.</p>
<a name="icon-urls"></a>
<h2>Icon URLs</h2>
<p>Icon URLs are provided through the <a href="qplacemanagerengine.html#constructIconUrl">QPlaceManagerEngine::constructIconUrl</a>() function. The expected behaviour is that the engine will use the <a href="qplaceicon.html#parameters">QPlaceIcon::parameters</a>() in order to construct an appropriate URL. When a <a href="qplace.html">QPlace</a> object is returned from the manager either from a search or a query to get place details, it is expected the engine will correctly populate the parameters as necessary.</p>
<p>The backend is free to choose what the parameter key and values are, however if a backend only ever has one URL per icon it is recommended that the <a href="qplaceicon.html#SingleUrl-var">QPlaceIcon::SingleUrl</a> be used as the key.</p>
<a name="categories"></a>
<h2>Categories</h2>
<p>The categories of a manager engine are relatively static entities; for engines accessing remote place datastores it may be desirable to cache the category structure rather than querying a server every time <a href="qplacemanagerengine.html#initializeCategories">QPlaceManagerEngine::initializeCategories</a>() is called. Depending on how dynamic the categories are, always downloading the freshest set of categories may be more appropriate.</p>
<a name="saving-places-to-the-manager"></a>
<h2>Saving Places to the Manager</h2>
<p>A place generally cannot be saved directly between managers as is because it contains manager specific data such as icons and categories. In order to facilitate saving to one's own manager, engine implementers should implement the <a href="qplacemanagerengine.html#compatiblePlace">QPlaceManagerEngine::compatiblePlace</a>() function. This function returns a copy of the input place with properties pruned or modified as necessary such that the copy can be saved into manager.</p>
<p>Construction of a compatible place may involve ignoring certain properties from the original place, for example if contact details are not supported, these are left out of the compatible place. Other times it may involve modifying certain properties, for example modifying the icon parameters to facilitate copying or downloading of the original place's icon to a location that the backend can access.</p>
<a name="cross-referencing-places-between-managers"></a>
<h2>Cross-Referencing Places Between Managers.</h2>
<p>Sometimes a situation may arise where we wish to cross-reference and match places between managers. Such a situation may arise where one manager provides read-only access to places (origin manager), while another second r/w manager (destination manager) is used to save selected favorites from the first. During a search of the origin manager, we may want to know which ones have been 'favorited' into the destination manager and perhaps display the customized favorite name rather than the original name.</p>
<a name="alternative-identifier-cross-referencing"></a>
<h3>Alternative Identifier Cross-Referencing</h3>
<p>In order to accomplish cross-referencing, there needs to be a link between the original place and the favorited place and this is typically handled via an alternative identifier attribute. The favorited place contains an alternative identifier attribute which has the identifier of the original place.</p>
<pre class="cpp">origin R<span class="operator">/</span>O manager(nokia) destination R<span class="operator">/</span>W manager (places_jsondb)
Save
Place id: ae246 <span class="operator">-</span><span class="operator">-</span><span class="operator">-</span><span class="operator">></span> Place id: <span class="number">0001</span>
Attribute type: x_provider Attribute type: x_id_nokia
Attribute value: nokia Attribute text value: ae246</pre>
<p>There are 3 prerequisites for implementing cross-referencing by alternative identifier. The first is that the origin manager must provide the x_provider attribute with the value being the name of the manager's <a href="qgeoserviceprovider.html">QGeoServiceProvider</a>. The attribute label should be kept empty, indicating the attribute should not be displayed to users.</p>
<p><b>Note: </b>It is generally expected that all managers should set the <tt>x_provider</tt> attribute.</p><p>The second is that <a href="qplacemanager.html#compatiblePlace">QPlaceManager::compatiblePlace</a>() of the destination manager use the <tt>x_provider</tt> attribute of the initial place and set an alternative identifier attribute of the place to be saved. The key of the alternative identifier attribute is <tt>x_id_<provider</tt> name> and the text value is the identifier of the initial place. The <tt>x_provider</tt> attribute should not be passed to the compatible place. When it is saved, the x_provider of the saved place is considered to be the destination manager.</p>
<p>The third is that <a href="qplacemanager.html#matchingPlaces">QPlaceManager::matchingPlaces</a>() of the destination manager accept the <a href="qplacematchrequest.html#AlternativeId-var">QPlaceMatchRequest::AlternativeId</a> as a parameter key and the alternative identifier attribute key as the value, in this case <tt>x_id_<provider</tt> name> would be the expected value. This indicates that the identifiers of places in the <a href="qplacematchrequest.html">QPlaceMatchRequest</a> should be matched against the <tt>x_id_<provider</tt> name> alternative identifier attributes.</p>
<p>Note that if the destination manager is to facilitate saving and cross-referencing from any arbitrary manager, it internally must accommodate saving of arbitrary key value pairs since we cannot know the provider names before hand, nor can we know what structure the ids will be.</p>
<a name="other-methods-of-linking"></a>
<h4>Other Methods of Linking</h4>
<p>If an origin manager does not supply a place id, it may be necessary to provide some other means of cross-referencing/matching. One approach might be to do so via the place coordinates, if the coordinate of a place in the origin manager is identical or close to a place in the destination manager, there is a high likelihood that they are the same place. In this case, the manager might implement <a href="qplacemanager.html#matchingPlaces">QPlaceManager::matchingPlaces</a>() to accept a <a href="qplacematchrequest.html">QPlaceMatchRequest</a> with a parameter key of 'proximity' and a parameter value of the distance two places must be in order to detect a match. for example if an origin place and destination place are within 50m of each other, they can be considered the same place.</p>
<p>Generally however it is recommended that cross referencing be implemented via alternative identifiers as mentioned above.</p>
<a name="user-readable-vs-non-user-readable-extended-attributes"></a>
<h4>User Readable vs Non-User Readable Extended Attributes</h4>
<p>If an attribute is not intended to be readable by end users, the label field should be kept empty as an indicator of this fact.</p>
</div>
<!-- @@@location-places-backend.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. 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> Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|