inc/engine/routes/GeoRouteQuery.h

   1 /*
   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
  10  *
  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.
  16  */
  17
  18 #ifndef GEOROUTEQUERY_H
  19 #define GEOROUTEQUERY_H
  20
  21 #include <map>
  22
  23 #include "common/HereMaps_global.h"
  24 #include "common/BaseQuery.h"
  25 #include "common/GeoCoordinates.h"
  26 #include "common/GeoBoundingBox.h"
  27
  28 HERE_MAPS_BEGIN_NAMESPACE
  29
  30 class GeoRouteReply;
  31 class QueryListener;
  32 class GeoRouteQueryListener;
  33
  34 /**
  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.
  40  *
  41  * \ingroup routes
  42  */
  43 class EXPORT_API GeoRouteQuery : public BaseQuery
  44 {
  45 public:
  46
  47     /**
  48      * This enumeration defines identifiers for the supported modes of travel.
  49      */
  50     enum TravelMode {
  51         TM_CarTravel = 0x0001,           ///< Indicates that the route is to be
  52                                          ///  traveled by car.
  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.
  56     };
  57
  58     /**
  59      * This enumeration defines identifiers for the supported route feature
  60      * types, feature types that can be favored or excluded by the route
  61      * calculation.
  62      */
  63     enum FeatureType {
  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.
  75     };
  76
  77     /**
  78      * This enumeration defines identifiers for the supported route feature weighting.
  79      */
  80     enum FeatureWeight {
  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.
  86     };
  87
  88     /**
  89      * This typedef defines a map of route feature types and weighting as a type.
  90      */
  91     typedef std::map< GeoRouteQuery::FeatureType, GeoRouteQuery::FeatureWeight > FeaturesMap;
  92
  93     /**
  94      * This enumeration defines identifiers for the supported route optimizations.
  95      */
  96     enum RouteOptimization {
  97         RO_ShortestRoute = 0x0001,    ///< Indicates the shortest route.
  98         RO_FastestRoute = 0x0002,     ///< Indicates the fastest route.
  99     };
 100
 101     /**
 102      * This enumeration defines identifiers for route segment detail specifiers.
 103      */
 104     enum SegmentDetail {
 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.
 107     };
 108
 109     /**
 110      * This enumeration defines identifiers for route maneuver specifiers.
 111      */
 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.
 115     };
 116
 117 #ifdef TIZEN_CUSTOMIZATION
 118     /**
 119      * This enumeration defines identifiers for route MetricSystem specifiers.
 120      */
 121     enum MetricSystem {
 122         DIST_metric = 0x0000,        ///< Indicates that MetricSystem is m & km
 123         DIST_imperial = 0x0001       ///< Indicates that MetricSystem is miles
 124     };
 125 #endif
 126
 127     /**
 128      * This method is a constructor that initializes a new instance of the
 129      * class, using the list of waypoints supplied by the caller.
 130      *
 131      * @param rWaypoints A constant reference to a vector of instances of
 132      *        <code>GeoCoordinates</code> that define the route waypoints.
 133      */
 134     GeoRouteQuery(const GeoCoordinateList &rWaypoints = GeoCoordinateList());
 135
 136     /**
 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.
 140      *
 141      * @param rOrigin A constant reference to an object that defines the point
 142      *        of origin for the route.
 143      *
 144      * @param rDestination A constant reference to an object that defines the
 145      *        destination for the route.
 146      */
 147     GeoRouteQuery(const GeoCoordinates &rOrigin, const GeoCoordinates &rDestination);
 148
 149     /**
 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
 152      * the caller.
 153      *
 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.
 156      */
 157     GeoRouteQuery(const GeoRouteQuery &rRhs);
 158
 159     /**
 160      * This method is the destructor for objects of this class.
 161      */
 162     ~GeoRouteQuery();
 163
 164     /**
 165      * This is the assignment operator.
 166      *
 167      * @param rRhs A constant reference to an object whose property values are
 168      *        to be copied to the given instance.
 169      */
 170     GeoRouteQuery& operator = (const GeoRouteQuery &rRhs);
 171
 172     /**
 173      * This method sets route waypoints, using the list of objects supplied by
 174      * the caller.
 175      *
 176      * @param rWaypoints A constant reference to a vector of instances of
 177      *        <code>GeoCoordinates</code> that define the route waypoints.
 178      */
 179     void SetWaypoints(const GeoCoordinateList &rWaypoints);
 180
 181     /**
 182      * This method retrieves the route waypoints.
 183      *
 184      * @return A vector of instances of <code>GeoCoordinates</code> that define
 185      *        the route waypoints.
 186      */
 187     GeoCoordinateList GetWaypoints() const;
 188
 189     /**
 190      * This method sets areas through which the route must not pass, using a
 191      * list of bounding box objects supplied by the caller.
 192      *
 193      * @param rAreas A constant reference to a list of bounding box objects that
 194      *        define the areas the route must avoid.
 195      */
 196     void SetExcludeAreas(const GeoBoundingBoxList &rAreas);
 197
 198     /**
 199      * This method retrieves a list of bounding boxes that defines areas through
 200      * which the route must not pass.
 201      *
 202      * @return A list of bounding box objects that define the areas the route
 203      *        must avoid.
 204      */
 205     GeoBoundingBoxList GetExcludeAreas() const;
 206
 207     // defaults to TravelByCar
 208     /**
 209      * This method sets the travel mode to be used in the route query.
 210      *
 211      * @param aTravelModes A value indicating the travel mode to use in the
 212      *        query.
 213      */
 214     void SetTravelModes(TravelMode aTravelModes);
 215
 216     /**
 217      * This method retrieves the travel mode used in the route query.
 218      *
 219      * @return A value indicating the travel mode used in the
 220      *        query.
 221      */
 222     TravelMode GetTravelModes() const;
 223
 224     /**
 225      * This method associates weighting with a feature to be used in the route
 226      * query.
 227      *
 228      * @param aFeatureType A value indicating the feature type to which the
 229      *        weighting is to apply.
 230      *
 231      * @param aFeatureWeight A value indicating the weighting to apply.
 232      */
 233     void SetFeatureWeight(FeatureType aFeatureType, FeatureWeight aFeatureWeight);
 234
 235     /**
 236      * This method retrieves the weighting for the feature type specified by the
 237      * caller.
 238      *
 239      * @param aFeatureType A value indicating the feature type for which to
 240      *        retrieve weighting.
 241      *
 242      * @return A value indicating the weighting associated with the named route
 243      *        feature.
 244      */
 245     FeatureWeight GetFeatureWeight(FeatureType aFeatureType) const;
 246
 247     /**
 248      * This method retrieves a map of route feature types specified for the
 249      * given query.
 250      *
 251      * @return An object containing a map of route feature types specified for
 252      *         the given query.
 253      */
 254     FeaturesMap GetFeatureTypes() const;
 255
 256     // defaults to OptimizeFastes)
 257     /**
 258      *  This method sets the route optimization option for the given query.
 259      *
 260      * @param aOptimization A value indicating the route optimization option to
 261      *        set for the given query.
 262      */
 263     void SetRouteOptimization(RouteOptimization aOptimization);
 264
 265     /**
 266      *  This method retrieves the route optimization selector set for the given
 267      *  query.
 268      *
 269      * @return A value indicating the route optimization selector set for the
 270      *        given query.
 271      */
 272     RouteOptimization GetRouteOptimization() const;
 273
 274     // defaults to BasicSegmentData
 275     /**
 276      * This method sets the segment detail selector for the given query.
 277      *
 278      * @param aSegmentDetail A value indicating the segment detail selector for
 279      *        the given query.
 280      */
 281     void SetSegmentDetail(SegmentDetail aSegmentDetail);
 282
 283     /**
 284      * This method retrieves the segment detail selector for the given query.
 285      *
 286      * @return A value indicating the segment detail selector set for the given
 287      *        query.
 288      */
 289     SegmentDetail GetSegmentDetail() const;
 290
 291     // defaults to BasicManeuvers
 292     /**
 293      * This method sets the maneuver detail selector for the given
 294      * query.
 295      *
 296      * @param aManeuverDetail A value indicating the maneuver detail selector for
 297      *        the given query.
 298      */
 299     void SetManeuverDetail(ManeuverDetail aMneuverDetail);
 300
 301     /**
 302      * This method retrieves the maneuver detail selector set for the given
 303      * query.
 304      *
 305      * @return A value indicating the maneuver detail selector for
 306      *        the given query.
 307      */
 308     ManeuverDetail GetManeuverDetail() const;
 309
 310 #ifdef TIZEN_CUSTOMIZATION
 311     /**
 312      * This method sets the MetricSystem selector for the given
 313      * query.
 314      *
 315      * @param aMetricSystem A value indicating the MetricSystemselector for
 316      *        the given query.
 317      */
 318     void SetMetricSystem(GeoRouteQuery::MetricSystem aMetricSystem);
 319
 320     /**
 321      * This method retrieves the MetricSystem selector set for the given query.
 322      *
 323      * @return A value indicating the MetricSystem selector for
 324      *        the given query.
 325      */
 326     GeoRouteQuery::MetricSystem GetMetricSystem(void) const;
 327
 328     /**
 329      * This method sets the bounding area for the given query.
 330      *
 331      * @param aMetricSystem A value indicating the bounding area for
 332      *        the given query.
 333      */
 334     void SetViewBounds(GeoBoundingBox aViewBounds);
 335
 336     /**
 337      * This method retrieves the bounding area set for the given query.
 338      *
 339      * @return A value indicating the bounding area for
 340      *        the given query.
 341      */
 342     GeoBoundingBox GetViewBounds(void) const;
 343
 344     /**
 345      * This method sets a value that indicates the maximum number of alternative routes
 346      * results to be retrieved in response to the query.
 347      *
 348      * @param uAlternatives An integer indicating the maximum number of results to
 349      *        be retrieved.
 350      */
 351     void SetAlternatives(size_t uAlternatives);
 352
 353     /**
 354      * This method retrieves a value that indicates the maximum number of alternative routes
 355      * results to be retrieved in response to the query.
 356      *
 357      * @return An integer indicating the maximum number of results to be retrieved.
 358      */
 359     size_t GetAlternatives(void) const;
 360
 361     /**
 362      * This method sets a value that indicates the realtime traffic status.
 363      *
 364      * @param uAlternatives An integer indicating the realtime traffic status.
 365      */
 366     void SetRealtimeTraffic(size_t uTraffic);
 367
 368     /**
 369      * This method retrieves a value that indicates the realtime traffic status.
 370      *
 371      * @return An integer indicating the realtime traffic status.
 372      */
 373     size_t GetRealtimeTraffic(void) const;
 374 #endif
 375
 376     /**
 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.
 379      *
 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.
 382      *
 383      * @param pUserData A pointer to user data to be passed back within the
 384      *        corresponding reply object.
 385      *
 386      * @return A vaur representing the identifier of issued request.
 387      */
 388     RestItemHandle::RequestId Execute(GeoRouteQueryListener& rListener, Tizen::Maps::HereObject* pUserData = NULL) const;
 389
 390     /**
 391      * This static method returns the base URI to be used for all subsequent
 392      * geo route queries.
 393      *
 394      * @return A string containing the base URI.
 395      */
 396     static String GetBaseUri();
 397
 398     /**
 399      * This static method returns the base URI to be used for all subsequent
 400      * geo route queries.
 401      *
 402      * @param sUri A constant reference to a string containing the base URI.
 403      */
 404     static void SetBaseUri(const String& sUri);
 405
 406 private:
 407     bool CreateBaseUrl(const String& sService, String& sDst) const;
 408
 409     String CreateUri() const;
 410
 411 private:
 412     class GeoRouteQueryImpl;
 413     GeoRouteQueryImpl* m_pImpl;
 414 };
 415
 416 HERE_MAPS_END_NAMESPACE
 417
 418 #endif /* GEOROUTEQUERY_H */