include/location_bounds.h

   1 /*
   2  * Copyright (c) 2011-2013 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_LOCATION_BOUNDS_H__
  18 #define __TIZEN_LOCATION_BOUNDS_H__
  19
  20 #include <tizen_type.h>
  21 #include <tizen_error.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 #define LOCATION_BOUNDS_ERROR_CLASS TIZEN_ERROR_LOCATION_MANAGER | 0x20
  28
  29
  30 /**
  31  * @addtogroup CAPI_LOCATION_BOUNDS_MODULE
  32  * @{
  33  */
  34
  35
  36 /**
  37  * @brief The structure type to represent coordinates with latitude and longitude.
  38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  39  */
  40 typedef struct {
  41         double latitude; /**< The latitude [-90.0 ~ 90.0] (degrees) */
  42         double longitude; /**< The longitude [-180.0 ~ 180.0] (degrees) */
  43 } location_coords_s;
  44
  45
  46 /**
  47  * @brief Enumeration for error code for Location manager.
  48  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  49  */
  50 typedef enum {
  51         LOCATION_BOUNDS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  52         LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  53         LOCATION_BOUNDS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  54         LOCATION_BOUNDS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
  55         LOCATION_BOUNDS_ERROR_INCORRECT_TYPE = LOCATION_BOUNDS_ERROR_CLASS | 0x01, /**< Incorrect bounds type for a given call */
  56         LOCATION_BOUNDS_ERROR_IS_ADDED = LOCATION_BOUNDS_ERROR_CLASS | 0x02, /**< Cannot remove bounds handle from location manager */
  57 } location_bound_error_e;
  58
  59
  60 /**
  61  * @brief Enumeration for Location boundary type.
  62  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  63  */
  64 typedef enum {
  65         LOCATION_BOUNDS_RECT = 1, /**< Rectangular geographical area type. */
  66         LOCATION_BOUNDS_CIRCLE, /**< Circle geographical area type.. */
  67         LOCATION_BOUNDS_POLYGON, /**< Polygon geographical area type.. */
  68 } location_bounds_type_e;
  69
  70
  71 /**
  72  * @brief Enumeration for the boundary state.
  73  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  74  */
  75 typedef enum {
  76         LOCATIONS_BOUNDARY_IN, /**< Boundary In (Zone In) */
  77         LOCATIONS_BOUNDARY_OUT /**< Boundary Out (Zone Out) */
  78 } location_boundary_state_e;
  79
  80
  81 /**
  82  * @brief The location boundary handle.
  83  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  84  */
  85 typedef struct location_bounds_s *location_bounds_h;
  86
  87
  88 /**
  89  * @brief Gets called iteratively to notify you of coordinates of a polygon.
  90  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  91  * @param[in] coords The coordinates
  92  * @param[in] user_data The user data passed from the foreach function
  93  * @return @c true to continue with the next iteration of the loop, \n
  94  *         @c false to break out of the loop
  95  * @pre location_bounds_foreach_polygon_coords() will invoke this callback.
  96  * @see location_bounds_foreach_polygon_coords()
  97  */
  98 typedef bool (*polygon_coords_cb)(location_coords_s coords, void *user_data);
  99
 100
 101 /**
 102  * @brief Called when the given boundary is entered or exited.
 103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 104  * @param[in] state The boundary state
 105  * @param[in] user_data The user data passed from the start function
 106  * @pre location_manager_start() will invoke this callback if you register this callback using location_bounds_set_state_changed_cb().
 107  * @see #location_boundary_state_e
 108  * @see location_manager_start()
 109  * @see location_bounds_set_state_changed_cb()
 110  */
 111 typedef void (*location_bounds_state_changed_cb)(location_boundary_state_e state, void *user_data);
 112
 113
 114 /**
 115  * @brief Creates a rect type of new location bounds.
 116  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 117  * @remarks You must release @a bounds using location_bounds_destroy().
 118  * @param[in] top_left The top left position
 119  * @param[in] bottom_right The bottom right position
 120  * @param[out] bounds The location bounds handle that is newly created
 121  * @return @c 0 on success,
 122  *         otherwise a negative error value
 123  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 124  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 125  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 126  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 127  * @see location_bounds_get_rect_coords()
 128  * @see location_bounds_destroy()
 129  */
 130 int location_bounds_create_rect(location_coords_s top_left, location_coords_s bottom_right, location_bounds_h *bounds);
 131
 132
 133 /**
 134  * @brief Creates a circle type of new location bounds.
 135  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 136  * @remarks You must release @a bounds using location_bounds_destroy().
 137  * @param[in] center The center position
 138  * @param[in] radius The radius of a circle (meters)
 139  * @param[out] bounds The location bounds handle that is newly created
 140  * @return @c 0 on success,
 141  *         otherwise a negative error value
 142  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 143  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 144  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 145  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 146  * @see location_bounds_get_circle_coords()
 147  * @see location_bounds_destroy()
 148  */
 149 int location_bounds_create_circle(location_coords_s center, double radius, location_bounds_h *bounds);
 150
 151
 152 /**
 153  * @brief Creates a polygon type of new location bounds.
 154  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 155  * @remarks You must release @a bounds using location_bounds_destroy().
 156  * @remarks @a length should be more than @c 3 to represent polygon.
 157  * @param[in] coords_list The list of coordinates
 158  * @param[in] length The length of the coordinates list
 159  * @param[out] bounds The location bounds handle that is newly created on success
 160  * @return @c 0 on success,
 161  *         otherwise a negative error value
 162  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 163  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 164  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 165  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 166  * @see location_bounds_foreach_polygon_coords()
 167  * @see location_bounds_destroy()
 168  */
 169 int location_bounds_create_polygon(location_coords_s *coords_list, int length, location_bounds_h *bounds);
 170
 171
 172 /**
 173  * @brief Checks whether the bounds contains the specified coordinates.
 174  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 175  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 176  * @param[in] bounds The location bounds handle
 177  * @param[in] coords The coordinates
 178  * @return @c true if the bounds contains the specified coordinates,
 179  *         otherwise else @c false
 180  * @exception #LOCATION_BOUNDS_ERROR_NONE Successful
 181  * @exception #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 182  * @exception #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
 183  * @exception #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 184  * @see location_bounds_create_rect()
 185  * @see location_bounds_create_circle()
 186  * @see location_bounds_create_polygon()
 187  */
 188 bool location_bounds_contains_coordinates(location_bounds_h bounds, location_coords_s coords);
 189
 190 /**
 191  * @brief Checks whether the edges of the bounds contain the specified coordinates within tolerance.
 192  * @since_tizen 6.0
 193  * @param[in] bounds The location bounds handle
 194  * @param[in] coords The coordinates
 195  * @param[in] tolerance tolerance in metres
 196  * @return @c true if the distance between edges of @a bounds and point at @a coords are not farther than @a tolerance
 197  *         otherwise @c false
 198  * @exception #LOCATION_BOUNDS_ERROR_NONE Successful
 199  * @exception #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 200  * @exception #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
 201  * @exception #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 202  * @see location_bounds_create_rect()
 203  * @see location_bounds_create_circle()
 204  * @see location_bounds_create_polygon()
 205  */
 206 bool location_bounds_contains_coordinates_on_edge(location_bounds_h bounds, location_coords_s coords, double tolerance);
 207
 208
 209 /**
 210  * @brief Gets the type of location bounds.
 211  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 212  * @param[in] bounds The location bounds handle
 213  * @param[out] type The type of location bounds
 214  * @return @c 0 on success,
 215  *         otherwise a negative error value
 216  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 217  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 218  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 219  * @see location_bounds_create_rect()
 220  * @see location_bounds_create_circle()
 221  * @see location_bounds_create_polygon()
 222  */
 223 int location_bounds_get_type(location_bounds_h bounds, location_bounds_type_e *type);
 224
 225
 226 /**
 227  * @brief Gets the center position and radius of circle bounds.
 228  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 229  * @param[in] bounds The location bounds handle
 230  * @param[out] top_left The top left position
 231  * @param[out] bottom_right The bottom right position
 232  * @return @c 0 on success,
 233  *         otherwise a negative error value
 234  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 235  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 236  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 237  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 238  * @see location_bounds_create_rect()
 239  */
 240 int location_bounds_get_rect_coords(location_bounds_h bounds, location_coords_s *top_left, location_coords_s *bottom_right);
 241
 242
 243 /**
 244  * @brief Gets the center position and radius of circle bounds.
 245  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 246  * @param[in] bounds The location bounds handle
 247  * @param[out] center The center position of the circle
 248  * @param[out] radius The radius of the circle
 249  * @return @c 0 on success,
 250  *         otherwise a negative error value
 251  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 252  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 253  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 254  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 255  * @see location_bounds_create_circle()
 256  */
 257 int location_bounds_get_circle_coords(location_bounds_h bounds, location_coords_s *center, double *radius);
 258
 259
 260 /**
 261  * @brief Get the coordinates of a polygon.
 262  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 263  * @param[in] bounds The location bounds handle
 264  * @param[in] callback The iteration callback
 265  * @param[in] user_data The user data to be passed to the callback function
 266  * @return @c 0 on success,
 267  *         otherwise a negative error value
 268  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 269  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 270  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 271  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 272  * @post It invokes polygon_coords_cb() to get coordinates of polygon.
 273  * @see polygon_coords_cb()
 274  * @see location_bounds_create_polygon()
 275  */
 276 int location_bounds_foreach_polygon_coords(location_bounds_h bounds, polygon_coords_cb callback, void *user_data);
 277
 278
 279 /**
 280  * @brief Releases the location bounds.
 281  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 282  * @param[in] bounds The location bounds handle
 283  * @return @c 0 on success,
 284  *         otherwise a negative error value
 285  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 286  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 287  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 288  * @see location_bounds_create_rect()
 289  * @see location_bounds_create_circle()
 290  * @see location_bounds_create_polygon()
 291 */
 292 int location_bounds_destroy(location_bounds_h bounds);
 293
 294
 295 /**
 296  * @brief Registers a callback function to be invoked when the boundary area is entered or exited.
 297  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 298  * @param[in] bounds The location bounds handle
 299  * @param[in] callback The callback function to register
 300  * @param[in] user_data The user data to be passed to the callback function
 301  * @return @c 0 on success,
 302  *         otherwise a negative error value
 303  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 304  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 305  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 306  * @post location_bounds_state_changed_cb() will be invoked.
 307  * @see location_bounds_unset_state_changed_cb()
 308  * @see location_bounds_state_changed_cb()
 309  */
 310 int location_bounds_set_state_changed_cb(location_bounds_h bounds, location_bounds_state_changed_cb callback, void *user_data);
 311
 312
 313 /**
 314  * @brief Unregisters the callback function.
 315  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 316  * @param[in] bounds The location bounds handle
 317  * @return @c 0 on success,
 318  *         otherwise a negative error value
 319  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 320  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 321  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 322  * @see location_bounds_set_state_changed_cb()
 323  */
 324 int location_bounds_unset_state_changed_cb(location_bounds_h bounds);
 325
 326
 327 /**
 328  * @}
 329  */
 330 #ifdef __cplusplus
 331 }
 332 #endif
 333
 334 #endif /* __TIZEN_LOCATION_BOUNDS_H__ */
 335