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_BOUNDARY_H_
23 #define __LOCATION_BOUNDARY_H_
25 #include <location-types.h>
26 #include <location-position.h>
30 GType location_boundary_get_type (void);
31 #define LOCATION_TYPE_BOUNDARY (location_boundary_get_type ())
35 * @file location-boundary.h
36 * @brief This file contains the definitions, structures, and functions related to boundary information.
39 * @addtogroup LocationAPI
41 * @defgroup LocationAPIBoundary Location Boundary
42 * @breif This provides APIs related to Location Boundary
43 * @addtogroup LocationAPIBoundary
49 * The type of the @location_boundary_foreach function of #LocationObject
51 typedef void (*LocationBoundaryFunc) (LocationBoundary *boundary, gpointer user_data);
54 * @brief This represents used geographical type, and supports rectangle or circle area.
57 LOCATION_BOUNDARY_NONE = 0, ///< Undefined geographical area type.
58 LOCATION_BOUNDARY_RECT, ///< Rectangular geographical area type.
59 LOCATION_BOUNDARY_CIRCLE, ///< Circle geographical area type.
60 LOCATION_BOUNDARY_POLYGON ///< Polygon geographical area type.
61 } LocationBoundaryType;
64 * @brief This represents a rectangular geographical area.
67 LocationPosition* left_top; ///< The left top position of rectangle.
68 LocationPosition* right_bottom; ///< The right bottom position of rectangle.
72 * @brief This represents a circle geographical area with center geographic position and radius.
75 LocationPosition* center; ///< The center position of a circle.
76 gdouble radius; ///< The radius of a circle.
80 * @brief This represents a polygon geographical area.
83 GList *position_list; ///< The collection of positions
87 * @brief This represents boundary information such as rectangular or circle area.
89 struct _LocationBoundary{
90 LocationBoundaryType type; ///< The boundary type of this information.
92 LocationRect rect; ///< The geographical information of a rectangle.
93 LocationCircle circle; ///< The geographical information of a circle.
94 LocationPolygon polygon; ///< The geographical information of a polygon.
99 * @brief Create a rectangular type of new #LocationBoundary with given information.
101 * @pre #location_init should be called before.\n
103 * @param [in] left_top - left top position.
104 * @param [in] right_bottom - right bottom position.
105 * @return a new #LocationBoundary
106 * @retval NULL if error occured
108 LocationBoundary *location_boundary_new_for_rect (LocationPosition *left_top, LocationPosition *right_bottom);
111 * @brief Create a circle type of new #LocationBoundary with given information.
113 * @pre #location_init should be called before.\n
115 * @param [in] center - center position.
116 * @param [in] radius - radius.
117 * @return a new #LocationBoundary
118 * @retval NULL if error occured
120 LocationBoundary *location_boundary_new_for_circle (LocationPosition *center, gdouble radius);
123 * @brief Create a polygon type of new #LocationBoundary with given information.
125 * @pre #location_init should be called before.\n
127 * @param [in] position_list - the list of positions.
128 * @return a new #LocationBoundary
129 * @retval NULL if error occured
131 LocationBoundary *location_boundary_new_for_polygon(GList *position_list);
134 * @brief Free a #LocationBoundary.
136 * @pre #location_init should be called before.\n
138 * @param [in] boundary - a #LocationBoundary.
141 void location_boundary_free (LocationBoundary *boundary);
144 * @brief Makes a copy of #LocationBoundary
146 * @pre #location_init should be called before.\n
148 * @param [in] boundary - a #LocationBoundary
149 * @return a new #LocationBoundary
150 * @retval NULL if error occured
152 LocationBoundary *location_boundary_copy (const LocationBoundary* boundary);
156 * Add Boundary on LocationFW.
157 * You should call this fuction when you want to receive a crossing signal(zone-in/zone-out) from #LocationBoundary.
158 * @remarks It supports multi-boundaries. \n
159 However a duplicated boundary would not be allowed.
161 * #location_new should be called before.\n
163 * @param [in] obj - a #LocationObject
164 * @param [in] boundary - a #LocationBoundary
167 * Please refer #LocationError for more information.
170 #include <location.h>
172 static void cb_zone_in (GObject *self, guint type, gpointer position, gpointer accuracy)
174 g_printf ("[zone-in] position - lat: %f, long: %f", position->latitude, position->longitude);
177 static void cb_zone_out (GObject *self, guint type, gpointer position, gpointer accuracy)
179 g_printf ("[zone-out] position - lat: %f, long: %f", position->latitude, position->longitude);
182 void location_test_boundary_add(LocationObject *loc)
184 LocationPosition* rb = location_position_new (0, 37.300, -121.86, 0, LOCATION_STATUS_2D_FIX);
185 LocationPosition* lt = location_position_new (0, 37.360, -121.92, 0, LOCATION_STATUS_2D_FIX);
187 LoationBoundary *boundary = location_boundary_new_for_rect (lt, rb);
189 ret = location_boundary_add(loc, boundary);
191 g_signal_connect(loc, "zone-in", G_CALLBACK(cb_zone_in), NULL);
192 g_siganl_connect(loc, "zone-out", G_CALLBACK(cb_zone_out), NULL);
194 location_position_free(rb);
195 location_position_free(lt);
199 int location_boundary_add(const LocationObject *obj, const LocationBoundary *boundary);
203 * Remove Boundary on LocationFW.
204 * You should call this function when you don't want to receive a crossing signal(zone-in/zone-out) from #LocationBoundary any more.
205 * @remarks It supports multi-boundaries.
207 * #location_init should be called before.\n
209 * @param [in] obj - a #LocationObject
210 * @param [in] boundary - a #LocationBoundary
214 * Please refer #LocationError for more information.
217 #include <location.h>
219 void location_test_boundary_remove(LocationObject *loc)
222 LocationPosition* rb = location_position_new (0, 37.300, -121.86, 0, LOCATION_STATUS_2D_FIX);
223 LocationPosition* lt = location_position_new (0, 37.360, -121.92, 0, LOCATION_STATUS_2D_FIX);
225 LoationBoundary *boundary = location_boundary_new_for_rect (lt, rb);
227 ret = location_boundary_remove(loc, boundary);
229 location_position_free(rb);
230 location_position_free(lt);
235 int location_boundary_remove(const LocationObject *obj, const LocationBoundary *boundary);
239 * Call a function for each element of a Boundary list.
242 * #location_init should be called before.\n
244 * @param [in] obj - a #LocationObject
245 * @param [in] func - a #LocationBoundaryFunc
246 * @param [in] user_data - a #void
250 * Please refer #LocationError for more information.
253 #include <location.h>
255 static void remove_boundary(LocationBoundary *boundary, void *user_data)
257 LocationBoundary *loc = (LocationBoundary *) user_data;
258 if (loc == NULL || boundary == NULL) return;
260 location_boundary_remove(loc, boundary);
263 void location_test_boundary_foreach(LocationObject *loc)
265 int ret = location_boundary_foreach(loc, remove_boundary, loc);
269 int location_boundary_foreach(const LocationObject *obj, LocationBoundaryFunc func, gpointer user_data);
273 * @brief Check if #LocationPosition is inside #LocationBoundary.
275 * @pre #location_init should be called before.\n
276 * @post None.* @param [in] boundary - a #LocationBoundary
277 * @param [in] position - a #LocationPosition
281 * FALSE - if outside\n
284 #include <location.h>
286 void location_test_boundary_if_inside(LocationObject *loc, LocationBoundary *boundary)
288 gboolean is_inside = FALSE;
289 LocationPosition* position = location_position_new (0, 37.300, -121.86, 0, LOCATION_STATUS_2D_FIX);
290 is_inside = location_boundary_if_inside(boundary, position);
291 if (is_inside == TRUE) g_printf("The position is inside of the boundary\n");
292 else g_printf("The position is outside of the boundary\n");
298 gboolean location_boundary_if_inside (LocationBoundary *boundary, LocationPosition *position);
301 * @brief Get bounding box of #LocationBoundary
303 LocationBoundary *location_boundary_get_bounding_box (LocationBoundary *boundary);
307 * @brief Get the center position of #LocationBoundary
309 LocationPosition * location_boundary_get_center_position (LocationBoundary *boundary);