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  */
  49 typedef enum {
  50         LOCATION_BOUNDS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  51         LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  52         LOCATION_BOUNDS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  53         LOCATION_BOUNDS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
  54         LOCATION_BOUNDS_ERROR_INCORRECT_TYPE = LOCATION_BOUNDS_ERROR_CLASS | 0x01, /**< Incorrect bounds type for a given call */
  55         LOCATION_BOUNDS_ERROR_IS_ADDED = LOCATION_BOUNDS_ERROR_CLASS | 0x02, /**< Cannot remove bounds handle from location manager */
  56 } location_bound_error_e;
  57
  58
  59 /**
  60  * @brief Enumeration for Location boundary type.
  61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  62  */
  63 typedef enum {
  64         LOCATION_BOUNDS_RECT = 1, /**< Rectangular geographical area type. */
  65         LOCATION_BOUNDS_CIRCLE, /**< Circle geographical area type.. */
  66         LOCATION_BOUNDS_POLYGON, /**< Polygon geographical area type.. */
  67 } location_bounds_type_e;
  68
  69
  70 /**
  71  * @brief Enumeration for the boundary state.
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73  */
  74 typedef enum {
  75         LOCATIONS_BOUNDARY_IN, /**< Boundary In (Zone In) */
  76         LOCATIONS_BOUNDARY_OUT /**< Boundary Out (Zone Out) */
  77 } location_boundary_state_e;
  78
  79
  80 /**
  81  * @brief The location boundary handle.
  82  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  83  */
  84 typedef struct location_bounds_s *location_bounds_h;
  85
  86
  87 /**
  88  * @brief Gets called iteratively to notify you of coordinates of a polygon.
  89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  90  * @param[in] coords The coordinates
  91  * @param[in] user_data The user data passed from the foreach function
  92  * @return @c true to continue with the next iteration of the loop, \n
  93  *         @c false to break out of the loop
  94  * @pre location_bounds_foreach_polygon_coords() will invoke this callback.
  95  * @see location_bounds_foreach_polygon_coords()
  96  */
  97 typedef bool (*polygon_coords_cb)(location_coords_s coords, void *user_data);
  98
  99
 100 /**
 101  * @brief Called when the given boundary is entered or exited.
 102  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 103  * @param[in] state The boundary state
 104  * @pre location_manager_start() will invoke this callback if you register this callback using location_bounds_set_state_changed_cb().
 105  * @see #location_boundary_state_e
 106  * @see location_manager_start()
 107  * @see location_bounds_set_state_changed_cb()
 108  */
 109 typedef void (*location_bounds_state_changed_cb)(location_boundary_state_e state, void *user_data);
 110
 111
 112 /**
 113  * @brief Creates a rect type of new location bounds.
 114  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 115  * @remarks You must release @a bounds using location_bounds_destroy().
 116  * @param[in] top_left The top left position
 117  * @param[in] bottom_right The bottom right position
 118  * @param[out] bounds The location bounds handle that is newly created
 119  * @return @c 0 on success,
 120  *         otherwise a negative error value
 121  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 122  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 123  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 124  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 125  * @see location_bounds_get_rect_coords()
 126  * @see location_bounds_destroy()
 127  */
 128 int location_bounds_create_rect(location_coords_s top_left, location_coords_s bottom_right, location_bounds_h *bounds);
 129
 130
 131 /**
 132  * @brief Creates a circle type of new location bounds.
 133  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 134  * @remarks You must release @a bounds using location_bounds_destroy().
 135  * @param[in] center The center position
 136  * @param[in] radius The radius of a circle (meters)
 137  * @param[out] bounds The location bounds handle that is newly created
 138  * @return @c 0 on success,
 139  *         otherwise a negative error value
 140  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 141  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 142  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 143  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 144  * @see location_bounds_get_circle_coords()
 145  * @see location_bounds_destroy()
 146  */
 147 int location_bounds_create_circle(location_coords_s center, double radius, location_bounds_h *bounds);
 148
 149
 150 /**
 151  * @brief Creates a polygon type of new location bounds.
 152  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 153  * @remarks You must release @a bounds using location_bounds_destroy().
 154  * @remarks @a length should be more than @c 3 to represent polygon.
 155  * @param[in] coords_list The list of coordinates
 156  * @param[in] length The length of the coordinates list
 157  * @param[out] bounds The location bounds handle that is newly created on success
 158  * @return @c 0 on success,
 159  *         otherwise a negative error value
 160  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 161  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 162  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 163  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 164  * @see location_bounds_foreach_polygon_coords()
 165  * @see location_bounds_destroy()
 166  */
 167 int location_bounds_create_polygon(location_coords_s *coords_list, int length, location_bounds_h *bounds);
 168
 169
 170 /**
 171  * @brief Checks whether the bounds contains the specified coordinates.
 172  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 173  * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 174  * @param[in] bounds The location bounds handle
 175  * @param[in] coords The coordinates
 176  * @return @c true if the bounds contains the specified coordinates,
 177  *         otherwise else @c false
 178  * @exception #LOCATION_BOUNDS_ERROR_NONE Successful
 179  * @exception #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 180  * @exception #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
 181  * @exception #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 182  * @see location_bounds_create_rect()
 183  * @see location_bounds_create_circle()
 184  * @see location_bounds_create_polygon()
 185  */
 186 bool location_bounds_contains_coordinates(location_bounds_h bounds, location_coords_s coords);
 187
 188
 189 /**
 190  * @brief Gets the type of location bounds.
 191  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 192  * @param[in] bounds The location bounds handle
 193  * @param[out] type The type of location bounds
 194  * @return @c 0 on success,
 195  *         otherwise a negative error value
 196  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 197  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 198  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 199  * @see location_bounds_create_rect()
 200  * @see location_bounds_create_circle()
 201  * @see location_bounds_create_polygon()
 202  */
 203 int location_bounds_get_type(location_bounds_h bounds, location_bounds_type_e *type);
 204
 205
 206 /**
 207  * @brief Gets the center position and radius of circle bounds.
 208  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 209  * @param[in] bounds The location bounds handle
 210  * @param[out] top_left The top left position
 211  * @param[out] bottom_right The bottom right position
 212  * @return @c 0 on success,
 213  *         otherwise a negative error value
 214  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 215  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 216  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 217  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 218  * @see location_bounds_create_rect()
 219  */
 220 int location_bounds_get_rect_coords(location_bounds_h bounds, location_coords_s *top_left, location_coords_s *bottom_right);
 221
 222
 223 /**
 224  * @brief Gets the center position and radius of circle bounds.
 225  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 226  * @param[in] bounds The location bounds handle
 227  * @param[out] center The center position of the circle
 228  * @param[out] radius The radius of the circle
 229  * @return @c 0 on success,
 230  *         otherwise a negative error value
 231  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 232  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 233  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 234  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 235  * @see location_bounds_create_circle()
 236  */
 237 int location_bounds_get_circle_coords(location_bounds_h bounds, location_coords_s *center, double *radius);
 238
 239
 240 /**
 241  * @brief Get the coordinates of a polygon.
 242  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 243  * @param[in] bounds The location bounds handle
 244  * @param[in] callback The iteration callback
 245  * @param[in] user_data The user data to be passed to the callback function
 246  * @return @c 0 on success,
 247  *         otherwise a negative error value
 248  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 249  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 250  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 251  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 252  * @post It invokes polygon_coords_cb() to get coordinates of polygon.
 253  * @see polygon_coords_cb()
 254  * @see location_bounds_create_polygon()
 255  */
 256 int location_bounds_foreach_polygon_coords(location_bounds_h bounds, polygon_coords_cb callback, void *user_data);
 257
 258
 259 /**
 260  * @brief Releases the location bounds.
 261  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 262  * @param[in] bounds The location bounds handle
 263  * @return @c 0 on success,
 264  *         otherwise a negative error value
 265  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 266  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 267  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 268  * @see location_bounds_create_rect()
 269  * @see location_bounds_create_circle()
 270  * @see location_bounds_create_polygon()
 271 */
 272 int location_bounds_destroy(location_bounds_h bounds);
 273
 274
 275 /**
 276  * @brief Registers a callback function to be invoked when the boundary area is entered or exited.
 277  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 278  * @param[in] bounds The location bounds handle
 279  * @param[in] callback The callback function to register
 280  * @param[in] user_data The user data to be passed to the callback function
 281  * @return @c 0 on success,
 282  *         otherwise a negative error value
 283  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 284  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 285  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 286  * @post location_bounds_state_changed_cb() will be invoked.
 287  * @see location_bounds_unset_state_changed_cb()
 288  * @see location_bounds_state_changed_cb()
 289  */
 290 int location_bounds_set_state_changed_cb(location_bounds_h bounds, location_bounds_state_changed_cb callback, void *user_data);
 291
 292
 293 /**
 294  * @brief Unregisters the callback function.
 295  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 296  * @param[in] bounds The location bounds handle
 297  * @return @c 0 on success,
 298  *         otherwise a negative error value
 299  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 300  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 301  * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
 302  * @see location_bounds_set_state_changed_cb()
 303  */
 304 int location_bounds_unset_state_changed_cb(location_bounds_h bounds);
 305
 306
 307 /**
 308  * @}
 309  */
 310 #ifdef __cplusplus
 311 }
 312 #endif
 313
 314 #endif /* __TIZEN_LOCATION_BOUNDS_H__ */
 315