2 * Copyright (c) 2011 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>
28 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
33 * @brief Enumerations of error code for Location manager.
37 LOCATIONS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
38 LOCATIONS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
39 LOCATIONS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
40 LOCATIONS_ERROR_INCORRECT_METHOD = TIZEN_ERROR_LOCATION_CLASS | 0x01, /**< Location manager contains incorrect method for a given call */
41 LOCATIONS_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_CLASS | 0x02, /**< Network unavailable */
42 LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_CLASS | 0x03, /**< Service unavailable */
43 LOCATIONS_ERROR_GPS_SETTING_OFF = TIZEN_ERROR_LOCATION_CLASS | 0x04, /**< GPS is not enabled */
49 * @brief Location method type.
53 LOCATIONS_METHOD_NONE=-1, /**< Undefined method. */
54 LOCATIONS_METHOD_HYBRID, /**< This method selects the best method available at the moment. */
55 LOCATIONS_METHOD_GPS, /**< This method uses Global Positioning System. */
56 LOCATIONS_METHOD_WPS, /**< This method uses Wifi Positioning System. */
57 LOCATIONS_METHOD_SPS /**< This method uses sensor. */
61 * @brief Approximate accuracy level of given information.
65 LOCATIONS_ACCURACY_NONE=0, /**< Invalid data. */
66 LOCATIONS_ACCURACY_COUNTRY, /**< Country accuracy level. */
67 LOCATIONS_ACCURACY_REGION, /**< Regional accuracy level. */
68 LOCATIONS_ACCURACY_LOCALITY, /**< Local accuracy level. */
69 LOCATIONS_ACCURACY_POSTALCODE, /**< Postal accuracy level. */
70 LOCATIONS_ACCURACY_STREET, /**< Street accuracy level. */
71 LOCATIONS_ACCURACY_DETAILED, /**< Detailed accuracy level. */
72 } location_accuracy_level_e;
75 * @brief Enumerations of the state of the location service.
79 LOCATIONS_SERVICE_DISABLED, /**< Service is disabled */
80 LOCATIONS_SERVICE_ENABLED /**< Service is enabled */
81 } location_service_state_e;
84 * @brief Enumerations of the boundary state.
88 LOCATIONS_BOUNDARY_IN, /**< Boundary In (Zone In) */
89 LOCATIONS_BOUNDARY_OUT /**< Boundary Out (Zone Out) */
90 } location_boundary_state_e;
93 * @brief The location manager handle.
95 typedef struct location_manager_s *location_manager_h;
104 * @addtogroup CAPI_LOCATION_MANAGER_MODULE
108 * @brief Called every 1 second with updated position information.
109 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
110 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
111 * @param[in] altitude The updated altitude (meters)
112 * @param[in] timestamp The timestamp (time when measurement took place)
113 * @param[in] user_data The user data passed from the call registration function
114 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
115 * @see location_manager_start()
116 * @see location_manager_set_position_updated_cb()
118 typedef void(*location_position_updated_cb )(double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
121 * @brief Called every 1 second with updated velocity information.
122 * @param[in] speed The updated speed (km/h)
123 * @param[in] direction The updated direction (in degrees from the north)
124 * @param[in] climb The updated climb (km/h)
125 * @param[in] timestamp The timestamp (time when measurement took place)
126 * @param[in] user_data The user data passed from the callback registration function
127 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb()
128 * @see location_manager_start()
129 * @see location_manager_set_velocity_updated_cb()
131 typedef void(*location_velocity_updated_cb )(double speed, double direction, double climb, time_t timestamp, void *user_data);
134 * @brief Called when the state of location service is changed from enabled to disabled or vice versa.
135 * @param[in] state The service state
136 * @param[in] user_data The user data passed from the callback registration function
137 * @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()
138 * @see location_manager_start()
139 * @see location_manager_stop()
140 * @see location_manager_set_service_state_changed_cb()
141 * @see #location_service_state_e
143 typedef void(*location_service_state_changed_cb )(location_service_state_e state, void *user_data);
146 * @brief Called when the user defined zones are entered or exited.
147 * @param[in] state The boundary state
148 * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
149 * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
150 * @param[in] altitude The updated altitude (meters)
151 * @param[in] timestamp The timestamp (time when measurement took place)
152 * @param[in] user_data The user data passed from the callback registration function
153 * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb()
154 * @see #location_boundary_state_e
155 * @see location_manager_start()
156 * @see location_manager_set_zone_changed_cb()
158 typedef void(*location_zone_changed_cb )(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
161 * @brief Checks whether the given location method is avaliable or not.
162 * @param[in] method The location method to be checked
163 * @return @c true if the specified location method is supported, \n else @c false
164 * @see location_manager_create()
165 * @see location_manager_get_method()
167 bool location_manager_is_supported_method(location_method_e method);
171 * @brief Creates a new location manager.
172 * @remarks @a manager must be released location_manager_destroy() by you.
173 * @param[in] method The location method
174 * @param[out] manager A location manager handle to be newly created on success
175 * @return 0 on success, otherwise a negative error value.
176 * @retval #LOCATIONS_ERROR_NONE Successful
177 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
178 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
179 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
180 * @see location_manager_destroy()
182 int location_manager_create(location_method_e method, location_manager_h* manager);
185 * @brief Releases the location manager.
186 * @param[in] manager The location manager handle
187 * @return 0 on success, otherwise a negative error value.
188 * @retval #LOCATIONS_ERROR_NONE Successful
189 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
190 * @see location_manager_create()
192 int location_manager_destroy(location_manager_h manager);
195 * @brief Starts the location service.
197 * @remarks There is no limit on number of location managers for which this function was called.
199 * Calling this function invokes a location service event. When the location service is enabled, the service state change callback
200 * (set using #location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as
201 * the first argument, and the service starts. \n
203 * Started service is a requirement for calling these functions:
205 * location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(),
206 * #gps_status_get_nmea(), gps_status_get_satellite_count_in_view(), gps_status_foreach_satellites_in_view(), gps_status_get_active_satellite_count().
208 * Once you stop the service, using #location_manager_stop(), you can no longer call the functions listed above.
210 * Starting and stopping the service is in the scope of the given location manager only (if there's more than one manager,
211 * starting and stopping should be executed for each of them separately).
213 * @param[in] manager The location manager handle
214 * @return 0 on success, otherwise a negative error value.
215 * @retval #LOCATIONS_ERROR_NONE Successful
216 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
217 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
218 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
219 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
220 * @post It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().
221 * @see location_manager_stop()
222 * @see location_manager_get_position()
223 * @see location_manager_get_velocity()
224 * @see location_manager_get_accuracy()
225 * @see location_manager_set_service_state_changed_cb()
226 * @see location_manager_set_position_updated_cb()
227 * @see location_position_updated_cb()
228 * @see location_manager_set_velocity_updated_cb()
229 * @see location_velocity_updated_cb()
230 * @see location_manager_set_zone_changed_cb()
231 * @see location_zone_changed_cb()
233 int location_manager_start(location_manager_h manager);
236 * @brief Stops the location service.
237 * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
238 * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
239 * When that happens, the service is stopped and the user is notified.
241 * You can stop and start the location manager as needed.
243 * @param[in] manager The location manager handle
244 * @return 0 on success, otherwise a negative error value.
245 * @retval #LOCATIONS_ERROR_NONE Successful
246 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
247 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
248 * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
249 * @see location_manager_start()
250 * @see location_manager_set_service_state_changed_cb()
251 * @see location_service_state_changed_cb()
253 int location_manager_stop(location_manager_h manager);
256 * @brief Sets a rectangular boundary for a given location manager.
257 * @param[in] manager The location manager handle
258 * @param[in] top_left_latitude The latitude of area's top left corner [-90.0 ~ 90.0] (degrees)
259 * @param[in] top_left_longitude The longitude of area's top left corner [-180.0 ~ 180.0] (degrees)
260 * @param[in] bottom_right_latitude The latitude of area's bottom right corner [-90.0 ~ 90.0] (degrees)
261 * @param[in] bottom_right_longitude The longitude of area's bottom right corner [-180.0 ~ 180.0] (degrees)
262 * @return 0 on success, otherwise a negative error value.
263 * @retval #LOCATIONS_ERROR_NONE Successful
264 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
265 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
266 * @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().
267 * @see location_manager_set_boundary_circle()
268 * @see location_manager_set_zone_changed_cb()
269 * @see location_manager_is_boundary_contains_coordinate()
271 int location_manager_set_boundary_rect(location_manager_h manager, double top_left_latitude, double top_left_longitude, double bottom_right_latitude, double bottom_right_longitude);
274 * @brief Sets a circular boundary for a given location manager.
275 * @param[in] manager The location manager handle
276 * @param[in] center_latitude The latitude of circle's center [-90.0 ~ 90.0] (degrees)
277 * @param[in] center_longitude The longitude of circle's center [-180.0 ~ 180.0] (degrees)
278 * @param[in] radius The radius of a circle (meters)
279 * @return 0 on success, otherwise a negative error value.
280 * @retval #LOCATIONS_ERROR_NONE Successful
281 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
282 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
283 * @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().
284 * @see location_manager_set_boundary_rect()
285 * @see location_manager_set_zone_changed_cb()
286 * @see location_manager_is_boundary_contains_coordinate()
288 int location_manager_set_boundary_circle(location_manager_h manager, double center_latitude, double center_longitude, double radius);
291 * @brief Check if the boundary contains the specified latitude and longitude.
292 * @param[in] manager The location manager handle
293 * @param[in] latitude The latitude to test against boundary [-90.0 ~ 90.0] (degrees)
294 * @param[in] longitude The longitude to test against boundary [-180.0 ~ 180.0] (degrees)
295 * @param[out] contained The result indicating whether the boundary contains the specified coordinate (@c true = contained, @c false = not contained )
296 * @return 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_OUT_OF_MEMORY Out of memory
300 * @see location_manager_set_boundary_rect()
301 * @see location_manager_set_boundary_circle()
303 int location_manager_is_boundary_contains_coordinate(location_manager_h manager, double latitude, double longitude, bool *contained);
306 * @brief Gets the given location manager's method.
308 * @param[in] manager The location manager handle
309 * @param[out] method The location method
310 * @return 0 on success, otherwise a negative error value.
311 * @retval #LOCATIONS_ERROR_NONE Successful
312 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
313 * @see location_manager_create()
315 int location_manager_get_method(location_manager_h manager, location_method_e *method);
318 * @brief Gets the current position information.
320 * The result is current altitude, latitude, and longitude, with a measurement timestamp.
322 * If @a altitude is negative, only altitude and latitude are available (fix status is 2D).
323 * If @a altitude is positive, fix status is 3D and returned altitude value is the result of measurement.
325 * @param[in] manager The location manager handle
326 * @param[out] altitude The current altitude (meters)
327 * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
328 * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
329 * @param[out] timestamp The timestamp (time when measurement took place)
330 * @return 0 on success, otherwise a negative error value.
331 * @retval #LOCATIONS_ERROR_NONE Successful
332 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
333 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
334 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
335 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
337 int location_manager_get_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
340 * @brief Gets the current velocity information.
342 * The result is current climb, direction, and speed, with a measurement timestamp.
344 * @param[in] manager The location manager handle
345 * @param[out] climb The climb (km/h)
346 * @param[out] direction The direction, degrees from the north
347 * @param[out] speed The speed (km/h)
348 * @param[out] timestamp The timestamp (time when measurement took place)
349 * @return 0 on success, otherwise a negative error value.
350 * @retval #LOCATIONS_ERROR_NONE Successful
351 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
352 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
353 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
354 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
356 int location_manager_get_velocity(location_manager_h manager, int *climb, int *direction, int *speed, time_t *timestamp);
359 * @brief Gets the current accuracy information.
360 * @param[in] manager The location manager handle
361 * @param[out] level The accuracy level
362 * @param[out] horizontal The horizontal accuracy (meters)
363 * @param[out] vertical The vertical accuracy (meters)
364 * @return 0 on success, otherwise a negative error value.
365 * @retval #LOCATIONS_ERROR_NONE Successful
366 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
367 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
368 * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
369 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
371 int location_manager_get_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
374 * @brief Gets the last known position information which is recorded.
376 * The @altitude, @latitude, @longitude, and @timestamp values should be 0, if there is no record of any previous position information.
377 * @param[in] manager The location manager handle
378 * @param[out] altitude The last known altitude (meters)
379 * @param[out] latitude The last known latitude [-90.0 ~ 90.0] (degrees)
380 * @param[out] longitude The last known longitude [-180.0 ~ 180.0] (degrees)
381 * @param[out] timestamp The timestamp (time when measurement took place)
382 * @return 0 on success, otherwise a negative error value.
383 * @retval #LOCATIONS_ERROR_NONE Successful
384 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
385 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
386 * @pre The location manager handle must be created by location_manager_create()
388 int location_manager_get_last_known_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
391 * @brief Registers a callback function to be invoked every 1 second with updated position information.
393 * @param[in] manager The location manager handle
394 * @param[in] callback The callback function to register
395 * @param[in] interval The interval [1 ~ 120] (seconds)
396 * @param[in] user_data The user data to be passed to the callback function
397 * @return 0 on success, otherwise a negative error value.
398 * @retval #LOCATIONS_ERROR_NONE Successful
399 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
400 * @post location_position_updated_cb() will be invoked
401 * @see location_manager_unset_position_updated_cb()
402 * @see location_position_updated_cb()
404 int location_manager_set_position_updated_cb(location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data);
407 * @brief Unregisters the callback function.
409 * @param[in] manager The location manager handle
410 * @return 0 on success, otherwise a negative error value.
411 * @retval #LOCATIONS_ERROR_NONE Successful
412 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
413 * @see location_manager_set_position_updated_cb()
415 int location_manager_unset_position_updated_cb(location_manager_h manager);
418 * @brief Registers a callback function to be invoked every 1 second with updated velocity information.
420 * @param[in] manager The location manager handle
421 * @param[in] callback The callback function to register
422 * @param[in] user_data The user data to be passed to the callback function
423 * @return 0 on success, otherwise a negative error value.
424 * @retval #LOCATIONS_ERROR_NONE Successful
425 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
426 * @post location_velocity_updated_cb() will be invoked
427 * @see location_manager_unset_velocity_updated_cb()
428 * @see location_velocity_updated_cb()
430 int location_manager_set_velocity_updated_cb(location_manager_h manager, location_velocity_updated_cb callback, void *user_data);
433 * @brief Unregisters the callback function.
435 * @param[in] manager The location manager handle
436 * @return 0 on success, otherwise a negative error value.
437 * @retval #LOCATIONS_ERROR_NONE Successful
438 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
439 * @see location_manager_set_velocity_updated_cb()
441 int location_manager_unset_velocity_updated_cb(location_manager_h manager);
444 * @brief Registers a callback function to be invoked when the location service state is changed.
446 * @param[in] manager The location manager handle
447 * @param[in] callback The callback function to register
448 * @param[in] user_data The user data to be passed to the callback function
449 * @return 0 on success, otherwise a negative error value.
450 * @retval #LOCATIONS_ERROR_NONE Successful
451 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
452 * @post location_service_state_changed_cb() will be invoked
453 * @see location_manager_unset_service_state_changed_cb()
454 * @see location_service_state_changed_cb()
455 * @see location_manager_start()
456 * @see location_manager_stop()
457 * @see #location_service_state_e
459 int location_manager_set_service_state_changed_cb(location_manager_h manager, location_service_state_changed_cb callback, void *user_data);
462 * @brief Unregisters the callback function.
463 * @param[in] manager The location manager handle
464 * @return 0 on success, otherwise a negative error value.
465 * @retval #LOCATIONS_ERROR_NONE Successful
466 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
467 * @see location_manager_set_service_state_changed_cb()
469 int location_manager_unset_service_state_changed_cb(location_manager_h manager);
472 * @brief Registers a callback function to be invoked when the previously set boundary area is entered or left.
474 * @param[in] manager The location manager handle
475 * @param[in] callback The callback function to register
476 * @param[in] user_data The user data to be passed to the callback function
477 * @return 0 on success, otherwise a negative error value.
478 * @retval #LOCATIONS_ERROR_NONE Successful
479 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
480 * @pre Either location_manager_set_boundary_rect() or location_manager_set_boundary_circle() is called before.
481 * @post location_zone_changed_cb() will be invoked
482 * @see location_manager_unset_zone_changed_cb()
483 * @see location_zone_changed_cb()
485 int location_manager_set_zone_changed_cb(location_manager_h manager, location_zone_changed_cb callback, void *user_data);
488 * @brief Unregisters the callback function.
489 * @param[in] manager The location manager handle
490 * @return 0 on success, otherwise a negative error value.
491 * @retval #LOCATIONS_ERROR_NONE Successful
492 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
493 * @see location_manager_set_zone_changed_cb()
495 int location_manager_unset_zone_changed_cb(location_manager_h manager);
501 * GPS Status & Satellites
505 * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE
510 * @brief Called once for each satellite in range.
511 * @param[in] azimuth The azimuth of the satellite (degrees)
512 * @param[in] elevation The elevation of the satellite (meters)
513 * @param[in] prn The PRN of the satellite
514 * @param[in] snr The SNR of the satellite [dB]
515 * @param[in] is_active The flag signaling if satellite is in use
516 * @param[in] user_data The user data passed from the foreach function
517 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
518 * @pre gps_status_foreach_satellites_in_view() will invoke this callback.
519 * @see gps_status_foreach_satellites_in_view()
521 typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data);
524 * @brief Gets the GPS NMEA data.
527 * This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.\n
528 * @a nmea must be released with @c free() by you.
530 * @param[in] manager The location manager handle
531 * @param[out] nmea The NMEA data
532 * @return 0 on success, otherwise a negative error value.
533 * @retval #LOCATIONS_ERROR_NONE Successful
534 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
535 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
536 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
537 * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
538 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
539 * @see location_manager_start()
541 int gps_status_get_nmea(location_manager_h manager, char **nmea);
544 * @brief Gets the number of satellites in view.
547 * This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
549 * @param[in] manager The location manager handle
550 * @param[out] count The number of satellites in view
551 * @return 0 on success, otherwise a negative error value.
552 * @retval #LOCATIONS_ERROR_NONE Successful
553 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
554 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
555 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
556 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
557 * @see gps_status_foreach_satellites_in_view()
559 int gps_status_get_satellite_count_in_view(location_manager_h manager, int *count);
562 * @brief Invokes the callback function for each satellite.
565 * This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
567 * @param[in] manager The location manager handle
568 * @param[in] callback The iteration callback function
569 * @param[in] user_data The user data to be passed to the callback function
570 * @return 0 on success, otherwise a negative error value.
571 * @retval #LOCATIONS_ERROR_NONE Successful
572 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
573 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
574 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
575 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
576 * @post It invokes gps_status_get_satellites_cb().
577 * @see gps_status_get_satellite_count_in_view()
578 * @see gps_status_get_satellites_cb()
580 int gps_status_foreach_satellites_in_view (location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
583 * @brief Gets the number of satellites available to be used.
586 * This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
588 * @param[in] manager The location manager handle
589 * @param[out] count The number of active satellites
590 * @return 0 on success, otherwise a negative error value.
591 * @retval #LOCATIONS_ERROR_NONE Successful
592 * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
593 * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
594 * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
595 * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
596 * @see gps_status_get_satellite_count_in_view()
598 int gps_status_get_active_satellite_count(location_manager_h manager, int *count);
606 #endif /* __TIZEN_LOCATION_LOCATIONS_H__ */