2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __TIZEN_LOCATION_BOUNDS_H__
18 #define __TIZEN_LOCATION_BOUNDS_H__
20 #include <tizen_type.h>
21 #include <tizen_error.h>
27 #define LOCATION_BOUNDS_ERROR_CLASS TIZEN_ERROR_LOCATION_CLASS | 0x20
30 * @addtogroup CAPI_LOCATION_BOUNDS_MODULE
35 * @brief Represents a coordinates with latitude and longitude.
39 double latitude; /**< The latitude [-90.0 ~ 90.0] (degrees) */
40 double longitude; /**< The longitude [-180.0 ~ 180.0] (degrees) */
44 * @brief The location boundary handle.
46 typedef void *location_bounds_h;
49 * @brief Enumerations of error code for Location manager.
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;
61 * @brief Location boundary type.
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;
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()
78 typedef bool (*polygon_coords_cb)(location_coords_s coords, void *user_data);
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()
94 int location_bounds_create_rect(location_coords_s top_left, location_coords_s bottom_right, location_bounds_h* bounds);
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()
109 int location_bounds_create_circle(location_coords_s center, double radius, location_bounds_h* bounds);
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()
125 int location_bounds_create_polygon(location_coords_s* coords_list, int length, location_bounds_h* bounds);
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()
137 bool location_bounds_is_contains_coordinates(location_bounds_h bounds, location_coords_s coords);
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()
150 int location_bounds_get_type(location_bounds_h bounds, location_bounds_type_e *type);
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()
163 int location_bounds_get_rect_coords(location_bounds_h bounds, location_coords_s *top_left, location_coords_s *bottom_right);
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()
176 int location_bounds_get_circle_coords(location_bounds_h bounds, location_coords_s *center, double *radius);
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()
191 int location_bounds_foreach_polygon_coords(location_bounds_h bounds, polygon_coords_cb callback, void *user_data);
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()
203 int location_bounds_destroy(location_bounds_h bounds);
212 #endif /* __TIZEN_LOCATION_BOUNDS_H__ */