inc/FLocLocation.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        FLocLocation.h
  20  * @brief       This is the header file for the %Location class.
  21  *
  22  * This header file contains the declarations of the %Location class.
  23  */
  24
  25 #ifndef _FLOC_LOCATION_H_
  26 #define _FLOC_LOCATION_H_
  27
  28 #include <FBaseObject.h>
  29
  30 namespace Tizen { namespace Base
  31 {
  32 class String;
  33 class DateTime;
  34 }}
  35
  36 namespace Tizen { namespace Locations
  37 {
  38 class Coordinates;
  39
  40 /**
  41 * @class        Location
  42 * @brief        This class contains and provides information about a location including its geographical coordinates, altitude, and so on.
  43 *
  44 * @since 2.0
  45 *
  46 * @final        This class is not intended for extension.
  47 *
  48 * The %Location class contains all information about a location that the location provider fixed at a certain moment.
  49 * It basically provides geographical coordinates and horizontal accuracy that gives the estimated error about the coordinates,
  50 * while the altitude, vertical accuracy, speed, and course at the location are optionally provided.
  51 * It also contains detailed and specific positioning information, such as satellites used to fix the location.
  52 *
  53 * An application obtains the %Location instances from LocationProvider.
  54 */
  55 class _OSP_EXPORT_ Location
  56         : public Tizen::Base::Object
  57 {
  58 public:
  59         /**
  60         * Copying of objects using this copy constructor is allowed.
  61         *
  62         * @since 2.0
  63         *
  64         * @param[in]    rhs     An instance of %Location to copy
  65         */
  66         Location(const Location& rhs);
  67
  68         /**
  69          * This destructor overrides Tizen::Base::Object::~Object().
  70          *
  71          * @since 2.0
  72          */
  73         virtual ~Location(void);
  74
  75         /**
  76         * Compares the calling instance with the specified instance for equality.
  77         *
  78         * @since 2.0
  79         *
  80         * @return       @c true if all the fields in the objects are equal, @n
  81         *                       else @c false
  82         * @param[in]    rhs     The object to compare
  83         */
  84         virtual bool Equals(const Tizen::Base::Object& rhs) const;
  85
  86         /**
  87         * Gets the hash value of the calling instance.
  88         *
  89         * @since 2.0
  90         *
  91         * @return       The hash value of the calling instance
  92         */
  93         virtual int GetHashCode(void) const;
  94
  95         /**
  96         * Gets the horizontal accuracy.
  97         *
  98         * @since 2.0
  99         *
 100         * @return       The horizontal accuracy in meters, @n
 101         *                       else @c NaN if it is not available
 102         */
 103         double GetHorizontalAccuracy(void) const;
 104
 105         /**
 106         * Gets the vertical accuracy.
 107         *
 108         * @since 2.0
 109         *
 110         * @return       The vertical accuracy in meters, @n
 111         *                       else @c NaN if it is not available
 112         */
 113         double GetVerticalAccuracy(void) const;
 114
 115         /**
 116         * Gets the course.
 117         *
 118         * The course is the angle of moving direction measured clockwise from true north.
 119         *
 120         * @since 2.0
 121         *
 122         * @return       The course in degrees within the range [0.0, +360.0], @n
 123         *                       else @c NaN if it is not available
 124         */
 125         double GetCourse(void) const;
 126
 127         /**
 128         * Gets the coordinates.
 129         *
 130         * @since 2.0
 131         *
 132         * @return       The geographical coordinates
 133         */
 134         Coordinates GetCoordinates(void) const;
 135
 136         /**
 137         * Gets the ground speed.
 138         *
 139         * @since 2.0
 140         *
 141         * @return       The speed in km/h, @n
 142         *                       else @c NaN if it is not available
 143         */
 144         double GetSpeed(void) const;
 145
 146         /**
 147         * Gets the timestamp when this location is fixed.
 148         *
 149         * @since 2.0
 150         *
 151         * @return       The fix time in UTC
 152         */
 153         Tizen::Base::DateTime GetTimestamp(void) const;
 154
 155         /**
 156         * Gets the detailed positioning information.
 157         *
 158         * The detailed positioning information is queried using a key, and the %GetExtraInfo() method returns the information corresponding to the key.
 159         * <table>
 160             <tr><th>Key</th><th>Information</th></tr>
 161             <tr><td>location_method</td><td>Positioning technology used to fix this location. Possible values are "gps" and "network".</td></tr>
 162             <tr><td>satellite</td>
 163                     <td>GPS satellite information in the semicolon-separated satellite sentences.
 164                     Each sentence forms "PRN, Elevation, Azimuth, SNR, Active" where PRN is a satellite ID, Elevation is in degree, Azimuth is in degree,
 165                     SNR is a signal to nose ratio in dBHZ, and Active is @c 1, if the satellite is in use for positioning, or @c 0.
 166                     For example, it can be "02, 40.0, 83.0, 35.0, 1; 15, 30.0, 65.0, 35.0, 0; 22, 80.0, 120.0, 40.0, 1;".</td>
 167             </tr></table>
 168         *
 169         * @since 2.0
 170         *
 171         * @return         The information corresponding to the key, @n
 172         *                 else an empty string if the @c key is invalid or the requested information is not available for this location
 173         * @param[in]     key       The key to the positioning information
 174         */
 175         Tizen::Base::String GetExtraInfo(const Tizen::Base::String& key) const;
 176
 177         /**
 178         * Checks the validity for this location.
 179         *
 180         * @since 2.0
 181         *
 182         * @return       @c true if the location is valid, @n
 183         *                       else @c false
 184         */
 185         bool IsValid(void) const;
 186
 187         /**
 188         * Copying of objects using this copy assignment operator is allowed.
 189         *
 190         * @since 2.0
 191         *
 192         * @return       A reference to the current instance
 193         * @param[in]    rhs     An instance of %Location to assign
 194         */
 195         Location& operator =(const Location& rhs);
 196
 197 private:
 198         //
 199         // This default constructor is intentionally declared as private so that only the platform can create an instance.
 200         //
 201         // @since 2.0
 202         //
 203         Location(void);
 204
 205 private:
 206         class _LocationImpl* __pImpl;
 207         friend class _LocationImpl;
 208 }; // Location
 209 }} // Tizen::Locations
 210 #endif // _FLOC_LOCATION_H_