4 * Copyright (c) 2010-2013 Samsung Electronics Co., Ltd. All rights reserved.
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
10 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 #ifndef __LOCATION_POSITION_H_
20 #define __LOCATION_POSITION_H_
22 #include <location-types.h>
24 #define MAX_KEY_LENGTH 16
25 #define HALF_KEY_LENGTH 8
29 GType location_position_get_type(void);
30 #define LOCATION_TYPE_POSITION (location_position_get_type())
33 * @file location-position.h
34 * @brief This file contains the internal definitions and structures related to position information.
37 * @addtogroup LocationAPI
39 * @defgroup LocationAPIPosition Location Position
40 * @breif This provides APIs related to Location Position
41 * @addtogroup LocationAPIPosition
47 * @brief This represents the various fix states.
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). */
56 * @brief This represents position information such as latitude-longitude-altitude values and timestamp.
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. */
67 * @brief This represents last known position information such as latitude-longitude values and accuracy.
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. */
80 * @brief Create a new #LocationPosition with given information.
82 * @pre #location_init should be called before.\n
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
92 LocationPosition *location_position_new(guint timestamp, gdouble latitude, gdouble longitude, gdouble altitude, LocationStatus status);
95 * @brief Free a #LocationPosition.
97 * @pre #location_init should be called before.\n
99 * @param [in] position - a #LocationPosition.
102 void location_position_free(LocationPosition *position);
105 * @brief Compares two positions for equality, returning TRUE if they are equal.
107 * @pre #location_init should be called before.\n
109 * @param [in] position1 - a #LocationPosition
110 * @param [in] position2 - a #LocationPosition
114 * FALSE - if not equal\n
116 gboolean location_position_equal(const LocationPosition *position1, const LocationPosition *position2);
119 * @brief Makes a copy of #LocationPosition
121 * @pre #location_init should be called before.\n
123 * @param [in] position - a #LocationPosition
124 * @return a new #LocationPosition
125 * @retval NULL if error occured
127 LocationPosition *location_position_copy(const LocationPosition *position);
129 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
130 /* Vincenty Inverse Solution of Geodesics on the Ellipsoid (c) Chris Veness 2002-2010 */
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 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
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.
142 * @param [in] pos1 - a #LocationPosition (decimal degree)
143 * @param [in] pos2 - a #LocationPosition (decimal degree)
144 * @param [out] distance - a #gulong (meters)
148 * Please refer #LocationError for more information.
150 int location_get_distance(const LocationPosition *pos1, const LocationPosition *pos2, gulong *distance);
153 * @brief Change position string to latitude and longitude integer.
155 * @pre #location_init should be called before.\n
157 * @param [in] position - string of last position.
158 * @param [in] lat - latitude.
159 * @param [in] lon - longitude.
162 void location_last_position_a2i(char *position, int *lat, int *lon);