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