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