location/manager/location-boundary.h

   1 /*
   2  * libslp-location
   3  *
   4  * Copyright (c) 2010-2013 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   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
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  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.
  17  */
  18
  19 #ifndef __LOCATION_BOUNDARY_H_
  20 #define __LOCATION_BOUNDARY_H_
  21
  22 #include <location-types.h>
  23 #include <location-position.h>
  24
  25 G_BEGIN_DECLS
  26
  27 GType location_boundary_get_type(void);
  28 #define LOCATION_TYPE_BOUNDARY (location_boundary_get_type())
  29
  30 /**
  31  * @file location-boundary.h
  32  * @brief This file contains the definitions, structures, and functions related to boundary information.
  33  */
  34 /**
  35  * @addtogroup LocationAPI
  36  * @{
  37  * @defgroup LocationAPIBoundary Location Boundary
  38  * @breif This provides APIs related to Location Boundary
  39  * @addtogroup LocationAPIBoundary
  40  * @{
  41  */
  42
  43 /**
  44  * @brief
  45  * The type of the @location_boundary_foreach function of #LocationObject
  46  */
  47 typedef void (*LocationBoundaryFunc)(LocationBoundary *boundary, gpointer user_data);
  48
  49 /**
  50  * @brief This represents used geographical type, and supports rectangle or circle area.
  51  */
  52 typedef enum {
  53         LOCATION_BOUNDARY_NONE = 0,             /*/< Undefined geographical area type. */
  54         LOCATION_BOUNDARY_RECT,                 /*/< Rectangular geographical area type. */
  55         LOCATION_BOUNDARY_CIRCLE,               /*/< Circle geographical area type. */
  56         LOCATION_BOUNDARY_POLYGON               /*/< Polygon geographical area type. */
  57 } LocationBoundaryType;
  58
  59 /**
  60  * @brief This represents a rectangular geographical area.
  61  */
  62 typedef struct {
  63         LocationPosition *left_top;             /*/< The left top position of rectangle. */
  64         LocationPosition *right_bottom; /*/< The right bottom position of rectangle. */
  65 } LocationRect;
  66
  67 /**
  68  * @brief This represents a circle geographical area with center geographic position and radius.
  69  */
  70 typedef struct {
  71         LocationPosition *center;               /*/< The center position of a circle. */
  72         gdouble radius;                                 /*/< The radius of a circle. */
  73 } LocationCircle;
  74
  75 /**
  76  * @brief This represents a polygon geographical area.
  77  */
  78 typedef struct {
  79         GList *position_list;                   /*/< The collection of positions */
  80 } LocationPolygon;
  81
  82 /**
  83  * @brief This represents boundary information such as rectangular or circle area.
  84  */
  85 struct _LocationBoundary {
  86         LocationBoundaryType type;              /*/< The boundary type of this information. */
  87         union {
  88                 LocationRect rect;                      /*/< The geographical information of a rectangle. */
  89                 LocationCircle circle;          /*/< The geographical information of a circle. */
  90                 LocationPolygon polygon;        /*/< The geographical information of a polygon. */
  91         };
  92 };
  93
  94 /**
  95  * @brief       Create a rectangular type of new #LocationBoundary with given information.
  96  * @remarks     None.
  97  * @pre         #location_init should be called before.\n
  98  * @post        None.
  99  * @param [in] left_top - left top position.
 100  * @param [in] right_bottom - right bottom position.
 101  * @return a new #LocationBoundary
 102  * @retval NULL if error occured
 103  */
 104 LocationBoundary *location_boundary_new_for_rect(LocationPosition *left_top, LocationPosition *right_bottom);
 105
 106 /**
 107  * @brief       Create a circle type of new #LocationBoundary with given information.
 108  * @remarks     None.
 109  * @pre         #location_init should be called before.\n
 110  * @post        None.
 111  * @param [in] center - center position.
 112  * @param [in] radius - radius.
 113  * @return a new #LocationBoundary
 114  * @retval NULL if error occured
 115  */
 116 LocationBoundary *location_boundary_new_for_circle(LocationPosition *center, gdouble radius);
 117
 118 /**
 119  * @brief       Create a polygon type of new #LocationBoundary with given information.
 120  * @remarks None.
 121  * @pre  #location_init should be called before.\n
 122  * @post         None.
 123  * @param [in] position_list - the list of positions.
 124  * @return a new #LocationBoundary
 125  * @retval NULL if error occured
 126  */
 127 LocationBoundary *location_boundary_new_for_polygon(GList *position_list);
 128
 129 /**
 130  * @brief       Free a #LocationBoundary.
 131  * @remarks None.
 132  * @pre  #location_init should be called before.\n
 133  * @post         None.
 134  * @param [in] boundary - a #LocationBoundary.
 135  * @return None.
 136  */
 137 void location_boundary_free(LocationBoundary *boundary);
 138
 139 /**
 140  * @brief       Makes a copy of #LocationBoundary
 141  * @remarks None.
 142  * @pre  #location_init should be called before.\n
 143  * @post         None.
 144  * @param [in] boundary - a #LocationBoundary
 145  * @return a new #LocationBoundary
 146  * @retval NULL if error occured
 147  */
 148 LocationBoundary *location_boundary_copy(const LocationBoundary *boundary);
 149
 150 /**
 151  * @brief Add Boundary on LocationFW. You should call this fuction when you want to receive a crossing signal(zone-in/zone-out) from #LocationBoundary.
 152  * @remarks It supports multi-boundaries. However a duplicated boundary would not be allowed.
 153  * @pre #location_new should be called before.\n
 154  * @post None.
 155  * @param [in] obj - a #LocationObject
 156  * @param [in] boundary - a #LocationBoundary
 157  * @return int
 158  * @retval 0 Success
 159  */
 160 int location_boundary_add(const LocationObject *obj, const LocationBoundary *boundary);
 161
 162 /**
 163  * @brief Remove Boundary on LocationFW.
 164  * You should call this function when you don't want to receive a crossing signal(zone-in/zone-out) from #LocationBoundary any more.
 165  * @remarks It supports multi-boundaries.
 166  * @pre #location_init should be called before.\n
 167  * @post None.
 168  * @param [in] obj - a #LocationObject
 169  * @param [in] boundary - a #LocationBoundary
 170  * @return int
 171  * @retval 0    Success
 172  */
 173 int location_boundary_remove(const LocationObject *obj, const LocationBoundary *boundary);
 174
 175 /**
 176  * @brief Call a function for each element of a Boundary list.
 177  * @remarks None.
 178  * @pre #location_init should be called before.\n
 179  * @post None.
 180  * @param [in] obj - a #LocationObject
 181  * @param [in] func - a #LocationBoundaryFunc
 182  * @param [in] user_data - a #void
 183  * @return int
 184  * @retval 0    Success
 185  */
 186 int location_boundary_foreach(const LocationObject *obj, LocationBoundaryFunc func, gpointer user_data);
 187
 188
 189 /**
 190  * @brief       Check if #LocationPosition is inside #LocationBoundary.
 191  * @remarks None.
 192  * @pre  #location_init should be called before.\n
 193  * @post         None.* @param [in] boundary - a #LocationBoundary
 194  * @param [in] position - a #LocationPosition
 195  * @return gboolean
 196  * @retval\n TRUE - if inside\n FALSE - if outside\n
 197  */
 198 gboolean location_boundary_if_inside(LocationBoundary *boundary, LocationPosition *position);
 199
 200 /**
 201  * @brief Get bounding box of #LocationBoundary
 202  */
 203 LocationBoundary *location_boundary_get_bounding_box(LocationBoundary *boundary);
 204
 205
 206 /**
 207  * @brief Get the center position of #LocationBoundary
 208  */
 209 LocationPosition *location_boundary_get_center_position(LocationBoundary *boundary);
 210
 211 /**
 212  * @} @}
 213  */
 214
 215 G_END_DECLS
 216
 217 #endif