inc/FLocCoordinates.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19 * @file         FLocCoordinates.h
  20 * @brief        This is the header file for the %Coordinates class.
  21 *
  22 * This header file contains the declarations of the %Coordinates class.
  23 */
  24
  25 #ifndef _FLOC_COORDINATES_H_
  26 #define _FLOC_COORDINATES_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FLocTypes.h>
  30
  31 namespace Tizen { namespace Base
  32 {
  33 class String;
  34 }}
  35
  36 namespace Tizen { namespace Locations
  37 {
  38
  39 /**
  40 * @class        Coordinates
  41 * @brief        This class represents a geographical point.
  42 *
  43 * @since 2.0
  44 *
  45 * @final        This class is not intended for extension.
  46 *
  47 * The %Coordinates class represents a geographical point specified by latitude, longitude, and altitude values and provides
  48 * geographic calculations between two points.
  49 *
  50 * The latitude and longitude in decimal degrees are sometimes represented in degrees, minutes, and seconds format. For example, 40.1874 degrees
  51 * can also be represented in "40:11.25"(40 degrees and 11.25 minutes) or "40:11:15.0" (40 degrees, 11 minutes and 15.0 seconds).
  52 * This class provides methods for converting a coordinate value to degrees and minutes or degrees, minutes, and seconds representation.
  53 */
  54 class _OSP_EXPORT_ Coordinates
  55         : public Tizen::Base::Object
  56 {
  57 public:
  58         /**
  59         * Initializes an instance of %Coordinates with the values of latitude, longitude, and altitude to Not-a-Number.
  60         *
  61         * An application should set values of the coordinates using Set() method to specify it.
  62         *
  63         * @since 2.0
  64         */
  65         Coordinates(void);
  66
  67         /**
  68         * Copying of objects using this copy constructor is allowed.
  69         *
  70         * @since 2.0
  71         *
  72         * @param[in]    rhs     An instance of %Coordinates to copy
  73         */
  74         Coordinates(const Coordinates& rhs);
  75
  76         /**
  77         * This destructor overrides Tizen::Base::Object::~Object().
  78         *
  79         * @since 2.0
  80         */
  81         virtual ~Coordinates(void);
  82
  83         /**
  84         * Compares the calling instance with the specified instance for equality.
  85         *
  86         * @since 2.0
  87         *
  88         * @return       @c true if all the fields in the objects are equal, @n
  89         *                       else @c false
  90         * @param[in]    rhs     The object to compare
  91         */
  92         virtual bool Equals(const Tizen::Base::Object& rhs) const;
  93
  94         /**
  95         * Gets the hash value of the calling instance.
  96         *
  97         * @since 2.0
  98         *
  99         * @return       The hash value of the calling instance
 100         */
 101         virtual int GetHashCode(void) const;
 102
 103         /**
 104         * Sets the latitude, longitude, and altitude values of the coordinates.
 105         *
 106         * An application should specify latitude and longitude values in the valid ranges of [-90.0, +90.0] and [-180.0, +180.0], respectively.
 107         * Otherwise, the %Set() method returns an @c E_INVALID_ARG exception.
 108         *
 109         * @since 2.0
 110         *
 111         * @return       An error code
 112         * @param[in]    latitude        The latitude of the coordinates in decimal degrees within the range [-90.0, +90.0]
 113         * @param[in]    longitude       The longitude of the coordinates in decimal degrees within the range [-180.0, +180.0]
 114         * @param[in]    altitude        The altitude of the coordinates in meters
 115         * @exception    E_SUCCESS       This method is successful.
 116         * @exception    E_INVALID_ARG   The specified @c latitude or @c longitude is invalid.
 117         * @see          GetLatitude()
 118         * @see          GetLongitude()
 119         * @see          GetAltitude()
 120         */
 121         result Set(double latitude, double longitude, double altitude);
 122
 123         /**
 124         * Sets the latitude value of the coordinates.
 125         *
 126         * An application should specify latitude value in the valid range of [-90.0, +90.0].
 127         * Otherwise, the %SetLatitude() method returns an @c E_INVALID_ARG exception.
 128         *
 129         * @since 2.0
 130         *
 131         * @return       An error code
 132         * @param[in]    latitude        The latitude of the coordinates in decimal degrees within the range [-90.0, +90.0]
 133         * @exception    E_SUCCESS       This method is successful.
 134         * @exception    E_INVALID_ARG   The specified @c latitude is invalid.
 135         * @see          GetLatitude()
 136         */
 137         result SetLatitude(double latitude);
 138
 139         /**
 140         * Sets the longitude value of the coordinates.
 141         *
 142         * An application should specify longitude value in the valid range of [-180.0, +180.0].
 143         * Otherwise, the %SetLongitude() method returns an @c E_INVALID_ARG exception.
 144         *
 145         * @since 2.0
 146         *
 147         * @return       An error code
 148         * @param[in]    longitude       The longitude of the coordinates in decimal degrees within the range [-180.0, +180.0]
 149         * @exception    E_SUCCESS       This method is successful.
 150         * @exception    E_INVALID_ARG   The specified @c longitude is invalid.
 151         * @see          GetLongitude()
 152         */
 153         result SetLongitude(double longitude);
 154
 155         /**
 156         * Sets the altitude value of the coordinates.
 157         *
 158         * @since 2.0
 159         *
 160         * @param[in]    altitude        The altitude of the coordinates in meters
 161         * @see          GetAltitude()
 162         */
 163         void SetAltitude(double altitude);
 164
 165         /**
 166         * Gets the latitude value of the coordinates.
 167         *
 168         * @since 2.0
 169         *
 170         * @return       The latitude in decimal degrees within the range [-90.0, +90.0], @n
 171         *                       else @c NaN if it is not available
 172         * @see          SetLatitude()
 173         */
 174         double GetLatitude(void) const;
 175
 176         /**
 177         * Gets the longitude value of the coordinates.
 178         *
 179         * @since 2.0
 180         *
 181         * @return       The longitude in decimal degrees within the range [-180.0, +180.0], @n
 182         *                       else @c NaN if it is not available
 183         * @see          SetLongitude()
 184         */
 185         double GetLongitude(void) const;
 186
 187         /**
 188         * Gets the altitude value of the coordinates.
 189         *
 190         * @since 2.0
 191         *
 192         * @return       The altitude in meters, @n
 193         *                       else @c NaN if it is not available
 194         * @see          SetAltitude()
 195         */
 196         double GetAltitude(void) const;
 197
 198         /**
 199         * Calculates the azimuth value.
 200         *
 201         * The coordinates are the starting point and @c dest is the destination for the azimuth calculation.
 202         * The azimuth is measured clockwise from true north based on the WGS84 ellipsoid model.
 203         *
 204         * The altitude value is not considered in calculation.
 205         *
 206         * @since 2.0
 207         *
 208         * @return       The azimuth value in decimal degrees within the range [0.0, +360.0], @n
 209         *                       else @c NaN if the latitude or the longitude of two points has an @c NaN value
 210         * @param[in]    dest The destination coordinates
 211         */
 212         double GetAzimuth(const Coordinates& dest) const;
 213
 214         /**
 215         * Calculates the geodetic distance to the given coordinates.
 216         *
 217         * The distance calculation is based on the WGS84 ellipsoid model.
 218         *
 219         * The altitude value is not considered in calculation.
 220         *
 221         * @since 2.0
 222         *
 223         * @return       The distance to the given coordinates in meters, @n
 224         *                       else @c NaN if the latitude or the longitude of two points has an @c NaN value
 225         * @param[in]    to The destination coordinates
 226         */
 227         double GetDistanceTo(const Coordinates& to) const;
 228
 229         /**
 230         * Converts the coordinate value into string.
 231         *
 232         * An application specifies formats like @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND for the result string.
 233         *
 234         * @since 2.0
 235         *
 236         * @return       An error code
 237         * @param[in]    degree  The coordinate in degrees within the range [-180.0, +180.0]
 238         * @param[in]    format  The desired format
 239         * @param[out]   string  The converted result in string
 240         * @exception    E_SUCCESS       The method is successful.
 241         * @exception    E_INVALID_ARG   The specified @c degree or @c format is invalid.
 242         * @see          Parse()
 243         */
 244         static result ToString(double degree, CoordinateFormat format, Tizen::Base::String& string);
 245
 246         /**
 247         * Converts a string into coordinate degree.
 248         *
 249         * The @c string should be in @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND format.
 250         *
 251         * @since 2.0
 252         *
 253         * @return       An error code
 254         * @param[in]    string  The string in degree-minute or degree-minute-second representation
 255         * @param[out]   degree  The converted result in decimal degrees
 256         * @exception    E_SUCCESS       The method is successful.
 257         * @exception    E_INVALID_ARG   The specified @c string is not in CoordinateFormat.
 258         * @see          ToString()
 259         */
 260         static result Parse(const Tizen::Base::String& string, double& degree);
 261
 262         /**
 263         * Copying of objects using this copy assignment operator is allowed.
 264         *
 265         * @since 2.0
 266         *
 267         * @return       A reference to the current instance
 268         * @param[in]    rhs     An instance of %Coordinates to assign
 269         */
 270         Coordinates& operator =(const Coordinates& rhs);
 271
 272 private:
 273         double __latitude;
 274         double __longitude;
 275         double __altitude;
 276
 277         class _CoordinatesImpl* __pImpl;
 278         friend class _CoordinatesImpl;
 279 }; // Coordinates
 280 }} // Tizen::Locations
 281 #endif // _FLOC_COORDINATES_H_