2 * Copyright (c) 2011-2013 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_MANAGER | 0x20
31 * @addtogroup CAPI_LOCATION_BOUNDS_MODULE
37 * @brief The structure type to represent coordinates with latitude and longitude.
38 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
41 double latitude; /**< The latitude [-90.0 ~ 90.0] (degrees) */
42 double longitude; /**< The longitude [-180.0 ~ 180.0] (degrees) */
47 * @brief Enumeration for error code for Location manager.
48 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
51 LOCATION_BOUNDS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
52 LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
53 LOCATION_BOUNDS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
54 LOCATION_BOUNDS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
55 LOCATION_BOUNDS_ERROR_INCORRECT_TYPE = LOCATION_BOUNDS_ERROR_CLASS | 0x01, /**< Incorrect bounds type for a given call */
56 LOCATION_BOUNDS_ERROR_IS_ADDED = LOCATION_BOUNDS_ERROR_CLASS | 0x02, /**< Cannot remove bounds handle from location manager */
57 } location_bound_error_e;
61 * @brief Enumeration for Location boundary type.
62 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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;
72 * @brief Enumeration for the boundary state.
73 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
76 LOCATIONS_BOUNDARY_IN, /**< Boundary In (Zone In) */
77 LOCATIONS_BOUNDARY_OUT /**< Boundary Out (Zone Out) */
78 } location_boundary_state_e;
82 * @brief The location boundary handle.
83 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
85 typedef struct location_bounds_s *location_bounds_h;
89 * @brief Gets called iteratively to notify you of coordinates of a polygon.
90 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
91 * @param[in] coords The coordinates
92 * @param[in] user_data The user data passed from the foreach function
93 * @return @c true to continue with the next iteration of the loop, \n
94 * @c false to break out of the loop
95 * @pre location_bounds_foreach_polygon_coords() will invoke this callback.
96 * @see location_bounds_foreach_polygon_coords()
98 typedef bool (*polygon_coords_cb)(location_coords_s coords, void *user_data);
102 * @brief Called when the given boundary is entered or exited.
103 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
104 * @param[in] state The boundary state
105 * @param[in] user_data The user data passed from the start function
106 * @pre location_manager_start() will invoke this callback if you register this callback using location_bounds_set_state_changed_cb().
107 * @see #location_boundary_state_e
108 * @see location_manager_start()
109 * @see location_bounds_set_state_changed_cb()
111 typedef void (*location_bounds_state_changed_cb)(location_boundary_state_e state, void *user_data);
115 * @brief Creates a rect type of new location bounds.
116 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
117 * @remarks You must release @a bounds using location_bounds_destroy().
118 * @param[in] top_left The top left position
119 * @param[in] bottom_right The bottom right position
120 * @param[out] bounds The location bounds handle that is newly created
121 * @return @c 0 on success,
122 * otherwise a negative error value
123 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
124 * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
125 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
126 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
127 * @see location_bounds_get_rect_coords()
128 * @see location_bounds_destroy()
130 int location_bounds_create_rect(location_coords_s top_left, location_coords_s bottom_right, location_bounds_h *bounds);
134 * @brief Creates a circle type of new location bounds.
135 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
136 * @remarks You must release @a bounds using location_bounds_destroy().
137 * @param[in] center The center position
138 * @param[in] radius The radius of a circle (meters)
139 * @param[out] bounds The location bounds handle that is newly created
140 * @return @c 0 on success,
141 * otherwise a negative error value
142 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
143 * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
144 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
145 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
146 * @see location_bounds_get_circle_coords()
147 * @see location_bounds_destroy()
149 int location_bounds_create_circle(location_coords_s center, double radius, location_bounds_h *bounds);
153 * @brief Creates a polygon type of new location bounds.
154 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
155 * @remarks You must release @a bounds using location_bounds_destroy().
156 * @remarks @a length should be more than @c 3 to represent polygon.
157 * @param[in] coords_list The list of coordinates
158 * @param[in] length The length of the coordinates list
159 * @param[out] bounds The location bounds handle that is newly created on success
160 * @return @c 0 on success,
161 * otherwise a negative error value
162 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
163 * @retval #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
164 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
165 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
166 * @see location_bounds_foreach_polygon_coords()
167 * @see location_bounds_destroy()
169 int location_bounds_create_polygon(location_coords_s *coords_list, int length, location_bounds_h *bounds);
173 * @brief Checks whether the bounds contains the specified coordinates.
174 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
175 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
176 * @param[in] bounds The location bounds handle
177 * @param[in] coords The coordinates
178 * @return @c true if the bounds contains the specified coordinates,
179 * otherwise else @c false
180 * @exception #LOCATION_BOUNDS_ERROR_NONE Successful
181 * @exception #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
182 * @exception #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
183 * @exception #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()
188 bool location_bounds_contains_coordinates(location_bounds_h bounds, location_coords_s coords);
191 * @brief Checks whether the edges of the bounds contain the specified coordinates within tolerance.
193 * @param[in] bounds The location bounds handle
194 * @param[in] coords The coordinates
195 * @param[in] tolerance tolerance in metres
196 * @return @c true if the distance between edges of @a bounds and point at @a coords are not farther than @a tolerance
198 * @exception #LOCATION_BOUNDS_ERROR_NONE Successful
199 * @exception #LOCATION_BOUNDS_ERROR_OUT_OF_MEMORY Out of memory
200 * @exception #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
201 * @exception #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
202 * @see location_bounds_create_rect()
203 * @see location_bounds_create_circle()
204 * @see location_bounds_create_polygon()
206 bool location_bounds_contains_coordinates_on_edge(location_bounds_h bounds, location_coords_s coords, double tolerance);
210 * @brief Gets the type of location bounds.
211 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
212 * @param[in] bounds The location bounds handle
213 * @param[out] type The type of location bounds
214 * @return @c 0 on success,
215 * otherwise a negative error value
216 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
217 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
218 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
219 * @see location_bounds_create_rect()
220 * @see location_bounds_create_circle()
221 * @see location_bounds_create_polygon()
223 int location_bounds_get_type(location_bounds_h bounds, location_bounds_type_e *type);
227 * @brief Gets the center position and radius of circle bounds.
228 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
229 * @param[in] bounds The location bounds handle
230 * @param[out] top_left The top left position
231 * @param[out] bottom_right The bottom right position
232 * @return @c 0 on success,
233 * otherwise a negative error value
234 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
235 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
236 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
237 * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
238 * @see location_bounds_create_rect()
240 int location_bounds_get_rect_coords(location_bounds_h bounds, location_coords_s *top_left, location_coords_s *bottom_right);
244 * @brief Gets the center position and radius of circle bounds.
245 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
246 * @param[in] bounds The location bounds handle
247 * @param[out] center The center position of the circle
248 * @param[out] radius The radius of the circle
249 * @return @c 0 on success,
250 * otherwise a negative error value
251 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
252 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
253 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
254 * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
255 * @see location_bounds_create_circle()
257 int location_bounds_get_circle_coords(location_bounds_h bounds, location_coords_s *center, double *radius);
261 * @brief Get the coordinates of a polygon.
262 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
263 * @param[in] bounds The location bounds handle
264 * @param[in] callback The iteration callback
265 * @param[in] user_data The user data to be passed to the callback function
266 * @return @c 0 on success,
267 * 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 * @retval #LOCATION_BOUNDS_ERROR_INCORRECT_TYPE Incorrect bounds type
272 * @post It invokes polygon_coords_cb() to get coordinates of polygon.
273 * @see polygon_coords_cb()
274 * @see location_bounds_create_polygon()
276 int location_bounds_foreach_polygon_coords(location_bounds_h bounds, polygon_coords_cb callback, void *user_data);
280 * @brief Releases the location bounds.
281 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
282 * @param[in] bounds The location bounds handle
283 * @return @c 0 on success,
284 * otherwise a negative error value
285 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
286 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
287 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
288 * @see location_bounds_create_rect()
289 * @see location_bounds_create_circle()
290 * @see location_bounds_create_polygon()
292 int location_bounds_destroy(location_bounds_h bounds);
296 * @brief Registers a callback function to be invoked when the boundary area is entered or exited.
297 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
298 * @param[in] bounds The location bounds handle
299 * @param[in] callback The callback function to register
300 * @param[in] user_data The user data to be passed to the callback function
301 * @return @c 0 on success,
302 * otherwise a negative error value
303 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
304 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
305 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
306 * @post location_bounds_state_changed_cb() will be invoked.
307 * @see location_bounds_unset_state_changed_cb()
308 * @see location_bounds_state_changed_cb()
310 int location_bounds_set_state_changed_cb(location_bounds_h bounds, location_bounds_state_changed_cb callback, void *user_data);
314 * @brief Unregisters the callback function.
315 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
316 * @param[in] bounds The location bounds handle
317 * @return @c 0 on success,
318 * otherwise a negative error value
319 * @retval #LOCATION_BOUNDS_ERROR_NONE Successful
320 * @retval #LOCATION_BOUNDS_ERROR_INVALID_PARAMETER Invalid parameter
321 * @retval #LOCATION_BOUNDS_ERROR_NOT_SUPPORTED Not supported
322 * @see location_bounds_set_state_changed_cb()
324 int location_bounds_unset_state_changed_cb(location_bounds_h bounds);
334 #endif /* __TIZEN_LOCATION_BOUNDS_H__ */