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_LOCATIONS_H__
18 #define __TIZEN_LOCATION_LOCATIONS_H__
21 #include <tizen_type.h>
22 #include <tizen_error.h>
24 #include <location_bounds.h>
31 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
36 * @brief Enumeration for error code for Location manager.
37 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
40 LOCATIONS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
41 LOCATIONS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
42 LOCATIONS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
43 LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
44 LOCATIONS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
45 LOCATIONS_ERROR_INCORRECT_METHOD = TIZEN_ERROR_LOCATION_MANAGER | 0x01, /**< Location manager contains incorrect method for a given call */
46 LOCATIONS_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_MANAGER | 0x02, /**< Network unavailable */
47 LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_MANAGER | 0x03, /**< Location service is not available */
48 LOCATIONS_ERROR_GPS_SETTING_OFF = TIZEN_ERROR_LOCATION_MANAGER | 0x04, /**< Setting for GPS, WPS, or MOCK is turned off */
49 LOCATIONS_ERROR_SECURITY_RESTRICTED = TIZEN_ERROR_LOCATION_MANAGER | 0x05, /**< Restricted by security system policy */
50 LOCATIONS_ERROR_SETTING_OFF = LOCATIONS_ERROR_GPS_SETTING_OFF, /**< Setting for GPS, WPS, or MOCK is turned off (Since 3.0) */
55 * @brief Enumeration for Location method type.
56 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
59 LOCATIONS_METHOD_NONE = -1, /**< Undefined method */
60 LOCATIONS_METHOD_HYBRID, /**< This method selects the best method available at the moment */
61 LOCATIONS_METHOD_GPS, /**< This method uses Global Positioning System */
62 LOCATIONS_METHOD_WPS, /**< This method uses WiFi Positioning System */
66 * @brief Enumeration for Approximate accuracy level of given information.
67 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
70 LOCATIONS_ACCURACY_NONE = 0, /**< Invalid data */
71 LOCATIONS_ACCURACY_COUNTRY, /**< Country accuracy level */
72 LOCATIONS_ACCURACY_REGION, /**< Regional accuracy level */
73 LOCATIONS_ACCURACY_LOCALITY, /**< Local accuracy level */
74 LOCATIONS_ACCURACY_POSTALCODE, /**< Postal accuracy level */
75 LOCATIONS_ACCURACY_STREET, /**< Street accuracy level */
76 LOCATIONS_ACCURACY_DETAILED, /**< Detailed accuracy level */
77 } location_accuracy_level_e;
80 * @brief Enumeration for the state of the location service.
81 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
84 LOCATIONS_SERVICE_DISABLED, /**< Service is disabled */
85 LOCATIONS_SERVICE_ENABLED, /**< Service is enabled */
86 } location_service_state_e;
89 * @deprecated Deprecated since 3.0
90 * @brief Enumeration for the location service accessibility state.
91 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
94 LOCATIONS_ACCESS_STATE_NONE, /**< Access state is not determined */
95 LOCATIONS_ACCESS_STATE_DENIED, /**< Access denied */
96 LOCATIONS_ACCESS_STATE_ALLOWED, /**< Access authorized */
97 } location_accessibility_state_e;
100 * @brief The location manager handle.
101 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
103 typedef struct location_manager_s *location_manager_h;
112 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
116 * @brief Called at defined interval with updated position information.
117 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
118 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
119 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
120 * @param[in] altitude The updated altitude (meters)
121 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
122 * @param[in] user_data The user data passed from the call registration function
123 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
124 * @see location_manager_start()
125 * @see location_manager_set_position_updated_cb()
127 typedef void(*location_position_updated_cb)(double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
130 * @brief Called at defined interval with updated velocity information.
131 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
132 * @param[in] speed The updated speed (km/h)
133 * @param[in] direction The updated direction (in degrees from the north)
134 * @param[in] climb The updated climb (km/h)
135 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
136 * @param[in] user_data The user data passed from the callback registration function
137 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb().
138 * @see location_manager_start()
139 * @see location_manager_set_velocity_updated_cb()
141 typedef void(*location_velocity_updated_cb)(double speed, double direction, double climb, time_t timestamp, void *user_data);
144 * @brief Called at defined interval with updated location information.
145 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
146 * @param[in] error #LOCATIONS_ERROR_NONE Successful
147 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
148 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
149 * @param[in] altitude The updated altitude (meters)
150 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
151 * @param[in] speed The updated speed (km/h)
152 * @param[in] direction The updated direction (in degrees from the north)
153 * @param[in] climb The updated climb (km/h)
154 * @param[in] user_data The user data passed from the callback registration function
155 * @pre location_manager_request_single_location() will invoke this callback.
156 * @see location_manager_request_single_location()
158 typedef void(*location_updated_cb)(location_error_e error, double latitude, double longitude, double altitude, time_t timestamp, double speed, double direction, double climb, void *user_data);
161 * @brief Called when the state of location service is changed from enabled to disabled or vice versa.
162 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
163 * @param[in] state The service state
164 * @param[in] user_data The user data passed from the callback registration function
165 * @pre Either location_manager_start() or location_manager_stop() will invoke this callback if you register this callback using location_manager_set_service_state_changed_cb()
166 * @see location_manager_start()
167 * @see location_manager_stop()
168 * @see location_manager_set_service_state_changed_cb()
169 * @see #location_service_state_e
171 typedef void(*location_service_state_changed_cb)(location_service_state_e state, void *user_data);
174 * @brief Called when the user defined zones are entered or exited.
175 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
176 * @param[in] state The boundary state
177 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
178 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
179 * @param[in] altitude The updated altitude (meters)
180 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
181 * @param[in] user_data The user data passed from the callback registration function
182 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb().
183 * @see #location_boundary_state_e
184 * @see location_manager_start()
185 * @see location_manager_set_zone_changed_cb()
187 typedef void(*location_zone_changed_cb)(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
190 * @brief Called when the state of location method is changed.
191 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
192 * @param[in] method The method changed on setting
193 * @param[in] enable The setting value changed
194 * @param[in] user_data The user data passed from the callback registration function
195 * @pre location_setting_changed_cb() will invoke this callback if you register this callback using location_manager_set_setting_changed_cb()
196 * @see location_manager_set_setting_changed_cb()
197 * @see location_manager_unset_setting_changed_cb()
199 typedef void(*location_setting_changed_cb)(location_method_e method, bool enable, void *user_data);
202 * @brief Called once for each location bound.
203 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
204 * @param[in] bounds The location bounds handle
205 * @param[in] user_data The user data passed from the callback registration function
206 * @return @c true to continue with the next iteration of the loop, otherwise @c false to break out of the loop.
207 * @pre location_manager_foreach_boundary() will invoke this callback.
208 * @see location_manager_foreach_boundary()
210 typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
213 * @brief Called at defined interval with updated location information.
214 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
215 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
216 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
217 * @param[in] altitude The updated altitude (meters)
218 * @param[in] speed The updated speed (km/h)
219 * @param[in] direction The updated direction (in degrees from the north)
220 * @param[in] horizontal_accuracy The horizontal accuracy (meters)
221 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
222 * @param[in] user_data The user data passed from the callback registration function
223 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
224 * @see location_manager_start()
225 * @see location_manager_set_distance_based_location_changed_cb()
226 * @see location_manager_set_location_changed_cb()
228 typedef void(*location_changed_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data);
231 * @brief Called when the batch interval is expired.
232 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
233 * @param[in] num_of_location The number of location batch data
234 * @param[in] user_data The user data passed from the callback registration function
235 * @pre location_manager_start_batch() will invoke this callback if you register this callback using location_manager_set_location_batch_cb()
236 * @see location_manager_start_batch()
237 * @see location_manager_set_location_batch_cb()
239 typedef void(*location_batch_cb)(int num_of_location, void *user_data);
242 * @brief Gets iteratively to receive location batch data.
243 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
244 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
245 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
246 * @param[in] altitude The updated altitude (meters)
247 * @param[in] speed The updated speed (km/h)
248 * @param[in] direction The updated direction (in degrees from the north)
249 * @param[in] horizontal The horizontal accuracy (meters)
250 * @param[in] vertical The vertical accuracy (meters)
251 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
252 * @param[in] user_data The user data passed from the callback registration function
253 * @return @c true to continue with the next iteration of the loop, otherwise @c false to break out of the loop.
254 * @pre location_manager_foreach_location_batch() will invoke this callback
255 * @see location_manager_foreach_location_batch()
257 typedef bool(*location_batch_get_location_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal, double vertical, time_t timestamp, void *user_data);
260 * @brief Checks whether the given location method is available.
261 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
262 * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
263 * @param[in] method The location method to be checked
264 * @return @c true if the specified location method is supported, otherwise @c false if it is not available
265 * @retval #LOCATIONS_ERROR_NONE Successful
266 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
267 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
268 * @see location_manager_create()
269 * @see location_manager_get_method()
271 bool location_manager_is_supported_method(location_method_e method);
274 * @brief Checks whether the given location method is enabled or not on setting.
275 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
276 * @param[in] method The location method to be checked
277 * @param[out] enable The result value of checking the given location method
278 * @return 0 on success, otherwise a negative error value
279 * @retval #LOCATIONS_ERROR_NONE Successful
280 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
281 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
282 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
283 * @see location_manager_create()
284 * @see location_manager_set_setting_changed_cb()
285 * @see location_manager_unset_setting_changed_cb()
287 int location_manager_is_enabled_method(location_method_e method, bool *enable);
291 * @brief Enables the given location method.
293 * @privlevel platform
294 * @privilege %http://tizen.org/privilege/location.enable
295 * @param[in] method The location method to be checked
296 * @param[in] enable The value to set
297 * @return 0 on success, otherwise a negative error value
298 * @retval #LOCATIONS_ERROR_NONE Successful
299 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
300 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
301 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
302 * @see location_manager_is_enabled_method()
303 * @see location_manager_create()
305 int location_manager_enable_method(const location_method_e method, const bool enable);
308 * @brief Creates a new location manager.
309 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
310 * @remarks You must release @a manager using location_manager_destroy().
311 * @param[in] method The location method
312 * @param[out] manager The location manager handle that is newly created
313 * @return @c 0 on success, otherwise a negative error value
314 * @retval #LOCATIONS_ERROR_NONE Successful
315 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
316 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
317 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
318 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
319 * @see location_manager_destroy()
321 int location_manager_create(location_method_e method, location_manager_h *manager);
324 * @brief Releases the location manager.
325 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
326 * @param[in] manager The location manager handle
327 * @return @c 0 on success, otherwise a negative error value
328 * @retval #LOCATIONS_ERROR_NONE Successful
329 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
330 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
331 * @see location_manager_create()
333 int location_manager_destroy(location_manager_h manager);
336 * @brief Request to update current location once.
337 * @remarks Do not request to start the location service using the same manager handler
338 * Calling this function invokes a location service event. When the location service is updated, location_updated_cb
339 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
341 * @privilege %http://tizen.org/privilege/location
342 * @param[in] manager The location manager handle
343 * @param[in] timeout Timeout to stop requesting single location after
344 * @param[in] callback The location callback function to register
345 * @param[in] user_data The user data to be passed to the callback function
346 * @retval #LOCATIONS_ERROR_NONE Successful
347 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
348 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
349 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
350 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
351 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
352 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
353 * @post It invokes location_updated_cb().
355 int location_manager_request_single_location(location_manager_h manager, int timeout, location_updated_cb callback, void *user_data);
358 * @brief Starts the location service.
359 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
361 * @privilege %http://tizen.org/privilege/location
363 * @remarks There is no limit on number of location managers for which this function was called.
365 * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
366 * (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as
367 * the first argument, and the service starts.
369 * @remarks The started service is a requirement for calling these functions:
370 * location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(),
371 * gps_status_get_nmea(), gps_status_get_satellite(), gps_status_foreach_satellites_in_view().
373 * @remarks Once you stop the service using location_manager_stop(), you can no longer call the functions listed above.
375 * @remarks Starting and stopping the service is in the scope of the given location manager only (if there is more than one manager,
376 * starting and stopping should be executed for each of them separately).
378 * @param[in] manager The location manager handle
379 * @return 0 on success, otherwise a negative error value
380 * @retval #LOCATIONS_ERROR_NONE Successful
381 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
382 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
383 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
384 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
385 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
386 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
387 * @post It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().
388 * @see location_manager_stop()
389 * @see location_manager_get_position()
390 * @see location_manager_get_velocity()
391 * @see location_manager_get_accuracy()
392 * @see location_manager_set_service_state_changed_cb()
393 * @see location_manager_set_position_updated_cb()
394 * @see location_position_updated_cb()
395 * @see location_manager_set_velocity_updated_cb()
396 * @see location_velocity_updated_cb()
397 * @see location_manager_set_zone_changed_cb()
398 * @see location_zone_changed_cb()
400 int location_manager_start(location_manager_h manager);
403 * @brief Stops the location service.
404 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
405 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
406 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
407 * When that happens, the service is stopped and the user is notified.
409 * @remarks You can stop and start the location manager as needed.
411 * @param[in] manager The location manager handle
412 * @return 0 on success, otherwise a negative error value
413 * @retval #LOCATIONS_ERROR_NONE Successful
414 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
415 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
416 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
417 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
418 * @see location_manager_start()
419 * @see location_manager_set_service_state_changed_cb()
420 * @see location_service_state_changed_cb()
422 int location_manager_stop(location_manager_h manager);
425 * @brief Adds a bounds for a given location manager.
426 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
427 * @param[in] manager The location manager handle
428 * @param[in] bounds The location bounds handle
429 * @return @c 0 on success, otherwise a negative error value
430 * @retval #LOCATIONS_ERROR_NONE Successful
431 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
432 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
433 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
434 * @post It invokes location_manager_set_zone_changed_cb() when a boundary is entered or exited, if you set a callback with location_manager_set_zone_changed_cb().
435 * @see location_manager_remove_boundary()
436 * @see location_manager_set_zone_changed_cb()
438 int location_manager_add_boundary(location_manager_h manager, const location_bounds_h bounds);
441 * @brief Deletes a bounds for a given location manager.
442 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
443 * @param[in] manager The location manager handle
444 * @param[in] bounds The location bounds handle
445 * @return @c 0 on success, otherwise a negative error value
446 * @retval #LOCATIONS_ERROR_NONE Successful
447 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
448 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
449 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
450 * @see location_manager_add_boundary()
452 int location_manager_remove_boundary(location_manager_h manager, const location_bounds_h bounds);
455 * @brief Retrieves all location bounds by invoking a specific callback for each location bounds
456 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
457 * @param[in] manager The location manager handle
458 * @param[in] callback The iteration callback
459 * @param[in] user_data The user data to be passed to the callback function
460 * @return @c 0 on success, otherwise a negative error value
461 * @retval #LOCATIONS_ERROR_NONE Successful
462 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
463 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
464 * @post location_bounds_cb() will be invoked
465 * @see location_manager_add_boundary()
466 * @see location_manager_remove_boundary()
467 * @see location_bounds_cb()
469 int location_manager_foreach_boundary(location_manager_h manager, location_bounds_cb callback, void *user_data);
472 * @brief Gets the given location manager's method.
473 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
474 * @param[in] manager The location manager handle
475 * @param[out] method The location method
476 * @return @c 0 on success, otherwise a negative error value
477 * @retval #LOCATIONS_ERROR_NONE Successful
478 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
479 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
480 * @see location_manager_create()
482 int location_manager_get_method(location_manager_h manager, location_method_e *method);
485 * @brief Gets the current position information.
486 * @details The result contains the current altitude, latitude, and longitude, with a measurement timestamp.
488 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
490 * @privilege %http://tizen.org/privilege/location
491 * @param[in] manager The location manager handle
492 * @param[out] altitude The current altitude (meters)
493 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
494 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
495 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
496 * @return 0 on success, otherwise a negative error value
497 * @retval #LOCATIONS_ERROR_NONE Successful
498 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
499 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
500 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
501 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
502 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
503 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
505 int location_manager_get_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
508 * @brief Gets the current position information.
509 * @details The result contains the current altitude, latitude, longitude, climb, direction, speed, level, horizontal and vertical with a measurement timestamp.
511 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
513 * @privilege %http://tizen.org/privilege/location
514 * @param[in] manager The location manager handle
515 * @param[out] altitude The current altitude (meters)
516 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
517 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
518 * @param[out] climb The climb (km/h)
519 * @param[out] direction The direction, degrees from the north
520 * @param[out] speed The speed (km/h)
521 * @param[out] level The accuracy level
522 * @param[out] horizontal The horizontal accuracy (meters)
523 * @param[out] vertical The vertical accuracy (meters)
524 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
525 * @return 0 on success, otherwise a negative error value
526 * @retval #LOCATIONS_ERROR_NONE Successful
527 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
528 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
529 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
530 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
531 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
532 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
534 int location_manager_get_location(location_manager_h manager, double *altitude, double *latitude, double *longitude, double *climb, double *direction, double *speed, location_accuracy_level_e *level, double *horizontal, double *vertical, time_t *timestamp);
537 * @brief Gets the current velocity information.
538 * @details The result contains the current climb, direction, and speed, with a measurement timestamp.
540 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
542 * @privilege %http://tizen.org/privilege/location
543 * @param[in] manager The location manager handle
544 * @param[out] climb The climb (km/h)
545 * @param[out] direction The direction, degrees from the north
546 * @param[out] speed The speed (km/h)
547 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
548 * @return @c 0 on success, otherwise a negative error value
549 * @retval #LOCATIONS_ERROR_NONE Successful
550 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
551 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
552 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
553 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
554 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
555 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
557 int location_manager_get_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
560 * @brief Gets the current accuracy information.
561 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
563 * @privilege %http://tizen.org/privilege/location
564 * @param[in] manager The location manager handle
565 * @param[out] level The accuracy level
566 * @param[out] horizontal The horizontal accuracy (meters)
567 * @param[out] vertical The vertical accuracy (meters)
568 * @return 0 on success, otherwise a negative error value
569 * @retval #LOCATIONS_ERROR_NONE Successful
570 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
571 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
572 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
573 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
574 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
575 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
577 int location_manager_get_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
580 * @brief Gets the last position information which is recorded.
581 * @details The @a altitude, @a latitude, @a longitude, and @c timestamp values should be 0, if there is no record of any previous position information.
582 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
584 * @privilege %http://tizen.org/privilege/location
585 * @param[in] manager The location manager handle
586 * @param[out] altitude The last altitude (meters)
587 * @param[out] latitude The last latitude [-90.0 ~ 90.0] (degrees)
588 * @param[out] longitude The last longitude [-180.0 ~ 180.0] (degrees)
589 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
590 * @return @c 0 on success, otherwise a negative error value
591 * @retval #LOCATIONS_ERROR_NONE Successful
592 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
593 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
594 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
595 * @pre The location manager handle must be created by location_manager_create()
597 int location_manager_get_last_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
600 * @brief Gets the last location information.
601 * @details The @a altitude, @a latitude, @a longitude, @a climb, @a direction, @a speed and @c timestamp values should be 0, if there is no record of any previous position information.
602 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
604 * @privilege %http://tizen.org/privilege/location
605 * @param[in] manager The location manager handle
606 * @param[out] altitude The current altitude (meters)
607 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
608 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
609 * @param[out] climb The climb (km/h)
610 * @param[out] direction The direction, degrees from the north
611 * @param[out] speed The speed (km/h)
612 * @param[out] level The accuracy level
613 * @param[out] horizontal The horizontal accuracy (meters)
614 * @param[out] vertical The vertical accuracy (meters)
615 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
616 * @return @c 0 on success, otherwise a negative error value
617 * @retval #LOCATIONS_ERROR_NONE Successful
618 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
619 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
620 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
621 * @pre The location manager handle must be created by location_manager_create()
623 int location_manager_get_last_location(location_manager_h manager, double *altitude, double *latitude, double *longitude, double *climb, double *direction, double *speed, location_accuracy_level_e *level, double *horizontal, double *vertical, time_t *timestamp);
627 * @brief Gets the last velocity information which is recorded.
628 * @details The @a climb, @a direction and @a speed values should be @c 0, if there is no record of any previous velocity information.
630 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
632 * @privilege %http://tizen.org/privilege/location
633 * @param[in] manager The location manager handle
634 * @param[out] climb The last climb (km/h)
635 * @param[out] direction The last direction, degrees from the north
636 * @param[out] speed The last speed (km/h)
637 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
638 * @return @c 0 on success, otherwise a negative error value
639 * @retval #LOCATIONS_ERROR_NONE Successful
640 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
641 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
642 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
643 * @pre The location manager handle must be created by location_manager_create()
645 int location_manager_get_last_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
648 * @brief Gets the last accuracy information which is recorded.
649 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
651 * @privilege %http://tizen.org/privilege/location
652 * @param[in] manager The location manager handle
653 * @param[out] level The last accuracy level
654 * @param[out] horizontal The last horizontal accuracy (meters)
655 * @param[out] vertical The last vertical accuracy (meters)
656 * @return 0 on success, otherwise a negative error value
657 * @retval #LOCATIONS_ERROR_NONE Successful
658 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
659 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
660 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
661 * @pre The location manager handle must be created by location_manager_create()
663 int location_manager_get_last_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
666 * @deprecated Deprecated since 3.0
667 * @brief Gets the current application's location accessibility status.
668 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
669 * @param[out] state The current location service accessibility status.
670 * @return 0 on success, otherwise a negative error value
671 * @retval #LOCATIONS_ERROR_NONE Successful
672 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
673 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
674 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
676 int location_manager_get_accessibility_state(location_accessibility_state_e *state) TIZEN_DEPRECATED_API;
679 * @brief Registers a callback function to be invoked at defined interval with updated position information.
681 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
682 * @param[in] manager The location manager handle
683 * @param[in] callback The callback function to register
684 * @param[in] interval The interval [1 ~ 120] (seconds)
685 * @param[in] user_data The user data to be passed to the callback function
686 * @return @c 0 on success, otherwise a negative error value
687 * @retval #LOCATIONS_ERROR_NONE Successful
688 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
689 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
690 * @post location_position_updated_cb() will be invoked
691 * @see location_manager_unset_position_updated_cb()
692 * @see location_position_updated_cb()
694 int location_manager_set_position_updated_cb(location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data);
697 * @brief Unregisters the callback function.
698 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
699 * @param[in] manager The location manager handle
700 * @return @c 0 on success, otherwise a negative error value
701 * @retval #LOCATIONS_ERROR_NONE Successful
702 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
703 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
704 * @see location_manager_set_position_updated_cb()
706 int location_manager_unset_position_updated_cb(location_manager_h manager);
709 * @brief Registers a callback function to be invoked at defined interval with updated velocity information.
710 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
711 * @param[in] manager The location manager handle
712 * @param[in] callback The callback function to register
713 * @param[in] interval The interval [1 ~ 120] (seconds)
714 * @param[in] user_data The user data to be passed to the callback function
715 * @return @c 0 on success, otherwise a negative error value
716 * @retval #LOCATIONS_ERROR_NONE Successful
717 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
718 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
719 * @post location_velocity_updated_cb() will be invoked
720 * @see location_manager_unset_velocity_updated_cb()
721 * @see location_velocity_updated_cb()
723 int location_manager_set_velocity_updated_cb(location_manager_h manager, location_velocity_updated_cb callback, int interval, void *user_data);
726 * @brief Unregisters the callback function.
727 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
728 * @param[in] manager The location manager handle
729 * @return @c 0 on success, otherwise a negative error value
730 * @retval #LOCATIONS_ERROR_NONE Successful
731 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
732 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
733 * @see location_manager_set_velocity_updated_cb()
735 int location_manager_unset_velocity_updated_cb(location_manager_h manager);
738 * @brief Registers a callback function to be invoked when the location service state is changed.
739 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
740 * @param[in] manager The location manager handle
741 * @param[in] callback The callback function to register
742 * @param[in] user_data The user data to be passed to the callback function
743 * @return @c 0 on success, otherwise a negative error value
744 * @retval #LOCATIONS_ERROR_NONE Successful
745 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
746 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
747 * @post location_service_state_changed_cb() will be invoked
748 * @see location_manager_unset_service_state_changed_cb()
749 * @see location_service_state_changed_cb()
750 * @see location_manager_start()
751 * @see location_manager_stop()
752 * @see #location_service_state_e
754 int location_manager_set_service_state_changed_cb(location_manager_h manager, location_service_state_changed_cb callback, void *user_data);
757 * @brief Unregisters the callback function.
758 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
759 * @param[in] manager The location manager handle
760 * @return @c 0 on success, otherwise a negative error value
761 * @retval #LOCATIONS_ERROR_NONE Successful
762 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
763 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
764 * @see location_manager_set_service_state_changed_cb()
766 int location_manager_unset_service_state_changed_cb(location_manager_h manager);
769 * @brief Registers a callback function to be invoked when the previously set boundary area is entered or left.
771 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
772 * @param[in] manager The location manager handle
773 * @param[in] callback The callback function to register
774 * @param[in] user_data The user data to be passed to the callback function
775 * @return @c 0 on success, otherwise a negative error value
776 * @retval #LOCATIONS_ERROR_NONE Successful
777 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
778 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
779 * @pre location_manager_add_boundary() is called before.
780 * @post location_zone_changed_cb() will be invoked
781 * @see location_manager_unset_zone_changed_cb()
782 * @see location_zone_changed_cb()
784 int location_manager_set_zone_changed_cb(location_manager_h manager, location_zone_changed_cb callback, void *user_data);
787 * @brief Unregisters the callback function.
788 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
789 * @param[in] manager The location manager handle
790 * @return 0 on success, otherwise a negative error value
791 * @retval #LOCATIONS_ERROR_NONE Successful
792 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
793 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
794 * @see location_manager_set_zone_changed_cb()
796 int location_manager_unset_zone_changed_cb(location_manager_h manager);
799 * @brief Registers a callback function to be invoked when the location setting is changed.
800 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
801 * @param[in] method The method to observe
802 * @param[in] callback The callback function to register
803 * @param[in] user_data The user data to be passed to the callback function
804 * @return 0 on success, otherwise a negative error value
805 * @retval #LOCATIONS_ERROR_NONE Successful
806 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
807 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
808 * @post location_setting_changed_cb() will be invoked
809 * @see location_manager_unset_setting_changed_cb()
810 * @see location_setting_changed_cb()
812 int location_manager_set_setting_changed_cb(location_method_e method, location_setting_changed_cb callback, void *user_data);
815 * @brief Unregisters the callback function.
816 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
817 * @param[in] method The method to observe
818 * @return 0 on success, otherwise a negative error value
819 * @retval #LOCATIONS_ERROR_NONE Successful
820 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
821 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
822 * @see location_manager_set_setting_changed_cb()
824 int location_manager_unset_setting_changed_cb(location_method_e method);
827 * @brief Gets the distance in meters between two locations.
828 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
829 * @param[in] start_latitude The starting latitude [-90.0 ~ 90.0] (degrees)
830 * @param[in] start_longitude The starting longitude [-180.0 ~ 180.0] (degrees)
831 * @param[in] end_latitude The ending latitude [-90.0 ~ 90.0] (degrees)
832 * @param[in] end_longitude The ending longitude [-180.0 ~ 180.0] (degrees)
833 * @param[out] distance The distance between two locations (meters)
834 * @return 0 on success, otherwise a negative error value
835 * @retval #LOCATIONS_ERROR_NONE Successful
836 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
837 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
839 int location_manager_get_distance(double start_latitude, double start_longitude, double end_latitude, double end_longitude, double *distance);
842 * @brief Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.
843 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
844 * @param[in] manager The location manager handle
845 * @param[in] callback The callback function to register
846 * @param[in] interval The minimum interval between position updates [1 ~ 120] (seconds)
847 * @param[in] distance The minimum distance between position updates [1 ~ 120] (meters)
848 * @param[in] user_data The user data to be passed to the callback function
849 * @return @c 0 on success, otherwise a negative error value
850 * @retval #LOCATIONS_ERROR_NONE Successful
851 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
852 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
853 * @post location_changed_cb() will be invoked
854 * @see location_manager_unset_distance_based_location_changed_cb()
855 * @see location_changed_cb()
857 int location_manager_set_distance_based_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, double distance, void *user_data);
860 * @brief Unregisters the callback function.
861 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
862 * @param[in] manager The location manager handle
863 * @return @c 0 on success, otherwise a negative error value
864 * @retval #LOCATIONS_ERROR_NONE Successful
865 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
866 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
867 * @see location_manager_set_distance_based_location_changed_cb()
869 int location_manager_unset_distance_based_location_changed_cb(location_manager_h manager);
872 * @brief Registers a callback function to be invoked at defined interval with updated location information.
873 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
874 * @param[in] manager The location manager handle
875 * @param[in] callback The callback function to register
876 * @param[in] interval The interval [1 ~ 120] (seconds)
877 * @param[in] user_data The user data to be passed to the callback function
878 * @return @c 0 on success, otherwise a negative error value
879 * @retval #LOCATIONS_ERROR_NONE Successful
880 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
881 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
882 * @post location_changed_cb() will be invoked
883 * @see location_manager_unset_location_changed_cb()
884 * @see location_changed_cb()
886 int location_manager_set_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, void *user_data);
889 * @brief Unregisters the callback function.
890 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
891 * @param[in] manager The location manager handle
892 * @return @c 0 on success, otherwise a negative error value
893 * @retval #LOCATIONS_ERROR_NONE Successful
894 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
895 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
896 * @see location_manager_set_location_changed_cb()
898 int location_manager_unset_location_changed_cb(location_manager_h manager);
901 * @brief Registers a callback function to be invoked when batch_period is expired.
902 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
903 * @remarks The batch_period should be greater than or equal to the batch_interval.
904 * @param[in] manager The location manager handle
905 * @param[in] callback The callback function to register
906 * @param[in] batch_interval The batch sampling interval [1 ~ 255] (seconds)
907 * @param[in] batch_period The batch period [1 ~ 60000] (seconds)
908 * @param[in] user_data The user data to be passed to the callback function
909 * @return @c 0 on success, otherwise a negative error value
910 * @retval #LOCATIONS_ERROR_NONE Successful
911 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
912 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
913 * @post location_batch_cb() will be invoked
914 * @see location_manager_start_batch()
915 * @see location_batch_cb()
916 * @see location_manager_unset_location_batch_cb()
918 int location_manager_set_location_batch_cb(location_manager_h manager, location_batch_cb callback, int batch_interval, int batch_period, void *user_data);
921 * @brief Unregisters the callback function.
922 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
923 * @param[in] manager The location manager handle
924 * @return @c 0 on success, otherwise a negative error value
925 * @retval #LOCATIONS_ERROR_NONE Successful
926 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
927 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
928 * @see location_manager_set_location_batch_cb()
930 int location_manager_unset_location_batch_cb(location_manager_h manager);
933 * @brief Starts the location batch service.
934 * @details Calling this function starts location batch service, location_batch_cb() will be invoked every @a batch_period seconds.
935 After that, you can obtain all locations with location_manager_foreach_location_batch().
936 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
938 * @privilege %http://tizen.org/privilege/location
939 * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
940 * (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as the first argument, and the service starts.
941 * @param[in] manager The location manager handle
942 * @return 0 on success, otherwise a negative error value
943 * @retval #LOCATIONS_ERROR_NONE Successful
944 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
945 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
946 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
947 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
948 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
949 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
950 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
951 * @pre location_manager_set_location_batch_cb()
952 * @see location_manager_set_service_state_changed_cb()
953 * @see location_service_state_changed_cb()
954 * @see location_manager_foreach_location_batch()
955 * @see location_manager_stop_batch()
957 int location_manager_start_batch(location_manager_h manager);
960 * @brief Stops the location batch service.
961 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
962 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
963 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
964 * @param[in] manager The location manager handle
965 * @return 0 on success, otherwise a negative error value
966 * @retval #LOCATIONS_ERROR_NONE Successful
967 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
968 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
969 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
970 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
971 * @see location_manager_start_batch()
972 * @see location_manager_set_service_state_changed_cb()
973 * @see location_service_state_changed_cb()
975 int location_manager_stop_batch(location_manager_h manager);
978 * @brief Retrieves all location information by invoking a specific callback for each location data.
979 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
981 * @privilege %http://tizen.org/privilege/location
982 * @param[in] manager The location manager handle
983 * @param[in] callback The iteration callback function
984 * @param[in] user_data The user data to be passed to the callback function
985 * @return @c 0 on success, otherwise a negative error value
986 * @retval #LOCATIONS_ERROR_NONE Successful
987 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
988 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
989 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
990 * @pre location_manager_foreach_location_batch() is available after location_batch_cb() is invoked
991 * @post location_batch_get_location_cb() will be invoked
992 * @see location_manager_start_batch()
993 * @see location_batch_cb()
994 * @see location_batch_get_location_cb()
996 int location_manager_foreach_location_batch(location_manager_h manager, location_batch_get_location_cb callback, void *user_data);
999 * @brief Checks whether the mock location is enabled.
1001 * @param[out] enabled Indicates whether the mock location is enabled
1002 * @return 0 on success, otherwise a negative error value
1003 * @retval #LOCATIONS_ERROR_NONE Successful
1004 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1005 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1006 * @see location_manager_enable_mock_location()
1007 * @see location_manager_set_mock_location()
1008 * @see location_manager_clear_mock_location()
1010 int location_manager_is_enabled_mock_location(bool *enabled);
1013 * @brief Enables mock location.
1014 * @details The mock location is a testing function to make location API and callback deliver a mock location
1015 * set by location_manager_set_mock_location() instead of real positioning data even in the other applications.
1016 * @remarks The mock location can only be enabled if developer mode is enabled.
1019 * @privilege %http://tizen.org/privilege/location
1020 * @param[in] enable The value to set
1021 * @return 0 on success, otherwise a negative error value
1022 * @retval #LOCATIONS_ERROR_NONE Successful
1023 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1024 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
1025 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1026 * @see location_manager_is_enabled_mock_location()
1027 * @see location_manager_set_mock_location()
1028 * @see location_manager_clear_mock_location()
1030 int location_manager_enable_mock_location(const bool enable);
1033 * @brief Sets a mock location for the given location method.
1034 * @details The location sets the given altitude, latitude, longitude, climb, direction, speed, level, horizontal and vertical accuracy.
1037 * @privilege %http://tizen.org/privilege/location
1038 * @param[in] manager The location manager handle
1039 * @param[in] latitude The current latitude [-90.0 ~ 90.0] (degrees)
1040 * @param[in] longitude The current longitude [-180.0 ~ 180.0] (degrees)
1041 * @param[in] altitude The current altitude (meters)
1042 * @param[in] speed The speed (km/h)
1043 * @param[in] direction The direction, degrees from the north [0.0 ~ 360.0]
1044 * @param[in] accuracy The horizontal accuracy (meters)
1045 * @return 0 on success, otherwise a negative error value
1046 * @retval #LOCATIONS_ERROR_NONE Successful
1047 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1048 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1049 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1050 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1051 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1052 * @see location_manager_create()
1053 * @see location_manager_is_enabled_mock_location()
1054 * @see location_manager_enable_mock_location()
1055 * @see location_manager_clear_mock_location()
1057 int location_manager_set_mock_location(location_manager_h manager, const double latitude, const double longitude, const double altitude, const double speed, const double direction, const double accuracy);
1060 * @brief Clears a mock location.
1063 * @privilege %http://tizen.org/privilege/location
1064 * @param[in] manager The location manager handle
1065 * @return 0 on success, otherwise a negative error value
1066 * @retval #LOCATIONS_ERROR_NONE Successful
1067 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1068 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1069 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1070 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1071 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1072 * @see location_manager_create()
1073 * @see location_manager_is_enabled_mock_location()
1074 * @see location_manager_enable_mock_location()
1075 * @see location_manager_set_mock_location()
1077 int location_manager_clear_mock_location(location_manager_h manager);
1084 * GPS Status & Satellites
1088 * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE
1093 * @brief Called once for each satellite in range.
1094 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1095 * @param[in] azimuth The azimuth of the satellite (degrees)
1096 * @param[in] elevation The elevation of the satellite (meters)
1097 * @param[in] prn The PRN of the satellite
1098 * @param[in] snr The SNR of the satellite [dB]
1099 * @param[in] is_active The flag signaling if satellite is in use
1100 * @param[in] user_data The user data passed from the foreach function
1101 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
1102 * @pre gps_status_foreach_satellites_in_view() will invoke this callback.
1103 * @pre gps_status_foreach_last_satellites_in_view() will invoke this callback.
1104 * @see gps_status_foreach_satellites_in_view()
1106 typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data);
1109 * @brief Called at defined interval with updated satellite information.
1110 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1111 * @param[out] num_of_active The last number of active satellites
1112 * @param[out] num_of_inview The last number of satellites in view
1113 * @param[out] timestamp The last timestamp (time when measurement took place or @c 0 if valid)
1114 * @param[in] user_data The user data passed from the call registration function
1115 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
1116 * @see location_manager_start()
1117 * @see location_manager_set_position_updated_cb()
1119 typedef void(*gps_status_satellite_updated_cb)(int num_of_active, int num_of_inview, time_t timestamp, void *user_data);
1122 * @brief Gets the GPS NMEA data.
1123 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1124 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1125 * You must release @a nmea using @c free().
1126 * @param[in] manager The location manager handle
1127 * @param[out] nmea The NMEA data
1128 * @return @c 0 on success, otherwise a negative error value
1129 * @retval #LOCATIONS_ERROR_NONE Successful
1130 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1131 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1132 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1133 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1134 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1135 * @see location_manager_start()
1137 int gps_status_get_nmea(location_manager_h manager, char **nmea);
1140 * @brief Gets the information of satellites.
1141 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1143 * @privilege %http://tizen.org/privilege/location
1144 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1145 * @param[in] manager The location manager handle
1146 * @param[out] num_of_active The number of active satellites
1147 * @param[out] num_of_inview The number of satellites in view
1148 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
1149 * @return @c 0 on success, otherwise a negative error value
1150 * @retval #LOCATIONS_ERROR_NONE Successful
1151 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1152 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1153 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1154 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1155 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1156 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1157 * @see gps_status_foreach_satellites_in_view()
1159 int gps_status_get_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1162 * @brief Registers a callback function to be invoked at defined interval with updated satellite information.
1163 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1165 * @privilege %http://tizen.org/privilege/location
1166 * @param[in] manager The location manager handle
1167 * @param[in] callback The callback function to register
1168 * @param[in] interval The interval [1 ~ 120] (seconds)
1169 * @param[in] user_data The user data to be passed to the callback function
1170 * @return 0 on success, otherwise a negative error value
1171 * @retval #LOCATIONS_ERROR_NONE Successful
1172 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1173 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1174 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1175 * @post gps_status_satellite_updated_cb() will be invoked
1176 * @see gps_status_unset_satellite_updated_cb()
1177 * @see gps_status_satellite_updated_cb()
1178 * @see gps_status_get_satellite()
1179 * @see gps_status_foreach_satellites_in_view()
1180 * @see gps_status_get_last_satellite()
1181 * @see gps_status_foreach_last_satellites_in_view()
1183 int gps_status_set_satellite_updated_cb(location_manager_h manager, gps_status_satellite_updated_cb callback, int interval, void *user_data);
1186 * @brief Unregisters the callback function.
1187 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1188 * @param[in] manager The location manager handle
1189 * @return @c 0 on success, otherwise a negative error value
1190 * @retval #LOCATIONS_ERROR_NONE Successful
1191 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1192 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1193 * @see gps_status_set_satellite_updated_cb()
1195 int gps_status_unset_satellite_updated_cb(location_manager_h manager);
1198 * @brief Invokes the callback function for each satellite.
1199 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1201 * @privilege %http://tizen.org/privilege/location
1202 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1203 * @param[in] manager The location manager handle
1204 * @param[in] callback The iteration callback function
1205 * @param[in] user_data The user data to be passed to the callback function
1206 * @return @c 0 on success, otherwise a negative error value
1207 * @retval #LOCATIONS_ERROR_NONE Successful
1208 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1209 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1210 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1211 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1212 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1213 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1214 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1215 * @post It invokes gps_status_get_satellites_cb().
1216 * @see gps_status_get_satellite()
1217 * @see gps_status_get_satellites_cb()
1219 int gps_status_foreach_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1222 * @brief Gets the last information of satellites.
1223 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1225 * @privilege %http://tizen.org/privilege/location
1226 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1227 * @param[in] manager The location manager handle
1228 * @param[out] num_of_active The last number of active satellites
1229 * @param[out] num_of_inview The last number of satellites in view
1230 * @param[out] timestamp The last timestamp (time when last measurement took place or @c 0 if valid)
1231 * @return @c 0 on success, otherwise a negative error value
1232 * @retval #LOCATIONS_ERROR_NONE Successful
1233 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1234 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1235 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1236 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1237 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1238 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1239 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1240 * @see gps_status_foreach_satellites_in_view()
1242 int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1245 * @brief Invokes the callback function for each last satellite which is recorded.
1246 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1248 * @privilege %http://tizen.org/privilege/location
1249 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1250 * @param[in] manager The location manager handle
1251 * @param[in] callback The iteration callback function
1252 * @param[in] user_data The user data to be passed to the callback function
1253 * @return @c 0 on success, otherwise a negative error value
1254 * @retval #LOCATIONS_ERROR_NONE Successful
1255 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1256 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1257 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1258 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1259 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1260 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1261 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1262 * @post It invokes gps_status_get_satellites_cb().
1263 * @see gps_status_get_last_satellite()
1264 * @see gps_status_get_satellites_cb()
1266 int gps_status_foreach_last_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1275 #endif /* __TIZEN_LOCATION_LOCATIONS_H__ */