location/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/location-types.h>
  26 #include <location/location-position.h>
  27
  28 /**
  29  * @file location-boundary.h
  30  * @brief This file contains the definitions, structures, and functions related to boundary information.
  31  * @addtogroup LocationTypes
  32  * @{
  33  */
  34
  35 G_BEGIN_DECLS
  36
  37 /**
  38  * @brief
  39  * The type of the @location_boundary_foreach function of #LocationObject
  40  */
  41 typedef void (*LocationBoundaryFunc) (LocationBoundary *boundary, gpointer user_data);
  42
  43 /**
  44  * @brief This represents used geographical type, and supports rectangle or circle area.
  45  */
  46 typedef enum {
  47         LOCATION_BOUNDARY_NONE = 0,  ///< Undefined geographical area type.
  48         LOCATION_BOUNDARY_RECT,      ///< Rectangular geographical area type.
  49         LOCATION_BOUNDARY_CIRCLE,     ///< Circle geographical area type.
  50         LOCATION_BOUNDARY_POLYGON               ///< Polygon geographical area type.
  51 } LocationBoundaryType;
  52
  53 /**
  54  * @brief This represents a rectangular geographical area.
  55  */
  56 typedef struct {
  57         LocationPosition* left_top;       ///< The left top position of rectangle.
  58         LocationPosition* right_bottom;   ///< The right bottom position of rectangle.
  59 } LocationRect;
  60
  61 /**
  62  * @brief This represents a circle geographical area with center geographic position and radius.
  63  */
  64 typedef struct {
  65         LocationPosition* center;      ///< The center position of a circle.
  66         gdouble radius;               ///< The radius of a circle.
  67 } LocationCircle;
  68
  69 /**
  70  * @brief This represents a polygon geographical area.
  71  */
  72 typedef struct {
  73         GList *position_list;   ///< The collection of positions
  74 } LocationPolygon;
  75
  76 /**
  77  * @brief This represents boundary information such as rectangular or circle area.
  78  */
  79 struct _LocationBoundary{
  80         LocationBoundaryType type;   ///< The boundary type of this information.
  81         union {
  82                 LocationRect rect;           ///< The geographical information of a rectangle.
  83                 LocationCircle circle;       ///< The geographical information of a circle.
  84                 LocationPolygon polygon;                ///< The geographical information of a polygon.
  85         };
  86 };
  87
  88 GType location_boundary_get_type (void);
  89 #define LOCATION_TYPE_BOUNDARY (location_boundary_get_type ())
  90
  91 /**
  92  * @brief   Create a rectangular type of new #LocationBoundary with given information.
  93  * @remarks None.
  94  * @pre     #location_init should be called before.\n
  95  * @post    None.
  96  * @param [in]  left_top - left top position.
  97  * @param [in]  right_bottom - right bottom position.
  98  * @return a new #LocationBoundary
  99  * @retval NULL if error occured
 100  */
 101 LocationBoundary *location_boundary_new_for_rect (LocationPosition *left_top, LocationPosition *right_bottom);
 102
 103 /**
 104  * @brief   Create a circle type of new #LocationBoundary with  given information.
 105  * @remarks None.
 106  * @pre     #location_init should be called before.\n
 107  * @post    None.
 108  * @param [in]  center - center position.
 109  * @param [in]  radius - radius.
 110  * @return a new #LocationBoundary
 111  * @retval NULL if error occured
 112  */
 113 LocationBoundary *location_boundary_new_for_circle (LocationPosition *center, gdouble radius);
 114
 115 /**
 116  * @brief   Create a polygon type of new #LocationBoundary with  given information.
 117  * @remarks None.
 118  * @pre     #location_init should be called before.\n
 119  * @post    None.
 120  * @param [in]  position_list - the list of positions.
 121  * @return a new #LocationBoundary
 122  * @retval NULL if error occured
 123  */
 124 LocationBoundary *location_boundary_new_for_polygon(GList *position_list);
 125
 126 /**
 127  * @brief   Free a #LocationBoundary.
 128  * @remarks None.
 129  * @pre     #location_init should be called before.\n
 130  * @post    None.
 131  * @param [in] boundary - a #LocationBoundary.
 132  * @return None.
 133  */
 134 void location_boundary_free (LocationBoundary *boundary);
 135
 136 /**
 137  * @brief   Makes a copy of #LocationBoundary
 138  * @remarks None.
 139  * @pre     #location_init should be called before.\n
 140  * @post    None.
 141  * @param [in]  boundary - a #LocationBoundary
 142  * @return a new #LocationBoundary
 143  * @retval NULL if error occured
 144  */
 145 LocationBoundary *location_boundary_copy (const LocationBoundary* boundary);
 146
 147 /**
 148  * @brief
 149  * Add Boundary on LocationFW.
 150  * You should call this fuction when you want to receive a crossing signal(zone-in/zone-out) from #LocationBoundary.
 151  * @remarks It supports multi-boundaries. \n
 152     However a duplicated boundary would not be allowed.
 153  * @pre
 154  * #location_new should be called before.\n
 155  * @post None.
 156  * @param [in]  obj - a #LocationObject
 157  * @param [in]  boundary - a #LocationBoundary
 158  * @return int
 159  * @retval 0                              Success
 160  * Please refer #LocationError for more information.
 161  * @par Example
 162  * @code
 163 #include <location.h>
 164
 165 static void cb_zone_in (GObject *self, guint type, gpointer position, gpointer accuracy)
 166 {
 167         g_printf ("[zone-in] position - lat: %f, long: %f", position->latitude, position->longitude);
 168 }
 169
 170 static void cb_zone_out (GObject *self, guint type, gpointer position, gpointer accuracy)
 171 {
 172         g_printf ("[zone-out] position - lat: %f, long: %f", position->latitude, position->longitude);
 173 }
 174
 175 void location_test_boundary_add(LocationObject *loc)
 176 {
 177         LocationPosition* rb = location_position_new (0, 37.300, -121.86, 0, LOCATION_STATUS_2D_FIX);
 178         LocationPosition* lt = location_position_new (0, 37.360, -121.92, 0, LOCATION_STATUS_2D_FIX);
 179
 180         LoationBoundary *boundary = location_boundary_new_for_rect (lt, rb);
 181
 182         ret = location_boundary_add(loc, boundary);
 183
 184         g_signal_connect(loc, "zone-in", G_CALLBACK(cb_zone_in), NULL);
 185         g_siganl_connect(loc, "zone-out", G_CALLBACK(cb_zone_out), NULL);
 186
 187         location_position_free(rb);
 188         location_position_free(lt);
 189 }
 190  * @endcode
 191  */
 192 int location_boundary_add(const LocationObject *obj, const LocationBoundary *boundary);
 193
 194 /**
 195  * @brief
 196  * Remove Boundary on LocationFW.
 197  * You should call this function when you don't want to receive a crossing signal(zone-in/zone-out) from #LocationBoundary any more.
 198  * @remarks It supports multi-boundaries.
 199  * @pre
 200  * #location_init should be called before.\n
 201  * @post None.
 202  * @param [in]  obj - a #LocationObject
 203  * @param [in]  boundary - a #LocationBoundary
 204  * @return int
 205  * @retval 0                              Success
 206  *
 207  * Please refer #LocationError for more information.
 208  * @par Example
 209  * @code
 210 #include <location.h>
 211
 212 void location_test_boundary_remove(LocationObject *loc)
 213 {
 214         int ret = 0;
 215         LocationPosition* rb = location_position_new (0, 37.300, -121.86, 0, LOCATION_STATUS_2D_FIX);
 216         LocationPosition* lt = location_position_new (0, 37.360, -121.92, 0, LOCATION_STATUS_2D_FIX);
 217
 218         LoationBoundary *boundary = location_boundary_new_for_rect (lt, rb);
 219
 220         ret = location_boundary_remove(loc, boundary);
 221
 222         location_position_free(rb);
 223         location_position_free(lt);
 224
 225 }
 226  * @endcode
 227  */
 228 int location_boundary_remove(const LocationObject *obj, const LocationBoundary *boundary);
 229
 230 /**
 231  * @brief
 232  * Call a function for each element of a Boundary list.
 233  * @remarks None.
 234  * @pre
 235  * #location_init should be called before.\n
 236  * @post None.
 237  * @param [in]  obj - a #LocationObject
 238  * @param [in]  func - a #LocationBoundaryFunc
 239  * @param [in]  user_data - a #void
 240  * @return int
 241  * @retval 0                              Success
 242  *
 243  * Please refer #LocationError for more information.
 244  * @par Example
 245  * @code
 246 #include <location.h>
 247
 248 static void remove_boundary(LocationBoundary *boundary, void *user_data)
 249 {
 250         LocationBoundary *loc = (LocationBoundary *) user_data;
 251         if (loc == NULL || boundary == NULL) return;
 252
 253         location_boundary_remove(loc, boundary);
 254 }
 255
 256 void location_test_boundary_foreach(LocationObject *loc)
 257 {
 258         int ret = location_boundary_foreach(loc, remove_boundary, loc);
 259 }
 260  * @endcode
 261  */
 262 int location_boundary_foreach(const LocationObject *obj, LocationBoundaryFunc func, gpointer user_data);
 263
 264
 265 /**
 266  * @brief   Check if #LocationPosition is inside #LocationBoundary.
 267  * @remarks None.
 268  * @pre     #location_init should be called before.\n
 269  * @post    None.* @param [in]  boundary - a #LocationBoundary
 270  * @param [in]  position - a #LocationPosition
 271  * @return gboolean
 272  * @retval\n
 273  * TRUE - if inside\n
 274  * FALSE - if outside\n
 275  * @par Example
 276  * @code
 277 #include <location.h>
 278
 279 void location_test_boundary_if_inside(LocationObject *loc, LocationBoundary *boundary)
 280 {
 281         gboolean is_inside = FALSE;
 282         LocationPosition* position = location_position_new (0, 37.300, -121.86, 0, LOCATION_STATUS_2D_FIX);
 283         is_inside = location_boundary_if_inside(boundary, position);
 284         if (is_inside == TRUE) g_printf("The position is inside of the boundary\n");
 285         else g_printf("The position is outside of the boundary\n");
 286
 287 }
 288  * @endcode
 289
 290  */
 291 gboolean location_boundary_if_inside (LocationBoundary *boundary, LocationPosition *position);
 292
 293 /**
 294  * @}
 295  */
 296
 297 G_END_DECLS
 298
 299 #endif