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
40QT_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*/
85QGeoRoutingManagerEngine::QGeoRoutingManagerEngine(const QVariantMap &parameters, QObject *parent)
86 : QObject(parent),
87 d_ptr(new QGeoRoutingManagerEnginePrivate())
88{
89 Q_UNUSED(parameters);
90}
91
92/*!
93 Destroys this engine.
94*/
95QGeoRoutingManagerEngine::~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*/
107void 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*/
119QString 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*/
130void 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*/
141int 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*/
197QGeoRouteReply *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*/
212void QGeoRoutingManagerEngine::setSupportedTravelModes(QGeoRouteRequest::TravelModes travelModes)
213{
214 d_ptr->supportedTravelModes = travelModes;
215}
216
217/*!
218 Returns the travel modes supported by this engine.
219*/
220QGeoRouteRequest::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*/
233void 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*/
242QGeoRouteRequest::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*/
255void 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*/
265QGeoRouteRequest::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*/
277void QGeoRoutingManagerEngine::setSupportedRouteOptimizations(QGeoRouteRequest::RouteOptimizations optimizations)
278{
279 d_ptr->supportedRouteOptimizations = optimizations;
280}
281
282/*!
283 Returns the route optimizations supported by this engine.
284*/
285QGeoRouteRequest::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*/
298void 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*/
307QGeoRouteRequest::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*/
320void 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*/
329QGeoRouteRequest::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*/
342void 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*/
352QLocale 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*/
365void 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*/
379QLocale::MeasurementSystem QGeoRoutingManagerEngine::measurementSystem() const
380{
381 return d_ptr->measurementSystem;
382}
383
384/*!
385\fn void QGeoRoutingManagerEngine::finished(QGeoRouteReply *reply)
386
387This signal is emitted when \a reply has finished processing.
388
389If reply::error() equals QGeoRouteReply::NoError then the processing
390finished successfully.
391
392This 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.
395Use deleteLater() instead.
396*/
397
398/*!
399\fn void QGeoRoutingManagerEngine::error(QGeoRouteReply *reply, QGeoRouteReply::Error error, QString errorString)
400
401This signal is emitted when an error has been detected in the processing of
402\a reply. The QGeoRoutingManagerEngine::finished() signal will probably follow.
403
404The error will be described by the error code \a error. If \a errorString is
405not empty it will contain a textual description of the error.
406
407This 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.
410Use deleteLater() instead.
411*/
412
413/*******************************************************************************
414*******************************************************************************/
415
416QGeoRoutingManagerEnginePrivate::QGeoRoutingManagerEnginePrivate()
417: managerVersion(-1), measurementSystem(locale.measurementSystem())
418{
419}
420
421QGeoRoutingManagerEnginePrivate::~QGeoRoutingManagerEnginePrivate() {}
422
423QT_END_NAMESPACE
424

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