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
37 * @brief Enumeration for error code for Location manager.
38 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
41 LOCATIONS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
42 LOCATIONS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
43 LOCATIONS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
44 LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
45 LOCATIONS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
46 LOCATIONS_ERROR_INCORRECT_METHOD = TIZEN_ERROR_LOCATION_MANAGER | 0x01, /**< Location manager contains incorrect method for a given call */
47 LOCATIONS_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_MANAGER | 0x02, /**< Network unavailable */
48 LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_MANAGER | 0x03, /**< Location service is not available */
49 LOCATIONS_ERROR_GPS_SETTING_OFF = TIZEN_ERROR_LOCATION_MANAGER | 0x04, /**< Setting for GPS, WPS, or MOCK is turned off */
50 LOCATIONS_ERROR_SECURITY_RESTRICTED = TIZEN_ERROR_LOCATION_MANAGER | 0x05, /**< Restricted by security system policy */
51 LOCATIONS_ERROR_SETTING_OFF = LOCATIONS_ERROR_GPS_SETTING_OFF, /**< Setting for GPS, WPS, or MOCK is turned off (Since 3.0) */
56 * @brief Enumeration for Location method type.
57 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
60 LOCATIONS_METHOD_NONE = -1, /**< Undefined method */
61 LOCATIONS_METHOD_HYBRID, /**< This method selects the best method available at the moment */
62 LOCATIONS_METHOD_GPS, /**< This method uses Global Positioning System */
63 LOCATIONS_METHOD_WPS, /**< This method uses WiFi Positioning System */
64 LOCATIONS_METHOD_PASSIVE, /**< This method can be used to passively receive location updates without power consumption (Since 3.0)*/
69 * @brief Enumeration for Approximate accuracy level of given information.
70 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
73 LOCATIONS_ACCURACY_NONE = 0, /**< Invalid data */
74 LOCATIONS_ACCURACY_COUNTRY, /**< Country accuracy level */
75 LOCATIONS_ACCURACY_REGION, /**< Regional accuracy level */
76 LOCATIONS_ACCURACY_LOCALITY, /**< Local accuracy level */
77 LOCATIONS_ACCURACY_POSTALCODE, /**< Postal accuracy level */
78 LOCATIONS_ACCURACY_STREET, /**< Street accuracy level */
79 LOCATIONS_ACCURACY_DETAILED, /**< Detailed accuracy level */
80 } location_accuracy_level_e;
84 * @brief Enumeration for the state of the location service.
85 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
88 LOCATIONS_SERVICE_DISABLED, /**< Service is disabled */
89 LOCATIONS_SERVICE_ENABLED, /**< Service is enabled */
90 } location_service_state_e;
94 * @deprecated Deprecated since 3.0
95 * @brief Enumeration for the location service accessibility state.
96 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
99 LOCATIONS_ACCESS_STATE_NONE, /**< Access state is not determined */
100 LOCATIONS_ACCESS_STATE_DENIED, /**< Access denied */
101 LOCATIONS_ACCESS_STATE_ALLOWED, /**< Access authorized */
102 } location_accessibility_state_e;
106 * @brief The location manager handle.
107 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
109 typedef struct location_manager_s *location_manager_h;
119 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
125 * @brief Called at defined interval with updated position information.
126 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
127 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
128 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
129 * @param[in] altitude The updated altitude (meters)
130 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
131 * @param[in] user_data The user data passed from the call registration function
132 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
133 * @see location_manager_start()
134 * @see location_manager_set_position_updated_cb()
136 typedef void(*location_position_updated_cb)(double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
140 * @brief Called at defined interval with updated velocity information.
141 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
142 * @param[in] speed The updated speed (km/h)
143 * @param[in] direction The updated direction (in degrees from the north)
144 * @param[in] climb The updated climb (km/h)
145 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
146 * @param[in] user_data The user data passed from the callback registration function
147 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb().
148 * @see location_manager_start()
149 * @see location_manager_set_velocity_updated_cb()
151 typedef void(*location_velocity_updated_cb)(double speed, double direction, double climb, time_t timestamp, void *user_data);
155 * @brief Called at defined interval with updated location information.
156 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
157 * @param[in] error #LOCATIONS_ERROR_NONE Successful
158 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
159 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
160 * @param[in] altitude The updated altitude (meters)
161 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
162 * @param[in] speed The updated speed (km/h)
163 * @param[in] direction The updated direction (in degrees from the north)
164 * @param[in] climb The updated climb (km/h)
165 * @param[in] user_data The user data passed from the callback registration function
166 * @pre location_manager_request_single_location() will invoke this callback.
167 * @see location_manager_request_single_location()
169 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);
173 * @brief Called when the state of location service is changed from enabled to disabled or vice versa.
174 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
175 * @param[in] state The service state
176 * @param[in] user_data The user data passed from the callback registration function
177 * @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().
178 * @see location_manager_start()
179 * @see location_manager_stop()
180 * @see location_manager_set_service_state_changed_cb()
181 * @see #location_service_state_e
183 typedef void(*location_service_state_changed_cb)(location_service_state_e state, void *user_data);
187 * @brief Called when the user-defined zones are entered or exited.
188 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
189 * @param[in] state The boundary state
190 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
191 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
192 * @param[in] altitude The updated altitude (meters)
193 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
194 * @param[in] user_data The user data passed from the callback registration function
195 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb().
196 * @see #location_boundary_state_e
197 * @see location_manager_start()
198 * @see location_manager_set_zone_changed_cb()
200 typedef void(*location_zone_changed_cb)(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
204 * @brief Called when the state of location method is changed.
205 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
206 * @param[in] method The method changed on setting
207 * @param[in] enable The setting value changed
208 * @param[in] user_data The user data passed from the callback registration function
209 * @pre location_setting_changed_cb() will invoke this callback if you register this callback using location_manager_set_setting_changed_cb().
210 * @see location_manager_set_setting_changed_cb()
211 * @see location_manager_unset_setting_changed_cb()
213 typedef void(*location_setting_changed_cb)(location_method_e method, bool enable, void *user_data);
217 * @brief Called once for each location bound.
218 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
219 * @param[in] bounds The location bounds handle
220 * @param[in] user_data The user data passed from the callback registration function
221 * @return @c true to continue with the next iteration of the loop,
222 * otherwise @c false to break out of the loop
223 * @pre location_manager_foreach_boundary() will invoke this callback.
224 * @see location_manager_foreach_boundary()
226 typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
230 * @brief Called at defined interval with updated location information.
231 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
232 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
233 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
234 * @param[in] altitude The updated altitude (meters)
235 * @param[in] speed The updated speed (km/h)
236 * @param[in] direction The updated direction (in degrees from the north)
237 * @param[in] horizontal_accuracy The horizontal accuracy (meters)
238 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
239 * @param[in] user_data The user data passed from the callback registration function
240 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
241 * @see location_manager_start()
242 * @see location_manager_set_distance_based_location_changed_cb()
243 * @see location_manager_set_location_changed_cb()
245 typedef void(*location_changed_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data);
249 * @brief Called when the batch interval is expired.
250 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
251 * @param[in] num_of_location The number of location batch data
252 * @param[in] user_data The user data passed from the callback registration function
253 * @pre location_manager_start_batch() will invoke this callback if you register this callback using location_manager_set_location_batch_cb().
254 * @see location_manager_start_batch()
255 * @see location_manager_set_location_batch_cb()
257 typedef void(*location_batch_cb)(int num_of_location, void *user_data);
261 * @brief Gets iteratively to receive location batch data.
262 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
263 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
264 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
265 * @param[in] altitude The updated altitude (meters)
266 * @param[in] speed The updated speed (km/h)
267 * @param[in] direction The updated direction (in degrees from the north)
268 * @param[in] horizontal The horizontal accuracy (meters)
269 * @param[in] vertical The vertical accuracy (meters)
270 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
271 * @param[in] user_data The user data passed from the callback registration function
272 * @return @c true to continue with the next iteration of the loop,
273 * otherwise @c false to break out of the loop
274 * @pre location_manager_foreach_location_batch() will invoke this callback
275 * @see location_manager_foreach_location_batch()
277 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);
281 * @brief Checks whether the given location method is available.
282 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
283 * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
284 * @param[in] method The location method to be checked
285 * @return @c true if the specified location method is supported,
286 * otherwise @c false if it is not available
287 * @retval #LOCATIONS_ERROR_NONE Successful
288 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
289 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
290 * @see location_manager_create()
291 * @see location_manager_get_method()
293 bool location_manager_is_supported_method(location_method_e method);
297 * @brief Checks whether the given location method is enabled or not on setting.
298 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
299 * @param[in] method The location method to be checked
300 * @param[out] enable The result value of checking the given location method
301 * @return @c 0 on success,
302 * otherwise a negative error value
303 * @retval #LOCATIONS_ERROR_NONE Successful
304 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
305 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
306 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
307 * @see location_manager_create()
308 * @see location_manager_set_setting_changed_cb()
309 * @see location_manager_unset_setting_changed_cb()
311 int location_manager_is_enabled_method(location_method_e method, bool *enable);
316 * @brief Enables the given location method.
318 * @privlevel platform
319 * @privilege %http://tizen.org/privilege/location.enable
320 * @param[in] method The location method to be checked
321 * @param[in] enable The value to set
322 * @return @c 0 on success,
323 * otherwise a negative error value
324 * @retval #LOCATIONS_ERROR_NONE Successful
325 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
326 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
327 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
328 * @see location_manager_is_enabled_method()
329 * @see location_manager_create()
331 int location_manager_enable_method(const location_method_e method, const bool enable);
335 * @brief Creates a new location manager.
336 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
337 * @remarks You must release @a manager using location_manager_destroy().
338 * @param[in] method The location method
339 * @param[out] manager The location manager handle that is newly created
340 * @return @c 0 on success,
341 * otherwise a negative error value
342 * @retval #LOCATIONS_ERROR_NONE Successful
343 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
344 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
345 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
346 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
347 * @see location_manager_destroy()
349 int location_manager_create(location_method_e method, location_manager_h *manager);
353 * @brief Releases the location manager.
354 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
355 * @param[in] manager The location manager handle
356 * @return @c 0 on success,
357 * otherwise a negative error value
358 * @retval #LOCATIONS_ERROR_NONE Successful
359 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
360 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
361 * @see location_manager_create()
363 int location_manager_destroy(location_manager_h manager);
367 * @brief Requests to update current location once.
368 * @remarks Do not request to start the location service using the same manager handler
369 * Calling this function invokes a location service event.
370 * When the location service is updated, location_updated_cb
371 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
373 * @privilege %http://tizen.org/privilege/location
374 * @param[in] manager The location manager handle
375 * @param[in] timeout Timeout to stop requesting single location after
376 * @param[in] callback The location callback function to register
377 * @param[in] user_data The user data to be passed to the callback function
378 * @retval #LOCATIONS_ERROR_NONE Successful
379 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
380 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
381 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
382 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
383 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
384 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
385 * @post It invokes location_updated_cb().
387 int location_manager_request_single_location(location_manager_h manager, int timeout, location_updated_cb callback, void *user_data);
391 * @brief Starts the location service.
392 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
394 * @privilege %http://tizen.org/privilege/location
395 * @remarks There is no limit on number of location managers for which this function was called.
396 * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
397 * (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as
398 * the first argument, and the service starts.
399 * @remarks The started service is a requirement for calling these functions:
400 * location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(),
401 * gps_status_get_nmea(), gps_status_get_satellite(), gps_status_foreach_satellites_in_view().
402 * @remarks Once you stop the service using location_manager_stop(), you can no longer call the functions listed above.
403 * @remarks Starting and stopping the service is in the scope of the given location manager only (if there is more than one manager,
404 * starting and stopping should be executed for each of them separately).
405 * @param[in] manager The location manager handle
406 * @return @c 0 on success,
407 * otherwise a negative error value
408 * @retval #LOCATIONS_ERROR_NONE Successful
409 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
410 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
411 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
412 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
413 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
414 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
415 * @post It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().
416 * @see location_manager_stop()
417 * @see location_manager_get_position()
418 * @see location_manager_get_velocity()
419 * @see location_manager_get_accuracy()
420 * @see location_manager_set_service_state_changed_cb()
421 * @see location_manager_set_position_updated_cb()
422 * @see location_position_updated_cb()
423 * @see location_manager_set_velocity_updated_cb()
424 * @see location_velocity_updated_cb()
425 * @see location_manager_set_zone_changed_cb()
426 * @see location_zone_changed_cb()
428 int location_manager_start(location_manager_h manager);
432 * @brief Stops the location service.
433 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
434 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
435 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
436 * When that happens, the service is stopped and the user is notified.
437 * @remarks You can stop and start the location manager as needed.
438 * @param[in] manager The location manager handle
439 * @return @c 0 on success,
440 * otherwise a negative error value
441 * @retval #LOCATIONS_ERROR_NONE Successful
442 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
443 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
444 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
445 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
446 * @see location_manager_start()
447 * @see location_manager_set_service_state_changed_cb()
448 * @see location_service_state_changed_cb()
450 int location_manager_stop(location_manager_h manager);
454 * @brief Adds bounds for a given location manager.
455 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
456 * @param[in] manager The location manager handle
457 * @param[in] bounds The location bounds handle
458 * @return @c 0 on success,
459 * otherwise a negative error value
460 * @retval #LOCATIONS_ERROR_NONE Successful
461 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
462 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
463 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
464 * @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().
465 * @see location_manager_remove_boundary()
466 * @see location_manager_set_zone_changed_cb()
468 int location_manager_add_boundary(location_manager_h manager, const location_bounds_h bounds);
472 * @brief Deletes bounds for a given location manager.
473 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
474 * @param[in] manager The location manager handle
475 * @param[in] bounds The location bounds handle
476 * @return @c 0 on success,
477 * otherwise a negative error value
478 * @retval #LOCATIONS_ERROR_NONE Successful
479 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
480 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
481 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
482 * @see location_manager_add_boundary()
484 int location_manager_remove_boundary(location_manager_h manager, const location_bounds_h bounds);
488 * @brief Retrieves all location bounds by invoking a specific callback for each location bounds
489 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
490 * @param[in] manager The location manager handle
491 * @param[in] callback The iteration callback
492 * @param[in] user_data The user data to be passed to the callback function
493 * @return @c 0 on success,
494 * otherwise a negative error value
495 * @retval #LOCATIONS_ERROR_NONE Successful
496 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
497 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
498 * @post location_bounds_cb() will be invoked.
499 * @see location_manager_add_boundary()
500 * @see location_manager_remove_boundary()
501 * @see location_bounds_cb()
503 int location_manager_foreach_boundary(location_manager_h manager, location_bounds_cb callback, void *user_data);
507 * @brief Gets the given location manager's method.
508 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
509 * @param[in] manager The location manager handle
510 * @param[out] method The location method
511 * @return @c 0 on success,
512 * otherwise a negative error value
513 * @retval #LOCATIONS_ERROR_NONE Successful
514 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
515 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
516 * @see location_manager_create()
518 int location_manager_get_method(location_manager_h manager, location_method_e *method);
522 * @brief Gets the current position information.
523 * @details The result contains the current altitude, latitude, and longitude with a measurement timestamp.
524 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
526 * @privilege %http://tizen.org/privilege/location
527 * @param[in] manager The location manager handle
528 * @param[out] altitude The current altitude (meters)
529 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
530 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
531 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
532 * @return @c 0 on success,
533 * otherwise a negative error value
534 * @retval #LOCATIONS_ERROR_NONE Successful
535 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
536 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
537 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
538 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
539 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
540 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
542 int location_manager_get_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
546 * @brief Gets the current position information.
547 * @details The result contains the current altitude, latitude, longitude, climb, direction, speed, level, horizontal, and vertical with a measurement timestamp.
548 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
550 * @privilege %http://tizen.org/privilege/location
551 * @param[in] manager The location manager handle
552 * @param[out] altitude The current altitude (meters)
553 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
554 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
555 * @param[out] climb The climb (km/h)
556 * @param[out] direction The direction, degrees from the north
557 * @param[out] speed The speed (km/h)
558 * @param[out] level The accuracy level
559 * @param[out] horizontal The horizontal accuracy (meters)
560 * @param[out] vertical The vertical accuracy (meters)
561 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
562 * @return @c 0 on success,
563 * otherwise a negative error value
564 * @retval #LOCATIONS_ERROR_NONE Successful
565 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
566 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
567 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
568 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
569 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
570 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
572 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);
576 * @brief Gets the current velocity information.
577 * @details The result contains the current climb, direction, and speed with a measurement timestamp.
578 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
580 * @privilege %http://tizen.org/privilege/location
581 * @param[in] manager The location manager handle
582 * @param[out] climb The climb (km/h)
583 * @param[out] direction The direction, degrees from the north
584 * @param[out] speed The speed (km/h)
585 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
586 * @return @c 0 on success,
587 * otherwise a negative error value
588 * @retval #LOCATIONS_ERROR_NONE Successful
589 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
590 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
591 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
592 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
593 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
594 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
596 int location_manager_get_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
600 * @brief Gets the current accuracy information.
601 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
603 * @privilege %http://tizen.org/privilege/location
604 * @param[in] manager The location manager handle
605 * @param[out] level The accuracy level
606 * @param[out] horizontal The horizontal accuracy (meters)
607 * @param[out] vertical The vertical accuracy (meters)
608 * @return @c 0 on success,
609 * otherwise a negative error value
610 * @retval #LOCATIONS_ERROR_NONE Successful
611 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
612 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
613 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
614 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
615 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
616 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
618 int location_manager_get_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
622 * @brief Gets the last position information which is recorded.
623 * @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.
624 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
626 * @privilege %http://tizen.org/privilege/location
627 * @param[in] manager The location manager handle
628 * @param[out] altitude The last altitude (meters)
629 * @param[out] latitude The last latitude [-90.0 ~ 90.0] (degrees)
630 * @param[out] longitude The last longitude [-180.0 ~ 180.0] (degrees)
631 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
632 * @return @c 0 on success,
633 * otherwise a negative error value
634 * @retval #LOCATIONS_ERROR_NONE Successful
635 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
636 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
637 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
638 * @pre The location manager handle must be created by location_manager_create()
640 int location_manager_get_last_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
644 * @brief Gets the last location information.
645 * @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.
646 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
648 * @privilege %http://tizen.org/privilege/location
649 * @param[in] manager The location manager handle
650 * @param[out] altitude The current altitude (meters)
651 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
652 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
653 * @param[out] climb The climb (km/h)
654 * @param[out] direction The direction, degrees from the north
655 * @param[out] speed The speed (km/h)
656 * @param[out] level The accuracy level
657 * @param[out] horizontal The horizontal accuracy (meters)
658 * @param[out] vertical The vertical accuracy (meters)
659 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
660 * @return @c 0 on success,
661 * otherwise a negative error value
662 * @retval #LOCATIONS_ERROR_NONE Successful
663 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
664 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
665 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
666 * @pre The location manager handle must be created by location_manager_create().
668 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);
672 * @brief Gets the last velocity information which is recorded.
673 * @details The @a climb, @a direction, and @a speed values should be @c 0, if there is no record of any previous velocity information.
674 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
676 * @privilege %http://tizen.org/privilege/location
677 * @param[in] manager The location manager handle
678 * @param[out] climb The last climb (km/h)
679 * @param[out] direction The last direction, degrees from the north
680 * @param[out] speed The last speed (km/h)
681 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
682 * @return @c 0 on success,
683 * otherwise a negative error value
684 * @retval #LOCATIONS_ERROR_NONE Successful
685 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
686 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
687 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
688 * @pre The location manager handle must be created by location_manager_create().
690 int location_manager_get_last_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
694 * @brief Gets the last accuracy information which is recorded.
695 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
697 * @privilege %http://tizen.org/privilege/location
698 * @param[in] manager The location manager handle
699 * @param[out] level The last accuracy level
700 * @param[out] horizontal The last horizontal accuracy (meters)
701 * @param[out] vertical The last vertical accuracy (meters)
702 * @return @c 0 on success,
703 * otherwise a negative error value
704 * @retval #LOCATIONS_ERROR_NONE Successful
705 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
706 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
707 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
708 * @pre The location manager handle must be created by location_manager_create().
710 int location_manager_get_last_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
714 * @deprecated Deprecated since 3.0
715 * @brief Gets the current application's location accessibility status.
716 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
717 * @param[out] state The current location service accessibility status
718 * @return @c 0 on success,
719 * otherwise a negative error value
720 * @retval #LOCATIONS_ERROR_NONE Successful
721 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
722 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
723 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
725 int location_manager_get_accessibility_state(location_accessibility_state_e *state) TIZEN_DEPRECATED_API;
729 * @brief Registers a callback function to be invoked at defined interval with updated position information.
730 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
731 * @param[in] manager The location manager handle
732 * @param[in] callback The callback function to register
733 * @param[in] interval The interval [1 ~ 120] (seconds)
734 * @param[in] user_data The user data to be passed to the callback function
735 * @return @c 0 on success,
736 * otherwise a negative error value
737 * @retval #LOCATIONS_ERROR_NONE Successful
738 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
739 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
740 * @post location_position_updated_cb() will be invoked
741 * @see location_manager_unset_position_updated_cb()
742 * @see location_position_updated_cb()
744 int location_manager_set_position_updated_cb(location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data);
748 * @brief Unregisters the callback function.
749 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
750 * @param[in] manager The location manager handle
751 * @return @c 0 on success,
752 * otherwise a negative error value
753 * @retval #LOCATIONS_ERROR_NONE Successful
754 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
755 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
756 * @see location_manager_set_position_updated_cb()
758 int location_manager_unset_position_updated_cb(location_manager_h manager);
762 * @brief Registers a callback function to be invoked at defined interval with updated velocity information.
763 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
764 * @param[in] manager The location manager handle
765 * @param[in] callback The callback function to register
766 * @param[in] interval The interval [1 ~ 120] (seconds)
767 * @param[in] user_data The user data to be passed to the callback function
768 * @return @c 0 on success,
769 * otherwise a negative error value
770 * @retval #LOCATIONS_ERROR_NONE Successful
771 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
772 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
773 * @post location_velocity_updated_cb() will be invoked
774 * @see location_manager_unset_velocity_updated_cb()
775 * @see location_velocity_updated_cb()
777 int location_manager_set_velocity_updated_cb(location_manager_h manager, location_velocity_updated_cb callback, int interval, void *user_data);
781 * @brief Unregisters the callback function.
782 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
783 * @param[in] manager The location manager handle
784 * @return @c 0 on success,
785 * otherwise a negative error value
786 * @retval #LOCATIONS_ERROR_NONE Successful
787 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
788 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
789 * @see location_manager_set_velocity_updated_cb()
791 int location_manager_unset_velocity_updated_cb(location_manager_h manager);
795 * @brief Registers a callback function to be invoked when the location service state is changed.
796 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
797 * @param[in] manager The location manager handle
798 * @param[in] callback The callback function to register
799 * @param[in] user_data The user data to be passed to the callback function
800 * @return @c 0 on success,
801 * otherwise a negative error value
802 * @retval #LOCATIONS_ERROR_NONE Successful
803 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
804 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
805 * @post location_service_state_changed_cb() will be invoked
806 * @see location_manager_unset_service_state_changed_cb()
807 * @see location_service_state_changed_cb()
808 * @see location_manager_start()
809 * @see location_manager_stop()
810 * @see #location_service_state_e
812 int location_manager_set_service_state_changed_cb(location_manager_h manager, location_service_state_changed_cb callback, void *user_data);
816 * @brief Unregisters the callback function.
817 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
818 * @param[in] manager The location manager handle
819 * @return @c 0 on success,
820 * otherwise a negative error value
821 * @retval #LOCATIONS_ERROR_NONE Successful
822 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
823 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
824 * @see location_manager_set_service_state_changed_cb()
826 int location_manager_unset_service_state_changed_cb(location_manager_h manager);
830 * @brief Registers a callback function to be invoked when the previously set boundary area is entered or left.
831 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
832 * @param[in] manager The location manager handle
833 * @param[in] callback The callback function to register
834 * @param[in] user_data The user data to be passed to the callback function
835 * @return @c 0 on success,
836 * otherwise a negative error value
837 * @retval #LOCATIONS_ERROR_NONE Successful
838 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
839 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
840 * @pre location_manager_add_boundary() is called before.
841 * @post location_zone_changed_cb() will be invoked
842 * @see location_manager_unset_zone_changed_cb()
843 * @see location_zone_changed_cb()
845 int location_manager_set_zone_changed_cb(location_manager_h manager, location_zone_changed_cb callback, void *user_data);
849 * @brief Unregisters the callback function.
850 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
851 * @param[in] manager The location manager handle
852 * @return @c 0 on success,
853 * otherwise a negative error value
854 * @retval #LOCATIONS_ERROR_NONE Successful
855 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
856 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
857 * @see location_manager_set_zone_changed_cb()
859 int location_manager_unset_zone_changed_cb(location_manager_h manager);
863 * @brief Registers a callback function to be invoked when the location setting is changed.
864 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
865 * @param[in] method The method to observe
866 * @param[in] callback The callback function to register
867 * @param[in] user_data The user data to be passed to the callback function
868 * @return @c 0 on success,
869 * otherwise a negative error value
870 * @retval #LOCATIONS_ERROR_NONE Successful
871 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
872 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
873 * @post location_setting_changed_cb() will be invoked
874 * @see location_manager_unset_setting_changed_cb()
875 * @see location_setting_changed_cb()
877 int location_manager_set_setting_changed_cb(location_method_e method, location_setting_changed_cb callback, void *user_data);
881 * @brief Unregisters the callback function.
882 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
883 * @param[in] method The method to observe
884 * @return @c 0 on success,
885 * otherwise a negative error value
886 * @retval #LOCATIONS_ERROR_NONE Successful
887 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
888 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
889 * @see location_manager_set_setting_changed_cb()
891 int location_manager_unset_setting_changed_cb(location_method_e method);
895 * @brief Gets the distance in meters between two locations.
896 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
897 * @param[in] start_latitude The starting latitude [-90.0 ~ 90.0] (degrees)
898 * @param[in] start_longitude The starting longitude [-180.0 ~ 180.0] (degrees)
899 * @param[in] end_latitude The ending latitude [-90.0 ~ 90.0] (degrees)
900 * @param[in] end_longitude The ending longitude [-180.0 ~ 180.0] (degrees)
901 * @param[out] distance The distance between two locations (meters)
902 * @return @c 0 on success,
903 * otherwise a negative error value
904 * @retval #LOCATIONS_ERROR_NONE Successful
905 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
906 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
908 int location_manager_get_distance(double start_latitude, double start_longitude, double end_latitude, double end_longitude, double *distance);
912 * @brief Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.
913 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
914 * @param[in] manager The location manager handle
915 * @param[in] callback The callback function to register
916 * @param[in] interval The minimum interval between position updates [1 ~ 120] (seconds)
917 * @param[in] distance The minimum distance between position updates [1 ~ 120] (meters)
918 * @param[in] user_data The user data to be passed to the callback function
919 * @return @c 0 on success,
920 * otherwise a negative error value
921 * @retval #LOCATIONS_ERROR_NONE Successful
922 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
923 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
924 * @post location_changed_cb() will be invoked
925 * @see location_manager_unset_distance_based_location_changed_cb()
926 * @see location_changed_cb()
928 int location_manager_set_distance_based_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, double distance, void *user_data);
932 * @brief Unregisters the callback function.
933 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
934 * @param[in] manager The location manager handle
935 * @return @c 0 on success,
936 * otherwise a negative error value
937 * @retval #LOCATIONS_ERROR_NONE Successful
938 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
939 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
940 * @see location_manager_set_distance_based_location_changed_cb()
942 int location_manager_unset_distance_based_location_changed_cb(location_manager_h manager);
946 * @brief Registers a callback function to be invoked at defined interval with updated location information.
947 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
948 * @param[in] manager The location manager handle
949 * @param[in] callback The callback function to register
950 * @param[in] interval The interval [1 ~ 120] (seconds)
951 * @param[in] user_data The user data to be passed to the callback function
952 * @return @c 0 on success,
953 * otherwise a negative error value
954 * @retval #LOCATIONS_ERROR_NONE Successful
955 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
956 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
957 * @post location_changed_cb() will be invoked
958 * @see location_manager_unset_location_changed_cb()
959 * @see location_changed_cb()
961 int location_manager_set_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, void *user_data);
965 * @brief Unregisters the callback function.
966 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
967 * @param[in] manager The location manager handle
968 * @return @c 0 on success,
969 * otherwise a negative error value
970 * @retval #LOCATIONS_ERROR_NONE Successful
971 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
972 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
973 * @see location_manager_set_location_changed_cb()
975 int location_manager_unset_location_changed_cb(location_manager_h manager);
979 * @brief Registers a callback function to be invoked when batch_period is expired.
980 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
981 * @remarks The batch_period should be greater than or equal to the batch_interval.
982 * @param[in] manager The location manager handle
983 * @param[in] callback The callback function to register
984 * @param[in] batch_interval The batch sampling interval [1 ~ 255] (seconds)
985 * @param[in] batch_period The batch period [1 ~ 60000] (seconds)
986 * @return @c 0 on success,
987 * otherwise a negative error value
988 * @retval #LOCATIONS_ERROR_NONE Successful
989 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
990 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
991 * @post location_batch_cb() will be invoked
992 * @see location_manager_start_batch()
993 * @see location_batch_cb()
994 * @see location_manager_unset_location_batch_cb()
996 int location_manager_set_location_batch_cb(location_manager_h manager, location_batch_cb callback, int batch_interval, int batch_period, void *user_data);
1000 * @brief Unregisters the callback function.
1001 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1002 * @param[in] manager The location manager handle
1003 * @return @c 0 on success,
1004 * otherwise a negative error value
1005 * @retval #LOCATIONS_ERROR_NONE Successful
1006 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1007 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1008 * @see location_manager_set_location_batch_cb()
1010 int location_manager_unset_location_batch_cb(location_manager_h manager);
1014 * @brief Starts the location batch service.
1015 * @details Calling this function starts location batch service, location_batch_cb() will be invoked every @a batch_period seconds.
1016 * After that, you can obtain all locations with location_manager_foreach_location_batch().
1017 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1019 * @privilege %http://tizen.org/privilege/location
1020 * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
1021 * (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as the first argument, and the service starts.
1022 * @param[in] manager The location manager handle
1023 * @return @c 0 on success,
1024 * otherwise a negative error value
1025 * @retval #LOCATIONS_ERROR_NONE Successful
1026 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1027 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1028 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1029 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
1030 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
1031 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1032 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1033 * @pre location_manager_set_location_batch_cb()
1034 * @see location_manager_set_service_state_changed_cb()
1035 * @see location_service_state_changed_cb()
1036 * @see location_manager_foreach_location_batch()
1037 * @see location_manager_stop_batch()
1039 int location_manager_start_batch(location_manager_h manager);
1043 * @brief Stops the location batch service.
1044 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1045 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
1046 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as the first argument.
1047 * @param[in] manager The location manager handle
1048 * @return @c 0 on success,
1049 * otherwise a negative error value
1050 * @retval #LOCATIONS_ERROR_NONE Successful
1051 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1052 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1053 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
1054 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1055 * @see location_manager_start_batch()
1056 * @see location_manager_set_service_state_changed_cb()
1057 * @see location_service_state_changed_cb()
1059 int location_manager_stop_batch(location_manager_h manager);
1063 * @brief Retrieves all location information by invoking a specific callback for each location data.
1064 * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1066 * @privilege %http://tizen.org/privilege/location
1067 * @param[in] manager The location manager handle
1068 * @param[in] callback The iteration callback function
1069 * @param[in] user_data The user data passed from the callback registration function
1070 * @return @c 0 on success,
1071 * otherwise a negative error value
1072 * @retval #LOCATIONS_ERROR_NONE Successful
1073 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1074 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1075 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1076 * @pre location_manager_foreach_location_batch() is available after location_batch_cb() is invoked
1077 * @post location_batch_get_location_cb() will be invoked
1078 * @see location_manager_start_batch()
1079 * @see location_batch_cb()
1080 * @see location_batch_get_location_cb()
1082 int location_manager_foreach_location_batch(location_manager_h manager, location_batch_get_location_cb callback, void *user_data);
1085 * @brief Checks whether the mock location is enabled.
1087 * @param[out] enabled Indicates whether the mock location is enabled
1088 * @return 0 on success, otherwise a negative error value
1089 * @retval #LOCATIONS_ERROR_NONE Successful
1090 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1091 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1092 * @see location_manager_enable_mock_location()
1093 * @see location_manager_set_mock_location()
1094 * @see location_manager_clear_mock_location()
1096 int location_manager_is_enabled_mock_location(bool *enabled);
1099 * @brief Enables mock location.
1101 * @remarks You can enable the mock location when developer mode is enabled.
1103 * @privilege %http://tizen.org/privilege/location
1104 * @param[in] enable The value to set
1105 * @return @c 0 on success,
1106 * otherwise a negative error value
1107 * @retval #LOCATIONS_ERROR_NONE Successful
1108 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1109 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
1110 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1111 * @see location_manager_is_enabled_method()
1112 * @see location_manager_create()
1113 * @see location_manager_set_mock_location()
1115 int location_manager_enable_mock_location(const bool enable);
1119 * @brief Sets a mock location for the given location method.
1120 * @details The location sets the given altitude, latitude, longitude, climb, direction, speed, level, horizontal, and vertical accuracy.
1123 * @privilege %http://tizen.org/privilege/location
1124 * @param[in] manager The location manager handle
1125 * @param[in] latitude The current latitude [-90.0 ~ 90.0] (degrees)
1126 * @param[in] longitude The current longitude [-180.0 ~ 180.0] (degrees)
1127 * @param[in] altitude The current altitude (meters)
1128 * @param[in] speed The speed (km/h)
1129 * @param[in] direction The direction, degrees from the north [0.0 ~ 360.0]
1130 * @param[in] accuracy The horizontal accuracy (meters)
1131 * @return @c 0 on success,
1132 * otherwise a negative error value
1133 * @retval #LOCATIONS_ERROR_NONE Successful
1134 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1135 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1136 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1137 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1138 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1139 * @see location_manager_is_enabled_method()
1140 * @see location_manager_enable_mock_location()
1141 * @see location_manager_create()
1142 * @see location_manager_clear_mock_location()
1144 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);
1148 * @brief Clears a mock location.
1151 * @privilege %http://tizen.org/privilege/location
1152 * @param[in] manager The location manager handle
1153 * @return @c 0 on success,
1154 * otherwise a negative error value
1155 * @retval #LOCATIONS_ERROR_NONE Successful
1156 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1157 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1158 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1159 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1160 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1161 * @see location_manager_is_enabled_method()
1162 * @see location_manager_enable_mock_location()
1163 * @see location_manager_create()
1164 * @see location_manager_set_mock_location()
1166 int location_manager_clear_mock_location(location_manager_h manager);
1174 * GPS Status & Satellites
1178 * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE
1183 * @brief Called once for each satellite in range.
1184 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1185 * @param[in] azimuth The azimuth of the satellite (degrees)
1186 * @param[in] elevation The elevation of the satellite (meters)
1187 * @param[in] prn The PRN of the satellite
1188 * @param[in] snr The SNR of the satellite [dB]
1189 * @param[in] is_active The flag signaling if satellite is in use
1190 * @param[in] user_data The user data passed from the foreach function
1191 * @return @c true to continue with the next iteration of the loop, \n
1192 * @c false to break out of the loop
1193 * @pre gps_status_foreach_satellites_in_view() will invoke this callback.
1194 * @pre gps_status_foreach_last_satellites_in_view() will invoke this callback.
1195 * @see gps_status_foreach_satellites_in_view()
1197 typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data);
1201 * @brief Called at defined interval with updated satellite information.
1202 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1203 * @param[out] num_of_active The last number of active satellites
1204 * @param[out] num_of_inview The last number of satellites in view
1205 * @param[out] timestamp The last timestamp (time when measurement took place or @c 0 if valid)
1206 * @param[in] user_data The user data passed from the call registration function
1207 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
1208 * @see location_manager_start()
1209 * @see location_manager_set_position_updated_cb()
1211 typedef void(*gps_status_satellite_updated_cb)(int num_of_active, int num_of_inview, time_t timestamp, void *user_data);
1215 * @brief Gets the GPS NMEA data.
1216 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1217 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1218 * You must release @a nmea using @c free().
1219 * @param[in] manager The location manager handle
1220 * @param[out] nmea The NMEA data
1221 * @return @c 0 on success,
1222 * otherwise a negative error value
1223 * @retval #LOCATIONS_ERROR_NONE Successful
1224 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1225 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1226 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1227 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1228 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1229 * @see location_manager_start()
1231 int gps_status_get_nmea(location_manager_h manager, char **nmea);
1235 * @brief Gets the information of satellites.
1236 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1238 * @privilege %http://tizen.org/privilege/location
1239 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1240 * @param[in] manager The location manager handle
1241 * @param[out] num_of_active The number of active satellites
1242 * @param[out] num_of_inview The number of satellites in view
1243 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
1244 * @return @c 0 on success,
1245 * otherwise a negative error value
1246 * @retval #LOCATIONS_ERROR_NONE Successful
1247 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1248 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1249 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1250 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1251 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1252 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1253 * @see gps_status_foreach_satellites_in_view()
1255 int gps_status_get_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1259 * @brief Registers a callback function to be invoked at defined interval with updated satellite information.
1260 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1262 * @privilege %http://tizen.org/privilege/location
1263 * @param[in] manager The location manager handle
1264 * @param[in] callback The callback function to register
1265 * @param[in] interval The interval [1 ~ 120] (seconds)
1266 * @param[in] user_data The user data to be passed to the callback function
1267 * @return @c 0 on success,
1268 * otherwise a negative error value
1269 * @retval #LOCATIONS_ERROR_NONE Successful
1270 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1271 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1272 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1273 * @post gps_status_satellite_updated_cb() will be invoked
1274 * @see gps_status_unset_satellite_updated_cb()
1275 * @see gps_status_satellite_updated_cb()
1276 * @see gps_status_get_satellite()
1277 * @see gps_status_foreach_satellites_in_view()
1278 * @see gps_status_get_last_satellite()
1279 * @see gps_status_foreach_last_satellites_in_view()
1281 int gps_status_set_satellite_updated_cb(location_manager_h manager, gps_status_satellite_updated_cb callback, int interval, void *user_data);
1285 * @brief Unregisters the callback function.
1286 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1287 * @param[in] manager The location manager handle
1288 * @return @c 0 on success,
1289 * otherwise a negative error value
1290 * @retval #LOCATIONS_ERROR_NONE Successful
1291 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1292 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1293 * @see gps_status_set_satellite_updated_cb()
1295 int gps_status_unset_satellite_updated_cb(location_manager_h manager);
1299 * @brief Invokes the callback function for each satellite.
1300 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1302 * @privilege %http://tizen.org/privilege/location
1303 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1304 * @param[in] manager The location manager handle
1305 * @param[in] callback The iteration callback function
1306 * @param[in] user_data The user data to be passed to the callback function
1307 * @return @c 0 on success,
1308 * otherwise a negative error value
1309 * @retval #LOCATIONS_ERROR_NONE Successful
1310 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1311 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1312 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1313 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1314 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1315 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1316 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1317 * @post It invokes gps_status_get_satellites_cb().
1318 * @see gps_status_get_satellite()
1319 * @see gps_status_get_satellites_cb()
1321 int gps_status_foreach_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1325 * @brief Gets the last information of satellites.
1326 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1328 * @privilege %http://tizen.org/privilege/location
1329 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1330 * @param[in] manager The location manager handle
1331 * @param[out] num_of_active The last number of active satellites
1332 * @param[out] num_of_inview The last number of satellites in view
1333 * @param[out] timestamp The last timestamp (time when last measurement took place or @c 0 if valid)
1334 * @return @c 0 on success,
1335 * otherwise a negative error value
1336 * @retval #LOCATIONS_ERROR_NONE Successful
1337 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1338 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1339 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1340 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1341 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1342 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1343 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1344 * @see gps_status_foreach_satellites_in_view()
1346 int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1350 * @brief Invokes the callback function for each last satellite which is recorded.
1351 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1353 * @privilege %http://tizen.org/privilege/location
1354 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1355 * @param[in] manager The location manager handle
1356 * @param[in] callback The iteration callback function
1357 * @param[in] user_data The user data to be passed to the callback function
1358 * @return @c 0 on success,
1359 * otherwise a negative error value
1360 * @retval #LOCATIONS_ERROR_NONE Successful
1361 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1362 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1363 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1364 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1365 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1366 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1367 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1368 * @post It invokes gps_status_get_satellites_cb().
1369 * @see gps_status_get_last_satellite()
1370 * @see gps_status_get_satellites_cb()
1372 int gps_status_foreach_last_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1382 #endif /* __TIZEN_LOCATION_LOCATIONS_H__ */