location/manager/location-position.h

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