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__
20 #include <tizen_type.h>
21 #include <tizen_error.h>
23 #include <location_bounds.h>
30 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
35 * @brief Enumeration for error code for Location manager.
36 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
39 LOCATIONS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
40 LOCATIONS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
41 LOCATIONS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
42 LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
43 LOCATIONS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
44 LOCATIONS_ERROR_INCORRECT_METHOD = TIZEN_ERROR_LOCATION_MANAGER | 0x01, /**< Location manager contains incorrect method for a given call */
45 LOCATIONS_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_MANAGER | 0x02, /**< Network unavailable */
46 LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_MANAGER | 0x03, /**< Location service is not available */
47 LOCATIONS_ERROR_GPS_SETTING_OFF = TIZEN_ERROR_LOCATION_MANAGER | 0x04, /**< Setting for GPS, WPS, or MOCK is turned off */
48 LOCATIONS_ERROR_SECURITY_RESTRICTED = TIZEN_ERROR_LOCATION_MANAGER | 0x05, /**< Restricted by security system policy */
49 LOCATIONS_ERROR_SETTING_OFF = LOCATIONS_ERROR_GPS_SETTING_OFF, /**< Setting for GPS, WPS, or MOCK is turned off (Since 3.0) */
54 * @brief Enumeration for Location method type.
55 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
58 LOCATIONS_METHOD_NONE = -1, /**< Undefined method */
59 LOCATIONS_METHOD_HYBRID, /**< This method selects the best method available at the moment */
60 LOCATIONS_METHOD_GPS, /**< This method uses Global Positioning System */
61 LOCATIONS_METHOD_WPS, /**< This method uses WiFi Positioning System */
62 LOCATIONS_METHOD_MOCK, /**< This method uses mock location for testing (Since 3.0)*/
66 * @brief Enumeration for Approximate accuracy level of given information.
67 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
70 LOCATIONS_ACCURACY_NONE = 0, /**< Invalid data */
71 LOCATIONS_ACCURACY_COUNTRY, /**< Country accuracy level */
72 LOCATIONS_ACCURACY_REGION, /**< Regional accuracy level */
73 LOCATIONS_ACCURACY_LOCALITY, /**< Local accuracy level */
74 LOCATIONS_ACCURACY_POSTALCODE, /**< Postal accuracy level */
75 LOCATIONS_ACCURACY_STREET, /**< Street accuracy level */
76 LOCATIONS_ACCURACY_DETAILED, /**< Detailed accuracy level */
77 } location_accuracy_level_e;
80 * @brief Enumeration for the state of the location service.
81 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
84 LOCATIONS_SERVICE_DISABLED, /**< Service is disabled */
85 LOCATIONS_SERVICE_ENABLED, /**< Service is enabled */
86 } location_service_state_e;
89 * @brief Enumeration for the location service accessibility state.
90 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
93 LOCATIONS_ACCESS_STATE_NONE, /**< Access state is not determined */
94 LOCATIONS_ACCESS_STATE_DENIED, /**< Access denied */
95 LOCATIONS_ACCESS_STATE_ALLOWED, /**< Access authorized */
96 } location_accessibility_state_e;
99 * @brief The location manager handle.
100 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
102 typedef struct location_manager_s *location_manager_h;
111 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
115 * @brief Called at defined interval with updated position information.
116 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
117 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
118 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
119 * @param[in] altitude The updated altitude (meters)
120 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
121 * @param[in] user_data The user data passed from the call registration function
122 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
123 * @see location_manager_start()
124 * @see location_manager_set_position_updated_cb()
126 typedef void(*location_position_updated_cb)(double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
129 * @brief Called at defined interval with updated velocity information.
130 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
131 * @param[in] speed The updated speed (km/h)
132 * @param[in] direction The updated direction (in degrees from the north)
133 * @param[in] climb The updated climb (km/h)
134 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
135 * @param[in] user_data The user data passed from the callback registration function
136 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb().
137 * @see location_manager_start()
138 * @see location_manager_set_velocity_updated_cb()
140 typedef void(*location_velocity_updated_cb)(double speed, double direction, double climb, time_t timestamp, void *user_data);
143 * @brief Called at defined interval with updated location information.
144 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
145 * @param[in] error #LOCATIONS_ERROR_NONE Successful
146 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
147 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
148 * @param[in] altitude The updated altitude (meters)
149 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
150 * @param[in] speed The updated speed (km/h)
151 * @param[in] direction The updated direction (in degrees from the north)
152 * @param[in] climb The updated climb (km/h)
153 * @param[in] user_data The user data passed from the callback registration function
154 * @pre location_manager_request_single_location() will invoke this callback.
155 * @see location_manager_request_single_location()
157 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);
160 * @brief Called when the state of location service is changed from enabled to disabled or vice versa.
161 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
162 * @param[in] state The service state
163 * @param[in] user_data The user data passed from the callback registration function
164 * @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()
165 * @see location_manager_start()
166 * @see location_manager_stop()
167 * @see location_manager_set_service_state_changed_cb()
168 * @see #location_service_state_e
170 typedef void(*location_service_state_changed_cb)(location_service_state_e state, void *user_data);
173 * @brief Called when the user defined zones are entered or exited.
174 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
175 * @param[in] state The boundary state
176 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
177 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
178 * @param[in] altitude The updated altitude (meters)
179 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
180 * @param[in] user_data The user data passed from the callback registration function
181 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb().
182 * @see #location_boundary_state_e
183 * @see location_manager_start()
184 * @see location_manager_set_zone_changed_cb()
186 typedef void(*location_zone_changed_cb)(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
189 * @brief Called when the state of location method is changed.
190 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
191 * @param[in] method The method changed on setting
192 * @param[in] enable The setting value changed
193 * @param[in] user_data The user data passed from the callback registration function
194 * @pre location_setting_changed_cb() will invoke this callback if you register this callback using location_manager_set_setting_changed_cb()
195 * @see location_manager_set_setting_changed_cb()
196 * @see location_manager_unset_setting_changed_cb()
198 typedef void(*location_setting_changed_cb)(location_method_e method, bool enable, void *user_data);
201 * @brief Called once for each location bound.
202 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
203 * @param[in] bounds The location bounds handle
204 * @param[in] user_data The user data passed from the callback registration function
205 * @pre location_manager_foreach_boundary() will invoke this callback.
206 * @see location_manager_foreach_boundary()
208 typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
211 * @brief Called at defined interval with updated location information.
213 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
214 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
215 * @param[in] altitude The updated altitude (meters)
216 * @param[in] speed The updated speed (km/h)
217 * @param[in] direction The updated direction (in degrees from the north)
218 * @param[in] horizontal_accuracy The horizontal accuracy (meters)
219 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
220 * @param[in] user_data The user data passed from the callback registration function
221 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
222 * @see location_manager_start()
223 * @see location_manager_set_distance_based_location_changed_cb()
224 * @see location_manager_set_location_changed_cb()
226 typedef void(*location_changed_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data);
229 * @brief Checks whether the given location method is available.
230 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
231 * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
232 * @param[in] method The location method to be checked
233 * @return @c true if the specified location method is supported, otherwise @c false if it is not available
234 * @retval #LOCATIONS_ERROR_NONE Successful
235 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
236 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
237 * @see location_manager_create()
238 * @see location_manager_get_method()
240 bool location_manager_is_supported_method(location_method_e method);
243 * @brief Checks whether the given location method is enabled or not on setting.
244 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
245 * @param[in] method The location method to be checked
246 * @param[out] enable The result value of checking the given location method
247 * @return 0 on success, otherwise a negative error value
248 * @retval #LOCATIONS_ERROR_NONE Successful
249 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
250 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
251 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
252 * @see location_manager_create()
253 * @see location_manager_set_setting_changed_cb()
254 * @see location_manager_unset_setting_changed_cb()
256 int location_manager_is_enabled_method(location_method_e method, bool *enable);
260 * @brief Enables the given location method.
262 * @privlevel platform
263 * @privilege %http://tizen.org/privilege/location.enable
264 * @param[in] method The location method to be checked
265 * @param[in] enable The value to set
266 * @return 0 on success, otherwise a negative error value
267 * @retval #LOCATIONS_ERROR_NONE Successful
268 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
269 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
270 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
271 * @see location_manager_is_enabled_method()
272 * @see location_manager_create()
274 int location_manager_enable_method(const location_method_e method, const bool enable);
277 * @brief Creates a new location manager.
278 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
279 * @remarks You must release @a manager using location_manager_destroy().
280 * @param[in] method The location method
281 * @param[out] manager The location manager handle that is newly created
282 * @return @c 0 on success, otherwise a negative error value
283 * @retval #LOCATIONS_ERROR_NONE Successful
284 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
285 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
286 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
287 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
288 * @see location_manager_destroy()
290 int location_manager_create(location_method_e method, location_manager_h *manager);
293 * @brief Releases the location manager.
294 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
295 * @param[in] manager The location manager handle
296 * @return @c 0 on success, otherwise a negative error value
297 * @retval #LOCATIONS_ERROR_NONE Successful
298 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
299 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
300 * @see location_manager_create()
302 int location_manager_destroy(location_manager_h manager);
305 * @brief Request to update current location once.
306 * @remarks Do not request to start the location service using the same manager handler
307 * Calling this function invokes a location service event. When the location service is updated, location_updated_cb
308 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
310 * @privilege %http://tizen.org/privilege/location
311 * @param[in] manager The location manager handle
312 * @param[in] timeout Timeout to stop requesting single location after
313 * @param[in] callback The location callback function to register
314 * @param[in] user_data The user data to be passed to the callback function
315 * @retval #LOCATIONS_ERROR_NONE Successful
316 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
317 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
318 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
319 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
320 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
321 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
322 * @post It invokes location_updated_cb().
324 int location_manager_request_single_location(location_manager_h manager, int timeout, location_updated_cb callback, void *user_data);
327 * @brief Starts the location service.
328 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
330 * @privilege %http://tizen.org/privilege/location
332 * @remarks There is no limit on number of location managers for which this function was called.
334 * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
335 * (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as
336 * the first argument, and the service starts.
338 * @remarks The started service is a requirement for calling these functions:
339 * location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(),
340 * gps_status_get_nmea(), gps_status_get_satellite(), gps_status_foreach_satellites_in_view().
342 * @remarks Once you stop the service using location_manager_stop(), you can no longer call the functions listed above.
344 * @remarks Starting and stopping the service is in the scope of the given location manager only (if there is more than one manager,
345 * starting and stopping should be executed for each of them separately).
347 * @param[in] manager The location manager handle
348 * @return 0 on success, otherwise a negative error value
349 * @retval #LOCATIONS_ERROR_NONE Successful
350 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
351 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
352 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
353 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
354 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
355 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
356 * @post It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().
357 * @see location_manager_stop()
358 * @see location_manager_get_position()
359 * @see location_manager_get_velocity()
360 * @see location_manager_get_accuracy()
361 * @see location_manager_set_service_state_changed_cb()
362 * @see location_manager_set_position_updated_cb()
363 * @see location_position_updated_cb()
364 * @see location_manager_set_velocity_updated_cb()
365 * @see location_velocity_updated_cb()
366 * @see location_manager_set_zone_changed_cb()
367 * @see location_zone_changed_cb()
369 int location_manager_start(location_manager_h manager);
372 * @brief Stops the location service.
373 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
374 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
375 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
376 * When that happens, the service is stopped and the user is notified.
378 * @remarks You can stop and start the location manager as needed.
380 * @param[in] manager The location manager handle
381 * @return 0 on success, otherwise a negative error value
382 * @retval #LOCATIONS_ERROR_NONE Successful
383 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
384 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
385 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
386 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
387 * @see location_manager_start()
388 * @see location_manager_set_service_state_changed_cb()
389 * @see location_service_state_changed_cb()
391 int location_manager_stop(location_manager_h manager);
394 * @brief Adds a bounds for a given location manager.
395 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
396 * @param[in] manager The location manager handle
397 * @param[in] bounds The location bounds handle
398 * @return @c 0 on success, otherwise a negative error value
399 * @retval #LOCATIONS_ERROR_NONE Successful
400 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
401 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
402 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
403 * @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().
404 * @see location_manager_remove_boundary()
405 * @see location_manager_set_zone_changed_cb()
407 int location_manager_add_boundary(location_manager_h manager, const location_bounds_h bounds);
410 * @brief Deletes a bounds for a given location manager.
411 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
412 * @param[in] manager The location manager handle
413 * @param[in] bounds The location bounds handle
414 * @return @c 0 on success, otherwise a negative error value
415 * @retval #LOCATIONS_ERROR_NONE Successful
416 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
417 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
418 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
419 * @see location_manager_add_boundary()
421 int location_manager_remove_boundary(location_manager_h manager, const location_bounds_h bounds);
424 * @brief Retrieves all location bounds by invoking a specific callback for each location bounds
425 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
426 * @param[in] manager The location manager handle
427 * @param[in] callback The iteration callback
428 * @param[in] user_data The user data to be passed to the callback function
429 * @return @c 0 on success, otherwise a negative error value
430 * @retval #LOCATIONS_ERROR_NONE Successful
431 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
432 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
433 * @post location_bounds_cb() will be invoked
434 * @see location_manager_add_boundary()
435 * @see location_manager_remove_boundary()
436 * @see location_bounds_cb()
438 int location_manager_foreach_boundary(location_manager_h manager, location_bounds_cb callback, void *user_data);
441 * @brief Gets the given location manager's method.
442 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
443 * @param[in] manager The location manager handle
444 * @param[out] method The location method
445 * @return @c 0 on success, otherwise a negative error value
446 * @retval #LOCATIONS_ERROR_NONE Successful
447 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
448 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
449 * @see location_manager_create()
451 int location_manager_get_method(location_manager_h manager, location_method_e *method);
454 * @brief Gets the current position information.
455 * @details The result contains the current altitude, latitude, and longitude, with a measurement timestamp.
457 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
459 * @privilege %http://tizen.org/privilege/location
460 * @param[in] manager The location manager handle
461 * @param[out] altitude The current altitude (meters)
462 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
463 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
464 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
465 * @return 0 on success, otherwise a negative error value
466 * @retval #LOCATIONS_ERROR_NONE Successful
467 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
468 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
469 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
470 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
471 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
472 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
474 int location_manager_get_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
477 * @brief Gets the current position information.
478 * @details The result contains the current altitude, latitude, longitude, climb, direction, speed, level, horizontal and vertical with a measurement timestamp.
480 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
482 * @privilege %http://tizen.org/privilege/location
483 * @param[in] manager The location manager handle
484 * @param[out] altitude The current altitude (meters)
485 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
486 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
487 * @param[out] climb The climb (km/h)
488 * @param[out] direction The direction, degrees from the north
489 * @param[out] speed The speed (km/h)
490 * @param[out] level The accuracy level
491 * @param[out] horizontal The horizontal accuracy (meters)
492 * @param[out] vertical The vertical accuracy (meters)
493 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
494 * @return 0 on success, otherwise a negative error value
495 * @retval #LOCATIONS_ERROR_NONE Successful
496 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
497 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
498 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
499 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
500 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
501 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
503 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);
506 * @brief Gets the current velocity information.
507 * @details The result contains the current climb, direction, and speed, with a measurement timestamp.
509 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
511 * @privilege %http://tizen.org/privilege/location
512 * @param[in] manager The location manager handle
513 * @param[out] climb The climb (km/h)
514 * @param[out] direction The direction, degrees from the north
515 * @param[out] speed The speed (km/h)
516 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
517 * @return @c 0 on success, otherwise a negative error value
518 * @retval #LOCATIONS_ERROR_NONE Successful
519 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
520 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
521 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
522 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
523 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
524 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
526 int location_manager_get_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
529 * @brief Gets the current accuracy information.
530 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
532 * @privilege %http://tizen.org/privilege/location
533 * @param[in] manager The location manager handle
534 * @param[out] level The accuracy level
535 * @param[out] horizontal The horizontal accuracy (meters)
536 * @param[out] vertical The vertical accuracy (meters)
537 * @return 0 on success, otherwise a negative error value
538 * @retval #LOCATIONS_ERROR_NONE Successful
539 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
540 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
541 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
542 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
543 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
544 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
546 int location_manager_get_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
549 * @brief Gets the last position information which is recorded.
550 * @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.
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 last altitude (meters)
556 * @param[out] latitude The last latitude [-90.0 ~ 90.0] (degrees)
557 * @param[out] longitude The last longitude [-180.0 ~ 180.0] (degrees)
558 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
559 * @return @c 0 on success, otherwise a negative error value
560 * @retval #LOCATIONS_ERROR_NONE Successful
561 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
562 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
563 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
564 * @pre The location manager handle must be created by location_manager_create()
566 int location_manager_get_last_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
569 * @brief Gets the last location information.
570 * @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.
571 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
573 * @privilege %http://tizen.org/privilege/location
574 * @param[in] manager The location manager handle
575 * @param[out] altitude The current altitude (meters)
576 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
577 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
578 * @param[out] climb The climb (km/h)
579 * @param[out] direction The direction, degrees from the north
580 * @param[out] speed The speed (km/h)
581 * @param[out] level The accuracy level
582 * @param[out] horizontal The horizontal accuracy (meters)
583 * @param[out] vertical The vertical accuracy (meters)
584 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
585 * @return @c 0 on success, otherwise a negative error value
586 * @retval #LOCATIONS_ERROR_NONE Successful
587 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
588 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
589 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
590 * @pre The location manager handle must be created by location_manager_create()
592 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);
596 * @brief Gets the last velocity information which is recorded.
597 * @details The @a climb, @a direction and @a speed values should be @c 0, if there is no record of any previous velocity information.
599 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
601 * @privilege %http://tizen.org/privilege/location
602 * @param[in] manager The location manager handle
603 * @param[out] climb The last climb (km/h)
604 * @param[out] direction The last direction, degrees from the north
605 * @param[out] speed The last speed (km/h)
606 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
607 * @return @c 0 on success, otherwise a negative error value
608 * @retval #LOCATIONS_ERROR_NONE Successful
609 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
610 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
611 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
612 * @pre The location manager handle must be created by location_manager_create()
614 int location_manager_get_last_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
617 * @brief Gets the last accuracy information which is recorded.
618 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
620 * @privilege %http://tizen.org/privilege/location
621 * @param[in] manager The location manager handle
622 * @param[out] level The last accuracy level
623 * @param[out] horizontal The last horizontal accuracy (meters)
624 * @param[out] vertical The last vertical accuracy (meters)
625 * @return 0 on success, otherwise a negative error value
626 * @retval #LOCATIONS_ERROR_NONE Successful
627 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
628 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
629 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
630 * @pre The location manager handle must be created by location_manager_create()
632 int location_manager_get_last_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
635 * @brief Gets the current application's location accessibility status.
636 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
637 * @param[out] state The current location service accessibility status.
638 * @return 0 on success, otherwise a negative error value
639 * @retval #LOCATIONS_ERROR_NONE Successful
640 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
641 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
642 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
644 int location_manager_get_accessibility_state(location_accessibility_state_e *state);
647 * @brief Registers a callback function to be invoked at defined interval with updated position information.
649 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
650 * @param[in] manager The location manager handle
651 * @param[in] callback The callback function to register
652 * @param[in] interval The interval [1 ~ 120] (seconds)
653 * @param[in] user_data The user data to be passed to the callback function
654 * @return @c 0 on success, otherwise a negative error value
655 * @retval #LOCATIONS_ERROR_NONE Successful
656 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
657 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
658 * @post location_position_updated_cb() will be invoked
659 * @see location_manager_unset_position_updated_cb()
660 * @see location_position_updated_cb()
662 int location_manager_set_position_updated_cb(location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data);
665 * @brief Unregisters the callback function.
666 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
667 * @param[in] manager The location manager handle
668 * @return @c 0 on success, otherwise a negative error value
669 * @retval #LOCATIONS_ERROR_NONE Successful
670 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
671 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
672 * @see location_manager_set_position_updated_cb()
674 int location_manager_unset_position_updated_cb(location_manager_h manager);
677 * @brief Registers a callback function to be invoked at defined interval with updated velocity information.
678 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
679 * @param[in] manager The location manager handle
680 * @param[in] callback The callback function to register
681 * @param[in] interval The interval [1 ~ 120] (seconds)
682 * @param[in] user_data The user data to be passed to the callback function
683 * @return @c 0 on success, otherwise a negative error value
684 * @retval #LOCATIONS_ERROR_NONE Successful
685 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
686 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
687 * @post location_velocity_updated_cb() will be invoked
688 * @see location_manager_unset_velocity_updated_cb()
689 * @see location_velocity_updated_cb()
691 int location_manager_set_velocity_updated_cb(location_manager_h manager, location_velocity_updated_cb callback, int interval, void *user_data);
694 * @brief Unregisters the callback function.
695 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
696 * @param[in] manager The location manager handle
697 * @return @c 0 on success, otherwise a negative error value
698 * @retval #LOCATIONS_ERROR_NONE Successful
699 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
700 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
701 * @see location_manager_set_velocity_updated_cb()
703 int location_manager_unset_velocity_updated_cb(location_manager_h manager);
706 * @brief Registers a callback function to be invoked when the location service state is changed.
707 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
708 * @param[in] manager The location manager handle
709 * @param[in] callback The callback function to register
710 * @param[in] user_data The user data to be passed to the callback function
711 * @return @c 0 on success, otherwise a negative error value
712 * @retval #LOCATIONS_ERROR_NONE Successful
713 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
714 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
715 * @post location_service_state_changed_cb() will be invoked
716 * @see location_manager_unset_service_state_changed_cb()
717 * @see location_service_state_changed_cb()
718 * @see location_manager_start()
719 * @see location_manager_stop()
720 * @see #location_service_state_e
722 int location_manager_set_service_state_changed_cb(location_manager_h manager, location_service_state_changed_cb callback, void *user_data);
725 * @brief Unregisters the callback function.
726 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
727 * @param[in] manager The location manager handle
728 * @return @c 0 on success, otherwise a negative error value
729 * @retval #LOCATIONS_ERROR_NONE Successful
730 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
731 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
732 * @see location_manager_set_service_state_changed_cb()
734 int location_manager_unset_service_state_changed_cb(location_manager_h manager);
737 * @brief Registers a callback function to be invoked when the previously set boundary area is entered or left.
739 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
740 * @param[in] manager The location manager handle
741 * @param[in] callback The callback function to register
742 * @param[in] user_data The user data to be passed to the callback function
743 * @return @c 0 on success, otherwise a negative error value
744 * @retval #LOCATIONS_ERROR_NONE Successful
745 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
746 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
747 * @pre location_manager_add_boundary() is called before.
748 * @post location_zone_changed_cb() will be invoked
749 * @see location_manager_unset_zone_changed_cb()
750 * @see location_zone_changed_cb()
752 int location_manager_set_zone_changed_cb(location_manager_h manager, location_zone_changed_cb callback, void *user_data);
755 * @brief Unregisters the callback function.
756 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
757 * @param[in] manager The location manager handle
758 * @return 0 on success, otherwise a negative error value
759 * @retval #LOCATIONS_ERROR_NONE Successful
760 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
761 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
762 * @see location_manager_set_zone_changed_cb()
764 int location_manager_unset_zone_changed_cb(location_manager_h manager);
767 * @brief Registers a callback function to be invoked when the location setting is changed.
768 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
769 * @param[in] method The method to observe
770 * @param[in] callback The callback function to register
771 * @param[in] user_data The user data to be passed to the callback function
772 * @return 0 on success, 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_setting_changed_cb() will be invoked
777 * @see location_manager_unset_setting_changed_cb()
778 * @see location_setting_changed_cb()
780 int location_manager_set_setting_changed_cb(location_method_e method, location_setting_changed_cb callback, void *user_data);
783 * @brief Unregisters the callback function.
784 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
785 * @param[in] method The method to observe
786 * @return 0 on success, otherwise a negative error value
787 * @retval #LOCATIONS_ERROR_NONE Successful
788 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
789 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
790 * @see location_manager_set_setting_changed_cb()
792 int location_manager_unset_setting_changed_cb(location_method_e method);
795 * @brief Gets the distance in meters between two locations.
796 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
797 * @param[in] start_latitude The starting latitude [-90.0 ~ 90.0] (degrees)
798 * @param[in] start_longitude The starting longitude [-180.0 ~ 180.0] (degrees)
799 * @param[in] end_latitude The ending latitude [-90.0 ~ 90.0] (degrees)
800 * @param[in] end_longitude The ending longitude [-180.0 ~ 180.0] (degrees)
801 * @param[out] distance The distance between two locations (meters)
802 * @return 0 on success, otherwise a negative error value
803 * @retval #LOCATIONS_ERROR_NONE Successful
804 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
805 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
807 int location_manager_get_distance(double start_latitude, double start_longitude, double end_latitude, double end_longitude, double *distance);
810 * @brief Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.
812 * @param[in] manager The location manager handle
813 * @param[in] callback The callback function to register
814 * @param[in] interval The minimum interval between position updates [1 ~ 120] (seconds)
815 * @param[in] distance The minimum distance between position updates [1 ~ 120] (meters)
816 * @param[in] user_data The user data to be passed to the callback function
817 * @return @c 0 on success, otherwise a negative error value
818 * @retval #LOCATIONS_ERROR_NONE Successful
819 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
820 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
821 * @post location_changed_cb() will be invoked
822 * @see location_manager_unset_distance_based_location_changed_cb()
823 * @see location_changed_cb()
825 int location_manager_set_distance_based_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, double distance, void *user_data);
828 * @brief Unregisters the callback function.
830 * @param[in] manager The location manager handle
831 * @return @c 0 on success, otherwise a negative error value
832 * @retval #LOCATIONS_ERROR_NONE Successful
833 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
834 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
835 * @see location_manager_set_distance_based_location_changed_cb()
837 int location_manager_unset_distance_based_location_changed_cb(location_manager_h manager);
840 * @brief Registers a callback function to be invoked at defined interval with updated location information.
842 * @param[in] manager The location manager handle
843 * @param[in] callback The callback function to register
844 * @param[in] interval The interval [1 ~ 120] (seconds)
845 * @param[in] user_data The user data to be passed to the callback function
846 * @return @c 0 on success, otherwise a negative error value
847 * @retval #LOCATIONS_ERROR_NONE Successful
848 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
849 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
850 * @post location_changed_cb() will be invoked
851 * @see location_manager_unset_location_changed_cb()
852 * @see location_changed_cb()
854 int location_manager_set_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, void *user_data);
857 * @brief Unregisters the callback function.
859 * @param[in] manager The location manager handle
860 * @return @c 0 on success, otherwise a negative error value
861 * @retval #LOCATIONS_ERROR_NONE Successful
862 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
863 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
864 * @see location_manager_set_location_changed_cb()
866 int location_manager_unset_location_changed_cb(location_manager_h manager);
869 * @brief Enables mock location.
870 * @remarks You can enable the mock location when developer mode is enabled.
873 * @privilege %http://tizen.org/privilege/location
874 * @param[in] enable The value to set
875 * @return 0 on success, otherwise a negative error value
876 * @retval #LOCATIONS_ERROR_NONE Successful
877 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
878 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
879 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
880 * @see location_manager_is_enabled_method()
881 * @see location_manager_create()
882 * @see location_manager_set_mock_location()
884 int location_manager_enable_mock_location(const bool enable);
887 * @brief Sets a mock location for the given location method.
888 * @details The location sets the given altitude, latitude, longitude, climb, direction, speed, level, horizontal and vertical accuracy.
892 * @privilege %http://tizen.org/privilege/location
893 * @param[in] manager The location manager handle
894 * @param[in] latitude The current latitude [-90.0 ~ 90.0] (degrees)
895 * @param[in] longitude The current longitude [-180.0 ~ 180.0] (degrees)
896 * @param[in] altitude The current altitude (meters)
897 * @param[in] speed The speed (km/h)
898 * @param[in] direction The direction, degrees from the north [0.0 ~ 360.0]
899 * @param[in] accuracy The horizontal accuracy (meters)
900 * @return 0 on success, otherwise a negative error value
901 * @retval #LOCATIONS_ERROR_NONE Successful
902 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
903 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
904 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
905 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
906 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
907 * @see location_manager_is_enabled_method()
908 * @see location_manager_enable_mock_location()
909 * @see location_manager_create()
910 * @see location_manager_clear_mock_location()
912 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);
915 * @brief Clears a mock location.
919 * @privilege %http://tizen.org/privilege/location
920 * @param[in] manager The location manager handle
921 * @return 0 on success, otherwise a negative error value
922 * @retval #LOCATIONS_ERROR_NONE Successful
923 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
924 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
925 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
926 * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
927 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
928 * @see location_manager_is_enabled_method()
929 * @see location_manager_enable_mock_location()
930 * @see location_manager_create()
931 * @see location_manager_set_mock_location()
933 int location_manager_clear_mock_location(location_manager_h manager);
940 * GPS Status & Satellites
944 * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE
949 * @brief Called once for each satellite in range.
950 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
951 * @param[in] azimuth The azimuth of the satellite (degrees)
952 * @param[in] elevation The elevation of the satellite (meters)
953 * @param[in] prn The PRN of the satellite
954 * @param[in] snr The SNR of the satellite [dB]
955 * @param[in] is_active The flag signaling if satellite is in use
956 * @param[in] user_data The user data passed from the foreach function
957 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
958 * @pre gps_status_foreach_satellites_in_view() will invoke this callback.
959 * @pre gps_status_foreach_last_satellites_in_view() will invoke this callback.
960 * @see gps_status_foreach_satellites_in_view()
962 typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data);
965 * @brief Called at defined interval with updated satellite information.
966 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
967 * @param[out] num_of_active The last number of active satellites
968 * @param[out] num_of_inview The last number of satellites in view
969 * @param[out] timestamp The last timestamp (time when measurement took place or @c 0 if valid)
970 * @param[in] user_data The user data passed from the call registration function
971 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
972 * @see location_manager_start()
973 * @see location_manager_set_position_updated_cb()
975 typedef void(*gps_status_satellite_updated_cb)(int num_of_active, int num_of_inview, time_t timestamp, void *user_data);
978 * @brief Gets the GPS NMEA data.
979 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
980 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
981 * You must release @a nmea using @c free().
982 * @param[in] manager The location manager handle
983 * @param[out] nmea The NMEA data
984 * @return @c 0 on success, otherwise a negative error value
985 * @retval #LOCATIONS_ERROR_NONE Successful
986 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
987 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
988 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
989 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
990 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
991 * @see location_manager_start()
993 int gps_status_get_nmea(location_manager_h manager, char **nmea);
996 * @brief Gets the information of satellites.
997 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
999 * @privilege %http://tizen.org/privilege/location
1000 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1001 * @param[in] manager The location manager handle
1002 * @param[out] num_of_active The number of active satellites
1003 * @param[out] num_of_inview The number of satellites in view
1004 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
1005 * @return @c 0 on success, otherwise a negative error value
1006 * @retval #LOCATIONS_ERROR_NONE Successful
1007 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1008 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1009 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1010 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1011 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1012 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1013 * @see gps_status_foreach_satellites_in_view()
1015 int gps_status_get_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1018 * @brief Registers a callback function to be invoked at defined interval with updated satellite information.
1019 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1021 * @privilege %http://tizen.org/privilege/location
1022 * @param[in] manager The location manager handle
1023 * @param[in] callback The callback function to register
1024 * @param[in] interval The interval [1 ~ 120] (seconds)
1025 * @param[in] user_data The user data to be passed to the callback function
1026 * @return 0 on success, otherwise a negative error value
1027 * @retval #LOCATIONS_ERROR_NONE Successful
1028 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1029 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1030 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1031 * @post gps_status_satellite_updated_cb() will be invoked
1032 * @see gps_status_unset_satellite_updated_cb()
1033 * @see gps_status_satellite_updated_cb()
1034 * @see gps_status_get_satellite()
1035 * @see gps_status_foreach_satellites_in_view()
1036 * @see gps_status_get_last_satellite()
1037 * @see gps_status_foreach_last_satellites_in_view()
1039 int gps_status_set_satellite_updated_cb(location_manager_h manager, gps_status_satellite_updated_cb callback, int interval, void *user_data);
1042 * @brief Unregisters the callback function.
1043 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1045 * @privilege %http://tizen.org/privilege/location
1046 * @param[in] manager The location manager handle
1047 * @return @c 0 on success, otherwise a negative error value
1048 * @retval #LOCATIONS_ERROR_NONE Successful
1049 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1050 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1051 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1052 * @see gps_status_set_satellite_updated_cb()
1054 int gps_status_unset_satellite_updated_cb(location_manager_h manager);
1057 * @brief Invokes the callback function for each satellite.
1058 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1060 * @privilege %http://tizen.org/privilege/location
1061 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1062 * @param[in] manager The location manager handle
1063 * @param[in] callback The iteration callback function
1064 * @param[in] user_data The user data to be passed to the callback function
1065 * @return @c 0 on success, otherwise a negative error value
1066 * @retval #LOCATIONS_ERROR_NONE Successful
1067 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1068 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1069 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1070 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1071 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1072 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1073 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1074 * @post It invokes gps_status_get_satellites_cb().
1075 * @see gps_status_get_satellite()
1076 * @see gps_status_get_satellites_cb()
1078 int gps_status_foreach_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1081 * @brief Gets the last information of satellites.
1082 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1084 * @privilege %http://tizen.org/privilege/location
1085 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1086 * @param[in] manager The location manager handle
1087 * @param[out] num_of_active The last number of active satellites
1088 * @param[out] num_of_inview The last number of satellites in view
1089 * @param[out] timestamp The last timestamp (time when last measurement took place or @c 0 if valid)
1090 * @return @c 0 on success, otherwise a negative error value
1091 * @retval #LOCATIONS_ERROR_NONE Successful
1092 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1093 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1094 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1095 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1096 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1097 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1098 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1099 * @see gps_status_foreach_satellites_in_view()
1101 int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1104 * @brief Invokes the callback function for each last satellite which is recorded.
1105 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1107 * @privilege %http://tizen.org/privilege/location
1108 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1109 * @param[in] manager The location manager handle
1110 * @param[in] callback The iteration callback function
1111 * @param[in] user_data The user data to be passed to the callback function
1112 * @return @c 0 on success, otherwise a negative error value
1113 * @retval #LOCATIONS_ERROR_NONE Successful
1114 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1115 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1116 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1117 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1118 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1119 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1120 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1121 * @post It invokes gps_status_get_satellites_cb().
1122 * @see gps_status_get_last_satellite()
1123 * @see gps_status_get_satellites_cb()
1125 int gps_status_foreach_last_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1134 #endif /* __TIZEN_LOCATION_LOCATIONS_H__ */