include/location_bounds.h

   1 /*
   2 * Copyright (c) 2011 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 The location boundary handle.
  45  */
  46  typedef void *location_bounds_h;
  47
  48 /**
  49  * @brief Enumerations of error code for Location manager.
  50  */
  51 typedef enum
  52 {
  53     LOCATION_BOUNDS_ERROR_NONE = TIZEN_ERROR_NONE,                                        /**< Successful */
  54     LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,                    /**< Out of memory */
  55     LOCATION_BOUNDS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,            /**< Invalid parameter */
  56     LOCATION_BOUNDS_ERROR_INCORRECT_TYPE = LOCATION_BOUNDS_ERROR_CLASS | 0x01,         /**< Incorrect bounds type for a given call */
  57 } location_bound_error_e;
  58
  59
  60 /**
  61  * @brief Location boundary type.
  62  */
  63 typedef enum
  64 {
  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  * @brief Gets called iteratively to notify you of coordinates of polygon.
  72  * @param[in] coords   The coordinates
  73  * @param[in] user_data The user data passed from the foreach function
  74  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
  75  * @pre location_bounds_foreach_polygon_coords() will invoke this callback.
  76  * @see location_bounds_foreach_polygon_coords()
  77  */
  78 typedef bool (*polygon_coords_cb)(location_coords_s coords, void *user_data);
  79
  80
  81 /**
  82  * @brief Creates a rect type of new location bounds.
  83  * @remarks @a bounds must be released location_bounds_destroy() by you.
  84  * @param[in] top_left  The top left position
  85  * @param[in] bottom_right  The bottom right position
  86  * @param[out] bounds  A location bounds handle to be newly created on success
  87  * @return 0 on success, otherwise a negative error value.
  88  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
  89  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
  90  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
  91  * @see location_bounds_get_rect_coords()
  92  * @see location_bounds_destroy()
  93  */
  94 int location_bounds_create_rect(location_coords_s top_left, location_coords_s bottom_right, location_bounds_h* bounds);
  95
  96 /**
  97  * @brief Creates a circle type of new location bounds.
  98  * @remarks @a bounds must be released location_bounds_destroy() by you.
  99  * @param[in] center  The center  position
 100  * @param[in] radius  The radius of a circle (meters)
 101  * @param[out] bounds  A location bounds handle to be newly created on success
 102  * @return 0 on success, otherwise a negative error value.
 103  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 104  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 105  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 106  * @see location_bounds_get_circle_coords()
 107  * @see location_bounds_destroy()
 108  */
 109 int location_bounds_create_circle(location_coords_s center, double radius, location_bounds_h* bounds);
 110
 111 /**
 112  * @brief Creates a polygon type of new location bounds.
 113  * @remarks @a bounds must be released location_bounds_destroy() by you.
 114  * @remarks @a length sholud be over than 3 to represent polygon.
 115  * @param[in] coords_list  The list of coordinates
 116  * @param[in] length  The length of the coordinates list
 117  * @param[out] bounds  A location bounds handle to be newly created on success
 118  * @return 0 on success, otherwise a negative error value.
 119  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 120  * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
 121  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 122  * @see location_bounds_foreach_polygon_coords()
 123  * @see location_bounds_destroy()
 124  */
 125 int location_bounds_create_polygon(location_coords_s* coords_list, int length, location_bounds_h* bounds);
 126
 127 /**
 128  * @brief Check if the bounds contains the specified coordinates.
 129  * @param[in]   bounds  The location bounds handle
 130  * @param[in]   coords   The coordinates
 131  * @param[out]   contained  The result indicating whether the boundary contains the specified coordinate (@c true = contained, @c false = not contained )
 132  * @return @c true if the bouns contains the specified coordinates. \n else @c false
 133  * @see location_bounds_create_rect()
 134  * @see location_bounds_create_circle()
 135  * @see location_bounds_create_polygon()
 136  */
 137 bool location_bounds_is_contains_coordinates(location_bounds_h bounds, location_coords_s coords);
 138
 139 /**
 140  * @brief Get the type of location bounds.
 141  * @param[in] bounds  The location bounds handle
 142  * @param[out] type The type of location bounds
 143  * @return 0 on success, otherwise a negative error value.
 144  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 145  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 146  * @see location_bounds_create_rect()
 147  * @see location_bounds_create_circle()
 148  * @see location_bounds_create_polygon()
 149  */
 150 int location_bounds_get_type(location_bounds_h bounds, location_bounds_type_e *type);
 151
 152 /**
 153  * @brief Get the center position and radius of circle bounds.
 154  * @param[in] bounds  The location bounds handle
 155  * @param[out] top_left  The top left position
 156  * @param[out] bottom_right  The bottom right position
 157  * @return 0 on success, otherwise a negative error value.
 158  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 159  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 160  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 161  * @see location_bounds_create_rect()
 162  */
 163 int location_bounds_get_rect_coords(location_bounds_h bounds, location_coords_s  *top_left, location_coords_s  *bottom_right);
 164
 165 /**
 166  * @brief Get the center position and radius of circle bounds.
 167  * @param[in] bounds  The location bounds handle
 168  * @param[out] center The center position of circle
 169  * @param[radius] center The radius of circle
 170  * @return 0 on success, otherwise a negative error value.
 171  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 172  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 173  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 174  * @see location_bounds_create_circle()
 175  */
 176 int location_bounds_get_circle_coords(location_bounds_h bounds, location_coords_s  *center, double *radius);
 177
 178 /**
 179  * @brief Get the coordinates of polygon.
 180  * @param[in] bounds  The location bounds handle
 181  * @param[in] callback  The geocoder get positions callback function
 182  * @param[in] user_data The user data to be passed to the callback function
 183  * @return 0 on success, otherwise a negative error value.
 184  * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
 185  * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER     Invalid parameter
 186  * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
 187  * @post It invokes polygon_coords_cb() to get coordinates of polygon.
 188  * @see polygon_coords_cb()
 189  * @see location_bounds_create_polygon()
 190  */
 191 int location_bounds_foreach_polygon_coords(location_bounds_h bounds, polygon_coords_cb callback, void *user_data);
 192
 193 /**
 194  * @brief Releases the location bounds.
 195  * @param[in] bounds The location bounds handle
 196  * @return 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  * @see location_bounds_create_rect()
 200  * @see location_bounds_create_circle()
 201  * @see location_bounds_create_polygon()
 202 */
 203 int location_bounds_destroy(location_bounds_h bounds);
 204
 205 /**
 206  * @}
 207  */
 208 #ifdef __cplusplus
 209 }
 210 #endif
 211
 212 #endif /* __TIZEN_LOCATION_BOUNDS_H__ */
 213