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>
32 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
38 * @brief Enumeration for error code for Location manager.
39 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
42 LOCATIONS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
43 LOCATIONS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
44 LOCATIONS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
45 LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
46 LOCATIONS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
47 LOCATIONS_ERROR_INCORRECT_METHOD = TIZEN_ERROR_LOCATION_MANAGER | 0x01, /**< Location manager contains incorrect method for a given call */
48 LOCATIONS_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_MANAGER | 0x02, /**< Network unavailable */
49 LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_MANAGER | 0x03, /**< Location service is not available */
50 LOCATIONS_ERROR_GPS_SETTING_OFF = TIZEN_ERROR_LOCATION_MANAGER | 0x04, /**< Setting for GPS, WPS, or MOCK is turned off */
51 LOCATIONS_ERROR_SECURITY_RESTRICTED = TIZEN_ERROR_LOCATION_MANAGER | 0x05, /**< Restricted by security system policy */
52 LOCATIONS_ERROR_SETTING_OFF = LOCATIONS_ERROR_GPS_SETTING_OFF, /**< Setting for GPS, WPS, or MOCK is turned off (Since 3.0) */
57 * @brief Enumeration for Location method type.
58 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
61 LOCATIONS_METHOD_NONE = -1, /**< Undefined method */
62 LOCATIONS_METHOD_HYBRID, /**< This method selects the best method available at the moment */
63 LOCATIONS_METHOD_GPS, /**< This method uses Global Positioning System */
64 LOCATIONS_METHOD_WPS, /**< This method uses WiFi Positioning System */
65 LOCATIONS_METHOD_PASSIVE, /**< This method can be used to passively receive location updates without power consumption (Since 3.0)*/
70 * @brief Enumeration for Approximate accuracy level of given information.
71 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
74 LOCATIONS_ACCURACY_NONE = 0, /**< Invalid data */
75 LOCATIONS_ACCURACY_COUNTRY, /**< Country accuracy level */
76 LOCATIONS_ACCURACY_REGION, /**< Regional accuracy level */
77 LOCATIONS_ACCURACY_LOCALITY, /**< Local accuracy level */
78 LOCATIONS_ACCURACY_POSTALCODE, /**< Postal accuracy level */
79 LOCATIONS_ACCURACY_STREET, /**< Street accuracy level */
80 LOCATIONS_ACCURACY_DETAILED, /**< Detailed accuracy level */
81 } location_accuracy_level_e;
85 * @brief Enumeration for the state of the location service.
86 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
89 LOCATIONS_SERVICE_DISABLED, /**< Service is disabled */
90 LOCATIONS_SERVICE_ENABLED, /**< Service is enabled */
91 } location_service_state_e;
95 * @deprecated Deprecated since 3.0
96 * @brief Enumeration for the location service accessibility state.
97 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
100 LOCATIONS_ACCESS_STATE_NONE, /**< Access state is not determined */
101 LOCATIONS_ACCESS_STATE_DENIED, /**< Access denied */
102 LOCATIONS_ACCESS_STATE_ALLOWED, /**< Access authorized */
103 } location_accessibility_state_e;
107 * @brief The location manager handle.
108 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
110 typedef struct location_manager_s *location_manager_h;
122 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
128 * @brief Called at defined interval with updated position information.
129 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
130 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
131 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
132 * @param[in] altitude The updated altitude (meters)
133 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
134 * @param[in] user_data The user data passed from the call registration function
135 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
136 * @see location_manager_start()
137 * @see location_manager_set_position_updated_cb()
139 typedef void(*location_position_updated_cb)(double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
143 * @brief Called at defined interval with updated velocity information.
144 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
145 * @param[in] speed The updated speed (km/h)
146 * @param[in] direction The updated direction (in degrees from the north)
147 * @param[in] climb The updated climb (km/h)
148 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
149 * @param[in] user_data The user data passed from the callback registration function
150 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb().
151 * @see location_manager_start()
152 * @see location_manager_set_velocity_updated_cb()
154 typedef void(*location_velocity_updated_cb)(double speed, double direction, double climb, time_t timestamp, void *user_data);
158 * @brief Called at defined interval with updated location information.
159 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
160 * @param[in] error #LOCATIONS_ERROR_NONE Successful
161 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
162 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
163 * @param[in] altitude The updated altitude (meters)
164 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
165 * @param[in] speed The updated speed (km/h)
166 * @param[in] direction The updated direction (in degrees from the north)
167 * @param[in] climb The updated climb (km/h)
168 * @param[in] user_data The user data passed from the callback registration function
169 * @pre location_manager_request_single_location() will invoke this callback.
170 * @see location_manager_request_single_location()
172 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);
176 * @brief Called when the state of location service is changed from enabled to disabled or vice versa.
177 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
178 * @param[in] state The service state
179 * @param[in] user_data The user data passed from the callback registration function
180 * @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().
181 * @see location_manager_start()
182 * @see location_manager_stop()
183 * @see location_manager_set_service_state_changed_cb()
184 * @see #location_service_state_e
186 typedef void(*location_service_state_changed_cb)(location_service_state_e state, void *user_data);
190 * @brief Called when the user-defined zones are entered or exited.
191 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
192 * @param[in] state The boundary state
193 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
194 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
195 * @param[in] altitude The updated altitude (meters)
196 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
197 * @param[in] user_data The user data passed from the callback registration function
198 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb().
199 * @see #location_boundary_state_e
200 * @see location_manager_start()
201 * @see location_manager_set_zone_changed_cb()
203 typedef void(*location_zone_changed_cb)(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
207 * @brief Called when the state of location method is changed.
208 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
209 * @param[in] method The method changed on setting
210 * @param[in] enable The setting value changed
211 * @param[in] user_data The user data passed from the callback registration function
212 * @pre location_setting_changed_cb() will invoke this callback if you register this callback using location_manager_set_setting_changed_cb().
213 * @see location_manager_set_setting_changed_cb()
214 * @see location_manager_unset_setting_changed_cb()
216 typedef void(*location_setting_changed_cb)(location_method_e method, bool enable, void *user_data);
220 * @brief Called once for each location bound.
221 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
222 * @param[in] bounds The location bounds handle
223 * @param[in] user_data The user data passed from the callback registration function
224 * @return @c true to continue with the next iteration of the loop,
225 * otherwise @c false to break out of the loop
226 * @pre location_manager_foreach_boundary() will invoke this callback.
227 * @see location_manager_foreach_boundary()
229 typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
233 * @brief Called at defined interval with updated location information.
234 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
235 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
236 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
237 * @param[in] altitude The updated altitude (meters)
238 * @param[in] speed The updated speed (km/h)
239 * @param[in] direction The updated direction (in degrees from the north)
240 * @param[in] horizontal_accuracy The horizontal accuracy (meters)
241 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
242 * @param[in] user_data The user data passed from the callback registration function
243 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
244 * @see location_manager_start()
245 * @see location_manager_set_distance_based_location_changed_cb()
246 * @see location_manager_set_location_changed_cb()
248 typedef void(*location_changed_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data);
252 * @brief Called when the batch interval is expired.
253 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
254 * @param[in] num_of_location The number of location batch data
255 * @param[in] user_data The user data passed from the callback registration function
256 * @pre location_manager_start_batch() will invoke this callback if you register this callback using location_manager_set_location_batch_cb().
257 * @see location_manager_start_batch()
258 * @see location_manager_set_location_batch_cb()
260 typedef void(*location_batch_cb)(int num_of_location, void *user_data);
264 * @brief Gets iteratively to receive location batch data.
265 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
266 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
267 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
268 * @param[in] altitude The updated altitude (meters)
269 * @param[in] speed The updated speed (km/h)
270 * @param[in] direction The updated direction (in degrees from the north)
271 * @param[in] horizontal The horizontal accuracy (meters)
272 * @param[in] vertical The vertical accuracy (meters)
273 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
274 * @param[in] user_data The user data passed from the callback registration function
275 * @return @c true to continue with the next iteration of the loop,
276 * otherwise @c false to break out of the loop
277 * @pre location_manager_foreach_location_batch() will invoke this callback.
278 * @see location_manager_foreach_location_batch()
280 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);
284 * @brief Checks whether the given location method is available.
285 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
286 * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
287 * @param[in] method The location method to be checked
288 * @return @c true if the specified location method is supported,
289 * otherwise @c false if it is not available
290 * @retval #LOCATIONS_ERROR_NONE Successful
291 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
292 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
293 * @see location_manager_create()
294 * @see location_manager_get_method()
296 bool location_manager_is_supported_method(location_method_e method);
300 * @brief Checks whether the given location method is enabled or not on setting.
301 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
302 * @param[in] method The location method to be checked
303 * @param[out] enable The result value of checking the given location method
304 * @return @c 0 on success,
305 * otherwise a negative error value
306 * @retval #LOCATIONS_ERROR_NONE Successful
307 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
308 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
309 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
310 * @see location_manager_create()
311 * @see location_manager_set_setting_changed_cb()
312 * @see location_manager_unset_setting_changed_cb()
314 int location_manager_is_enabled_method(location_method_e method, bool *enable);
319 * @brief Enables the given location method.
321 * @privlevel platform
322 * @privilege %http://tizen.org/privilege/location.enable
323 * @param[in] method The location method to be checked
324 * @param[in] enable The value to set
325 * @return @c 0 on success,
326 * otherwise a negative error value
327 * @retval #LOCATIONS_ERROR_NONE Successful
328 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
329 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
330 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
331 * @see location_manager_is_enabled_method()
332 * @see location_manager_create()
334 int location_manager_enable_method(const location_method_e method, const bool enable);
338 * @brief Creates a new location manager.
339 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
340 * @remarks You must release @a manager using location_manager_destroy().
341 * @param[in] method The location method
342 * @param[out] manager The location manager handle that is newly created
343 * @return @c 0 on success,
344 * otherwise a negative error value
345 * @retval #LOCATIONS_ERROR_NONE Successful
346 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
347 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
348 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
349 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
350 * @see location_manager_destroy()
352 int location_manager_create(location_method_e method, location_manager_h *manager);
356 * @brief Releases the location manager.
357 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
358 * @param[in] manager The location manager handle
359 * @return @c 0 on success,
360 * otherwise a negative error value
361 * @retval #LOCATIONS_ERROR_NONE Successful
362 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
363 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
364 * @see location_manager_create()
366 int location_manager_destroy(location_manager_h manager);
370 * @brief Requests to update current location once.
371 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
373 * @privilege %http://tizen.org/privilege/location
374 * @remarks Do not request to start the location service using the same manager handler.
375 * Calling this function invokes a location service event. When the location service is updated, location_updated_cb.
376 * @param[in] manager The location manager handle
377 * @param[in] timeout Timeout to stop requesting single location after
378 * @param[in] callback The location callback function to register
379 * @param[in] user_data The user data to be passed to the callback function
380 * @retval #LOCATIONS_ERROR_NONE Successful
381 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
382 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
383 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
384 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
385 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
386 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
387 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
388 * @post It invokes location_updated_cb().
390 int location_manager_request_single_location(location_manager_h manager, int timeout, location_updated_cb callback, void *user_data);
394 * @brief Starts the location service.
395 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
397 * @privilege %http://tizen.org/privilege/location
398 * @remarks There is no limit on number of location managers for which this function was called.
399 * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
400 * (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as
401 * the first argument, and the service starts.
402 * @remarks The started service is a requirement for calling these functions:
403 * location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(),
404 * gps_status_get_nmea(), gps_status_get_satellite(), gps_status_foreach_satellites_in_view().
405 * @remarks Once you stop the service using location_manager_stop(), you can no longer call the functions listed above.
406 * @remarks Starting and stopping the service is in the scope of the given location manager only (if there is more than one manager,
407 * starting and stopping should be executed for each of them separately).
408 * @param[in] manager The location manager handle
409 * @return @c 0 on success,
410 * otherwise a negative error value
411 * @retval #LOCATIONS_ERROR_NONE Successful
412 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
413 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
414 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
415 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
416 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
417 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
418 * @post It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().
419 * @see location_manager_stop()
420 * @see location_manager_get_position()
421 * @see location_manager_get_velocity()
422 * @see location_manager_get_accuracy()
423 * @see location_manager_set_service_state_changed_cb()
424 * @see location_manager_set_position_updated_cb()
425 * @see location_position_updated_cb()
426 * @see location_manager_set_velocity_updated_cb()
427 * @see location_velocity_updated_cb()
428 * @see location_manager_set_zone_changed_cb()
429 * @see location_zone_changed_cb()
431 int location_manager_start(location_manager_h manager);
435 * @brief Stops the location service.
436 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
437 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
438 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
439 * When that happens, the service is stopped and the user is notified.
440 * @remarks You can stop and start the location manager as needed.
441 * @param[in] manager The location manager handle
442 * @return @c 0 on success,
443 * otherwise a negative error value
444 * @retval #LOCATIONS_ERROR_NONE Successful
445 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
446 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
447 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
448 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
449 * @see location_manager_start()
450 * @see location_manager_set_service_state_changed_cb()
451 * @see location_service_state_changed_cb()
453 int location_manager_stop(location_manager_h manager);
457 * @brief Adds bounds for a given location manager.
458 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
459 * @param[in] manager The location manager handle
460 * @param[in] bounds The location bounds handle
461 * @return @c 0 on success,
462 * otherwise a negative error value
463 * @retval #LOCATIONS_ERROR_NONE Successful
464 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
465 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
466 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
467 * @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().
468 * @see location_manager_remove_boundary()
469 * @see location_manager_set_zone_changed_cb()
471 int location_manager_add_boundary(location_manager_h manager, const location_bounds_h bounds);
475 * @brief Deletes bounds for a given location manager.
476 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
477 * @param[in] manager The location manager handle
478 * @param[in] bounds The location bounds handle
479 * @return @c 0 on success,
480 * otherwise a negative error value
481 * @retval #LOCATIONS_ERROR_NONE Successful
482 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
483 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
484 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
485 * @see location_manager_add_boundary()
487 int location_manager_remove_boundary(location_manager_h manager, const location_bounds_h bounds);
491 * @brief Retrieves all location bounds by invoking a specific callback for each location bounds
492 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
493 * @param[in] manager The location manager handle
494 * @param[in] callback The iteration callback
495 * @param[in] user_data The user data to be passed to the callback function
496 * @return @c 0 on success,
497 * otherwise a negative error value
498 * @retval #LOCATIONS_ERROR_NONE Successful
499 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
500 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
501 * @post location_bounds_cb() will be invoked.
502 * @see location_manager_add_boundary()
503 * @see location_manager_remove_boundary()
504 * @see location_bounds_cb()
506 int location_manager_foreach_boundary(location_manager_h manager, location_bounds_cb callback, void *user_data);
510 * @brief Gets the given location manager's method.
511 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
512 * @param[in] manager The location manager handle
513 * @param[out] method The location method
514 * @return @c 0 on success,
515 * otherwise a negative error value
516 * @retval #LOCATIONS_ERROR_NONE Successful
517 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
518 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
519 * @see location_manager_create()
521 int location_manager_get_method(location_manager_h manager, location_method_e *method);
525 * @brief Gets the current position information.
526 * @details The result contains the current altitude, latitude, and longitude with a measurement timestamp.
527 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
529 * @privilege %http://tizen.org/privilege/location
530 * @param[in] manager The location manager handle
531 * @param[out] altitude The current altitude (meters)
532 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
533 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
534 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
535 * @return @c 0 on success,
536 * otherwise a negative error value
537 * @retval #LOCATIONS_ERROR_NONE Successful
538 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
539 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
540 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
541 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
542 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
543 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
545 int location_manager_get_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
549 * @brief Gets the current position information.
550 * @details The result contains the current altitude, latitude, longitude, climb, direction, speed, level, horizontal, and vertical with a measurement timestamp.
551 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
553 * @privilege %http://tizen.org/privilege/location
554 * @param[in] manager The location manager handle
555 * @param[out] altitude The current altitude (meters)
556 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
557 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
558 * @param[out] climb The climb (km/h)
559 * @param[out] direction The direction, degrees from the north
560 * @param[out] speed The speed (km/h)
561 * @param[out] level The accuracy level
562 * @param[out] horizontal The horizontal accuracy (meters)
563 * @param[out] vertical The vertical accuracy (meters)
564 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
565 * @return @c 0 on success,
566 * otherwise a negative error value
567 * @retval #LOCATIONS_ERROR_NONE Successful
568 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
569 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
570 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
571 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
572 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
573 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
575 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);
579 * @brief Gets the current velocity information.
580 * @details The result contains the current climb, direction, and speed with a measurement timestamp.
581 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
583 * @privilege %http://tizen.org/privilege/location
584 * @param[in] manager The location manager handle
585 * @param[out] climb The climb (km/h)
586 * @param[out] direction The direction, degrees from the north
587 * @param[out] speed The speed (km/h)
588 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
589 * @return @c 0 on success,
590 * otherwise a negative error value
591 * @retval #LOCATIONS_ERROR_NONE Successful
592 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
593 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
594 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
595 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
596 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
597 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
599 int location_manager_get_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
603 * @brief Gets the current accuracy information.
604 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
606 * @privilege %http://tizen.org/privilege/location
607 * @param[in] manager The location manager handle
608 * @param[out] level The accuracy level
609 * @param[out] horizontal The horizontal accuracy (meters)
610 * @param[out] vertical The vertical accuracy (meters)
611 * @return @c 0 on success,
612 * otherwise a negative error value
613 * @retval #LOCATIONS_ERROR_NONE Successful
614 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
615 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
616 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
617 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
618 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
619 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
621 int location_manager_get_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
625 * @brief Gets the last position information which is recorded.
626 * @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.
627 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
629 * @privilege %http://tizen.org/privilege/location
630 * @param[in] manager The location manager handle
631 * @param[out] altitude The last altitude (meters)
632 * @param[out] latitude The last latitude [-90.0 ~ 90.0] (degrees)
633 * @param[out] longitude The last longitude [-180.0 ~ 180.0] (degrees)
634 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
635 * @return @c 0 on success,
636 * otherwise a negative error value
637 * @retval #LOCATIONS_ERROR_NONE Successful
638 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
639 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
640 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
641 * @pre The location manager handle must be created by location_manager_create().
643 int location_manager_get_last_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
647 * @brief Gets the last location information.
648 * @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.
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] altitude The current altitude (meters)
654 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
655 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
656 * @param[out] climb The climb (km/h)
657 * @param[out] direction The direction, degrees from the north
658 * @param[out] speed The speed (km/h)
659 * @param[out] level The accuracy level
660 * @param[out] horizontal The horizontal accuracy (meters)
661 * @param[out] vertical The vertical accuracy (meters)
662 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
663 * @return @c 0 on success,
664 * otherwise a negative error value
665 * @retval #LOCATIONS_ERROR_NONE Successful
666 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
667 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
668 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
669 * @pre The location manager handle must be created by location_manager_create().
671 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);
675 * @brief Gets the last velocity information which is recorded.
676 * @details The @a climb, @a direction, and @a speed values should be @c 0, if there is no record of any previous velocity information.
677 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
679 * @privilege %http://tizen.org/privilege/location
680 * @param[in] manager The location manager handle
681 * @param[out] climb The last climb (km/h)
682 * @param[out] direction The last direction, degrees from the north
683 * @param[out] speed The last speed (km/h)
684 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
685 * @return @c 0 on success,
686 * otherwise a negative error value
687 * @retval #LOCATIONS_ERROR_NONE Successful
688 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
689 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
690 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
691 * @pre The location manager handle must be created by location_manager_create().
693 int location_manager_get_last_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
697 * @brief Gets the last accuracy information which is recorded.
698 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
700 * @privilege %http://tizen.org/privilege/location
701 * @param[in] manager The location manager handle
702 * @param[out] level The last accuracy level
703 * @param[out] horizontal The last horizontal accuracy (meters)
704 * @param[out] vertical The last vertical accuracy (meters)
705 * @return @c 0 on success,
706 * otherwise a negative error value
707 * @retval #LOCATIONS_ERROR_NONE Successful
708 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
709 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
710 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
711 * @pre The location manager handle must be created by location_manager_create().
713 int location_manager_get_last_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
717 * @deprecated Deprecated since 3.0
718 * @brief Gets the current application's location accessibility status.
719 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
720 * @param[out] state The current location service accessibility status
721 * @return @c 0 on success,
722 * otherwise a negative error value
723 * @retval #LOCATIONS_ERROR_NONE Successful
724 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
725 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
726 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
728 int location_manager_get_accessibility_state(location_accessibility_state_e *state) TIZEN_DEPRECATED_API;
732 * @brief Registers a callback function to be invoked at defined interval with updated position information.
733 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
734 * @param[in] manager The location manager handle
735 * @param[in] callback The callback function to register
736 * @param[in] interval The interval [1 ~ 120] (seconds)
737 * @param[in] user_data The user data to be passed to the callback function
738 * @return @c 0 on success,
739 * otherwise a negative error value
740 * @retval #LOCATIONS_ERROR_NONE Successful
741 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
742 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
743 * @post location_position_updated_cb() will be invoked.
744 * @see location_manager_unset_position_updated_cb()
745 * @see location_position_updated_cb()
747 int location_manager_set_position_updated_cb(location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data);
751 * @brief Unregisters the callback function.
752 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
753 * @param[in] manager The location manager handle
754 * @return @c 0 on success,
755 * otherwise a negative error value
756 * @retval #LOCATIONS_ERROR_NONE Successful
757 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
758 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
759 * @see location_manager_set_position_updated_cb()
761 int location_manager_unset_position_updated_cb(location_manager_h manager);
765 * @brief Registers a callback function to be invoked at defined interval with updated velocity information.
766 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
767 * @param[in] manager The location manager handle
768 * @param[in] callback The callback function to register
769 * @param[in] interval The interval [1 ~ 120] (seconds)
770 * @param[in] user_data The user data to be passed to the callback function
771 * @return @c 0 on success,
772 * otherwise a negative error value
773 * @retval #LOCATIONS_ERROR_NONE Successful
774 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
775 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
776 * @post location_velocity_updated_cb() will be invoked.
777 * @see location_manager_unset_velocity_updated_cb()
778 * @see location_velocity_updated_cb()
780 int location_manager_set_velocity_updated_cb(location_manager_h manager, location_velocity_updated_cb callback, int interval, void *user_data);
784 * @brief Unregisters the callback function.
785 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
786 * @param[in] manager The location manager handle
787 * @return @c 0 on success,
788 * otherwise a negative error value
789 * @retval #LOCATIONS_ERROR_NONE Successful
790 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
791 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
792 * @see location_manager_set_velocity_updated_cb()
794 int location_manager_unset_velocity_updated_cb(location_manager_h manager);
798 * @brief Registers a callback function to be invoked when the location service state is changed.
799 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
800 * @param[in] manager The location manager handle
801 * @param[in] callback The callback function to register
802 * @param[in] user_data The user data to be passed to the callback function
803 * @return @c 0 on success,
804 * 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_service_state_changed_cb() will be invoked.
809 * @see location_manager_unset_service_state_changed_cb()
810 * @see location_service_state_changed_cb()
811 * @see location_manager_start()
812 * @see location_manager_stop()
813 * @see #location_service_state_e
815 int location_manager_set_service_state_changed_cb(location_manager_h manager, location_service_state_changed_cb callback, void *user_data);
819 * @brief Unregisters the callback function.
820 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
821 * @param[in] manager The location manager handle
822 * @return @c 0 on success,
823 * otherwise a negative error value
824 * @retval #LOCATIONS_ERROR_NONE Successful
825 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
826 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
827 * @see location_manager_set_service_state_changed_cb()
829 int location_manager_unset_service_state_changed_cb(location_manager_h manager);
833 * @brief Registers a callback function to be invoked when the previously set boundary area is entered or left.
834 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
835 * @param[in] manager The location manager handle
836 * @param[in] callback The callback function to register
837 * @param[in] user_data The user data to be passed to the callback function
838 * @return @c 0 on success,
839 * otherwise a negative error value
840 * @retval #LOCATIONS_ERROR_NONE Successful
841 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
842 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
843 * @pre location_manager_add_boundary() is called before.
844 * @post location_zone_changed_cb() will be invoked.
845 * @see location_manager_unset_zone_changed_cb()
846 * @see location_zone_changed_cb()
848 int location_manager_set_zone_changed_cb(location_manager_h manager, location_zone_changed_cb callback, void *user_data);
852 * @brief Unregisters the callback function.
853 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
854 * @param[in] manager The location manager handle
855 * @return @c 0 on success,
856 * otherwise a negative error value
857 * @retval #LOCATIONS_ERROR_NONE Successful
858 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
859 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
860 * @see location_manager_set_zone_changed_cb()
862 int location_manager_unset_zone_changed_cb(location_manager_h manager);
866 * @brief Registers a callback function to be invoked when the location setting is changed.
867 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
868 * @param[in] method The method to observe
869 * @param[in] callback The callback function to register
870 * @param[in] user_data The user data to be passed to the callback function
871 * @return @c 0 on success,
872 * otherwise a negative error value
873 * @retval #LOCATIONS_ERROR_NONE Successful
874 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
875 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
876 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
877 * @post location_setting_changed_cb() will be invoked.
878 * @see location_manager_unset_setting_changed_cb()
879 * @see location_setting_changed_cb()
881 int location_manager_set_setting_changed_cb(location_method_e method, location_setting_changed_cb callback, void *user_data);
885 * @brief Unregisters the callback function.
886 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
887 * @param[in] method The method to observe
888 * @return @c 0 on success,
889 * otherwise a negative error value
890 * @retval #LOCATIONS_ERROR_NONE Successful
891 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
892 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
893 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
894 * @see location_manager_set_setting_changed_cb()
896 int location_manager_unset_setting_changed_cb(location_method_e method);
900 * @brief Gets the distance in meters between two locations.
901 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
902 * @param[in] start_latitude The starting latitude [-90.0 ~ 90.0] (degrees)
903 * @param[in] start_longitude The starting longitude [-180.0 ~ 180.0] (degrees)
904 * @param[in] end_latitude The ending latitude [-90.0 ~ 90.0] (degrees)
905 * @param[in] end_longitude The ending longitude [-180.0 ~ 180.0] (degrees)
906 * @param[out] distance The distance between two locations (meters)
907 * @return @c 0 on success,
908 * otherwise a negative error value
909 * @retval #LOCATIONS_ERROR_NONE Successful
910 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
911 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
913 int location_manager_get_distance(double start_latitude, double start_longitude, double end_latitude, double end_longitude, double *distance);
917 * @brief Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.
918 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
919 * @param[in] manager The location manager handle
920 * @param[in] callback The callback function to register
921 * @param[in] interval The minimum interval between position updates [1 ~ 120] (seconds)
922 * @param[in] distance The minimum distance between position updates [1 ~ 120] (meters)
923 * @param[in] user_data The user data to be passed to the callback function
924 * @return @c 0 on success,
925 * otherwise a negative error value
926 * @retval #LOCATIONS_ERROR_NONE Successful
927 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
928 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
929 * @post location_changed_cb() will be invoked.
930 * @see location_manager_unset_distance_based_location_changed_cb()
931 * @see location_changed_cb()
933 int location_manager_set_distance_based_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, double distance, void *user_data);
937 * @brief Unregisters the callback function.
938 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
939 * @param[in] manager The location manager handle
940 * @return @c 0 on success,
941 * otherwise a negative error value
942 * @retval #LOCATIONS_ERROR_NONE Successful
943 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
944 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
945 * @see location_manager_set_distance_based_location_changed_cb()
947 int location_manager_unset_distance_based_location_changed_cb(location_manager_h manager);
951 * @brief Registers a callback function to be invoked at defined interval with updated location information.
952 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
953 * @param[in] manager The location manager handle
954 * @param[in] callback The callback function to register
955 * @param[in] interval The interval [1 ~ 120] (seconds)
956 * @param[in] user_data The user data to be passed to the callback function
957 * @return @c 0 on success,
958 * otherwise a negative error value
959 * @retval #LOCATIONS_ERROR_NONE Successful
960 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
961 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
962 * @post location_changed_cb() will be invoked.
963 * @see location_manager_unset_location_changed_cb()
964 * @see location_changed_cb()
966 int location_manager_set_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, void *user_data);
970 * @brief Unregisters the callback function.
971 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
972 * @param[in] manager The location manager handle
973 * @return @c 0 on success,
974 * otherwise a negative error value
975 * @retval #LOCATIONS_ERROR_NONE Successful
976 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
977 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
978 * @see location_manager_set_location_changed_cb()
980 int location_manager_unset_location_changed_cb(location_manager_h manager);
984 * @brief Registers a callback function to be invoked when batch_period is expired.
985 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
986 * @remarks The batch_period should be greater than or equal to the batch_interval.
987 * In addition, sometimes the period may not work as you intended, the maximum permissible value for batch_period is device specific.
988 * @param[in] manager The location manager handle
989 * @param[in] callback The callback function to register
990 * @param[in] batch_interval The batch sampling interval [1 ~ 255] (seconds)
991 * @param[in] batch_period The batch period [1 ~ 60000] (seconds)
992 * @param[in] user_data The user data to be passed to the callback function
993 * @return @c 0 on success,
994 * otherwise a negative error value
995 * @retval #LOCATIONS_ERROR_NONE Successful
996 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
997 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
998 * @post location_batch_cb() will be invoked.
999 * @see location_manager_start_batch()
1000 * @see location_batch_cb()
1001 * @see location_manager_unset_location_batch_cb()
1003 int location_manager_set_location_batch_cb(location_manager_h manager, location_batch_cb callback, int batch_interval, int batch_period, void *user_data);
1007 * @brief Unregisters the callback function.
1008 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1009 * @param[in] manager The location manager handle
1010 * @return @c 0 on success,
1011 * otherwise a negative error value
1012 * @retval #LOCATIONS_ERROR_NONE Successful
1013 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1014 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1015 * @see location_manager_set_location_batch_cb()
1017 int location_manager_unset_location_batch_cb(location_manager_h manager);
1021 * @brief Starts the location batch service.
1022 * @details Calling this function starts location batch service, location_batch_cb() will be invoked every @a batch_period seconds.
1023 * After that, you can obtain all locations with location_manager_foreach_location_batch().
1024 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1026 * @privilege %http://tizen.org/privilege/location
1027 * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
1028 * (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as the first argument, and the service starts.
1029 * @param[in] manager The location manager handle
1030 * @return @c 0 on success,
1031 * otherwise a negative error value
1032 * @retval #LOCATIONS_ERROR_NONE Successful
1033 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1034 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1035 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1036 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
1037 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
1038 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1039 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1040 * @pre location_manager_set_location_batch_cb()
1041 * @see location_manager_set_service_state_changed_cb()
1042 * @see location_service_state_changed_cb()
1043 * @see location_manager_foreach_location_batch()
1044 * @see location_manager_stop_batch()
1046 int location_manager_start_batch(location_manager_h manager);
1050 * @brief Stops the location batch service.
1051 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1052 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
1053 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as the first argument.
1054 * @param[in] manager The location manager handle
1055 * @return @c 0 on success,
1056 * otherwise a negative error value
1057 * @retval #LOCATIONS_ERROR_NONE Successful
1058 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1059 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1060 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
1061 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1062 * @see location_manager_start_batch()
1063 * @see location_manager_set_service_state_changed_cb()
1064 * @see location_service_state_changed_cb()
1066 int location_manager_stop_batch(location_manager_h manager);
1070 * @brief Retrieves all location information by invoking a specific callback for each location data.
1071 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1073 * @privilege %http://tizen.org/privilege/location
1074 * @param[in] manager The location manager handle
1075 * @param[in] callback The iteration callback function
1076 * @param[in] user_data The user data to be passed to the callback function
1077 * @return @c 0 on success,
1078 * otherwise a negative error value
1079 * @retval #LOCATIONS_ERROR_NONE Successful
1080 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1081 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1082 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1083 * @pre location_manager_foreach_location_batch() is available after location_batch_cb() is invoked.
1084 * @post location_batch_get_location_cb() will be invoked.
1085 * @see location_manager_start_batch()
1086 * @see location_batch_cb()
1087 * @see location_batch_get_location_cb()
1089 int location_manager_foreach_location_batch(location_manager_h manager, location_batch_get_location_cb callback, void *user_data);
1093 * @brief Checks whether the mock location is enabled.
1095 * @param[out] enabled Indicates whether the mock location is enabled
1096 * @return @c 0 on success,
1097 * otherwise a negative error value
1098 * @retval #LOCATIONS_ERROR_NONE Successful
1099 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1100 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1101 * @see location_manager_enable_mock_location()
1102 * @see location_manager_set_mock_location()
1103 * @see location_manager_clear_mock_location()
1105 int location_manager_is_enabled_mock_location(bool *enabled);
1109 * @brief Enables mock location.
1110 * @details The mock location is a testing function to make location API and callback deliver a mock location
1111 * set by location_manager_set_mock_location() instead of real positioning data even in the other applications.
1114 * @privilege %http://tizen.org/privilege/location
1115 * @remarks The mock location can only be enabled if developer mode is enabled.
1116 * @param[in] enable The value to set
1117 * @return @c 0 on success,
1118 * otherwise a negative error value
1119 * @retval #LOCATIONS_ERROR_NONE Successful
1120 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1121 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
1122 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1123 * @see location_manager_is_enabled_mock_location()
1124 * @see location_manager_set_mock_location()
1125 * @see location_manager_clear_mock_location()
1127 int location_manager_enable_mock_location(const bool enable);
1131 * @brief Sets a mock location for the given location method.
1132 * @details The location sets the given altitude, latitude, longitude, climb, direction, speed, level, horizontal, and vertical accuracy.
1135 * @privilege %http://tizen.org/privilege/location
1136 * @param[in] manager The location manager handle
1137 * @param[in] latitude The current latitude [-90.0 ~ 90.0] (degrees)
1138 * @param[in] longitude The current longitude [-180.0 ~ 180.0] (degrees)
1139 * @param[in] altitude The current altitude (meters)
1140 * @param[in] speed The speed (km/h)
1141 * @param[in] direction The direction, degrees from the north [0.0 ~ 360.0]
1142 * @param[in] accuracy The horizontal accuracy (meters)
1143 * @return @c 0 on success,
1144 * otherwise a negative error value
1145 * @retval #LOCATIONS_ERROR_NONE Successful
1146 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1147 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1148 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1149 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1150 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1151 * @see location_manager_create()
1152 * @see location_manager_is_enabled_mock_location()
1153 * @see location_manager_enable_mock_location()
1154 * @see location_manager_clear_mock_location()
1156 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);
1160 * @brief Clears a mock location.
1163 * @privilege %http://tizen.org/privilege/location
1164 * @param[in] manager The location manager handle
1165 * @return @c 0 on success,
1166 * otherwise a negative error value
1167 * @retval #LOCATIONS_ERROR_NONE Successful
1168 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1169 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1170 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1171 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1172 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1173 * @see location_manager_create()
1174 * @see location_manager_is_enabled_mock_location()
1175 * @see location_manager_enable_mock_location()
1176 * @see location_manager_set_mock_location()
1178 int location_manager_clear_mock_location(location_manager_h manager);
1187 * GPS Status & Satellites
1192 * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE
1198 * @brief Called once for each satellite in range.
1199 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1200 * @param[in] azimuth The azimuth of the satellite (degrees)
1201 * @param[in] elevation The elevation of the satellite (meters)
1202 * @param[in] prn The PRN of the satellite
1203 * @param[in] snr The SNR of the satellite [dB]
1204 * @param[in] is_active The flag signaling if satellite is in use
1205 * @param[in] user_data The user data passed from the foreach function
1206 * @return @c true to continue with the next iteration of the loop, \n
1207 * @c false to break out of the loop
1208 * @pre gps_status_foreach_satellites_in_view() will invoke this callback.
1209 * @pre gps_status_foreach_last_satellites_in_view() will invoke this callback.
1210 * @see gps_status_foreach_satellites_in_view()
1212 typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data);
1216 * @brief Called at defined interval with updated satellite information.
1217 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1218 * @param[out] num_of_active The last number of active satellites
1219 * @param[out] num_of_inview The last number of satellites in view
1220 * @param[out] timestamp The last timestamp (time when measurement took place or @c 0 if valid)
1221 * @param[in] user_data The user data passed from the call registration function
1222 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
1223 * @see location_manager_start()
1224 * @see location_manager_set_position_updated_cb()
1226 typedef void(*gps_status_satellite_updated_cb)(int num_of_active, int num_of_inview, time_t timestamp, void *user_data);
1230 * @brief Gets the GPS NMEA data.
1231 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1232 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1233 * You must release @a nmea using @c free().
1234 * @param[in] manager The location manager handle
1235 * @param[out] nmea The NMEA data
1236 * @return @c 0 on success,
1237 * otherwise a negative error value
1238 * @retval #LOCATIONS_ERROR_NONE Successful
1239 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1240 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1241 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1242 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1243 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1244 * @see location_manager_start()
1246 int gps_status_get_nmea(location_manager_h manager, char **nmea);
1250 * @brief Gets the information of satellites.
1251 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1253 * @privilege %http://tizen.org/privilege/location
1254 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1255 * @param[in] manager The location manager handle
1256 * @param[out] num_of_active The number of active satellites
1257 * @param[out] num_of_inview The number of satellites in view
1258 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
1259 * @return @c 0 on success,
1260 * otherwise a negative error value
1261 * @retval #LOCATIONS_ERROR_NONE Successful
1262 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1263 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1264 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1265 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1266 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1267 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1268 * @see gps_status_foreach_satellites_in_view()
1270 int gps_status_get_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1274 * @brief Registers a callback function to be invoked at defined interval with updated satellite information.
1275 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1277 * @privilege %http://tizen.org/privilege/location
1278 * @param[in] manager The location manager handle
1279 * @param[in] callback The callback function to register
1280 * @param[in] interval The interval [1 ~ 120] (seconds)
1281 * @param[in] user_data The user data to be passed to the callback function
1282 * @return @c 0 on success,
1283 * otherwise a negative error value
1284 * @retval #LOCATIONS_ERROR_NONE Successful
1285 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1286 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1287 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1288 * @post gps_status_satellite_updated_cb() will be invoked.
1289 * @see gps_status_unset_satellite_updated_cb()
1290 * @see gps_status_satellite_updated_cb()
1291 * @see gps_status_get_satellite()
1292 * @see gps_status_foreach_satellites_in_view()
1293 * @see gps_status_get_last_satellite()
1294 * @see gps_status_foreach_last_satellites_in_view()
1296 int gps_status_set_satellite_updated_cb(location_manager_h manager, gps_status_satellite_updated_cb callback, int interval, void *user_data);
1300 * @brief Unregisters the callback function.
1301 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1302 * @param[in] manager The location manager handle
1303 * @return @c 0 on success,
1304 * otherwise a negative error value
1305 * @retval #LOCATIONS_ERROR_NONE Successful
1306 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1307 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1308 * @see gps_status_set_satellite_updated_cb()
1310 int gps_status_unset_satellite_updated_cb(location_manager_h manager);
1314 * @brief Invokes the callback function for each satellite.
1315 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1317 * @privilege %http://tizen.org/privilege/location
1318 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1319 * @param[in] manager The location manager handle
1320 * @param[in] callback The iteration callback function
1321 * @param[in] user_data The user data to be passed to the callback function
1322 * @return @c 0 on success,
1323 * otherwise a negative error value
1324 * @retval #LOCATIONS_ERROR_NONE Successful
1325 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1326 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1327 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1328 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1329 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1330 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1331 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1332 * @post It invokes gps_status_get_satellites_cb().
1333 * @see gps_status_get_satellite()
1334 * @see gps_status_get_satellites_cb()
1336 int gps_status_foreach_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1340 * @brief Gets the last information of satellites.
1341 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1343 * @privilege %http://tizen.org/privilege/location
1344 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1345 * @param[in] manager The location manager handle
1346 * @param[out] num_of_active The last number of active satellites
1347 * @param[out] num_of_inview The last number of satellites in view
1348 * @param[out] timestamp The last timestamp (time when last measurement took place or @c 0 if valid)
1349 * @return @c 0 on success,
1350 * otherwise a negative error value
1351 * @retval #LOCATIONS_ERROR_NONE Successful
1352 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1353 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1354 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1355 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1356 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1357 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1358 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1359 * @see gps_status_foreach_satellites_in_view()
1361 int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1365 * @brief Invokes the callback function for each last satellite which is recorded.
1366 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1368 * @privilege %http://tizen.org/privilege/location
1369 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1370 * @param[in] manager The location manager handle
1371 * @param[in] callback The iteration callback function
1372 * @param[in] user_data The user data to be passed to the callback function
1373 * @return @c 0 on success,
1374 * otherwise a negative error value
1375 * @retval #LOCATIONS_ERROR_NONE Successful
1376 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1377 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1378 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1379 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1380 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1381 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1382 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1383 * @post It invokes gps_status_get_satellites_cb().
1384 * @see gps_status_get_last_satellite()
1385 * @see gps_status_get_satellites_cb()
1387 int gps_status_foreach_last_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1397 #endif /* __TIZEN_LOCATION_LOCATIONS_H__ */