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