location/manager/location-boundary.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_BOUNDARY_H_
  23 #define __LOCATION_BOUNDARY_H_
  24
  25 #include <location-types.h>
  26 #include <location-position.h>
  27
  28 G_BEGIN_DECLS
  29
  30 GType location_boundary_get_type (void);
  31 #define LOCATION_TYPE_BOUNDARY (location_boundary_get_type ())
  32
  33
  34 /**
  35  * @file location-boundary.h
  36  * @brief This file contains the definitions, structures, and functions related to boundary information.
  37  */
  38 /**
  39  * @addtogroup LocationAPI
  40  * @{
  41  * @defgroup LocationAPIBoundary Location Boundary
  42  * @breif This provides APIs related to Location Boundary
  43  * @addtogroup LocationAPIBoundary
  44  * @{
  45  */
  46
  47 /**
  48  * @brief
  49  * The type of the @location_boundary_foreach function of #LocationObject
  50  */
  51 typedef void (*LocationBoundaryFunc) (LocationBoundary *boundary, gpointer user_data);
  52
  53 /**
  54  * @brief This represents used geographical type, and supports rectangle or circle area.
  55  */
  56 typedef enum {
  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;
  62
  63 /**
  64  * @brief This represents a rectangular geographical area.
  65  */
  66 typedef struct {
  67         LocationPosition* left_top;       ///< The left top position of rectangle.
  68         LocationPosition* right_bottom;   ///< The right bottom position of rectangle.
  69 } LocationRect;
  70
  71 /**
  72  * @brief This represents a circle geographical area with center geographic position and radius.
  73  */
  74 typedef struct {
  75         LocationPosition* center;      ///< The center position of a circle.
  76         gdouble radius;               ///< The radius of a circle.
  77 } LocationCircle;
  78
  79 /**
  80  * @brief This represents a polygon geographical area.
  81  */
  82 typedef struct {
  83         GList *position_list;   ///< The collection of positions
  84 } LocationPolygon;
  85
  86 /**
  87  * @brief This represents boundary information such as rectangular or circle area.
  88  */
  89 struct _LocationBoundary{
  90         LocationBoundaryType type;   ///< The boundary type of this information.
  91         union {
  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.
  95         };
  96 };
  97
  98 /**
  99  * @brief   Create a rectangular type of new #LocationBoundary with given information.
 100  * @remarks None.
 101  * @pre     #location_init should be called before.\n
 102  * @post    None.
 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
 107  */
 108 LocationBoundary *location_boundary_new_for_rect (LocationPosition *left_top, LocationPosition *right_bottom);
 109
 110 /**
 111  * @brief   Create a circle type of new #LocationBoundary with  given information.
 112  * @remarks None.
 113  * @pre     #location_init should be called before.\n
 114  * @post    None.
 115  * @param [in]  center - center position.
 116  * @param [in]  radius - radius.
 117  * @return a new #LocationBoundary
 118  * @retval NULL if error occured
 119  */
 120 LocationBoundary *location_boundary_new_for_circle (LocationPosition *center, gdouble radius);
 121
 122 /**
 123  * @brief   Create a polygon type of new #LocationBoundary with  given information.
 124  * @remarks None.
 125  * @pre     #location_init should be called before.\n
 126  * @post    None.
 127  * @param [in]  position_list - the list of positions.
 128  * @return a new #LocationBoundary
 129  * @retval NULL if error occured
 130  */
 131 LocationBoundary *location_boundary_new_for_polygon(GList *position_list);
 132
 133 /**
 134  * @brief   Free a #LocationBoundary.
 135  * @remarks None.
 136  * @pre     #location_init should be called before.\n
 137  * @post    None.
 138  * @param [in] boundary - a #LocationBoundary.
 139  * @return None.
 140  */
 141 void location_boundary_free (LocationBoundary *boundary);
 142
 143 /**
 144  * @brief   Makes a copy of #LocationBoundary
 145  * @remarks None.
 146  * @pre     #location_init should be called before.\n
 147  * @post    None.
 148  * @param [in]  boundary - a #LocationBoundary
 149  * @return a new #LocationBoundary
 150  * @retval NULL if error occured
 151  */
 152 LocationBoundary *location_boundary_copy (const LocationBoundary* boundary);
 153
 154 /**
 155  * @brief
 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.
 160  * @pre
 161  * #location_new should be called before.\n
 162  * @post None.
 163  * @param [in]  obj - a #LocationObject
 164  * @param [in]  boundary - a #LocationBoundary
 165  * @return int
 166  * @retval 0                              Success
 167  * Please refer #LocationError for more information.
 168  * @par Example
 169  * @code
 170 #include <location.h>
 171
 172 static void cb_zone_in (GObject *self, guint type, gpointer position, gpointer accuracy)
 173 {
 174         g_printf ("[zone-in] position - lat: %f, long: %f", position->latitude, position->longitude);
 175 }
 176
 177 static void cb_zone_out (GObject *self, guint type, gpointer position, gpointer accuracy)
 178 {
 179         g_printf ("[zone-out] position - lat: %f, long: %f", position->latitude, position->longitude);
 180 }
 181
 182 void location_test_boundary_add(LocationObject *loc)
 183 {
 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);
 186
 187         LoationBoundary *boundary = location_boundary_new_for_rect (lt, rb);
 188
 189         ret = location_boundary_add(loc, boundary);
 190
 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);
 193
 194         location_position_free(rb);
 195         location_position_free(lt);
 196 }
 197  * @endcode
 198  */
 199 int location_boundary_add(const LocationObject *obj, const LocationBoundary *boundary);
 200
 201 /**
 202  * @brief
 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.
 206  * @pre
 207  * #location_init should be called before.\n
 208  * @post None.
 209  * @param [in]  obj - a #LocationObject
 210  * @param [in]  boundary - a #LocationBoundary
 211  * @return int
 212  * @retval 0                              Success
 213  *
 214  * Please refer #LocationError for more information.
 215  * @par Example
 216  * @code
 217 #include <location.h>
 218
 219 void location_test_boundary_remove(LocationObject *loc)
 220 {
 221         int ret = 0;
 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);
 224
 225         LoationBoundary *boundary = location_boundary_new_for_rect (lt, rb);
 226
 227         ret = location_boundary_remove(loc, boundary);
 228
 229         location_position_free(rb);
 230         location_position_free(lt);
 231
 232 }
 233  * @endcode
 234  */
 235 int location_boundary_remove(const LocationObject *obj, const LocationBoundary *boundary);
 236
 237 /**
 238  * @brief
 239  * Call a function for each element of a Boundary list.
 240  * @remarks None.
 241  * @pre
 242  * #location_init should be called before.\n
 243  * @post None.
 244  * @param [in]  obj - a #LocationObject
 245  * @param [in]  func - a #LocationBoundaryFunc
 246  * @param [in]  user_data - a #void
 247  * @return int
 248  * @retval 0                              Success
 249  *
 250  * Please refer #LocationError for more information.
 251  * @par Example
 252  * @code
 253 #include <location.h>
 254
 255 static void remove_boundary(LocationBoundary *boundary, void *user_data)
 256 {
 257         LocationBoundary *loc = (LocationBoundary *) user_data;
 258         if (loc == NULL || boundary == NULL) return;
 259
 260         location_boundary_remove(loc, boundary);
 261 }
 262
 263 void location_test_boundary_foreach(LocationObject *loc)
 264 {
 265         int ret = location_boundary_foreach(loc, remove_boundary, loc);
 266 }
 267  * @endcode
 268  */
 269 int location_boundary_foreach(const LocationObject *obj, LocationBoundaryFunc func, gpointer user_data);
 270
 271
 272 /**
 273  * @brief   Check if #LocationPosition is inside #LocationBoundary.
 274  * @remarks None.
 275  * @pre     #location_init should be called before.\n
 276  * @post    None.* @param [in]  boundary - a #LocationBoundary
 277  * @param [in]  position - a #LocationPosition
 278  * @return gboolean
 279  * @retval\n
 280  * TRUE - if inside\n
 281  * FALSE - if outside\n
 282  * @par Example
 283  * @code
 284 #include <location.h>
 285
 286 void location_test_boundary_if_inside(LocationObject *loc, LocationBoundary *boundary)
 287 {
 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");
 293
 294 }
 295  * @endcode
 296
 297  */
 298 gboolean location_boundary_if_inside (LocationBoundary *boundary, LocationPosition *position);
 299
 300 /**
 301  * @brief Get bounding box of #LocationBoundary
 302  */
 303 LocationBoundary *location_boundary_get_bounding_box (LocationBoundary *boundary);
 304
 305
 306 /**
 307  * @brief Get the center position of #LocationBoundary
 308  */
 309 LocationPosition * location_boundary_get_center_position (LocationBoundary *boundary);
 310
 311 /**
 312  * @} @}
 313  */
 314
 315 G_END_DECLS
 316
 317 #endif