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  * @param[in] bounds The location bounds handle
 193  * @param[in] coords The coordinates
 194  * @param[in] tolerance tolerance in metres
 195  * @return @c true if the edges of the bounds contain the specified coordinates within tolerance,
 196  *         otherwise else @c false
 197  * @exception #LOCATION_BOUNDS_ERROR_NONE Successful
 198  * @exception #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 199  * @exception #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
 200  * @exception #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 201  * @see location_bounds_create_rect()
 202  * @see location_bounds_create_circle()
 203  * @see location_bounds_create_polygon()
 204  */
 205 bool location_bounds_contains_coordinates_on_edge(location_bounds_h bounds, location_coords_s coords, double tolerance);
 206
 207
 208 /**
 209  * @brief Gets the type of location bounds.
 210  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 211  * @param[in] bounds The location bounds handle
 212  * @param[out] type The type of location bounds
 213  * @return @c 0 on success,
 214  *         otherwise a negative error value
 215  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 216  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 217  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 218  * @see location_bounds_create_rect()
 219  * @see location_bounds_create_circle()
 220  * @see location_bounds_create_polygon()
 221  */
 222 int location_bounds_get_type(location_bounds_h bounds, location_bounds_type_e *type);
 223
 224
 225 /**
 226  * @brief Gets the center position and radius of circle bounds.
 227  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 228  * @param[in] bounds The location bounds handle
 229  * @param[out] top_left The top left position
 230  * @param[out] bottom_right The bottom right position
 231  * @return @c 0 on success,
 232  *         otherwise a negative error value
 233  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 234  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 235  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 236  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 237  * @see location_bounds_create_rect()
 238  */
 239 int location_bounds_get_rect_coords(location_bounds_h bounds, location_coords_s *top_left, location_coords_s *bottom_right);
 240
 241
 242 /**
 243  * @brief Gets the center position and radius of circle bounds.
 244  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 245  * @param[in] bounds The location bounds handle
 246  * @param[out] center The center position of the circle
 247  * @param[out] radius The radius of the circle
 248  * @return @c 0 on success,
 249  *         otherwise a negative error value
 250  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 251  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 252  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 253  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 254  * @see location_bounds_create_circle()
 255  */
 256 int location_bounds_get_circle_coords(location_bounds_h bounds, location_coords_s *center, double *radius);
 257
 258
 259 /**
 260  * @brief Get the coordinates of a polygon.
 261  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 262  * @param[in] bounds The location bounds handle
 263  * @param[in] callback The iteration callback
 264  * @param[in] user_data The user data to be passed to the callback function
 265  * @return @c 0 on success,
 266  *         otherwise a negative error value
 267  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 268  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 269  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 270  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 271  * @post It invokes polygon_coords_cb() to get coordinates of polygon.
 272  * @see polygon_coords_cb()
 273  * @see location_bounds_create_polygon()
 274  */
 275 int location_bounds_foreach_polygon_coords(location_bounds_h bounds, polygon_coords_cb callback, void *user_data);
 276
 277
 278 /**
 279  * @brief Releases the location bounds.
 280  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 281  * @param[in] bounds The location bounds handle
 282  * @return @c 0 on success,
 283  *         otherwise a negative error value
 284  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 285  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 286  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 287  * @see location_bounds_create_rect()
 288  * @see location_bounds_create_circle()
 289  * @see location_bounds_create_polygon()
 290 */
 291 int location_bounds_destroy(location_bounds_h bounds);
 292
 293
 294 /**
 295  * @brief Registers a callback function to be invoked when the boundary area is entered or exited.
 296  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 297  * @param[in] bounds The location bounds handle
 298  * @param[in] callback The callback function to register
 299  * @param[in] user_data The user data to be passed to the callback function
 300  * @return @c 0 on success,
 301  *         otherwise a negative error value
 302  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 303  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 304  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 305  * @post location_bounds_state_changed_cb() will be invoked.
 306  * @see location_bounds_unset_state_changed_cb()
 307  * @see location_bounds_state_changed_cb()
 308  */
 309 int location_bounds_set_state_changed_cb(location_bounds_h bounds, location_bounds_state_changed_cb callback, void *user_data);
 310
 311
 312 /**
 313  * @brief Unregisters the callback function.
 314  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 315  * @param[in] bounds The location bounds handle
 316  * @return @c 0 on success,
 317  *         otherwise a negative error value
 318  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 319  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 320  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 321  * @see location_bounds_set_state_changed_cb()
 322  */
 323 int location_bounds_unset_state_changed_cb(location_bounds_h bounds);
 324
 325
 326 /**
 327  * @}
 328  */
 329 #ifdef __cplusplus
 330 }
 331 #endif
 332
 333 #endif /* __TIZEN_LOCATION_BOUNDS_H__ */
 334