location/manager/location-position.h

   1 /*
   2  * libslp-location
   3  *
   4  * Copyright (c) 2010-2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Youngae Kang <youngae.kang@samsung.com>, Yunhan Kim <yhan.kim@samsung.com>,
   7  *          Genie Kim <daejins.kim@samsung.com>, Minjune Kim <sena06.kim@samsung.com>
   8  *
   9  * Licensed under the Apache License, Version 2.0 (the "License");
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  */
  21
  22 #ifndef __LOCATION_POSITION_H_
  23 #define __LOCATION_POSITION_H_
  24
  25 #include <location-types.h>
  26
  27 #define MAX_KEY_LENGTH          16
  28 #define HALF_KEY_LENGTH         8
  29
  30 G_BEGIN_DECLS
  31
  32 GType location_position_get_type (void);
  33 #define LOCATION_TYPE_POSITION (location_position_get_type ())
  34
  35 /**
  36  * @file location-position.h
  37  * @brief This file contains the internal definitions and structures related to position information.
  38  */
  39 /**
  40  * @addtogroup LocationAPI
  41  * @{
  42  * @defgroup LocationAPIPosition Location Position
  43  * @breif This provides APIs related to Location Position
  44  * @addtogroup LocationAPIPosition
  45  * @{
  46  *
  47  */
  48
  49 /**
  50  * @brief This represents the various fix states.
  51  */
  52 typedef enum
  53 {
  54         LOCATION_STATUS_NO_FIX = 0,     ///< No fix status.
  55         LOCATION_STATUS_2D_FIX,         ///< 2D fix status (latitude/longitude/speed/direction).
  56         LOCATION_STATUS_3D_FIX          ///< 3D fix status (altitude/climb as well).
  57 } LocationStatus;
  58
  59 /**
  60  * @brief This represents position information such as latitude-longitude-altitude values and timestamp.
  61  */
  62 struct _LocationPosition
  63 {
  64         guint timestamp;        ///< Time stamp.
  65         gdouble latitude;       ///< Latitude data.
  66         gdouble longitude;      ///< Longitude data.
  67         gdouble altitude;       ///< Altitude data.
  68         LocationStatus status;  ///< Fix states.
  69 };
  70
  71 /**
  72  * @brief This represents last known position information such as latitude-longitude values and accuracy.
  73  */
  74 struct _LocationLastPosition
  75 {
  76         LocationMethod method;  ///< Location Method.
  77         guint timestamp;        ///< Time stamp.
  78         gdouble latitude;       ///< Latitude data.
  79         gdouble longitude;      ///< Longitude data.
  80         gdouble altitude;       ///< Altitude data.
  81         gdouble horizontal_accuracy;    ///< Horizontal accuracy data.
  82         gdouble vertical_accuracy;      ///< Vertical accuracy data.
  83 };
  84
  85 /**
  86  * @brief   Create a new #LocationPosition with given information.
  87  * @remarks None.
  88  * @pre     #location_init should be called before.\n
  89  * @post    None.
  90  * @param [in]  timestamp - Time stamp.
  91  * @param [in]  latitude - Latitude data.
  92  * @param [in]  longitude - Longitude data.
  93  * @param [in]  altitude - Altitude data.
  94  * @param [in]  status - a #LocationStatus.
  95  * @return a new #LocationPosition
  96  * @retval NULL if error occured
  97  */
  98 LocationPosition *location_position_new (guint timestamp, gdouble latitude, gdouble longitude, gdouble altitude, LocationStatus status);
  99
 100 /**
 101  * @brief   Free a #LocationPosition.
 102  * @remarks None.
 103  * @pre     #location_init should be called before.\n
 104  * @post    None.
 105  * @param [in] position - a #LocationPosition.
 106  * @return None.
 107  */
 108 void location_position_free (LocationPosition *position);
 109
 110 /**
 111  * @brief   Compares two positions for equality, returning TRUE if they are equal.
 112  * @remarks None.
 113  * @pre     #location_init should be called before.\n
 114  * @post    None.
 115  * @param [in]  position1 - a #LocationPosition
 116  * @param [in]  position2 - a #LocationPosition
 117  * @return gboolean
 118  * @retval\n
 119  * TRUE - if equal\n
 120  * FALSE - if not equal\n
 121  */
 122 gboolean location_position_equal (const LocationPosition *position1, const LocationPosition *position2);
 123
 124 /**
 125  * @brief   Makes a copy of #LocationPosition
 126  * @remarks None.
 127  * @pre     #location_init should be called before.\n
 128  * @post    None.
 129  * @param [in]  position - a #LocationPosition
 130  * @return a new #LocationPosition
 131  * @retval NULL if error occured
 132  */
 133 LocationPosition *location_position_copy (const LocationPosition *position);
 134
 135 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  */
 136 /* Vincenty Inverse Solution of Geodesics on the Ellipsoid (c) Chris Veness 2002-2010             */
 137 /*                                                                                                */
 138 /* from: Vincenty inverse formula - T Vincenty, "Direct and Inverse Solutions of Geodesics on the */
 139 /*       Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975    */
 140 /*       http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf                                             */
 141 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  */
 142
 143 /**
 144  * @brief   Gets the approximate distance between two points. A distance is defined using the WGS84 ellipsoid.
 145  * @remarks Uses meters as a unit of measurement for a distance.
 146  * @pre     None.
 147  * @post    None.
 148  * @param [in]  pos1 - a #LocationPosition (decimal degree)
 149  * @param [in]  pos2 - a #LocationPosition (decimal degree)
 150  * @param [out]  distance - a #gulong (meters)
 151  * @return int
 152  * @retval 0                              Success.
 153  *
 154  * Please refer #LocationError for more information.
 155  */
 156 int location_get_distance(const LocationPosition *pos1, const LocationPosition *pos2, gulong *distance);
 157
 158 /**
 159  * @brief   Change position string to latitude and longitude integer.
 160  * @remarks None.
 161  * @pre     #location_init should be called before.\n
 162  * @post    None.
 163  * @param [in]  position - string of last position.
 164  * @param [in]  lat - latitude.
 165  * @param [in]  lon - longitude.
 166  * @return None.
 167  */
 168 void location_last_position_a2i(char *position, int *lat, int *lon);
 169
 170 /**
 171  * @} @}
 172  */
 173
 174 G_END_DECLS
 175
 176 #endif