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