Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qgeocodingmanagerengine.cpp
Go to the documentation of this file.
1// Copyright (C) 2015 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qgeocodingmanagerengine.h"
5#include "qgeocodingmanagerengine_p.h"
6
7#include "qgeoaddress.h"
8#include "qgeocoordinate.h"
9
10#include <QtPositioning/QGeoShape>
11
12QT_BEGIN_NAMESPACE
13
14/*!
15 \class QGeoCodingManagerEngine
16 \inmodule QtLocation
17 \ingroup QtLocation-impl
18 \since 5.6
19
20 \brief The QGeoCodingManagerEngine class provides an interface and
21 convenience methods to implementers of QGeoServiceProvider plugins who want
22 to provide support for geocoding operations.
23
24 \note There are no source or binary compatibility guarantees for the
25 backend classes. The API is only guaranteed to work with the Qt version it
26 was developed against. API changes will however only be made in minor
27 releases. (6.6, 6.7, and so on.)
28
29 In the default implementation, supportsGeocoding() and
30 supportsReverseGeocoding() returns false while geocode() and
31 reverseGeocode() cause QGeoCodeReply::UnsupportedOptionError to occur.
32
33 If the service provider supports geocoding the subclass should provide an
34 implementation of geocode() and call setSupportsGeocoding(true) at
35 some point in time before geocode() is called.
36
37 Similarly, if the service provider supports reverse geocoding the subclass
38 should provide an implementation reverseGeocode() and call
39 setSupportsReverseGeocoding(true) at some point in time before
40 reverseGeocode() is called.
41
42 A subclass of QGeoCodingManagerEngine will often make use of a subclass
43 fo QGeoCodeReply internally, in order to add any engine-specific
44 data (such as a QNetworkReply object for network-based services) to the
45 QGeoCodeReply instances used by the engine.
46
47 \sa QGeoCodingManager
48*/
49
50/*!
51 Constructs a new engine with the specified \a parent, using \a parameters
52 to pass any implementation specific data to the engine.
53*/
54QGeoCodingManagerEngine::QGeoCodingManagerEngine(const QVariantMap &parameters, QObject *parent)
55 : QObject(parent),
56 d_ptr(new QGeoCodingManagerEnginePrivate())
57{
58 Q_UNUSED(parameters);
59}
60
61/*!
62 Destroys this engine.
63*/
64QGeoCodingManagerEngine::~QGeoCodingManagerEngine()
65{
66 delete d_ptr;
67}
68
69/*!
70 Sets the name which this engine implementation uses to distinguish itself
71 from the implementations provided by other plugins to \a managerName.
72
73 The combination of managerName() and managerVersion() should be unique
74 amongst plugin implementations.
75*/
76void QGeoCodingManagerEngine::setManagerName(const QString &managerName)
77{
78 d_ptr->managerName = managerName;
79}
80
81/*!
82 Returns the name which this engine implementation uses to distinguish
83 itself from the implementations provided by other plugins.
84
85 The combination of managerName() and managerVersion() should be unique
86 amongst plugin implementations.
87*/
88QString QGeoCodingManagerEngine::managerName() const
89{
90 return d_ptr->managerName;
91}
92
93/*!
94 Sets the version of this engine implementation to \a managerVersion.
95
96 The combination of managerName() and managerVersion() should be unique
97 amongst plugin implementations.
98*/
99void QGeoCodingManagerEngine::setManagerVersion(int managerVersion)
100{
101 d_ptr->managerVersion = managerVersion;
102}
103
104/*!
105 Returns the version of this engine implementation.
106
107 The combination of managerName() and managerVersion() should be unique
108 amongst plugin implementations.
109*/
110int QGeoCodingManagerEngine::managerVersion() const
111{
112 return d_ptr->managerVersion;
113}
114
115/*!
116 Begins the geocoding of \a address. Geocoding is the process of finding a
117 coordinate that corresponds to a given address.
118
119 A QGeoCodeReply object will be returned, which can be used to manage the
120 geocoding operation and to return the results of the operation.
121
122 This engine and the returned QGeoCodeReply object will emit signals
123 indicating if the operation completes or if errors occur.
124
125 If supportsGeocoding() returns false an
126 QGeoCodeReply::UnsupportedOptionError will occur.
127
128 Once the operation has completed, QGeoCodeReply::locations() can be used to
129 retrieve the results, which will consist of a list of QGeoLocation objects.
130 These objects represent a combination of coordinate and address data.
131
132 The address data returned in the results may be different from \a address.
133 This will usually occur if the geocoding service backend uses a different
134 canonical form of addresses or if \a address was only partially filled out.
135
136 If \a bounds is non-null and a valid QGeoShape it will be used to
137 limit the results to those that are contained by \a bounds. This is
138 particularly useful if \a address is only partially filled out, as the
139 service will attempt to geocode all matches for the specified data.
140
141 The user is responsible for deleting the returned reply object, although
142 this can be done in the slot connected to QGeoCodingManagerEngine::finished(),
143 QGeoCodingManagerEngine::errorOccurred(), QGeoCodeReply::finished() or
144 QGeoCodeReply::errorOccurred() with deleteLater().
145*/
146QGeoCodeReply *QGeoCodingManagerEngine::geocode(const QGeoAddress &address,
147 const QGeoShape &bounds)
148{
149 Q_UNUSED(address);
150 Q_UNUSED(bounds);
151 return new QGeoCodeReply(QGeoCodeReply::UnsupportedOptionError,
152 QLatin1String("Geocoding is not supported by this service provider."), this);
153}
154
155/*!
156 Begins the reverse geocoding of \a coordinate. Reverse geocoding is the
157 process of finding an address that corresponds to a given coordinate.
158
159 A QGeoCodeReply object will be returned, which can be used to manage the
160 reverse geocoding operation and to return the results of the operation.
161
162 This engine and the returned QGeoCodeReply object will emit signals
163 indicating if the operation completes or if errors occur.
164
165 If supportsReverseGeocoding() returns false an
166 QGeoCodeReply::UnsupportedOptionError will occur.
167
168 At that point QGeoCodeReply::locations() can be used to retrieve the
169 results, which will consist of a list of QGeoLocation objects. These objects
170 represent a combination of coordinate and address data.
171
172 The coordinate data returned in the results may be different from \a
173 coordinate. This will usually occur if the reverse geocoding service
174 backend shifts the coordinates to be closer to the matching addresses, or
175 if the backend returns results at multiple levels of detail.
176
177 If multiple results are returned by the reverse geocoding service backend
178 they will be provided in order of specificity. This normally occurs if the
179 backend is configured to reverse geocode across multiple levels of detail.
180 As an example, some services will return address and coordinate pairs for
181 the street address, the city, the state and the country.
182
183 If \a bounds is non-null and a valid QGeoShape it will be used to
184 limit the results to those that are contained by \a bounds.
185
186 The user is responsible for deleting the returned reply object, although
187 this can be done in the slot connected to QGeoCodingManagerEngine::finished(),
188 QGeoCodingManagerEngine::errorOccurred(), QGeoCodeReply::finished() or
189 QGeoCodeReply::errorOccurred() with deleteLater().
190*/
191QGeoCodeReply *QGeoCodingManagerEngine::reverseGeocode(const QGeoCoordinate &coordinate,
192 const QGeoShape &bounds)
193{
194 Q_UNUSED(coordinate);
195 Q_UNUSED(bounds);
196 return new QGeoCodeReply(QGeoCodeReply::UnsupportedOptionError,
197 QLatin1String("Reverse geocoding is not supported by this service provider."), this);
198}
199
200/*!
201 Begins geocoding for a location matching \a address.
202
203 A QGeoCodeReply object will be returned, which can be used to manage the
204 geocoding operation and to return the results of the operation.
205
206 This engine and the returned QGeoCodeReply object will emit signals
207 indicating if the operation completes or if errors occur.
208
209 Once the operation has completed, QGeoCodeReply::locations() can be used to
210 retrieve the results, which will consist of a list of QGeoLocation objects.
211 These objects represent a combination of coordinate and address data.
212
213 If \a limit is -1 the entire result set will be returned, otherwise at most
214 \a limit results will be returned.
215
216 The \a offset parameter is used to ask the geocoding service to not return the
217 first \a offset results.
218
219 The \a limit and \a offset results are used together to implement paging.
220
221 If \a bounds is non-null and a valid QGeoShape it will be used to
222 limit the results to those that are contained by \a bounds.
223
224 The user is responsible for deleting the returned reply object, although
225 this can be done in the slot connected to QGeoCodingManagerEngine::finished(),
226 QGeoCodingManagerEngine::errorOccurred(), QGeoCodeReply::finished() or
227 QGeoCodeReply::errorOccurred() with deleteLater().
228*/
229QGeoCodeReply *QGeoCodingManagerEngine::geocode(const QString &address,
230 int limit,
231 int offset,
232 const QGeoShape &bounds)
233{
234 Q_UNUSED(address);
235 Q_UNUSED(limit);
236 Q_UNUSED(offset);
237 Q_UNUSED(bounds);
238
239 return new QGeoCodeReply(QGeoCodeReply::UnsupportedOptionError,
240 QLatin1String("Searching is not supported by this service provider."), this);
241}
242
243/*!
244 Sets the locale to be used by this manager to \a locale.
245
246 If this geocoding manager supports returning the results
247 in different languages, they will be returned in the language of \a locale.
248
249 The locale used defaults to the system locale if this is not set.
250*/
251void QGeoCodingManagerEngine::setLocale(const QLocale &locale)
252{
253 d_ptr->locale = locale;
254}
255
256/*!
257 Returns the locale used to hint to this geocoding manager about what
258 language to use for the results.
259*/
260QLocale QGeoCodingManagerEngine::locale() const
261{
262 return d_ptr->locale;
263}
264
265/*!
266\fn void QGeoCodingManagerEngine::finished(QGeoCodeReply *reply)
267
268 This signal is emitted when \a reply has finished processing.
269
270 If reply::error() equals QGeoCodeReply::NoError then the processing
271 finished successfully.
272
273 This signal and QGeoCodeReply::finished() will be emitted at the same
274 time.
275
276 \note Do not delete the \a reply object in the slot connected to this
277 signal. Use deleteLater() instead.
278*/
279
280/*!
281\fn void QGeoCodingManagerEngine::errorOccurred(QGeoCodeReply *reply, QGeoCodeReply::Error error, const QString &errorString)
282
283 This signal is emitted when an error has been detected in the processing of
284 \a reply. The QGeoCodingManagerEngine::finished() signal will probably follow.
285
286 The error will be described by the error code \a error. If \a errorString is
287 not empty it will contain a textual description of the error.
288
289 This signal and QGeoCodeReply::errorOccurred() will be emitted at the same time.
290
291 \note Do not delete the \a reply object in the slot connected to this
292 signal. Use deleteLater() instead.
293*/
294
295QT_END_NAMESPACE