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

source code of qtlocation/src/location/maps/qgeocodingmanagerengine.cpp