4 * Copyright (c) 2010-2011 Samsung Electronics Co., Ltd. All rights reserved.
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>
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
13 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #ifndef __LOCATION_POSITION_H_
23 #define __LOCATION_POSITION_H_
25 #include <location/location-types.h>
27 #define MAX_KEY_LENGTH 16
28 #define HALF_KEY_LENGTH 8
31 * @file location-position.h
32 * @brief This file contains the internal definitions and structures related to position information.
33 * @addtogroup LocationTypes
40 * @brief This represents the various fix states.
44 LOCATION_STATUS_NO_FIX = 0, ///< No fix status.
45 LOCATION_STATUS_2D_FIX, ///< 2D fix status (latitude/longitude/speed/direction).
46 LOCATION_STATUS_3D_FIX ///< 3D fix status (altitude/climb as well).
50 * @brief This represents position information such as latitude-longitude-altitude values and timestamp.
52 struct _LocationPosition
54 guint timestamp; ///< Time stamp.
55 guint updated_timestamp; ///< lastest updated time stamp.
56 gdouble latitude; ///< Latitude data.
57 gdouble longitude; ///< Longitude data.
58 gdouble altitude; ///< Altitude data.
59 LocationStatus status; ///< Fix states.
63 * @brief This represents last known position information such as latitude-longitude values and accuracy.
65 struct _LocationLastPosition
67 guint timestamp; ///< Time stamp.
68 gdouble latitude; ///< Latitude data.
69 gdouble longitude; ///< Longitude data.
70 gdouble accuracy; ///< Accuracy data.
73 GType location_position_get_type (void);
74 #define LOCATION_TYPE_POSITION (location_position_get_type ())
77 * @brief Create a new #LocationPosition with given information.
79 * @pre #location_init should be called before.\n
81 * @param [in] timestamp - Time stamp.
82 * @param [in] latitude - Latitude data.
83 * @param [in] longitude - Longitude data.
84 * @param [in] altitude - Altitude data.
85 * @param [in] status - a #LocationStatus.
86 * @return a new #LocationPosition
87 * @retval NULL if error occured
89 LocationPosition *location_position_new (guint timestamp, gdouble latitude, gdouble longitude, gdouble altitude, LocationStatus status);
92 * @brief Free a #LocationPosition.
94 * @pre #location_init should be called before.\n
96 * @param [in] position - a #LocationPosition.
99 void location_position_free (LocationPosition *position);
102 * @brief Compares two positoins for equality, returning TRUE if they are equal.
104 * @pre #location_init should be called before.\n
106 * @param [in] position1 - a #LocationPosition
107 * @param [in] position2 - a #LocationPosition
111 * FALSE - if not equal\n
113 gboolean location_position_equal (const LocationPosition *position1, const LocationPosition *position2);
116 * @brief Makes a copy of #LocationPosition
118 * @pre #location_init should be called before.\n
120 * @param [in] position - a #LocationPosition
121 * @return a new #LocationPosition
122 * @retval NULL if error occured
124 LocationPosition *location_position_copy (const LocationPosition *position);
126 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
127 /* Vincenty Inverse Solution of Geodesics on the Ellipsoid (c) Chris Veness 2002-2010 */
129 /* from: Vincenty inverse formula - T Vincenty, "Direct and Inverse Solutions of Geodesics on the */
130 /* Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975 */
131 /* http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf */
132 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
135 * @brief Gets the approximate distance between two points. A distance is defined using the WGS84 ellipsoid.
136 * @remarks Uses meters as a unit of measurement for a distance.
139 * @param [in] pos1 - a #LocationPosition (decimal degree)
140 * @param [in] pos2 - a #LocationPosition (decimal degree)
141 * @param [out] distance - a #gulong (meters)
145 * Please refer #LocationError for more information.
147 int location_get_distance(const LocationPosition *pos1, const LocationPosition *pos2, gulong *distance);
150 * @brief Change position string to latitude and longitude integer.
152 * @pre #location_init should be called before.\n
154 * @param [in] position - string of last position.
155 * @param [in] lat - latitude.
156 * @param [in] lon - longitude.
159 void location_last_position_a2i(char *position, int *lat, int *lon);