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, /**< GPS/WPS setting is not enabled */
48 LOCATIONS_ERROR_SECURITY_RESTRICTED = TIZEN_ERROR_LOCATION_MANAGER | 0x05, /**< Restricted by security system policy */
53 * @brief Enumeration for Location method type.
54 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
57 LOCATIONS_METHOD_NONE = -1, /**< Undefined method */
58 LOCATIONS_METHOD_HYBRID, /**< This method selects the best method available at the moment */
59 LOCATIONS_METHOD_GPS, /**< This method uses Global Positioning System */
60 LOCATIONS_METHOD_WPS, /**< This method uses WiFi Positioning System */
64 * @brief Enumeration for Approximate accuracy level of given information.
65 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
68 LOCATIONS_ACCURACY_NONE = 0, /**< Invalid data */
69 LOCATIONS_ACCURACY_COUNTRY, /**< Country accuracy level */
70 LOCATIONS_ACCURACY_REGION, /**< Regional accuracy level */
71 LOCATIONS_ACCURACY_LOCALITY, /**< Local accuracy level */
72 LOCATIONS_ACCURACY_POSTALCODE, /**< Postal accuracy level */
73 LOCATIONS_ACCURACY_STREET, /**< Street accuracy level */
74 LOCATIONS_ACCURACY_DETAILED, /**< Detailed accuracy level */
75 } location_accuracy_level_e;
78 * @brief Enumeration for the state of the location service.
79 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
82 LOCATIONS_SERVICE_DISABLED, /**< Service is disabled */
83 LOCATIONS_SERVICE_ENABLED, /**< Service is enabled */
84 } location_service_state_e;
87 * @brief Enumeration for the location service accessibility state.
88 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
91 LOCATIONS_ACCESS_STATE_NONE, /**< Access state is not determined */
92 LOCATIONS_ACCESS_STATE_DENIED, /**< Access denied */
93 LOCATIONS_ACCESS_STATE_ALLOWED, /**< Access authorized */
94 } location_accessibility_state_e;
97 * @brief The location manager handle.
98 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
100 typedef struct location_manager_s *location_manager_h;
109 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
113 * @brief Called at defined interval with updated position information.
114 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
115 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
116 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
117 * @param[in] altitude The updated altitude (meters)
118 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
119 * @param[in] user_data The user data passed from the call registration function
120 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
121 * @see location_manager_start()
122 * @see location_manager_set_position_updated_cb()
124 typedef void(*location_position_updated_cb)(double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
127 * @brief Called at defined interval with updated velocity information.
128 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
129 * @param[in] speed The updated speed (km/h)
130 * @param[in] direction The updated direction (in degrees from the north)
131 * @param[in] climb The updated climb (km/h)
132 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
133 * @param[in] user_data The user data passed from the callback registration function
134 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb().
135 * @see location_manager_start()
136 * @see location_manager_set_velocity_updated_cb()
138 typedef void(*location_velocity_updated_cb)(double speed, double direction, double climb, time_t timestamp, void *user_data);
141 * @brief Called at defined interval with updated location information.
142 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
143 * @param[in] error #LOCATIONS_ERROR_NONE Successful
144 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
145 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
146 * @param[in] altitude The updated altitude (meters)
147 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
148 * @param[in] speed The updated speed (km/h)
149 * @param[in] direction The updated direction (in degrees from the north)
150 * @param[in] climb The updated climb (km/h)
151 * @param[in] user_data The user data passed from the callback registration function
152 * @pre location_manager_request_single_location() will invoke this callback.
153 * @see location_manager_request_single_location()
155 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);
158 * @brief Called when the state of location service is changed from enabled to disabled or vice versa.
159 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
160 * @param[in] state The service state
161 * @param[in] user_data The user data passed from the callback registration function
162 * @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()
163 * @see location_manager_start()
164 * @see location_manager_stop()
165 * @see location_manager_set_service_state_changed_cb()
166 * @see #location_service_state_e
168 typedef void(*location_service_state_changed_cb)(location_service_state_e state, void *user_data);
171 * @brief Called when the user defined zones are entered or exited.
172 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
173 * @param[in] state The boundary state
174 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
175 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
176 * @param[in] altitude The updated altitude (meters)
177 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
178 * @param[in] user_data The user data passed from the callback registration function
179 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb().
180 * @see #location_boundary_state_e
181 * @see location_manager_start()
182 * @see location_manager_set_zone_changed_cb()
184 typedef void(*location_zone_changed_cb)(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
187 * @brief Called when the state of location method is changed.
188 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
189 * @param[in] method The method changed on setting
190 * @param[in] enable The setting value changed
191 * @param[in] user_data The user data passed from the callback registration function
192 * @pre location_setting_changed_cb() will invoke this callback if you register this callback using location_manager_set_setting_changed_cb()
193 * @see location_manager_set_setting_changed_cb()
194 * @see location_manager_unset_setting_changed_cb()
196 typedef void(*location_setting_changed_cb)(location_method_e method, bool enable, void *user_data);
199 * @brief Gets called iteratively to notify you of location bounds.
200 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
201 * @param[in] bounds The location bounds handle
202 * @param[in] user_data The user data passed from the callback registration function
203 * @pre location_manager_foreach_boundary() will invoke this callback.
204 * @see location_manager_foreach_boundary()
206 typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
209 * @brief Called at defined interval with updated location information.
211 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
212 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
213 * @param[in] altitude The updated altitude (meters)
214 * @param[in] speed The updated speed (km/h)
215 * @param[in] direction The updated direction (in degrees from the north)
216 * @param[in] horizontal_accuracy The horizontal accuracy (meters)
217 * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
218 * @param[in] user_data The user data passed from the callback registration function
219 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
220 * @see location_manager_start()
221 * @see location_manager_set_distance_based_location_changed_cb()
222 * @see location_manager_set_location_changed_cb()
224 typedef void(*location_changed_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data);
227 * @brief Checks whether the given location method is available.
228 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
229 * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
230 * @param[in] method The location method to be checked
231 * @return @c true if the specified location method is supported, otherwise @c false if it is not available
232 * @exception #LOCATIONS_ERROR_NONE Successful
233 * @exception #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
234 * @exception #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
235 * @see location_manager_create()
236 * @see location_manager_get_method()
238 bool location_manager_is_supported_method(location_method_e method);
241 * @brief Checks whether the given location method is enabled or not on setting.
242 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
243 * @param[in] method The location method to be checked
244 * @param[out] enable The result value of checking the given location method
245 * @return 0 on success, otherwise a negative error value
246 * @retval #LOCATIONS_ERROR_NONE Successful
247 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
248 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
249 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
250 * @see location_manager_create()
251 * @see location_manager_set_setting_changed_cb()
252 * @see location_manager_unset_setting_changed_cb()
254 int location_manager_is_enabled_method(location_method_e method, bool *enable);
258 * @brief Enable the given location method.
260 * @privlevel platform
261 * @privilege %http://tizen.org/privilege/location.enable
262 * @param[in] method The location method to be checked
263 * @param[in] enable The value to set
264 * @return 0 on success, otherwise a negative error value
265 * @retval #LOCATIONS_ERROR_NONE Successful
266 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
267 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
268 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
269 * @see location_manager_is_enabled_method()
270 * @see location_manager_create()
272 int location_manager_enable_method(const location_method_e method, const bool enable);
275 * @brief Creates a new location manager.
276 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
277 * @remarks You must release @a manager using location_manager_destroy().
278 * @param[in] method The location method
279 * @param[out] manager The location manager handle that is newly created
280 * @return @c 0 on success, otherwise a negative error value
281 * @retval #LOCATIONS_ERROR_NONE Successful
282 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
283 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
284 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
285 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
286 * @see location_manager_destroy()
288 int location_manager_create(location_method_e method, location_manager_h *manager);
291 * @brief Releases the location manager.
292 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
293 * @param[in] manager The location manager handle
294 * @return @c 0 on success, otherwise a negative error value
295 * @retval #LOCATIONS_ERROR_NONE Successful
296 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
297 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
298 * @see location_manager_create()
300 int location_manager_destroy(location_manager_h manager);
303 * @brief Request to update current location once.
304 * @remarks Do not request to start the location service using the same manager handler
305 * Calling this function invokes a location service event. When the location service is updated, location_updated_cb
306 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
308 * @privilege %http://tizen.org/privilege/location
309 * @param[in] manager The location manager handle
310 * @param[in] timeout Timeout to stop requesting single location after
311 * @param[in] callback The location callback function to register
312 * @param[in] user_data The user data to be passed to the callback function
313 * @retval #LOCATIONS_ERROR_NONE Successful
314 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
315 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
316 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
317 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
318 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
319 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
320 * @post It invokes location_updated_cb().
322 int location_manager_request_single_location(location_manager_h manager, int timeout, location_updated_cb callback, void *user_data);
325 * @brief Starts the location service.
326 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
328 * @privilege %http://tizen.org/privilege/location
330 * @remarks There is no limit on number of location managers for which this function was called.
332 * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
333 * (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as
334 * the first argument, and the service starts.
336 * @remarks The started service is a requirement for calling these functions:
337 * location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(),
338 * gps_status_get_nmea(), gps_status_get_satellite(), gps_status_foreach_satellites_in_view().
340 * @remarks Once you stop the service using location_manager_stop(), you can no longer call the functions listed above.
342 * @remarks Starting and stopping the service is in the scope of the given location manager only (if there is more than one manager,
343 * starting and stopping should be executed for each of them separately).
345 * @param[in] manager The location manager handle
346 * @return 0 on success, otherwise a negative error value
347 * @retval #LOCATIONS_ERROR_NONE Successful
348 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
349 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
350 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
351 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
352 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
353 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
354 * @post It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().
355 * @see location_manager_stop()
356 * @see location_manager_get_position()
357 * @see location_manager_get_velocity()
358 * @see location_manager_get_accuracy()
359 * @see location_manager_set_service_state_changed_cb()
360 * @see location_manager_set_position_updated_cb()
361 * @see location_position_updated_cb()
362 * @see location_manager_set_velocity_updated_cb()
363 * @see location_velocity_updated_cb()
364 * @see location_manager_set_zone_changed_cb()
365 * @see location_zone_changed_cb()
367 int location_manager_start(location_manager_h manager);
370 * @brief Stops the location service.
371 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
372 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
373 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
374 * When that happens, the service is stopped and the user is notified.
376 * You can stop and start the location manager as needed.
378 * @param[in] manager The location manager handle
379 * @return 0 on success, otherwise a negative error value
380 * @retval #LOCATIONS_ERROR_NONE Successful
381 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
382 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
383 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
384 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
385 * @see location_manager_start()
386 * @see location_manager_set_service_state_changed_cb()
387 * @see location_service_state_changed_cb()
389 int location_manager_stop(location_manager_h manager);
392 * @brief Adds a bounds for a given location manager.
393 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
394 * @param[in] manager The location manager handle
395 * @param[in] bounds The location bounds handle
396 * @return @c 0 on success, otherwise a negative error value
397 * @retval #LOCATIONS_ERROR_NONE Successful
398 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
399 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
400 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
401 * @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().
402 * @see location_manager_remove_boundary()
403 * @see location_manager_set_zone_changed_cb()
405 int location_manager_add_boundary(location_manager_h manager, const location_bounds_h bounds);
408 * @brief Deletes a bounds for a given location manager.
409 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
410 * @param[in] manager The location manager handle
411 * @param[in] bounds The location bounds handle
412 * @return @c 0 on success, otherwise a negative error value
413 * @retval #LOCATIONS_ERROR_NONE Successful
414 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
415 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
416 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
417 * @see location_manager_add_boundary()
419 int location_manager_remove_boundary(location_manager_h manager, const location_bounds_h bounds);
422 * @brief Retrieves all location bounds by invoking a specific callback for each location bounds
423 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
424 * @param[in] manager The location manager handle
425 * @param[in] callback The iteration callback
426 * @param[in] user_data The user data to be passed to the callback function
427 * @return @c 0 on success, otherwise a negative error value
428 * @retval #LOCATIONS_ERROR_NONE Successful
429 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
430 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
431 * @post location_bounds_cb() will be invoked
432 * @see location_manager_add_boundary()
433 * @see location_manager_remove_boundary()
434 * @see location_bounds_cb()
436 int location_manager_foreach_boundary(location_manager_h manager, location_bounds_cb callback, void *user_data);
439 * @brief Gets the given location manager's method.
440 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
441 * @param[in] manager The location manager handle
442 * @param[out] method The location method
443 * @return @c 0 on success, otherwise a negative error value
444 * @retval #LOCATIONS_ERROR_NONE Successful
445 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
446 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
447 * @see location_manager_create()
449 int location_manager_get_method(location_manager_h manager, location_method_e *method);
452 * @brief Gets the current position information.
453 * @details The result contains the current altitude, latitude, and longitude, with a measurement timestamp.
455 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
457 * @privilege %http://tizen.org/privilege/location
458 * @param[in] manager The location manager handle
459 * @param[out] altitude The current altitude (meters)
460 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
461 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
462 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
463 * @return 0 on success, otherwise a negative error value
464 * @retval #LOCATIONS_ERROR_NONE Successful
465 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
466 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
467 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
468 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
469 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
470 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
472 int location_manager_get_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
475 * @brief Gets the current position information.
476 * @details The result contains the current altitude, latitude, longitude, climb, direction, speed, level, horizontal and vertical with a measurement timestamp.
478 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
480 * @privilege %http://tizen.org/privilege/location
481 * @param[in] manager The location manager handle
482 * @param[out] altitude The current altitude (meters)
483 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
484 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
485 * @param[out] climb The climb (km/h)
486 * @param[out] direction The direction, degrees from the north
487 * @param[out] speed The speed (km/h)
488 * @param[out] level The accuracy level
489 * @param[out] horizontal The horizontal accuracy (meters)
490 * @param[out] vertical The vertical accuracy (meters)
491 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
492 * @return 0 on success, otherwise a negative error value
493 * @retval #LOCATIONS_ERROR_NONE Successful
494 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
495 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
496 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
497 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
498 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
499 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
501 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);
504 * @brief Gets the current velocity information.
505 * @details The result contains the current climb, direction, and speed, with a measurement timestamp.
507 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
509 * @privilege %http://tizen.org/privilege/location
510 * @param[in] manager The location manager handle
511 * @param[out] climb The climb (km/h)
512 * @param[out] direction The direction, degrees from the north
513 * @param[out] speed The speed (km/h)
514 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
515 * @return @c 0 on success, otherwise a negative error value
516 * @retval #LOCATIONS_ERROR_NONE Successful
517 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
518 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
519 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
520 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
521 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
522 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
524 int location_manager_get_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
527 * @brief Gets the current accuracy information.
528 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
530 * @privilege %http://tizen.org/privilege/location
531 * @param[in] manager The location manager handle
532 * @param[out] level The accuracy level
533 * @param[out] horizontal The horizontal accuracy (meters)
534 * @param[out] vertical The vertical accuracy (meters)
535 * @return 0 on success, otherwise a negative error value
536 * @retval #LOCATIONS_ERROR_NONE Successful
537 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
538 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
539 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
540 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
541 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
542 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
544 int location_manager_get_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
547 * @brief Gets the last position information which is recorded.
548 * @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.
549 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
551 * @privilege %http://tizen.org/privilege/location
552 * @param[in] manager The location manager handle
553 * @param[out] altitude The last altitude (meters)
554 * @param[out] latitude The last latitude [-90.0 ~ 90.0] (degrees)
555 * @param[out] longitude The last longitude [-180.0 ~ 180.0] (degrees)
556 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
557 * @return @c 0 on success, otherwise a negative error value
558 * @retval #LOCATIONS_ERROR_NONE Successful
559 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
560 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
561 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
562 * @pre The location manager handle must be created by location_manager_create()
564 int location_manager_get_last_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
567 * @brief Gets the last location information.
568 * @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.
569 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
571 * @privilege %http://tizen.org/privilege/location
572 * @param[in] manager The location manager handle
573 * @param[out] altitude The current altitude (meters)
574 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
575 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
576 * @param[out] climb The climb (km/h)
577 * @param[out] direction The direction, degrees from the north
578 * @param[out] speed The speed (km/h)
579 * @param[out] level The accuracy level
580 * @param[out] horizontal The horizontal accuracy (meters)
581 * @param[out] vertical The vertical accuracy (meters)
582 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
583 * @return @c 0 on success, otherwise a negative error value
584 * @retval #LOCATIONS_ERROR_NONE Successful
585 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
586 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
587 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
588 * @pre The location manager handle must be created by location_manager_create()
590 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);
594 * @brief Gets the last velocity information which is recorded.
595 * @details The @a climb, @a direction and @a speed values should be @c 0, if there is no record of any previous velocity information.
597 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
599 * @privilege %http://tizen.org/privilege/location
600 * @param[in] manager The location manager handle
601 * @param[out] climb The last climb (km/h)
602 * @param[out] direction The last direction, degrees from the north
603 * @param[out] speed The last speed (km/h)
604 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
605 * @return @c 0 on success, otherwise a negative error value
606 * @retval #LOCATIONS_ERROR_NONE Successful
607 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
608 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
609 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
610 * @pre The location manager handle must be created by location_manager_create()
612 int location_manager_get_last_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
615 * @brief Gets the last accuracy information which is recorded.
616 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
618 * @privilege %http://tizen.org/privilege/location
619 * @param[in] manager The location manager handle
620 * @param[out] level The last accuracy level
621 * @param[out] horizontal The last horizontal accuracy (meters)
622 * @param[out] vertical The last vertical accuracy (meters)
623 * @return 0 on success, otherwise a negative error value
624 * @retval #LOCATIONS_ERROR_NONE Successful
625 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
626 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
627 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
628 * @pre The location manager handle must be created by location_manager_create()
630 int location_manager_get_last_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
633 * @brief Gets the current application's location accessibility status.
634 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
635 * @param[out] state The current location service accessibility status.
636 * @return 0 on success, otherwise a negative error value
637 * @retval #LOCATIONS_ERROR_NONE Successful
638 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
639 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
640 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
642 int location_manager_get_accessibility_state(location_accessibility_state_e *state);
645 * @brief Registers a callback function to be invoked at defined interval with updated position information.
647 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
648 * @param[in] manager The location manager handle
649 * @param[in] callback The callback function to register
650 * @param[in] interval The interval [1 ~ 120] (seconds)
651 * @param[in] user_data The user data to be passed to the callback function
652 * @return @c 0 on success, otherwise a negative error value
653 * @retval #LOCATIONS_ERROR_NONE Successful
654 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
655 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
656 * @post location_position_updated_cb() will be invoked
657 * @see location_manager_unset_position_updated_cb()
658 * @see location_position_updated_cb()
660 int location_manager_set_position_updated_cb(location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data);
663 * @brief Unregisters the callback function.
664 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
665 * @param[in] manager The location manager handle
666 * @return @c 0 on success, otherwise a negative error value
667 * @retval #LOCATIONS_ERROR_NONE Successful
668 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
669 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
670 * @see location_manager_set_position_updated_cb()
672 int location_manager_unset_position_updated_cb(location_manager_h manager);
675 * @brief Registers a callback function to be invoked at defined interval with updated velocity information.
676 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
677 * @param[in] manager The location manager handle
678 * @param[in] callback The callback function to register
679 * @param[in] interval The interval [1 ~ 120] (seconds)
680 * @param[in] user_data The user data to be passed to the callback function
681 * @return @c 0 on success, otherwise a negative error value
682 * @retval #LOCATIONS_ERROR_NONE Successful
683 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
684 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
685 * @post location_velocity_updated_cb() will be invoked
686 * @see location_manager_unset_velocity_updated_cb()
687 * @see location_velocity_updated_cb()
689 int location_manager_set_velocity_updated_cb(location_manager_h manager, location_velocity_updated_cb callback, int interval, void *user_data);
692 * @brief Unregisters the callback function.
693 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
694 * @param[in] manager The location manager handle
695 * @return @c 0 on success, otherwise a negative error value
696 * @retval #LOCATIONS_ERROR_NONE Successful
697 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
698 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
699 * @see location_manager_set_velocity_updated_cb()
701 int location_manager_unset_velocity_updated_cb(location_manager_h manager);
704 * @brief Registers a callback function to be invoked when the location service state is changed.
705 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
706 * @param[in] manager The location manager handle
707 * @param[in] callback The callback function to register
708 * @param[in] user_data The user data to be passed to the callback function
709 * @return @c 0 on success, otherwise a negative error value
710 * @retval #LOCATIONS_ERROR_NONE Successful
711 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
712 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
713 * @post location_service_state_changed_cb() will be invoked
714 * @see location_manager_unset_service_state_changed_cb()
715 * @see location_service_state_changed_cb()
716 * @see location_manager_start()
717 * @see location_manager_stop()
718 * @see #location_service_state_e
720 int location_manager_set_service_state_changed_cb(location_manager_h manager, location_service_state_changed_cb callback, void *user_data);
723 * @brief Unregisters the callback function.
724 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
725 * @param[in] manager The location manager handle
726 * @return @c 0 on success, otherwise a negative error value
727 * @retval #LOCATIONS_ERROR_NONE Successful
728 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
729 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
730 * @see location_manager_set_service_state_changed_cb()
732 int location_manager_unset_service_state_changed_cb(location_manager_h manager);
735 * @brief Registers a callback function to be invoked when the previously set boundary area is entered or left.
737 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
738 * @param[in] manager The location manager handle
739 * @param[in] callback The callback function to register
740 * @param[in] user_data The user data to be passed to the callback function
741 * @return @c 0 on success, otherwise a negative error value
742 * @retval #LOCATIONS_ERROR_NONE Successful
743 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
744 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
745 * @pre location_manager_add_boundary() is called before.
746 * @post location_zone_changed_cb() will be invoked
747 * @see location_manager_unset_zone_changed_cb()
748 * @see location_zone_changed_cb()
750 int location_manager_set_zone_changed_cb(location_manager_h manager, location_zone_changed_cb callback, void *user_data);
753 * @brief Unregisters the callback function.
754 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
755 * @param[in] manager The location manager handle
756 * @return 0 on success, otherwise a negative error value
757 * @retval #LOCATIONS_ERROR_NONE Successful
758 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
759 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
760 * @see location_manager_set_zone_changed_cb()
762 int location_manager_unset_zone_changed_cb(location_manager_h manager);
765 * @brief Registers a callback function to be invoked when the location setting is changed.
766 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
767 * @param[in] method The method to observe
768 * @param[in] callback The callback function to register
769 * @param[in] user_data The user data to be passed to the callback function
770 * @return 0 on success, otherwise a negative error value
771 * @retval #LOCATIONS_ERROR_NONE Successful
772 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
773 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
774 * @post location_setting_changed_cb() will be invoked
775 * @see location_manager_unset_setting_changed_cb()
776 * @see location_setting_changed_cb()
778 int location_manager_set_setting_changed_cb(location_method_e method, location_setting_changed_cb callback, 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] method The method to observe
784 * @return 0 on success, otherwise a negative error value
785 * @retval #LOCATIONS_ERROR_NONE Successful
786 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
787 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
788 * @see location_manager_set_setting_changed_cb()
790 int location_manager_unset_setting_changed_cb(location_method_e method);
793 * @brief Gets the distance in meters between two locations.
794 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
795 * @param[in] start_latitude The starting latitude [-90.0 ~ 90.0] (degrees)
796 * @param[in] start_longitude The starting longitude [-180.0 ~ 180.0] (degrees)
797 * @param[in] end_latitude The ending latitude [-90.0 ~ 90.0] (degrees)
798 * @param[in] end_longitude The ending longitude [-180.0 ~ 180.0] (degrees)
799 * @param[out] distance The distance between two locations (meters)
800 * @return 0 on success, otherwise a negative error value
801 * @retval #LOCATIONS_ERROR_NONE Successful
802 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
803 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
805 int location_manager_get_distance(double start_latitude, double start_longitude, double end_latitude, double end_longitude, double *distance);
808 * @brief Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.
810 * @param[in] manager The location manager handle
811 * @param[in] callback The callback function to register
812 * @param[in] interval The minimum interval between position updates [1 ~ 120] (seconds)
813 * @param[in] distance The minimum distance between position updates [1 ~ 120] (meters)
814 * @param[in] user_data The user data to be passed to the callback function
815 * @return @c 0 on success, otherwise a negative error value
816 * @retval #LOCATIONS_ERROR_NONE Successful
817 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
818 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
819 * @post location_changed_cb() will be invoked
820 * @see location_manager_unset_distance_based_location_changed_cb()
821 * @see location_changed_cb()
823 int location_manager_set_distance_based_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, double distance, void *user_data);
826 * @brief Unregisters the callback function.
828 * @param[in] manager The location manager handle
829 * @return @c 0 on success, otherwise a negative error value
830 * @retval #LOCATIONS_ERROR_NONE Successful
831 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
832 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
833 * @see location_manager_set_distance_based_location_changed_cb()
835 int location_manager_unset_distance_based_location_changed_cb(location_manager_h manager);
838 * @brief Registers a callback function to be invoked at defined interval with updated location information.
840 * @param[in] manager The location manager handle
841 * @param[in] callback The callback function to register
842 * @param[in] interval The interval [1 ~ 120] (seconds)
843 * @param[in] user_data The user data to be passed to the callback function
844 * @return @c 0 on success, otherwise a negative error value
845 * @retval #LOCATIONS_ERROR_NONE Successful
846 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
847 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
848 * @post location_changed_cb() will be invoked
849 * @see location_manager_unset_location_changed_cb()
850 * @see location_changed_cb()
852 int location_manager_set_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, void *user_data);
855 * @brief Unregisters the callback function.
857 * @param[in] manager The location manager handle
858 * @return @c 0 on success, otherwise a negative error value
859 * @retval #LOCATIONS_ERROR_NONE Successful
860 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
861 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
862 * @see location_manager_set_location_changed_cb()
864 int location_manager_unset_location_changed_cb(location_manager_h manager);
871 * GPS Status & Satellites
875 * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE
880 * @brief Called once for each satellite in range.
881 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
882 * @param[in] azimuth The azimuth of the satellite (degrees)
883 * @param[in] elevation The elevation of the satellite (meters)
884 * @param[in] prn The PRN of the satellite
885 * @param[in] snr The SNR of the satellite [dB]
886 * @param[in] is_active The flag signaling if satellite is in use
887 * @param[in] user_data The user data passed from the foreach function
888 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
889 * @pre gps_status_foreach_satellites_in_view() will invoke this callback.
890 * @pre gps_status_foreach_last_satellites_in_view() will invoke this callback.
891 * @see gps_status_foreach_satellites_in_view()
893 typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data);
896 * @brief Called at defined interval with updated satellite information.
897 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
898 * @param[out] num_of_active The last number of active satellites
899 * @param[out] num_of_inview The last number of satellites in view
900 * @param[out] timestamp The last timestamp (time when measurement took place or @c 0 if valid)
901 * @param[in] user_data The user data passed from the call registration function
902 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
903 * @see location_manager_start()
904 * @see location_manager_set_position_updated_cb()
906 typedef void(*gps_status_satellite_updated_cb)(int num_of_active, int num_of_inview, time_t timestamp, void *user_data);
909 * @brief Gets the GPS NMEA data.
910 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
911 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
912 * You must release @a nmea using @c free().
913 * @param[in] manager The location manager handle
914 * @param[out] nmea The NMEA data
915 * @return @c 0 on success, otherwise a negative error value
916 * @retval #LOCATIONS_ERROR_NONE Successful
917 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
918 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
919 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
920 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
921 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
922 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
923 * @see location_manager_start()
925 int gps_status_get_nmea(location_manager_h manager, char **nmea);
928 * @brief Gets the information of satellites.
929 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
931 * @privilege %http://tizen.org/privilege/location
932 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
933 * @param[in] manager The location manager handle
934 * @param[out] num_of_active The number of active satellites
935 * @param[out] num_of_inview The number of satellites in view
936 * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
937 * @return @c 0 on success, otherwise a negative error value
938 * @retval #LOCATIONS_ERROR_NONE Successful
939 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
940 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
941 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
942 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
943 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
944 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
945 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
946 * @see gps_status_foreach_satellites_in_view()
948 int gps_status_get_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
951 * @brief Registers a callback function to be invoked at defined interval with updated satellite information.
952 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
954 * @privilege %http://tizen.org/privilege/location
955 * @param[in] manager The location manager handle
956 * @param[in] callback The callback function to register
957 * @param[in] interval The interval [1 ~ 120] (seconds)
958 * @param[in] user_data The user data to be passed to the callback function
959 * @return 0 on success, otherwise a negative error value
960 * @retval #LOCATIONS_ERROR_NONE Successful
961 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
962 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
963 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
964 * @post gps_status_satellite_updated_cb() will be invoked
965 * @see gps_status_unset_satellite_updated_cb()
966 * @see gps_status_satellite_updated_cb()
967 * @see gps_status_get_satellite()
968 * @see gps_status_foreach_satellites_in_view()
969 * @see gps_status_get_last_satellite()
970 * @see gps_status_foreach_last_satellites_in_view()
972 int gps_status_set_satellite_updated_cb(location_manager_h manager, gps_status_satellite_updated_cb callback, int interval, void *user_data);
975 * @brief Unregisters the callback function.
976 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
978 * @privilege %http://tizen.org/privilege/location
979 * @param[in] manager The location manager handle
980 * @return @c 0 on success, otherwise a negative error value
981 * @retval #LOCATIONS_ERROR_NONE Successful
982 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
983 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
984 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
985 * @see gps_status_set_satellite_updated_cb()
987 int gps_status_unset_satellite_updated_cb(location_manager_h manager);
990 * @brief Invokes the callback function for each satellite.
991 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
993 * @privilege %http://tizen.org/privilege/location
994 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
995 * @param[in] manager The location manager handle
996 * @param[in] callback The iteration callback function
997 * @param[in] user_data The user data to be passed to the callback function
998 * @return @c 0 on success, otherwise a negative error value
999 * @retval #LOCATIONS_ERROR_NONE Successful
1000 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1001 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1002 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1003 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1004 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1005 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1006 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1007 * @post It invokes gps_status_get_satellites_cb().
1008 * @see gps_status_get_satellite()
1009 * @see gps_status_get_satellites_cb()
1011 int gps_status_foreach_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1014 * @brief Gets the last information of satellites.
1015 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1017 * @privilege %http://tizen.org/privilege/location
1018 * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1019 * @param[in] manager The location manager handle
1020 * @param[out] num_of_active The last number of active satellites
1021 * @param[out] num_of_inview The last number of satellites in view
1022 * @param[out] timestamp The last timestamp (time when last measurement took place or @c 0 if valid)
1023 * @return @c 0 on success, otherwise a negative error value
1024 * @retval #LOCATIONS_ERROR_NONE Successful
1025 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1026 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1027 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1028 * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1029 * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1030 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1031 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1032 * @see gps_status_foreach_satellites_in_view()
1034 int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1037 * @brief Invokes the callback function for each last satellite which is recorded.
1038 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1040 * @privilege %http://tizen.org/privilege/location
1041 * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1042 * @param[in] manager The location manager handle
1043 * @param[in] callback The iteration callback function
1044 * @param[in] user_data The user data to be passed to the callback function
1045 * @return @c 0 on success, otherwise a negative error value
1046 * @retval #LOCATIONS_ERROR_NONE Successful
1047 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1048 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1049 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
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 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
1053 * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb()
1054 * @post It invokes gps_status_get_satellites_cb().
1055 * @see gps_status_get_last_satellite()
1056 * @see gps_status_get_satellites_cb()
1058 int gps_status_foreach_last_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1067 #endif /* __TIZEN_LOCATION_LOCATIONS_H__ */