inc/engine/routes/GeoRoute.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 GEOROUTE_H
  19 #define GEOROUTE_H
  20
  21 #include <vector>
  22
  23 #include "common/HereMaps_global.h"
  24 #include "common/GeoCoordinates.h"
  25 #include "routes/GeoRouteQuery.h"
  26 #include "routes/RouteSegment.h"
  27
  28 HERE_MAPS_BEGIN_NAMESPACE
  29
  30 class RouteSegment;
  31 class GeoBoundingBox;
  32
  33 class GeoRoute;
  34
  35 /**
  36  * This typedef defines a list (vector) of instances of <code>GeoRoute</code> as
  37  * a type.
  38  *
  39  * \ingroup routes
  40  */
  41 typedef std::vector<GeoRoute> GeoRouteList;
  42
  43 /**
  44  * This class encapsulates a route. Instances of the class are data objects. The
  45  * information they contain can be used to draw routes on the map.
  46  *
  47  * A route object contains member variables that represent:
  48  * <ul>
  49  *
  50  * <li> route segments - sections of the route encapsulated as instances of
  51  *      <code>RouteSegment</code></li>
  52  *
  53  * <li> maneuvers - instances of <code>Maneuver</code></li> that contain
  54  *      navigation instructions for the person following the route, indicating
  55  *      how to continue from one section of the route to the next</li>
  56  *
  57  * <li> route geometry - a list of instances of <code>GeoCoordinates</code></li>
  58  *      that contains the point objects with the coordinates of the geographical
  59  *      locations through which the route passes</li>
  60  *
  61  * <li> duration - the length of time required to travel the route from start
  62  *      to finish</li>
  63  *
  64  * </ul>
  65  *
  66  * Note that the above list is indicative, rather than comprehensive.
  67  */
  68 class EXPORT_API GeoRoute
  69 {
  70 public:
  71
  72    /**
  73     * This is the default constructor.
  74     */
  75     GeoRoute();
  76
  77    /**
  78     * This method is the copy constructor.
  79     *
  80     * @param rRhs An object whose contents are to be copied to the instance
  81     *        being created.
  82     */
  83     GeoRoute(const GeoRoute& rRhs);
  84
  85    /**
  86     * This method is the destructor.
  87     */
  88     ~GeoRoute();
  89
  90     /**
  91      * This method sets the id of the route object.
  92      *
  93      * @param rId A constant reference to a string containing the unique id of
  94      *        the route object.
  95      */
  96     void SetRouteId(const String& rId);
  97
  98     /**
  99      * This method retrieves the id of the route object.
 100      *
 101      * @return A string containing the unique id of
 102      *        the route object.
 103      */
 104     String GetRouteId() const;
 105
 106     /**
 107      * This method sets class property holding the request used to obtain the
 108      * route data.
 109      *
 110      * @param rRequest A constant reference to an object that encapsulates the
 111      *        query used to obtain the route data.
 112      */
 113     void SetRequest(const GeoRouteQuery& rRequest);
 114
 115     /**
 116      * This method retrieves the value class property holding the request used
 117      * to obtain the route data.
 118      *
 119      * @return An object that encapsulates the query used to obtain the route
 120      *       data.
 121      */
 122     GeoRouteQuery GetRequest() const;
 123
 124     /**
 125      * This method sets a property that holds the bounding box enclosing
 126      * the route. The bounding box is defined by the geographic coordinates of
 127      * its top-left and bottom-right corners.
 128      *
 129      * @param rBounds A constant reference to an object containing the bounding
 130      *        box.
 131      */
 132     void SetBounds(const GeoBoundingBox& rBounds);
 133
 134     /**
 135      * This method retrieves the value of a class property that holds the
 136      * bounding box enclosing the route. The bounding box is defined by the
 137      * geographic coordinates of its top-left and bottom-right corners.
 138      *
 139      * @return An object containing the bounding box.
 140      */
 141     GeoBoundingBox GetBounds() const;
 142
 143     /**
 144      * This method sets a class property that holds the list of segments of the
 145      * route.
 146      *
 147      * @param vRouteSegmentList A constant reference to an object that defines
 148      *        the first segment of the route.
 149      */
 150     void SetRouteSegmentList(const RouteSegmentList& vRouteSegmentList);
 151
 152     /**
 153      * This method retrieves the value of a class property that holds the list of
 154      * segments of the route.
 155      *
 156      * @return An object that defines the list of segments of the route.
 157      */
 158      RouteSegmentList GetRouteSegmentList() const;
 159
 160     /**
 161      * This method sets a class property that holds the time required to travel
 162      * the length of the route.
 163      *
 164      * @param aSecs An integer value specifying the time required to travel the
 165      *        length of the route in seconds.
 166      */
 167     void SetTravelTime(int aSecs);
 168
 169     /**
 170      * This method retrieves the value of a class property that holds the time
 171      * required to travel the length of the route.
 172      *
 173      * @return An integer value specifying the time required to travel the
 174      *        length of the route in seconds.
 175      */
 176     int GetTravelTime() const;
 177
 178 #ifdef TIZEN_MIGRATION
 179     /**
 180      * This method sets a class property that holds the time required to traffic
 181      * the length of the route.
 182      *
 183      * @param aSecs An integer value specifying the time required to traffic the
 184      *        length of the route in seconds.
 185      */
 186     void SetTrafficTime(int aSecs);
 187
 188     /**
 189      * This method retrieves the value of a class property that holds the time
 190      * required to traffic the length of the route.
 191      *
 192      * @return An integer value specifying the time required to traffic the
 193      *        length of the route in seconds.
 194      */
 195     int GetTrafficTime() const;
 196 #endif
 197
 198     /**
 199      * This method sets a class property that holds the length of the route --
 200      * the total distance to travel between the start and end points of the
 201      * route.
 202      *
 203      * @param aDistance A value specifying the length of the route in meters.
 204      */
 205     void SetDistance(double aDistance);
 206
 207     /**
 208      * This method retrieves the value of a class property that holds the length
 209      * of the route -- the total distance to travel between the start and end
 210      * points of the route.
 211      *
 212      * @return A value specifying the length of the route in meters.
 213      */
 214     double GetDistance() const;
 215
 216     /**
 217      * This method sets a class property indicating the travel mode for which
 218      * the route was calculated.
 219      *
 220      * @param aTravelMode A value indicating the mode of travel for the route.
 221      */
 222     void SetTravelMode(GeoRouteQuery::TravelMode aTravelMode);
 223
 224     /**
 225      * This method retrieves the value of a class property indicating the travel
 226      * mode for which the route was calculated.
 227      *
 228      * @return A value indicating the mode of travel for the route.
 229      */
 230     GeoRouteQuery::TravelMode GetTravelMode() const;
 231
 232     /**
 233      * This method sets a class property that defines the geometry of the route
 234      * (it holds the coordinates of the points through which the route passes,
 235      * the vertices of the route).
 236      *
 237      * @param rPath A constant reference to an object containing the geographic
 238      *       coordinates of the points through which the route passes (the route
 239      *       vertices).
 240      */
 241     void SetPath(const GeoCoordinateList& rPath);
 242
 243     /**
 244      * This method retrieves the value of a class property that defines the
 245      * geometry of the route (it holds the coordinates of the points through
 246      * which the route passes, the vertices of the route).
 247      *
 248      * @return An object containing the geographic coordinates of the points
 249      *       through which the route passes (the route vertices).
 250      */
 251     GeoCoordinateList GetPath() const;
 252
 253     /**
 254      * This is the assignment operator.
 255      *
 256      * @param rRhs A constant reference to an object whose properties are to be
 257      *       copied to the given instance of the class.
 258      *
 259      * @return A reference to the given instance of the class after its member
 260      *       elements have been updated.
 261      */
 262     GeoRoute& operator = (const GeoRoute& rRhs);
 263
 264 private:
 265     class GeoRouteImpl;
 266     GeoRouteImpl* m_pImpl;
 267 };
 268
 269 HERE_MAPS_END_NAMESPACE
 270
 271 #endif /* GEOROUTE_H */