2 * Copyright (C) 2013 HERE Global B.V. All rights reserved.
3 * This software, including documentation, is protected by copyright controlled by
4 * HERE Global B.V. (“Software”). All rights are reserved. Copying, including reproducing,
5 * storing, adapting or translating, any or all of this material requires the prior
6 * written consent of HERE Global B.V. You may use this
7 * Software in accordance with the terms and conditions defined in the
8 * HERE Location Platform Services Terms and Conditions, available at
9 * http://developer.here.com/terms-conditions-base
11 * As an additional permission to the above, you may distribute Software,
12 * in object code format as part of an Application, according to, and subject to, terms and
13 * conditions defined in the Tizen Software Development kit (“SDK”) License Agreement.
14 * You may distribute such object code format Application under terms of your choice,
15 * provided that the header and source files of the Software have not been modified.
18 #ifndef GEOROUTEQUERY_H
19 #define GEOROUTEQUERY_H
23 #include "common/HereMaps_global.h"
24 #include "common/BaseQuery.h"
25 #include "common/GeoCoordinates.h"
26 #include "common/GeoBoundingBox.h"
28 HERE_MAPS_BEGIN_NAMESPACE
32 class GeoRouteQueryListener;
35 * This class encapsulates a query that requests a route calculation. The
36 * required calculation is specified in terms of route features, including the
37 * start and end points, waypoints (the locations through which the route must
38 * pass), areas to include and to avoid, mode of travel, route features with
39 * weighting, required optimization, etc.
43 class EXPORT_API GeoRouteQuery : public BaseQuery
48 * This enumeration defines identifiers for the supported modes of travel.
51 TM_CarTravel = 0x0001, ///< Indicates that the route is to be
53 TM_PedestrianTravel = 0x0002, ///< Indicates that the route is for a pedestrian.
54 TM_PublicTransitTravel = 0x0008, ///< Indicates that the route is to be
55 /// traveled using public transport.
59 * This enumeration defines identifiers for the supported route feature
60 * types, feature types that can be favored or excluded by the route
64 FT_NoFeature = 0x00000000, ///< Indicates no route features (are selected).
65 FT_TollFeature = 0x00000001, ///< Indicates toll roads (toll gates/booths).
66 FT_MotorwayFeature = 0x00000002, ///< Indicates motorway(s).
67 FT_BoatFerryFeature = 0x00000004, ///< Indicates a boat ferry.
68 FT_RailFerryFeature = 0x00000008, ///< Indicates rail (train) ferry.
69 FT_PublicTransitFeature = 0x00000010, ///< Indicates public transport.
70 FT_TunnelFeature = 0x00000020, ///< Indicates tunnel.
71 FT_DirtRoadFeature = 0x00000040, ///< Indicates dirt road.
72 FT_ParksFeature = 0x00000080, ///< Indicates park.
73 FT_HOVLane = 0x00000100, ///< Indicates a high-occupancy vehicle lane.
74 FT_Stairs = 0x00000200 ///< Indicates stairs.
78 * This enumeration defines identifiers for the supported route feature weighting.
81 FW_NormalFeatureWeight = 0x00000000, ///< Indicates normal weighting.
82 FW_PreferFeatureWeight = 0x00000001, ///< Indicates that a feature is preferred.
83 FW_AvoidFeatureWeight = 0x00000002, ///< Indicates that a feature is to be avoided.
84 FW_SoftExcludeFeatureWeight = 0x00000004, ///< Indicates that soft-exclude applies to the feature.
85 FW_StrictExcludeFeatureWeight = 0x00000008 ///< Indicates that the feature is to be strictly excluded.
89 * This typedef defines a map of route feature types and weighting as a type.
91 typedef std::map< GeoRouteQuery::FeatureType, GeoRouteQuery::FeatureWeight > FeaturesMap;
94 * This enumeration defines identifiers for the supported route optimizations.
96 enum RouteOptimization {
97 RO_ShortestRoute = 0x0001, ///< Indicates the shortest route.
98 RO_FastestRoute = 0x0002, ///< Indicates the fastest route.
102 * This enumeration defines identifiers for route segment detail specifiers.
105 SD_NoSegmentData = 0x0000, ///< Indicates that no route segment data are to be included.
106 SD_BasicSegmentData = 0x0001 ///< Indicates that basic route segment data are to be included.
110 * This enumeration defines identifiers for route maneuver specifiers.
112 enum ManeuverDetail {
113 MD_NoManeuvers = 0x0000, ///< Indicates that manuevers are to be included int he route.
114 MD_BasicManeuvers = 0x0001 ///< Indicates that basic maneuvers are to be included in the route calculation.
117 #ifdef TIZEN_CUSTOMIZATION
119 * This enumeration defines identifiers for route MetricSystem specifiers.
122 DIST_metric = 0x0000, ///< Indicates that MetricSystem is m & km
123 DIST_imperial = 0x0001 ///< Indicates that MetricSystem is miles
128 * This method is a constructor that initializes a new instance of the
129 * class, using the list of waypoints supplied by the caller.
131 * @param rWaypoints A constant reference to a vector of instances of
132 * <code>GeoCoordinates</code> that define the route waypoints.
134 GeoRouteQuery(const GeoCoordinateList &rWaypoints = GeoCoordinateList());
137 * This method is a constructor that initializes a new instance of the
138 * class, using the objects representing the route origin and destination
139 * supplied by the caller.
141 * @param rOrigin A constant reference to an object that defines the point
142 * of origin for the route.
144 * @param rDestination A constant reference to an object that defines the
145 * destination for the route.
147 GeoRouteQuery(const GeoCoordinates &rOrigin, const GeoCoordinates &rDestination);
150 * This method is a copy constructor that initializes a new instance of the
151 * class by copying the values of the properties of the object supplied by
154 * @param rRhs A constant reference to an object whose property values are
155 * to be used to initialize a new instance of the class.
157 GeoRouteQuery(const GeoRouteQuery &rRhs);
160 * This method is the destructor for objects of this class.
165 * This is the assignment operator.
167 * @param rRhs A constant reference to an object whose property values are
168 * to be copied to the given instance.
170 GeoRouteQuery& operator = (const GeoRouteQuery &rRhs);
173 * This method sets route waypoints, using the list of objects supplied by
176 * @param rWaypoints A constant reference to a vector of instances of
177 * <code>GeoCoordinates</code> that define the route waypoints.
179 void SetWaypoints(const GeoCoordinateList &rWaypoints);
182 * This method retrieves the route waypoints.
184 * @return A vector of instances of <code>GeoCoordinates</code> that define
185 * the route waypoints.
187 GeoCoordinateList GetWaypoints() const;
190 * This method sets areas through which the route must not pass, using a
191 * list of bounding box objects supplied by the caller.
193 * @param rAreas A constant reference to a list of bounding box objects that
194 * define the areas the route must avoid.
196 void SetExcludeAreas(const GeoBoundingBoxList &rAreas);
199 * This method retrieves a list of bounding boxes that defines areas through
200 * which the route must not pass.
202 * @return A list of bounding box objects that define the areas the route
205 GeoBoundingBoxList GetExcludeAreas() const;
207 // defaults to TravelByCar
209 * This method sets the travel mode to be used in the route query.
211 * @param aTravelModes A value indicating the travel mode to use in the
214 void SetTravelModes(TravelMode aTravelModes);
217 * This method retrieves the travel mode used in the route query.
219 * @return A value indicating the travel mode used in the
222 TravelMode GetTravelModes() const;
225 * This method associates weighting with a feature to be used in the route
228 * @param aFeatureType A value indicating the feature type to which the
229 * weighting is to apply.
231 * @param aFeatureWeight A value indicating the weighting to apply.
233 void SetFeatureWeight(FeatureType aFeatureType, FeatureWeight aFeatureWeight);
236 * This method retrieves the weighting for the feature type specified by the
239 * @param aFeatureType A value indicating the feature type for which to
240 * retrieve weighting.
242 * @return A value indicating the weighting associated with the named route
245 FeatureWeight GetFeatureWeight(FeatureType aFeatureType) const;
248 * This method retrieves a map of route feature types specified for the
251 * @return An object containing a map of route feature types specified for
254 FeaturesMap GetFeatureTypes() const;
256 // defaults to OptimizeFastes)
258 * This method sets the route optimization option for the given query.
260 * @param aOptimization A value indicating the route optimization option to
261 * set for the given query.
263 void SetRouteOptimization(RouteOptimization aOptimization);
266 * This method retrieves the route optimization selector set for the given
269 * @return A value indicating the route optimization selector set for the
272 RouteOptimization GetRouteOptimization() const;
274 // defaults to BasicSegmentData
276 * This method sets the segment detail selector for the given query.
278 * @param aSegmentDetail A value indicating the segment detail selector for
281 void SetSegmentDetail(SegmentDetail aSegmentDetail);
284 * This method retrieves the segment detail selector for the given query.
286 * @return A value indicating the segment detail selector set for the given
289 SegmentDetail GetSegmentDetail() const;
291 // defaults to BasicManeuvers
293 * This method sets the maneuver detail selector for the given
296 * @param aManeuverDetail A value indicating the maneuver detail selector for
299 void SetManeuverDetail(ManeuverDetail aMneuverDetail);
302 * This method retrieves the maneuver detail selector set for the given
305 * @return A value indicating the maneuver detail selector for
308 ManeuverDetail GetManeuverDetail() const;
310 #ifdef TIZEN_CUSTOMIZATION
312 * This method sets the MetricSystem selector for the given
315 * @param aMetricSystem A value indicating the MetricSystemselector for
318 void SetMetricSystem(GeoRouteQuery::MetricSystem aMetricSystem);
321 * This method retrieves the MetricSystem selector set for the given query.
323 * @return A value indicating the MetricSystem selector for
326 GeoRouteQuery::MetricSystem GetMetricSystem(void) const;
329 * This method sets the bounding area for the given query.
331 * @param aMetricSystem A value indicating the bounding area for
334 void SetViewBounds(GeoBoundingBox aViewBounds);
337 * This method retrieves the bounding area set for the given query.
339 * @return A value indicating the bounding area for
342 GeoBoundingBox GetViewBounds(void) const;
345 * This method sets a value that indicates the maximum number of alternative routes
346 * results to be retrieved in response to the query.
348 * @param uAlternatives An integer indicating the maximum number of results to
351 void SetAlternatives(size_t uAlternatives);
354 * This method retrieves a value that indicates the maximum number of alternative routes
355 * results to be retrieved in response to the query.
357 * @return An integer indicating the maximum number of results to be retrieved.
359 size_t GetAlternatives(void) const;
362 * This method sets a value that indicates the realtime traffic status.
364 * @param uAlternatives An integer indicating the realtime traffic status.
366 void SetRealtimeTraffic(size_t uTraffic);
369 * This method retrieves a value that indicates the realtime traffic status.
371 * @return An integer indicating the realtime traffic status.
373 size_t GetRealtimeTraffic(void) const;
377 * This method attempts to establish a connection with the server and then,
378 * if the connection has been established, it builds and submits a query.
380 * @rListener rListener A reference to an object that is to be notified when
381 * the reply to the query has arrived from the server.
383 * @param pUserData A pointer to user data to be passed back within the
384 * corresponding reply object.
386 * @return A vaur representing the identifier of issued request.
388 RestItemHandle::RequestId Execute(GeoRouteQueryListener& rListener, Tizen::Maps::HereObject* pUserData = NULL) const;
391 * This static method returns the base URI to be used for all subsequent
394 * @return A string containing the base URI.
396 static String GetBaseUri();
399 * This static method returns the base URI to be used for all subsequent
402 * @param sUri A constant reference to a string containing the base URI.
404 static void SetBaseUri(const String& sUri);
407 bool CreateBaseUrl(const String& sService, String& sDst) const;
409 String CreateUri() const;
412 class GeoRouteQueryImpl;
413 GeoRouteQueryImpl* m_pImpl;
416 HERE_MAPS_END_NAMESPACE
418 #endif /* GEOROUTEQUERY_H */