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 "qgeoroutingmanagerengine.h" |
38 | #include "qgeoroutingmanagerengine_p.h" |
39 | |
40 | QT_BEGIN_NAMESPACE |
41 | |
42 | /*! |
43 | \class QGeoRoutingManagerEngine |
44 | \inmodule QtLocation |
45 | \ingroup QtLocation-impl |
46 | \since 5.6 |
47 | |
48 | \brief The QGeoRoutingManagerEngine class provides an interface and |
49 | convenience methods to implementers of QGeoServiceProvider plugins who want |
50 | to provide access to geographic routing information. |
51 | |
52 | Subclasses of QGeoRoutingManagerEngine need to provide an implementation of |
53 | calculateRoute(). |
54 | |
55 | In the default implementation, supportsRouteUpdates() returns false and |
56 | updateRoute() returns a QGeoRouteReply object containing a |
57 | QGeoRouteReply::UnsupportedOptionError. |
58 | |
59 | If the routing service supports updating routes as they are being |
60 | traveled, the subclass should provide an implementation of updateRoute() |
61 | and call setSupportsRouteUpdates(true) at some point in time before |
62 | updateRoute() is called. |
63 | |
64 | The function setSupportsRouteUpdates() is one of several functions which |
65 | configure the reported capabilities of the engine. If the capabilities |
66 | of an engine differ from the default values these functions should be |
67 | used so that the reported capabilities are accurate. |
68 | |
69 | It is important that this is done before calculateRoute(), updateRoute() |
70 | or any of the capability reporting functions are used to prevent |
71 | incorrect or inconsistent behavior. |
72 | |
73 | A subclass of QGeoRouteManagerEngine will often make use of a subclass |
74 | fo QGeoRouteReply internally, in order to add any engine-specific |
75 | data (such as a QNetworkReply object for network-based services) to the |
76 | QGeoRouteReply instances used by the engine. |
77 | |
78 | \sa QGeoRoutingManager |
79 | */ |
80 | |
81 | /*! |
82 | Constructs a new engine with the specified \a parent, using \a parameters |
83 | to pass any implementation specific data to the engine. |
84 | */ |
85 | QGeoRoutingManagerEngine::QGeoRoutingManagerEngine(const QVariantMap ¶meters, QObject *parent) |
86 | : QObject(parent), |
87 | d_ptr(new QGeoRoutingManagerEnginePrivate()) |
88 | { |
89 | Q_UNUSED(parameters); |
90 | } |
91 | |
92 | /*! |
93 | Destroys this engine. |
94 | */ |
95 | QGeoRoutingManagerEngine::~QGeoRoutingManagerEngine() |
96 | { |
97 | delete d_ptr; |
98 | } |
99 | |
100 | /*! |
101 | Sets the name which this engine implementation uses to distinguish itself |
102 | from the implementations provided by other plugins to \a managerName. |
103 | |
104 | The combination of managerName() and managerVersion() should be unique |
105 | amongst plugin implementations. |
106 | */ |
107 | void QGeoRoutingManagerEngine::setManagerName(const QString &managerName) |
108 | { |
109 | d_ptr->managerName = managerName; |
110 | } |
111 | |
112 | /*! |
113 | Returns the name which this engine implementation uses to distinguish |
114 | itself from the implementations provided by other plugins. |
115 | |
116 | The combination of managerName() and managerVersion() should be unique |
117 | amongst plugin implementations. |
118 | */ |
119 | QString QGeoRoutingManagerEngine::managerName() const |
120 | { |
121 | return d_ptr->managerName; |
122 | } |
123 | |
124 | /*! |
125 | Sets the version of this engine implementation to \a managerVersion. |
126 | |
127 | The combination of managerName() and managerVersion() should be unique |
128 | amongst plugin implementations. |
129 | */ |
130 | void QGeoRoutingManagerEngine::setManagerVersion(int managerVersion) |
131 | { |
132 | d_ptr->managerVersion = managerVersion; |
133 | } |
134 | |
135 | /*! |
136 | Returns the version of this engine implementation. |
137 | |
138 | The combination of managerName() and managerVersion() should be unique |
139 | amongst plugin implementations. |
140 | */ |
141 | int QGeoRoutingManagerEngine::managerVersion() const |
142 | { |
143 | return d_ptr->managerVersion; |
144 | } |
145 | |
146 | /*! |
147 | \fn QGeoRouteReply *QGeoRoutingManagerEngine::calculateRoute(const QGeoRouteRequest &request) |
148 | |
149 | Begins the calculation of the route specified by \a request. |
150 | |
151 | A QGeoRouteReply object will be returned, which can be used to manage the |
152 | routing operation and to return the results of the operation. |
153 | |
154 | This engine and the returned QGeoRouteReply object will emit signals |
155 | indicating if the operation completes or if errors occur. |
156 | |
157 | Once the operation has completed, QGeoRouteReply::routes can be used to |
158 | retrieve the calculated route or routes. |
159 | |
160 | If \a request includes features which are not supported by this engine, as |
161 | reported by the methods in this engine, then a |
162 | QGeoRouteReply::UnsupportedOptionError will occur. |
163 | |
164 | The user is responsible for deleting the returned reply object, although |
165 | this can be done in the slot connected to QGeoRoutingManagerEngine::finished(), |
166 | QGeoRoutingManagerEngine::error(), QGeoRouteReply::finished() or |
167 | QGeoRouteReply::error() with deleteLater(). |
168 | */ |
169 | |
170 | /*! |
171 | Begins the process of updating \a route based on the current position \a |
172 | position. |
173 | |
174 | A QGeoRouteReply object will be returned, which can be used to manage the |
175 | routing operation and to return the results of the operation. |
176 | |
177 | This engine and the returned QGeoRouteReply object will emit signals |
178 | indicating if the operation completes or if errors occur. |
179 | |
180 | If supportsRouteUpdates() returns false an |
181 | QGeoRouteReply::UnsupportedOptionError will occur. |
182 | |
183 | Once the operation has completed, QGeoRouteReply::routes can be used to |
184 | retrieve the updated route. |
185 | |
186 | The returned route could be entirely different to the original route, |
187 | especially if \a position is far enough away from the initial route. |
188 | Otherwise the route will be similar, although the remaining time and |
189 | distance will be updated and any segments of the original route which |
190 | have been traversed will be removed. |
191 | |
192 | The user is responsible for deleting the returned reply object, although |
193 | this can be done in the slot connected to QGeoRoutingManagerEngine::finished(), |
194 | QGeoRoutingManagerEngine::error(), QGeoRouteReply::finished() or |
195 | QGeoRouteReply::error() with deleteLater(). |
196 | */ |
197 | QGeoRouteReply *QGeoRoutingManagerEngine::updateRoute(const QGeoRoute &route, const QGeoCoordinate &position) |
198 | { |
199 | Q_UNUSED(route); |
200 | Q_UNUSED(position); |
201 | return new QGeoRouteReply(QGeoRouteReply::UnsupportedOptionError, |
202 | QLatin1String("The updating of routes is not supported by this service provider." ), this); |
203 | } |
204 | |
205 | /*! |
206 | Sets the travel modes supported by this engine to \a travelModes. |
207 | |
208 | It is important that subclasses use this method to ensure that the engine |
209 | reports its capabilities correctly. If this function is not used the |
210 | engine will report that it supports no travel modes at all. |
211 | */ |
212 | void QGeoRoutingManagerEngine::setSupportedTravelModes(QGeoRouteRequest::TravelModes travelModes) |
213 | { |
214 | d_ptr->supportedTravelModes = travelModes; |
215 | } |
216 | |
217 | /*! |
218 | Returns the travel modes supported by this engine. |
219 | */ |
220 | QGeoRouteRequest::TravelModes QGeoRoutingManagerEngine::supportedTravelModes() const |
221 | { |
222 | return d_ptr->supportedTravelModes; |
223 | } |
224 | |
225 | /*! |
226 | Sets the types of features that this engine can take into account |
227 | during route planning to \a featureTypes. |
228 | |
229 | It is important that subclasses use this method to ensure that the engine |
230 | reports its capabilities correctly. If this function is not used the |
231 | engine will report that it supports no feature types at all. |
232 | */ |
233 | void QGeoRoutingManagerEngine::setSupportedFeatureTypes(QGeoRouteRequest::FeatureTypes featureTypes) |
234 | { |
235 | d_ptr->supportedFeatureTypes = featureTypes; |
236 | } |
237 | |
238 | /*! |
239 | Returns the types of features that this engine can take into account |
240 | during route planning. |
241 | */ |
242 | QGeoRouteRequest::FeatureTypes QGeoRoutingManagerEngine::supportedFeatureTypes() const |
243 | { |
244 | return d_ptr->supportedFeatureTypes; |
245 | } |
246 | |
247 | /*! |
248 | Sets the weightings which this engine can apply to different features |
249 | during route planning to \a featureWeights. |
250 | |
251 | It is important that subclasses use this method to ensure that the engine |
252 | reports its capabilities correctly. If this function is not used the |
253 | engine will report that it supports no feature weights at all. |
254 | */ |
255 | void QGeoRoutingManagerEngine::setSupportedFeatureWeights(QGeoRouteRequest::FeatureWeights featureWeights) |
256 | { |
257 | d_ptr->supportedFeatureWeights = featureWeights; |
258 | d_ptr->supportedFeatureWeights |= QGeoRouteRequest::NeutralFeatureWeight; |
259 | } |
260 | |
261 | /*! |
262 | Returns the weightings which this engine can apply to different features |
263 | during route planning. |
264 | */ |
265 | QGeoRouteRequest::FeatureWeights QGeoRoutingManagerEngine::supportedFeatureWeights() const |
266 | { |
267 | return d_ptr->supportedFeatureWeights; |
268 | } |
269 | |
270 | /*! |
271 | Sets the route optimizations supported by this engine to \a optimizations. |
272 | |
273 | It is important that subclasses use this method to ensure that the engine |
274 | reports its capabilities correctly. If this function is not used the |
275 | engine will report that it supports no route optimizations at all. |
276 | */ |
277 | void QGeoRoutingManagerEngine::setSupportedRouteOptimizations(QGeoRouteRequest::RouteOptimizations optimizations) |
278 | { |
279 | d_ptr->supportedRouteOptimizations = optimizations; |
280 | } |
281 | |
282 | /*! |
283 | Returns the route optimizations supported by this engine. |
284 | */ |
285 | QGeoRouteRequest::RouteOptimizations QGeoRoutingManagerEngine::supportedRouteOptimizations() const |
286 | { |
287 | return d_ptr->supportedRouteOptimizations; |
288 | } |
289 | |
290 | /*! |
291 | Sets the levels of detail for routing segments which can be |
292 | requested by this engine to \a segmentDetails. |
293 | |
294 | It is important that subclasses use this method to ensure that the engine |
295 | reports its capabilities correctly. If this function is not used the |
296 | engine will report that it supports no segment detail at all. |
297 | */ |
298 | void QGeoRoutingManagerEngine::setSupportedSegmentDetails(QGeoRouteRequest::SegmentDetails segmentDetails) |
299 | { |
300 | d_ptr->supportedSegmentDetails = segmentDetails; |
301 | } |
302 | |
303 | /*! |
304 | Returns the levels of detail for routing segments which can be |
305 | requested by this engine. |
306 | */ |
307 | QGeoRouteRequest::SegmentDetails QGeoRoutingManagerEngine::supportedSegmentDetails() const |
308 | { |
309 | return d_ptr->supportedSegmentDetails; |
310 | } |
311 | |
312 | /*! |
313 | Sets the levels of detail for navigation maneuvers which can be |
314 | requested by this engine to \a maneuverDetails. |
315 | |
316 | It is important that subclasses use this method to ensure that the engine |
317 | reports its capabilities correctly. If this function is not used the |
318 | engine will report that it supports no maneuver details at all. |
319 | */ |
320 | void QGeoRoutingManagerEngine::setSupportedManeuverDetails(QGeoRouteRequest::ManeuverDetails maneuverDetails) |
321 | { |
322 | d_ptr->supportedManeuverDetails = maneuverDetails; |
323 | } |
324 | |
325 | /*! |
326 | Returns the levels of detail for navigation maneuvers which can be |
327 | requested by this engine. |
328 | */ |
329 | QGeoRouteRequest::ManeuverDetails QGeoRoutingManagerEngine::supportedManeuverDetails() const |
330 | { |
331 | return d_ptr->supportedManeuverDetails; |
332 | } |
333 | |
334 | /*! |
335 | Sets the locale to be used by this manager to \a locale. |
336 | |
337 | If this routing manager supports returning addresses and instructions |
338 | in different languages, they will be returned in the language of \a locale. |
339 | |
340 | The locale used defaults to the system locale if this is not set. |
341 | */ |
342 | void QGeoRoutingManagerEngine::setLocale(const QLocale &locale) |
343 | { |
344 | d_ptr->locale = locale; |
345 | d_ptr->measurementSystem = locale.measurementSystem(); |
346 | } |
347 | |
348 | /*! |
349 | Returns the locale used to hint to this routing manager about what |
350 | language to use for addresses and instructions. |
351 | */ |
352 | QLocale QGeoRoutingManagerEngine::locale() const |
353 | { |
354 | return d_ptr->locale; |
355 | } |
356 | |
357 | /*! |
358 | Sets the measurement system used by this manager to \a system. |
359 | |
360 | The measurement system can be set independently of the locale. Both setLocale() and this |
361 | function set the measurement system. The value set by the last function called will be used. |
362 | |
363 | \sa measurementSystem(), locale(), setLocale() |
364 | */ |
365 | void QGeoRoutingManagerEngine::setMeasurementSystem(QLocale::MeasurementSystem system) |
366 | { |
367 | d_ptr->measurementSystem = system; |
368 | } |
369 | |
370 | /*! |
371 | Returns the measurement system used by this manager. |
372 | |
373 | If setMeasurementSystem() has been called then the value returned by this function may be |
374 | different to that returned by locale().\l {QLocale::measurementSystem()}{measurementSystem()}. |
375 | In which case the value returned by this function is what will be used by the manager. |
376 | |
377 | \sa setMeasurementSystem(), setLocale() |
378 | */ |
379 | QLocale::MeasurementSystem QGeoRoutingManagerEngine::measurementSystem() const |
380 | { |
381 | return d_ptr->measurementSystem; |
382 | } |
383 | |
384 | /*! |
385 | \fn void QGeoRoutingManagerEngine::finished(QGeoRouteReply *reply) |
386 | |
387 | This signal is emitted when \a reply has finished processing. |
388 | |
389 | If reply::error() equals QGeoRouteReply::NoError then the processing |
390 | finished successfully. |
391 | |
392 | This signal and QGeoRouteReply::finished() will be emitted at the same time. |
393 | |
394 | \note Do not delete the \a reply object in the slot connected to this signal. |
395 | Use deleteLater() instead. |
396 | */ |
397 | |
398 | /*! |
399 | \fn void QGeoRoutingManagerEngine::error(QGeoRouteReply *reply, QGeoRouteReply::Error error, QString errorString) |
400 | |
401 | This signal is emitted when an error has been detected in the processing of |
402 | \a reply. The QGeoRoutingManagerEngine::finished() signal will probably follow. |
403 | |
404 | The error will be described by the error code \a error. If \a errorString is |
405 | not empty it will contain a textual description of the error. |
406 | |
407 | This signal and QGeoRouteReply::error() will be emitted at the same time. |
408 | |
409 | \note Do not delete the \a reply object in the slot connected to this signal. |
410 | Use deleteLater() instead. |
411 | */ |
412 | |
413 | /******************************************************************************* |
414 | *******************************************************************************/ |
415 | |
416 | QGeoRoutingManagerEnginePrivate::QGeoRoutingManagerEnginePrivate() |
417 | : managerVersion(-1), measurementSystem(locale.measurementSystem()) |
418 | { |
419 | } |
420 | |
421 | QGeoRoutingManagerEnginePrivate::~QGeoRoutingManagerEnginePrivate() {} |
422 | |
423 | QT_END_NAMESPACE |
424 | |