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 "qgeoroutereply.h"
38 #include "qgeoroutereply_p.h"
39
40 QT_BEGIN_NAMESPACE
41
42 /*!
43 \class QGeoRouteReply
44 \inmodule QtLocation
45 \ingroup QtLocation-routing
46 \since 5.6
47
48 \brief The QGeoRouteReply class manages an operation started by an instance
49 of QGeoRoutingManager.
50
51 Instances of QGeoRouteReply manage the state and results of these
52 operations.
53
54 The isFinished(), error() and errorString() methods provide information
55 on whether the operation has completed and if it completed successfully.
56
57 The finished() and error(QGeoRouteReply::Error,QString)
58 signals can be used to monitor the progress of the operation.
59
60 It is possible that a newly created QGeoRouteReply may be in a finished
61 state, most commonly because an error has occurred. Since such an instance
62 will never emit the finished() or
63 error(QGeoRouteReply::Error,QString) signals, it is
64 important to check the result of isFinished() before making the connections
65 to the signals. The documentation for QGeoRoutingManager demonstrates how
66 this might be carried out.
67
68 If the operation completes successfully the results will be able to be
69 accessed with routes().
70 */
71
72 /*!
73 \enum QGeoRouteReply::Error
74
75 Describes an error which prevented the completion of the operation.
76
77 \value NoError
78 No error has occurred.
79 \value EngineNotSetError
80 The routing manager that was used did not have a QGeoRoutingManagerEngine instance associated with it.
81 \value CommunicationError
82 An error occurred while communicating with the service provider.
83 \value ParseError
84 The response from the service provider was in an unrecognizable format.
85 \value UnsupportedOptionError
86 The requested operation or one of the options for the operation are not
87 supported by the service provider.
88 \value UnknownError
89 An error occurred which does not fit into any of the other categories.
90 */
91
92 /*!
93 Constructs a route reply object based on \a request, with the specified \a parent.
94 */
QGeoRouteReply(const QGeoRouteRequest & request,QObject * parent)95 QGeoRouteReply::QGeoRouteReply(const QGeoRouteRequest &request, QObject *parent)
96 : QObject(parent),
97 d_ptr(new QGeoRouteReplyPrivate(request))
98 {
99 }
100
101 /*!
102 Constructs a route reply with a given \a error and \a errorString and the specified \a parent.
103 */
QGeoRouteReply(Error error,const QString & errorString,QObject * parent)104 QGeoRouteReply::QGeoRouteReply(Error error, const QString &errorString, QObject *parent)
105 : QObject(parent),
106 d_ptr(new QGeoRouteReplyPrivate(error, errorString)) {}
107
108 /*!
109 Destroys this route reply object.
110 */
~QGeoRouteReply()111 QGeoRouteReply::~QGeoRouteReply()
112 {
113 delete d_ptr;
114 }
115
116 /*!
117 Sets whether or not this reply has finished to \a finished.
118
119 If \a finished is true, this will cause the finished() signal to be
120 emitted.
121
122 If the operation completed successfully, QGeoRouteReply::setRoutes() should
123 be called before this function. If an error occurred,
124 QGeoRouteReply::setError() should be used instead.
125 */
setFinished(bool finished)126 void QGeoRouteReply::setFinished(bool finished)
127 {
128 d_ptr->isFinished = finished;
129 if (d_ptr->isFinished)
130 emit this->finished();
131 }
132
133 /*!
134 Return true if the operation completed successfully or encountered an
135 error which cause the operation to come to a halt.
136 */
isFinished() const137 bool QGeoRouteReply::isFinished() const
138 {
139 return d_ptr->isFinished;
140 }
141
142 /*!
143 Sets the error state of this reply to \a error and the textual
144 representation of the error to \a errorString.
145
146 This will also cause error() and finished() signals to be emitted, in that
147 order.
148 */
setError(QGeoRouteReply::Error error,const QString & errorString)149 void QGeoRouteReply::setError(QGeoRouteReply::Error error, const QString &errorString)
150 {
151 d_ptr->error = error;
152 d_ptr->errorString = errorString;
153 emit this->error(error, errorString);
154 setFinished(true);
155 }
156
157 /*!
158 Returns the error state of this reply.
159
160 If the result is QGeoRouteReply::NoError then no error has occurred.
161 */
error() const162 QGeoRouteReply::Error QGeoRouteReply::error() const
163 {
164 return d_ptr->error;
165 }
166
167 /*!
168 Returns the textual representation of the error state of this reply.
169
170 If no error has occurred this will return an empty string. It is possible
171 that an error occurred which has no associated textual representation, in
172 which case this will also return an empty string.
173
174 To determine whether an error has occurred, check to see if
175 QGeoRouteReply::error() is equal to QGeoRouteReply::NoError.
176 */
errorString() const177 QString QGeoRouteReply::errorString() const
178 {
179 return d_ptr->errorString;
180 }
181
182 /*!
183 Returns the route request which specified the route.
184 */
request() const185 QGeoRouteRequest QGeoRouteReply::request() const
186 {
187 return d_ptr->request;
188 }
189
190 /*!
191 Returns the list of routes which were requested.
192 */
routes() const193 QList<QGeoRoute> QGeoRouteReply::routes() const
194 {
195 return d_ptr->routes;
196 }
197
198 /*!
199 Sets the list of routes in the reply to \a routes.
200 */
setRoutes(const QList<QGeoRoute> & routes)201 void QGeoRouteReply::setRoutes(const QList<QGeoRoute> &routes)
202 {
203 d_ptr->routes = routes;
204 }
205
206 /*!
207 Appends the list of \a routes to the existing list.
208 */
addRoutes(const QList<QGeoRoute> & routes)209 void QGeoRouteReply::addRoutes(const QList<QGeoRoute> &routes)
210 {
211 d_ptr->routes.append(routes);
212 }
213
214 /*!
215 \fn void QGeoRouteReply::aborted()
216 \since 5.9
217
218 This signal is emitted when the operation has been cancelled.
219
220 \sa abort()
221 */
222
223 /*!
224 Cancels the operation immediately.
225
226 This will do nothing if the reply is finished.
227 */
abort()228 void QGeoRouteReply::abort()
229 {
230 emit aborted();
231 }
232
233 /*!
234 \fn void QGeoRouteReply::finished()
235
236 This signal is emitted when this reply has finished processing.
237
238 If error() equals QGeoRouteReply::NoError then the processing
239 finished successfully.
240
241 This signal and QGeoRoutingManager::finished() will be
242 emitted at the same time.
243
244 \note Do not delete this reply object in the slot connected to this
245 signal. Use deleteLater() instead.
246 */
247 /*!
248 \fn void QGeoRouteReply::error(QGeoRouteReply::Error error, const QString &errorString)
249
250 This signal is emitted when an error has been detected in the processing of
251 this reply. The finished() signal will probably follow.
252
253 The error will be described by the error code \a error. If \a errorString is
254 not empty it will contain a textual description of the error.
255
256 This signal and QGeoRoutingManager::error() will be emitted at the same time.
257
258 \note Do not delete this reply object in the slot connected to this
259 signal. Use deleteLater() instead.
260 */
261
262 /*******************************************************************************
263 *******************************************************************************/
264
QGeoRouteReplyPrivate(const QGeoRouteRequest & request)265 QGeoRouteReplyPrivate::QGeoRouteReplyPrivate(const QGeoRouteRequest &request)
266 : error(QGeoRouteReply::NoError),
267 isFinished(false),
268 request(request) {}
269
QGeoRouteReplyPrivate(QGeoRouteReply::Error error,QString errorString)270 QGeoRouteReplyPrivate::QGeoRouteReplyPrivate(QGeoRouteReply::Error error, QString errorString)
271 : error(error),
272 errorString(errorString),
273 isFinished(true) {}
274
~QGeoRouteReplyPrivate()275 QGeoRouteReplyPrivate::~QGeoRouteReplyPrivate() {}
276
277 QT_END_NAMESPACE
278