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 | |
40 | QT_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 | */ |
96 | QGeoCodeReply::QGeoCodeReply(QObject *parent) |
97 | : QObject(parent), |
98 | d_ptr(new QGeoCodeReplyPrivate()) {} |
99 | |
100 | QGeoCodeReply::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 | */ |
110 | QGeoCodeReply::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 | */ |
117 | QGeoCodeReply::~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 | */ |
132 | void 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 | */ |
143 | bool 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 | */ |
155 | void 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 | */ |
168 | QGeoCodeReply::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 | */ |
183 | QString QGeoCodeReply::errorString() const |
184 | { |
185 | return d_ptr->errorString; |
186 | } |
187 | |
188 | /*! |
189 | Sets the viewport which contains the results to \a viewport. |
190 | */ |
191 | void 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 | */ |
202 | QGeoShape 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 | */ |
213 | QList<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 | */ |
221 | void 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 | */ |
229 | void 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 | */ |
250 | void 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 | */ |
265 | int 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 | */ |
274 | int 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 | */ |
284 | void 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 | */ |
293 | void 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 | |
330 | QGeoCodeReplyPrivate::QGeoCodeReplyPrivate() |
331 | : error(QGeoCodeReply::NoError), |
332 | isFinished(false), |
333 | limit(-1), |
334 | offset(0) {} |
335 | |
336 | QGeoCodeReplyPrivate::QGeoCodeReplyPrivate(QGeoCodeReply::Error error, const QString &errorString) |
337 | : error(error), |
338 | errorString(errorString), |
339 | isFinished(true), |
340 | limit(-1), |
341 | offset(0) {} |
342 | |
343 | QGeoCodeReplyPrivate::~QGeoCodeReplyPrivate() {} |
344 | |
345 | QVariantMap QGeoCodeReplyPrivate::() const |
346 | { |
347 | return QVariantMap(); |
348 | } |
349 | |
350 | const QGeoCodeReplyPrivate *QGeoCodeReplyPrivate::get(const QGeoCodeReply &reply) |
351 | { |
352 | return reply.d_ptr; |
353 | } |
354 | |
355 | QGeoCodeReplyPrivate *QGeoCodeReplyPrivate::get(QGeoCodeReply &reply) |
356 | { |
357 | return reply.d_ptr; |
358 | } |
359 | |
360 | QT_END_NAMESPACE |
361 | |