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 "qgeocodereply.h"
38#include "qgeocodereply_p.h"
39
40QT_BEGIN_NAMESPACE
41/*!
42 \class QGeoCodeReply
43 \inmodule QtLocation
44 \ingroup QtLocation-geocoding
45 \since 5.6
46
47 \brief The QGeoCodeReply class manages an operation started by an
48 instance of QGeoCodingManager.
49
50 Instances of QGeoCodeReply manage the state and results of these
51 operations.
52
53 The isFinished(), error() and errorString() methods provide information
54 on whether the operation has completed and if it completed successfully.
55
56 The finished() and error(QGeoCodeReply::Error,QString)
57 signals can be used to monitor the progress of the operation.
58
59 It is possible that a newly created QGeoCodeReply may be in a finished
60 state, most commonly because an error has occurred. Since such an instance
61 will never emit the finished() or
62 error(QGeoCodeReply::Error,QString) signals, it is
63 important to check the result of isFinished() before making the connections
64 to the signals. The documentation for QGeoCodingManager demonstrates how
65 this might be carried out.
66
67 If the operation completes successfully the results will be able to be
68 accessed with locations().
69*/
70
71/*!
72 \enum QGeoCodeReply::Error
73
74 Describes an error which prevented the completion of the operation.
75
76 \value NoError
77 No error has occurred.
78 \value EngineNotSetError
79 The geocoding manager that was used did not have a QGeoCodingManagerEngine instance associated with it.
80 \value CommunicationError
81 An error occurred while communicating with the service provider.
82 \value ParseError
83 The response from the service provider was in an unrecognizable format.
84 \value UnsupportedOptionError
85 The requested operation or one of the options for the operation are not
86 supported by the service provider.
87 \value CombinationError
88 An error occurred while results where being combined from multiple sources.
89 \value UnknownError
90 An error occurred which does not fit into any of the other categories.
91*/
92
93/*!
94 Constructs a geocode reply with the specified \a parent.
95*/
96QGeoCodeReply::QGeoCodeReply(QObject *parent)
97 : QObject(parent),
98 d_ptr(new QGeoCodeReplyPrivate()) {}
99
100QGeoCodeReply::QGeoCodeReply(QGeoCodeReplyPrivate &dd, QObject *parent)
101 : QObject(parent),
102 d_ptr(&dd)
103{
104
105}
106
107/*!
108 Constructs a geocode reply with a given \a error and \a errorString and the specified \a parent.
109*/
110QGeoCodeReply::QGeoCodeReply(Error error, const QString &errorString, QObject *parent)
111 : QObject(parent),
112 d_ptr(new QGeoCodeReplyPrivate(error, errorString)) {}
113
114/*!
115 Destroys this reply object.
116*/
117QGeoCodeReply::~QGeoCodeReply()
118{
119 delete d_ptr;
120}
121
122/*!
123 Sets whether or not this reply has finished to \a finished.
124
125 If \a finished is true, this will cause the finished() signal to be
126 emitted.
127
128 If the operation completed successfully, QGeoCodeReply::setLocations()
129 should be called before this function. If an error occurred,
130 QGeoCodeReply::setError() should be used instead.
131*/
132void QGeoCodeReply::setFinished(bool finished)
133{
134 d_ptr->isFinished = finished;
135 if (d_ptr->isFinished)
136 emit this->finished();
137}
138
139/*!
140 Return true if the operation completed successfully or encountered an
141 error which cause the operation to come to a halt.
142*/
143bool QGeoCodeReply::isFinished() const
144{
145 return d_ptr->isFinished;
146}
147
148/*!
149 Sets the error state of this reply to \a error and the textual
150 representation of the error to \a errorString.
151
152 This will also cause error() and finished() signals to be emitted, in that
153 order.
154*/
155void QGeoCodeReply::setError(QGeoCodeReply::Error error, const QString &errorString)
156{
157 d_ptr->error = error;
158 d_ptr->errorString = errorString;
159 emit this->error(error, errorString);
160 setFinished(true);
161}
162
163/*!
164 Returns the error state of this reply.
165
166 If the result is QGeoCodeReply::NoError then no error has occurred.
167*/
168QGeoCodeReply::Error QGeoCodeReply::error() const
169{
170 return d_ptr->error;
171}
172
173/*!
174 Returns the textual representation of the error state of this reply.
175
176 If no error has occurred this will return an empty string. It is possible
177 that an error occurred which has no associated textual representation, in
178 which case this will also return an empty string.
179
180 To determine whether an error has occurred, check to see if
181 QGeoCodeReply::error() is equal to QGeoCodeReply::NoError.
182*/
183QString QGeoCodeReply::errorString() const
184{
185 return d_ptr->errorString;
186}
187
188/*!
189 Sets the viewport which contains the results to \a viewport.
190*/
191void QGeoCodeReply::setViewport(const QGeoShape &viewport)
192{
193 d_ptr->viewport = viewport;
194}
195
196/*!
197 Returns the viewport which contains the results.
198
199 This function will return 0 if no viewport bias
200 was specified in the QGeoCodingManager function which created this reply.
201*/
202QGeoShape QGeoCodeReply::viewport() const
203{
204 return d_ptr->viewport;
205}
206
207/*!
208 Returns a list of locations.
209
210 The locations are the results of the operation corresponding to the
211 QGeoCodingManager function which created this reply.
212*/
213QList<QGeoLocation> QGeoCodeReply::locations() const
214{
215 return d_ptr->locations;
216}
217
218/*!
219 Adds \a location to the list of locations in this reply.
220*/
221void QGeoCodeReply::addLocation(const QGeoLocation &location)
222{
223 d_ptr->locations.append(t: location);
224}
225
226/*!
227 Sets the list of \a locations in the reply.
228*/
229void QGeoCodeReply::setLocations(const QList<QGeoLocation> &locations)
230{
231 d_ptr->locations = locations;
232}
233
234/*!
235 \fn void QGeoCodeReply::aborted()
236 \since 5.9
237
238 This signal is emitted when the operation has been cancelled.
239
240 \sa abort()
241*/
242
243/*!
244 Cancels the operation immediately.
245
246 This will do nothing if the reply is finished.
247
248 \sa aborted()
249*/
250void QGeoCodeReply::abort()
251{
252 if (!isFinished())
253 setFinished(true);
254 emit aborted();
255}
256
257/*!
258 Returns the limit on the number of responses from each data source.
259
260 If no limit was set this function will return -1.
261
262 This may be more than locations().length() if the number of responses
263 was less than the number requested.
264*/
265int QGeoCodeReply::limit() const
266{
267 return d_ptr->limit;
268}
269
270/*!
271 Returns the offset into the entire result set at which to start
272 fetching results.
273*/
274int QGeoCodeReply::offset() const
275{
276 return d_ptr->offset;
277}
278
279/*!
280 Sets the limit on the number of responses from each data source to \a limit.
281
282 If \a limit is -1 then all available responses will be returned.
283*/
284void QGeoCodeReply::setLimit(int limit)
285{
286 d_ptr->limit = limit;
287}
288
289/*!
290 Sets the offset in the entire result set at which to start
291 fetching result to \a offset.
292*/
293void QGeoCodeReply::setOffset(int offset)
294{
295 d_ptr->offset = offset;
296}
297
298/*!
299 \fn void QGeoCodeReply::finished()
300
301 This signal is emitted when this reply has finished processing.
302
303 If error() equals QGeoCodeReply::NoError then the processing
304 finished successfully.
305
306 This signal and QGeoCodingManager::finished() will be
307 emitted at the same time.
308
309 \note Do not delete this reply object in the slot connected to this
310 signal. Use deleteLater() instead.
311*/
312/*!
313 \fn void QGeoCodeReply::error(QGeoCodeReply::Error error, const QString &errorString)
314
315 This signal is emitted when an error has been detected in the processing of
316 this reply. The finished() signal will probably follow.
317
318 The error will be described by the error code \a error. If \a errorString is
319 not empty it will contain a textual description of the error.
320
321 This signal and QGeoCodingManager::error() will be emitted at the same time.
322
323 \note Do not delete this reply object in the slot connected to this
324 signal. Use deleteLater() instead.
325*/
326
327/*******************************************************************************
328*******************************************************************************/
329
330QGeoCodeReplyPrivate::QGeoCodeReplyPrivate()
331 : error(QGeoCodeReply::NoError),
332 isFinished(false),
333 limit(-1),
334 offset(0) {}
335
336QGeoCodeReplyPrivate::QGeoCodeReplyPrivate(QGeoCodeReply::Error error, const QString &errorString)
337 : error(error),
338 errorString(errorString),
339 isFinished(true),
340 limit(-1),
341 offset(0) {}
342
343QGeoCodeReplyPrivate::~QGeoCodeReplyPrivate() {}
344
345QVariantMap QGeoCodeReplyPrivate::extraData() const
346{
347 return QVariantMap();
348}
349
350const QGeoCodeReplyPrivate *QGeoCodeReplyPrivate::get(const QGeoCodeReply &reply)
351{
352 return reply.d_ptr;
353}
354
355QGeoCodeReplyPrivate *QGeoCodeReplyPrivate::get(QGeoCodeReply &reply)
356{
357 return reply.d_ptr;
358}
359
360QT_END_NAMESPACE
361

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