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 | */ |
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 | */ |
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 | */ |
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 | */ |
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 | */ |
137 | 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 | */ |
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 | */ |
162 | 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 | */ |
177 | QString QGeoRouteReply::errorString() const |
178 | { |
179 | return d_ptr->errorString; |
180 | } |
181 | |
182 | /*! |
183 | Returns the route request which specified the route. |
184 | */ |
185 | QGeoRouteRequest QGeoRouteReply::request() const |
186 | { |
187 | return d_ptr->request; |
188 | } |
189 | |
190 | /*! |
191 | Returns the list of routes which were requested. |
192 | */ |
193 | 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 | */ |
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 | */ |
209 | void QGeoRouteReply::addRoutes(const QList<QGeoRoute> &routes) |
210 | { |
211 | d_ptr->routes.append(t: 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 | */ |
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 | |
265 | QGeoRouteReplyPrivate::QGeoRouteReplyPrivate(const QGeoRouteRequest &request) |
266 | : error(QGeoRouteReply::NoError), |
267 | isFinished(false), |
268 | request(request) {} |
269 | |
270 | QGeoRouteReplyPrivate::QGeoRouteReplyPrivate(QGeoRouteReply::Error error, QString errorString) |
271 | : error(error), |
272 | errorString(errorString), |
273 | isFinished(true) {} |
274 | |
275 | QGeoRouteReplyPrivate::~QGeoRouteReplyPrivate() {} |
276 | |
277 | QT_END_NAMESPACE |
278 | |