include/locations.h

   1 /*
   2  * Copyright (c) 2011-2013 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 #ifndef __TIZEN_LOCATION_LOCATIONS_H__
  18 #define __TIZEN_LOCATION_LOCATIONS_H__
  19
  20 #include <tizen.h>
  21 #include <tizen_type.h>
  22 #include <tizen_error.h>
  23 #include <time.h>
  24 #include <location_bounds.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30
  31 /**
  32  * @addtogroup CAPI_LOCATION_MANAGER_MODULE
  33  * @{
  34  */
  35
  36
  37 /**
  38  * @brief Enumeration for error code for Location manager.
  39  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  40  */
  41 typedef enum {
  42         LOCATIONS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  43         LOCATIONS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  44         LOCATIONS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  45         LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  46         LOCATIONS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
  47         LOCATIONS_ERROR_INCORRECT_METHOD = TIZEN_ERROR_LOCATION_MANAGER | 0x01, /**< Location manager contains incorrect method for a given call */
  48         LOCATIONS_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_MANAGER | 0x02, /**< Network unavailable */
  49         LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_MANAGER | 0x03, /**< Location service is not available */
  50         LOCATIONS_ERROR_GPS_SETTING_OFF = TIZEN_ERROR_LOCATION_MANAGER | 0x04, /**< Setting for GPS, WPS, or MOCK is turned off */
  51         LOCATIONS_ERROR_SECURITY_RESTRICTED = TIZEN_ERROR_LOCATION_MANAGER | 0x05, /**< Restricted by security system policy */
  52         LOCATIONS_ERROR_SETTING_OFF = LOCATIONS_ERROR_GPS_SETTING_OFF, /**< Setting for GPS, WPS, or MOCK is turned off (Since 3.0) */
  53 } location_error_e;
  54
  55
  56 /**
  57  * @brief Enumeration for Location method type.
  58  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  59  */
  60 typedef enum {
  61         LOCATIONS_METHOD_NONE = -1, /**< Undefined method */
  62         LOCATIONS_METHOD_HYBRID, /**< This method selects the best method available at the moment */
  63         LOCATIONS_METHOD_GPS, /**< This method uses Global Positioning System */
  64         LOCATIONS_METHOD_WPS, /**< This method uses WiFi Positioning System */
  65         LOCATIONS_METHOD_PASSIVE, /**< This method can be used to passively receive location updates without power consumption (Since 3.0)*/
  66 } location_method_e;
  67
  68
  69 /**
  70  * @brief Enumeration for Approximate accuracy level of given information.
  71  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  72  */
  73 typedef enum {
  74         LOCATIONS_ACCURACY_NONE = 0, /**< Invalid data */
  75         LOCATIONS_ACCURACY_COUNTRY, /**< Country accuracy level */
  76         LOCATIONS_ACCURACY_REGION, /**< Regional accuracy level */
  77         LOCATIONS_ACCURACY_LOCALITY, /**< Local accuracy level */
  78         LOCATIONS_ACCURACY_POSTALCODE, /**< Postal accuracy level */
  79         LOCATIONS_ACCURACY_STREET, /**< Street accuracy level */
  80         LOCATIONS_ACCURACY_DETAILED, /**< Detailed accuracy level */
  81 } location_accuracy_level_e;
  82
  83
  84 /**
  85  * @brief Enumeration for the state of the location service.
  86  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  87  */
  88 typedef enum {
  89         LOCATIONS_SERVICE_DISABLED, /**< Service is disabled */
  90         LOCATIONS_SERVICE_ENABLED, /**< Service is enabled */
  91 } location_service_state_e;
  92
  93
  94 /**
  95  * @deprecated Deprecated since 3.0
  96  * @brief Enumeration for the location service accessibility state.
  97  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  98  */
  99 typedef enum {
 100         LOCATIONS_ACCESS_STATE_NONE, /**< Access state is not determined */
 101         LOCATIONS_ACCESS_STATE_DENIED, /**< Access denied */
 102         LOCATIONS_ACCESS_STATE_ALLOWED, /**< Access authorized */
 103 } location_accessibility_state_e;
 104
 105
 106 /**
 107  * @brief The location manager handle.
 108  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 109  */
 110 typedef struct location_manager_s *location_manager_h;
 111
 112
 113 /**
 114  * @}
 115  */
 116 /*
 117  * Location Manager
 118 */
 119
 120
 121 /**
 122  * @addtogroup CAPI_LOCATION_MANAGER_MODULE
 123  * @{
 124  */
 125
 126
 127 /**
 128  * @brief Called at defined interval with updated position information.
 129  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 130  * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
 131  * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
 132  * @param[in] altitude The updated altitude (meters)
 133  * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 134  * @param[in] user_data The user data passed from the call registration function
 135  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
 136  * @see location_manager_start()
 137  * @see location_manager_set_position_updated_cb()
 138  */
 139 typedef void(*location_position_updated_cb)(double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
 140
 141
 142 /**
 143  * @brief Called at defined interval with updated velocity information.
 144  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 145  * @param[in] speed The updated speed (km/h)
 146  * @param[in] direction The updated direction (in degrees from the north)
 147  * @param[in] climb The updated climb (km/h)
 148  * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 149  * @param[in] user_data The user data passed from the callback registration function
 150  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb().
 151  * @see location_manager_start()
 152  * @see location_manager_set_velocity_updated_cb()
 153  */
 154 typedef void(*location_velocity_updated_cb)(double speed, double direction, double climb, time_t timestamp, void *user_data);
 155
 156
 157 /**
 158  * @brief Called at defined interval with updated location information.
 159  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 160  * @param[in] error #LOCATIONS_ERROR_NONE Successful
 161  * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
 162  * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
 163  * @param[in] altitude The updated altitude (meters)
 164  * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 165  * @param[in] speed The updated speed (km/h)
 166  * @param[in] direction The updated direction (in degrees from the north)
 167  * @param[in] climb The updated climb (km/h)
 168  * @param[in] user_data The user data passed from the callback registration function
 169  * @pre location_manager_request_single_location() will invoke this callback.
 170  * @see location_manager_request_single_location()
 171  */
 172 typedef void(*location_updated_cb)(location_error_e error, double latitude, double longitude, double altitude, time_t timestamp, double speed, double direction, double climb, void *user_data);
 173
 174
 175 /**
 176  * @brief Called when the state of location service is changed from enabled to disabled or vice versa.
 177  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 178  * @param[in] state The service state
 179  * @param[in] user_data The user data passed from the callback registration function
 180  * @pre Either location_manager_start() or location_manager_stop() will invoke this callback if you register this callback using location_manager_set_service_state_changed_cb().
 181  * @see location_manager_start()
 182  * @see location_manager_stop()
 183  * @see location_manager_set_service_state_changed_cb()
 184  * @see #location_service_state_e
 185  */
 186 typedef void(*location_service_state_changed_cb)(location_service_state_e state, void *user_data);
 187
 188
 189 /**
 190  * @brief Called when the user-defined zones are entered or exited.
 191  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 192  * @param[in] state The boundary state
 193  * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
 194  * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
 195  * @param[in] altitude The updated altitude (meters)
 196  * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 197  * @param[in] user_data The user data passed from the callback registration function
 198  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb().
 199  * @see #location_boundary_state_e
 200  * @see location_manager_start()
 201  * @see location_manager_set_zone_changed_cb()
 202  */
 203 typedef void(*location_zone_changed_cb)(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
 204
 205
 206 /**
 207  * @brief Called when the state of location method is changed.
 208  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 209  * @param[in] method The method changed on setting
 210  * @param[in] enable The setting value changed
 211  * @param[in] user_data The user data passed from the callback registration function
 212  * @pre location_setting_changed_cb() will invoke this callback if you register this callback using location_manager_set_setting_changed_cb().
 213  * @see location_manager_set_setting_changed_cb()
 214  * @see location_manager_unset_setting_changed_cb()
 215  */
 216 typedef void(*location_setting_changed_cb)(location_method_e method, bool enable, void *user_data);
 217
 218
 219 /**
 220  * @brief Called once for each location bound.
 221  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 222  * @param[in] bounds The location bounds handle
 223  * @param[in] user_data The user data passed from the callback registration function
 224  * @return @c true to continue with the next iteration of the loop,
 225  *         otherwise @c false to break out of the loop
 226  * @pre location_manager_foreach_boundary() will invoke this callback.
 227  * @see location_manager_foreach_boundary()
 228  */
 229 typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
 230
 231
 232 /**
 233  * @brief Called at defined interval with updated location information.
 234  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 235  * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
 236  * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
 237  * @param[in] altitude The updated altitude (meters)
 238  * @param[in] speed The updated speed (km/h)
 239  * @param[in] direction The updated direction (in degrees from the north)
 240  * @param[in] horizontal_accuracy The horizontal accuracy (meters)
 241  * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 242  * @param[in] user_data The user data passed from the callback registration function
 243  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
 244  * @see location_manager_start()
 245  * @see location_manager_set_distance_based_location_changed_cb()
 246  * @see location_manager_set_location_changed_cb()
 247  */
 248 typedef void(*location_changed_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal_accuracy, time_t timestamp, void *user_data);
 249
 250
 251 /**
 252  * @brief Called when the batch interval is expired.
 253  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 254  * @param[in] num_of_location The number of location batch data
 255  * @param[in] user_data The user data passed from the callback registration function
 256  * @pre location_manager_start_batch() will invoke this callback if you register this callback using location_manager_set_location_batch_cb().
 257  * @see location_manager_start_batch()
 258  * @see location_manager_set_location_batch_cb()
 259  */
 260 typedef void(*location_batch_cb)(int num_of_location, void *user_data);
 261
 262
 263 /**
 264  * @brief Gets iteratively to receive location batch data.
 265  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 266  * @param[in] latitude The updated latitude [-90.0 ~ 90.0] (degrees)
 267  * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
 268  * @param[in] altitude The updated altitude (meters)
 269  * @param[in] speed The updated speed (km/h)
 270  * @param[in] direction The updated direction (in degrees from the north)
 271  * @param[in] horizontal The horizontal accuracy (meters)
 272  * @param[in] vertical The vertical accuracy (meters)
 273  * @param[in] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 274  * @param[in] user_data The user data passed from the callback registration function
 275  * @return @c true to continue with the next iteration of the loop,
 276  *         otherwise @c false to break out of the loop
 277  * @pre location_manager_foreach_location_batch() will invoke this callback.
 278  * @see location_manager_foreach_location_batch()
 279  */
 280 typedef bool(*location_batch_get_location_cb)(double latitude, double longitude, double altitude, double speed, double direction, double horizontal, double vertical, time_t timestamp, void *user_data);
 281
 282
 283 /**
 284  * @brief Checks whether the given location method is available.
 285  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 286  * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
 287  * @param[in] method The location method to be checked
 288  * @return @c true if the specified location method is supported,
 289  *         otherwise @c false if it is not available
 290  * @retval #LOCATIONS_ERROR_NONE Successful
 291  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 292  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 293  * @see location_manager_create()
 294  * @see location_manager_get_method()
 295  */
 296 bool location_manager_is_supported_method(location_method_e method);
 297
 298
 299 /**
 300  * @brief Checks whether the given location method is enabled or not on setting.
 301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 302  * @param[in] method The location method to be checked
 303  * @param[out] enable The result value of checking the given location method
 304  * @return @c 0 on success,
 305  *         otherwise a negative error value
 306  * @retval #LOCATIONS_ERROR_NONE Successful
 307  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 308  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 309  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 310  * @see location_manager_create()
 311  * @see location_manager_set_setting_changed_cb()
 312  * @see location_manager_unset_setting_changed_cb()
 313  */
 314 int location_manager_is_enabled_method(location_method_e method, bool *enable);
 315
 316
 317 /**
 318  * @platform
 319  * @brief Enables the given location method.
 320  * @since_tizen 2.3.1
 321  * @privlevel platform
 322  * @privilege %http://tizen.org/privilege/location.enable
 323  * @param[in] method The location method to be checked
 324  * @param[in] enable The value to set
 325  * @return @c 0 on success,
 326  *         otherwise a negative error value
 327  * @retval #LOCATIONS_ERROR_NONE Successful
 328  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 329  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
 330  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 331  * @see location_manager_is_enabled_method()
 332  * @see location_manager_create()
 333  */
 334 int location_manager_enable_method(const location_method_e method, const bool enable);
 335
 336
 337 /**
 338  * @brief Creates a new location manager.
 339  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 340  * @remarks You must release @a manager using location_manager_destroy().
 341  * @param[in] method The location method
 342  * @param[out] manager The location manager handle that is newly created
 343  * @return @c 0 on success,
 344  *         otherwise a negative error value
 345  * @retval #LOCATIONS_ERROR_NONE Successful
 346  * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
 347  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 348  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 349  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 350  * @see location_manager_destroy()
 351  */
 352 int location_manager_create(location_method_e method, location_manager_h *manager);
 353
 354
 355 /**
 356  * @brief Releases the location manager.
 357  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 358  * @param[in] manager The location manager handle
 359  * @return @c 0 on success,
 360  *         otherwise a negative error value
 361  * @retval #LOCATIONS_ERROR_NONE Successful
 362  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 363  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 364  * @see location_manager_create()
 365 */
 366 int location_manager_destroy(location_manager_h manager);
 367
 368
 369 /**
 370  * @brief Requests to update current location once.
 371  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 372  * @privlevel public
 373  * @privilege %http://tizen.org/privilege/location
 374  * @remarks Do not request to start the location service using the same manager handler.
 375  *          Calling this function invokes a location service event. When the location service is updated, location_updated_cb.
 376  * @param[in] manager The location manager handle
 377  * @param[in] timeout Timeout to stop requesting single location after
 378  * @param[in] callback The location callback function to register
 379  * @param[in] user_data The user data to be passed to the callback function
 380  * @retval #LOCATIONS_ERROR_NONE Successful
 381  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 382  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 383  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 384  * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
 385  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 386  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 387  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 388  * @post It invokes location_updated_cb().
 389  */
 390 int location_manager_request_single_location(location_manager_h manager, int timeout, location_updated_cb callback, void *user_data);
 391
 392
 393 /**
 394  * @brief Starts the location service.
 395  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 396  * @privlevel public
 397  * @privilege %http://tizen.org/privilege/location
 398  * @remarks There is no limit on number of location managers for which this function was called.
 399  * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
 400  *          (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as
 401  *          the first argument, and the service starts.
 402  * @remarks The started service is a requirement for calling these functions:
 403  *          location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(),
 404  *          gps_status_get_nmea(), gps_status_get_satellite(), gps_status_foreach_satellites_in_view().
 405  * @remarks Once you stop the service using location_manager_stop(), you can no longer call the functions listed above.
 406  * @remarks Starting and stopping the service is in the scope of the given location manager only (if there is more than one manager,
 407  *          starting and stopping should be executed for each of them separately).
 408  * @param[in] manager The location manager handle
 409  * @return @c 0 on success,
 410  *         otherwise a negative error value
 411  * @retval #LOCATIONS_ERROR_NONE Successful
 412  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 413  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 414  * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
 415  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 416  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 417  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 418  * @post It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().
 419  * @see location_manager_stop()
 420  * @see location_manager_get_position()
 421  * @see location_manager_get_velocity()
 422  * @see location_manager_get_accuracy()
 423  * @see location_manager_set_service_state_changed_cb()
 424  * @see location_manager_set_position_updated_cb()
 425  * @see location_position_updated_cb()
 426  * @see location_manager_set_velocity_updated_cb()
 427  * @see location_velocity_updated_cb()
 428  * @see location_manager_set_zone_changed_cb()
 429  * @see location_zone_changed_cb()
 430  */
 431 int location_manager_start(location_manager_h manager);
 432
 433
 434 /**
 435  * @brief Stops the location service.
 436  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 437  * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
 438  *          #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
 439  *          When that happens, the service is stopped and the user is notified.
 440  * @remarks You can stop and start the location manager as needed.
 441  * @param[in] manager The location manager handle
 442  * @return @c 0 on success,
 443  *         otherwise a negative error value
 444  * @retval #LOCATIONS_ERROR_NONE Successful
 445  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 446  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 447  * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
 448  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 449  * @see location_manager_start()
 450  * @see location_manager_set_service_state_changed_cb()
 451  * @see location_service_state_changed_cb()
 452  */
 453 int location_manager_stop(location_manager_h manager);
 454
 455
 456 /**
 457  * @brief Adds bounds for a given location manager.
 458  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 459  * @param[in] manager The location manager handle
 460  * @param[in] bounds The location bounds handle
 461  * @return @c 0 on success,
 462  *         otherwise a negative error value
 463  * @retval #LOCATIONS_ERROR_NONE Successful
 464  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 465  * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
 466  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 467  * @post It invokes location_manager_set_zone_changed_cb() when a boundary is entered or exited, if you set a callback with location_manager_set_zone_changed_cb().
 468  * @see location_manager_remove_boundary()
 469  * @see location_manager_set_zone_changed_cb()
 470  */
 471 int location_manager_add_boundary(location_manager_h manager, const location_bounds_h bounds);
 472
 473
 474 /**
 475  * @brief Deletes bounds for a given location manager.
 476  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 477  * @param[in] manager The location manager handle
 478  * @param[in] bounds The location bounds handle
 479  * @return @c 0 on success,
 480  *         otherwise a negative error value
 481  * @retval #LOCATIONS_ERROR_NONE Successful
 482  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 483  * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
 484  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 485  * @see location_manager_add_boundary()
 486  */
 487 int location_manager_remove_boundary(location_manager_h manager, const location_bounds_h bounds);
 488
 489
 490 /**
 491  * @brief Retrieves all location bounds by invoking a specific callback for each location bounds
 492  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 493  * @param[in] manager The location manager handle
 494  * @param[in] callback The iteration callback
 495  * @param[in] user_data The user data to be passed to the callback function
 496  * @return @c 0 on success,
 497  *         otherwise a negative error value
 498  * @retval #LOCATIONS_ERROR_NONE Successful
 499  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 500  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 501  * @post location_bounds_cb() will be invoked.
 502  * @see location_manager_add_boundary()
 503  * @see location_manager_remove_boundary()
 504  * @see location_bounds_cb()
 505  */
 506 int location_manager_foreach_boundary(location_manager_h manager, location_bounds_cb callback, void *user_data);
 507
 508
 509 /**
 510  * @brief Gets the given location manager's method.
 511  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 512  * @param[in] manager The location manager handle
 513  * @param[out] method The location method
 514  * @return @c 0 on success,
 515  *         otherwise a negative error value
 516  * @retval #LOCATIONS_ERROR_NONE Successful
 517  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 518  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 519  * @see location_manager_create()
 520  */
 521 int location_manager_get_method(location_manager_h manager, location_method_e *method);
 522
 523
 524 /**
 525  * @brief Gets the current position information.
 526  * @details The result contains the current altitude, latitude, and longitude with a measurement timestamp.
 527  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 528  * @privlevel public
 529  * @privilege %http://tizen.org/privilege/location
 530  * @param[in] manager The location manager handle
 531  * @param[out] altitude The current altitude (meters)
 532  * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
 533  * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
 534  * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 535  * @return @c 0 on success,
 536  *         otherwise a negative error value
 537  * @retval #LOCATIONS_ERROR_NONE Successful
 538  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 539  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 540  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 541  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 542  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 543  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
 544  */
 545 int location_manager_get_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
 546
 547
 548 /**
 549  * @brief Gets the current position information.
 550  * @details The result contains the current altitude, latitude, longitude, climb, direction, speed, level, horizontal, and vertical with a measurement timestamp.
 551  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 552  * @privlevel public
 553  * @privilege %http://tizen.org/privilege/location
 554  * @param[in] manager The location manager handle
 555  * @param[out] altitude The current altitude (meters)
 556  * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
 557  * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
 558  * @param[out] climb The climb (km/h)
 559  * @param[out] direction The direction, degrees from the north
 560  * @param[out] speed The speed (km/h)
 561  * @param[out] level The accuracy level
 562  * @param[out] horizontal The horizontal accuracy (meters)
 563  * @param[out] vertical The vertical accuracy (meters)
 564  * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 565  * @return @c 0 on success,
 566  *         otherwise a negative error value
 567  * @retval #LOCATIONS_ERROR_NONE Successful
 568  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 569  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 570  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 571  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 572  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 573  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
 574  */
 575 int location_manager_get_location(location_manager_h manager, double *altitude, double *latitude, double *longitude, double *climb, double *direction, double *speed, location_accuracy_level_e *level, double *horizontal, double *vertical, time_t *timestamp);
 576
 577
 578 /**
 579  * @brief Gets the current velocity information.
 580  * @details The result contains the current climb, direction, and speed with a measurement timestamp.
 581  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 582  * @privlevel public
 583  * @privilege %http://tizen.org/privilege/location
 584  * @param[in] manager The location manager handle
 585  * @param[out] climb The climb (km/h)
 586  * @param[out] direction The direction, degrees from the north
 587  * @param[out] speed The speed (km/h)
 588  * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 589  * @return @c 0 on success,
 590  *         otherwise a negative error value
 591  * @retval #LOCATIONS_ERROR_NONE Successful
 592  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 593  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 594  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 595  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 596  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 597  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
 598  */
 599 int location_manager_get_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
 600
 601
 602 /**
 603  * @brief Gets the current accuracy information.
 604  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 605  * @privlevel public
 606  * @privilege %http://tizen.org/privilege/location
 607  * @param[in] manager The location manager handle
 608  * @param[out] level The accuracy level
 609  * @param[out] horizontal The horizontal accuracy (meters)
 610  * @param[out] vertical The vertical accuracy (meters)
 611  * @return @c 0 on success,
 612  *         otherwise a negative error value
 613  * @retval #LOCATIONS_ERROR_NONE Successful
 614  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 615  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 616  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 617  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 618  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 619  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
 620  */
 621 int location_manager_get_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
 622
 623
 624 /**
 625  * @brief Gets the last position information which is recorded.
 626  * @details The @a altitude, @a latitude, @a longitude, and @c timestamp values should be 0, if there is no record of any previous position information.
 627  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 628  * @privlevel public
 629  * @privilege %http://tizen.org/privilege/location
 630  * @param[in] manager The location manager handle
 631  * @param[out] altitude The last altitude (meters)
 632  * @param[out] latitude The last latitude [-90.0 ~ 90.0] (degrees)
 633  * @param[out] longitude The last longitude [-180.0 ~ 180.0] (degrees)
 634  * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 635  * @return @c 0 on success,
 636  *         otherwise a negative error value
 637  * @retval #LOCATIONS_ERROR_NONE Successful
 638  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 639  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 640  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 641  * @pre The location manager handle must be created by location_manager_create().
 642  */
 643 int location_manager_get_last_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
 644
 645
 646 /**
 647  * @brief Gets the last location information.
 648  * @details The @a altitude, @a latitude, @a longitude, @a climb, @a direction, @a speed, and @c timestamp values should be 0, if there is no record of any previous position information.
 649  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 650  * @privlevel public
 651  * @privilege %http://tizen.org/privilege/location
 652  * @param[in] manager The location manager handle
 653  * @param[out] altitude The current altitude (meters)
 654  * @param[out] latitude The current latitude [-90.0 ~ 90.0] (degrees)
 655  * @param[out] longitude The current longitude [-180.0 ~ 180.0] (degrees)
 656  * @param[out] climb The climb (km/h)
 657  * @param[out] direction The direction, degrees from the north
 658  * @param[out] speed The speed (km/h)
 659  * @param[out] level The accuracy level
 660  * @param[out] horizontal The horizontal accuracy (meters)
 661  * @param[out] vertical The vertical accuracy (meters)
 662  * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 663  * @return @c 0 on success,
 664  *         otherwise a negative error value
 665  * @retval #LOCATIONS_ERROR_NONE Successful
 666  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 667  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 668  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 669  * @pre The location manager handle must be created by location_manager_create().
 670  */
 671 int location_manager_get_last_location(location_manager_h manager, double *altitude, double *latitude, double *longitude, double *climb, double *direction, double *speed, location_accuracy_level_e *level, double *horizontal, double *vertical, time_t *timestamp);
 672
 673
 674 /**
 675  * @brief Gets the last velocity information which is recorded.
 676  * @details The @a climb, @a direction, and @a speed values should be @c 0, if there is no record of any previous velocity information.
 677  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 678  * @privlevel public
 679  * @privilege %http://tizen.org/privilege/location
 680  * @param[in] manager The location manager handle
 681  * @param[out] climb The last climb (km/h)
 682  * @param[out] direction The last direction, degrees from the north
 683  * @param[out] speed The last speed (km/h)
 684  * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
 685  * @return @c 0 on success,
 686  *         otherwise a negative error value
 687  * @retval #LOCATIONS_ERROR_NONE Successful
 688  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 689  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 690  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 691  * @pre The location manager handle must be created by location_manager_create().
 692  */
 693 int location_manager_get_last_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
 694
 695
 696 /**
 697  * @brief Gets the last accuracy information which is recorded.
 698  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 699  * @privlevel public
 700  * @privilege %http://tizen.org/privilege/location
 701  * @param[in] manager The location manager handle
 702  * @param[out] level The last accuracy level
 703  * @param[out] horizontal The last horizontal accuracy (meters)
 704  * @param[out] vertical The last vertical accuracy (meters)
 705  * @return @c 0 on success,
 706  *         otherwise a negative error value
 707  * @retval #LOCATIONS_ERROR_NONE Successful
 708  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 709  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
 710  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 711  * @pre The location manager handle must be created by location_manager_create().
 712  */
 713 int location_manager_get_last_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
 714
 715
 716 /**
 717  * @deprecated Deprecated since 3.0
 718  * @brief Gets the current application's location accessibility status.
 719  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 720  * @param[out] state The current location service accessibility status
 721  * @return @c 0 on success,
 722  *         otherwise a negative error value
 723  * @retval #LOCATIONS_ERROR_NONE Successful
 724  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 725  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 726  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 727  */
 728 int location_manager_get_accessibility_state(location_accessibility_state_e *state) TIZEN_DEPRECATED_API;
 729
 730
 731 /**
 732  * @brief Registers a callback function to be invoked at defined interval with updated position information.
 733  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 734  * @param[in] manager The location manager handle
 735  * @param[in] callback The callback function to register
 736  * @param[in] interval The interval [1 ~ 120] (seconds)
 737  * @param[in] user_data The user data to be passed to the callback function
 738  * @return @c 0 on success,
 739  *         otherwise a negative error value
 740  * @retval #LOCATIONS_ERROR_NONE Successful
 741  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 742  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 743  * @post location_position_updated_cb() will be invoked.
 744  * @see location_manager_unset_position_updated_cb()
 745  * @see location_position_updated_cb()
 746  */
 747 int location_manager_set_position_updated_cb(location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data);
 748
 749
 750 /**
 751  * @brief Unregisters the callback function.
 752  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 753  * @param[in] manager The location manager handle
 754  * @return @c 0 on success,
 755  *         otherwise a negative error value
 756  * @retval #LOCATIONS_ERROR_NONE Successful
 757  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 758  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 759  * @see location_manager_set_position_updated_cb()
 760  */
 761 int location_manager_unset_position_updated_cb(location_manager_h manager);
 762
 763
 764 /**
 765  * @brief Registers a callback function to be invoked at defined interval with updated velocity information.
 766  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 767  * @param[in] manager The location manager handle
 768  * @param[in] callback The callback function to register
 769  * @param[in] interval The interval [1 ~ 120] (seconds)
 770  * @param[in] user_data The user data to be passed to the callback function
 771  * @return @c 0 on success,
 772  *         otherwise a negative error value
 773  * @retval #LOCATIONS_ERROR_NONE Successful
 774  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 775  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 776  * @post location_velocity_updated_cb() will be invoked.
 777  * @see location_manager_unset_velocity_updated_cb()
 778  * @see location_velocity_updated_cb()
 779  */
 780 int location_manager_set_velocity_updated_cb(location_manager_h manager, location_velocity_updated_cb callback, int interval, void *user_data);
 781
 782
 783 /**
 784  * @brief Unregisters the callback function.
 785  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 786  * @param[in] manager The location manager handle
 787  * @return @c 0 on success,
 788  *         otherwise a negative error value
 789  * @retval #LOCATIONS_ERROR_NONE Successful
 790  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 791  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 792  * @see location_manager_set_velocity_updated_cb()
 793  */
 794 int location_manager_unset_velocity_updated_cb(location_manager_h manager);
 795
 796
 797 /**
 798  * @brief Registers a callback function to be invoked when the location service state is changed.
 799  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 800  * @param[in] manager The location manager handle
 801  * @param[in] callback The callback function to register
 802  * @param[in] user_data The user data to be passed to the callback function
 803  * @return @c 0 on success,
 804  *         otherwise a negative error value
 805  * @retval #LOCATIONS_ERROR_NONE Successful
 806  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 807  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 808  * @post location_service_state_changed_cb() will be invoked.
 809  * @see location_manager_unset_service_state_changed_cb()
 810  * @see location_service_state_changed_cb()
 811  * @see location_manager_start()
 812  * @see location_manager_stop()
 813  * @see #location_service_state_e
 814 */
 815 int location_manager_set_service_state_changed_cb(location_manager_h manager, location_service_state_changed_cb callback, void *user_data);
 816
 817
 818 /**
 819  * @brief Unregisters the callback function.
 820  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 821  * @param[in] manager The location manager handle
 822  * @return @c 0 on success,
 823  *         otherwise a negative error value
 824  * @retval #LOCATIONS_ERROR_NONE Successful
 825  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 826  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 827  * @see location_manager_set_service_state_changed_cb()
 828  */
 829 int location_manager_unset_service_state_changed_cb(location_manager_h manager);
 830
 831
 832 /**
 833  * @brief Registers a callback function to be invoked when the previously set boundary area is entered or left.
 834  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 835  * @param[in] manager The location manager handle
 836  * @param[in] callback The callback function to register
 837  * @param[in] user_data The user data to be passed to the callback function
 838  * @return @c 0 on success,
 839  *         otherwise a negative error value
 840  * @retval #LOCATIONS_ERROR_NONE Successful
 841  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 842  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 843  * @pre location_manager_add_boundary() is called before.
 844  * @post location_zone_changed_cb() will be invoked.
 845  * @see location_manager_unset_zone_changed_cb()
 846  * @see location_zone_changed_cb()
 847  */
 848 int location_manager_set_zone_changed_cb(location_manager_h manager, location_zone_changed_cb callback, void *user_data);
 849
 850
 851 /**
 852  * @brief Unregisters the callback function.
 853  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 854  * @param[in] manager The location manager handle
 855  * @return @c 0 on success,
 856  *         otherwise a negative error value
 857  * @retval #LOCATIONS_ERROR_NONE Successful
 858  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 859  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 860  * @see location_manager_set_zone_changed_cb()
 861  */
 862 int location_manager_unset_zone_changed_cb(location_manager_h manager);
 863
 864
 865 /**
 866  * @brief Registers a callback function to be invoked when the location setting is changed.
 867  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 868  * @param[in] method The method to observe
 869  * @param[in] callback The callback function to register
 870  * @param[in] user_data The user data to be passed to the callback function
 871  * @return @c 0 on success,
 872  *         otherwise a negative error value
 873  * @retval #LOCATIONS_ERROR_NONE Successful
 874  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 875  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 876  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 877  * @post location_setting_changed_cb() will be invoked.
 878  * @see location_manager_unset_setting_changed_cb()
 879  * @see location_setting_changed_cb()
 880  */
 881 int location_manager_set_setting_changed_cb(location_method_e method, location_setting_changed_cb callback, void *user_data);
 882
 883
 884 /**
 885  * @brief Unregisters the callback function.
 886  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 887  * @param[in] method The method to observe
 888  * @return @c 0 on success,
 889  *         otherwise a negative error value
 890  * @retval #LOCATIONS_ERROR_NONE Successful
 891  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 892  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 893  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 894  * @see location_manager_set_setting_changed_cb()
 895  */
 896 int location_manager_unset_setting_changed_cb(location_method_e method);
 897
 898
 899 /**
 900  * @brief Gets the distance in meters between two locations.
 901  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 902  * @param[in] start_latitude The starting latitude [-90.0 ~ 90.0] (degrees)
 903  * @param[in] start_longitude The starting longitude [-180.0 ~ 180.0] (degrees)
 904  * @param[in] end_latitude The ending latitude [-90.0 ~ 90.0] (degrees)
 905  * @param[in] end_longitude The ending longitude [-180.0 ~ 180.0] (degrees)
 906  * @param[out] distance The distance between two locations (meters)
 907  * @return @c 0 on success,
 908  *         otherwise a negative error value
 909  * @retval #LOCATIONS_ERROR_NONE Successful
 910  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 911  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 912  */
 913 int location_manager_get_distance(double start_latitude, double start_longitude, double end_latitude, double end_longitude, double *distance);
 914
 915
 916 /**
 917  * @brief Registers a callback function to be invoked at minimum interval or minimum distance with updated position information.
 918  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 919  * @param[in] manager The location manager handle
 920  * @param[in] callback The callback function to register
 921  * @param[in] interval The minimum interval between position updates [1 ~ 120] (seconds)
 922  * @param[in] distance The minimum distance between position updates [1 ~ 120] (meters)
 923  * @param[in] user_data The user data to be passed to the callback function
 924  * @return @c 0 on success,
 925  *         otherwise a negative error value
 926  * @retval #LOCATIONS_ERROR_NONE Successful
 927  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 928  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 929  * @post location_changed_cb() will be invoked.
 930  * @see location_manager_unset_distance_based_location_changed_cb()
 931  * @see location_changed_cb()
 932  */
 933 int location_manager_set_distance_based_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, double distance, void *user_data);
 934
 935
 936 /**
 937  * @brief Unregisters the callback function.
 938  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 939  * @param[in] manager The location manager handle
 940  * @return @c 0 on success,
 941  *         otherwise a negative error value
 942  * @retval #LOCATIONS_ERROR_NONE Successful
 943  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 944  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 945  * @see location_manager_set_distance_based_location_changed_cb()
 946  */
 947 int location_manager_unset_distance_based_location_changed_cb(location_manager_h manager);
 948
 949
 950 /**
 951  * @brief Registers a callback function to be invoked at defined interval with updated location information.
 952  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 953  * @param[in] manager The location manager handle
 954  * @param[in] callback The callback function to register
 955  * @param[in] interval The interval [1 ~ 120] (seconds)
 956  * @param[in] user_data The user data to be passed to the callback function
 957  * @return @c 0 on success,
 958  *         otherwise a negative error value
 959  * @retval #LOCATIONS_ERROR_NONE Successful
 960  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 961  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 962  * @post location_changed_cb() will be invoked.
 963  * @see location_manager_unset_location_changed_cb()
 964  * @see location_changed_cb()
 965  */
 966 int location_manager_set_location_changed_cb(location_manager_h manager, location_changed_cb callback, int interval, void *user_data);
 967
 968
 969 /**
 970  * @brief Unregisters the callback function.
 971  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 972  * @param[in] manager The location manager handle
 973  * @return @c 0 on success,
 974  *         otherwise a negative error value
 975  * @retval #LOCATIONS_ERROR_NONE Successful
 976  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 977  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 978  * @see location_manager_set_location_changed_cb()
 979  */
 980 int location_manager_unset_location_changed_cb(location_manager_h manager);
 981
 982
 983 /**
 984  * @brief Registers a callback function to be invoked when batch_period is expired.
 985  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 986  * @remarks The batch_period should be greater than or equal to the batch_interval.
 987  *          In addition, sometimes the period may not work as you intended, the maximum permissible value for batch_period is device specific.
 988  * @param[in] manager The location manager handle
 989  * @param[in] callback The callback function to register
 990  * @param[in] batch_interval The batch sampling interval [1 ~ 255] (seconds)
 991  * @param[in] batch_period The batch period [1 ~ 60000] (seconds)
 992  * @param[in] user_data The user data to be passed to the callback function
 993  * @return @c 0 on success,
 994  *         otherwise a negative error value
 995  * @retval #LOCATIONS_ERROR_NONE Successful
 996  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 997  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
 998  * @post location_batch_cb() will be invoked.
 999  * @see location_manager_start_batch()
1000  * @see location_batch_cb()
1001  * @see location_manager_unset_location_batch_cb()
1002  */
1003 int location_manager_set_location_batch_cb(location_manager_h manager, location_batch_cb callback, int batch_interval, int batch_period, void *user_data);
1004
1005
1006 /**
1007  * @brief Unregisters the callback function.
1008  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1009  * @param[in] manager The location manager handle
1010  * @return @c 0 on success,
1011  *         otherwise a negative error value
1012  * @retval #LOCATIONS_ERROR_NONE Successful
1013  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1014  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1015  * @see location_manager_set_location_batch_cb()
1016  */
1017 int location_manager_unset_location_batch_cb(location_manager_h manager);
1018
1019
1020 /**
1021  * @brief Starts the location batch service.
1022  * @details Calling this function starts location batch service, location_batch_cb() will be invoked every @a batch_period seconds.
1023  *          After that, you can obtain all locations with location_manager_foreach_location_batch().
1024  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1025  * @privlevel public
1026  * @privilege %http://tizen.org/privilege/location
1027  * @remarks Calling this function invokes a location service event. When the location service is enabled, the service state change callback
1028  *          (set using location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as the first argument, and the service starts.
1029  * @param[in] manager The location manager handle
1030  * @return @c 0 on success,
1031  *         otherwise a negative error value
1032  * @retval #LOCATIONS_ERROR_NONE Successful
1033  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1034  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1035  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1036  * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
1037  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
1038  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1039  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1040  * @pre location_manager_set_location_batch_cb()
1041  * @see location_manager_set_service_state_changed_cb()
1042  * @see location_service_state_changed_cb()
1043  * @see location_manager_foreach_location_batch()
1044  * @see location_manager_stop_batch()
1045  */
1046 int location_manager_start_batch(location_manager_h manager);
1047
1048
1049 /**
1050  * @brief Stops the location batch service.
1051  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1052  * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
1053  *          #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as the first argument.
1054  * @param[in] manager The location manager handle
1055  * @return @c 0 on success,
1056  *         otherwise a negative error value
1057  * @retval #LOCATIONS_ERROR_NONE Successful
1058  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1059  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1060  * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
1061  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1062  * @see location_manager_start_batch()
1063  * @see location_manager_set_service_state_changed_cb()
1064  * @see location_service_state_changed_cb()
1065  */
1066 int location_manager_stop_batch(location_manager_h manager);
1067
1068
1069 /**
1070  * @brief Retrieves all location information by invoking a specific callback for each location data.
1071  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1072  * @privlevel public
1073  * @privilege %http://tizen.org/privilege/location
1074  * @param[in] manager The location manager handle
1075  * @param[in] callback The iteration callback function
1076  * @param[in] user_data The user data to be passed to the callback function
1077  * @return @c 0 on success,
1078  *         otherwise a negative error value
1079  * @retval #LOCATIONS_ERROR_NONE Successful
1080  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1081  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1082  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1083  * @pre location_manager_foreach_location_batch() is available after location_batch_cb() is invoked.
1084  * @post location_batch_get_location_cb() will be invoked.
1085  * @see location_manager_start_batch()
1086  * @see location_batch_cb()
1087  * @see location_batch_get_location_cb()
1088  */
1089 int location_manager_foreach_location_batch(location_manager_h manager, location_batch_get_location_cb callback, void *user_data);
1090
1091
1092 /**
1093  * @brief Checks whether the mock location is enabled.
1094  * @since_tizen 3.0
1095  * @param[out] enabled Indicates whether the mock location is enabled
1096  * @return @c 0 on success,
1097  *         otherwise a negative error value
1098  * @retval #LOCATIONS_ERROR_NONE Successful
1099  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1100  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1101  * @see location_manager_enable_mock_location()
1102  * @see location_manager_set_mock_location()
1103  * @see location_manager_clear_mock_location()
1104  */
1105 int location_manager_is_enabled_mock_location(bool *enabled);
1106
1107
1108 /**
1109  * @brief Enables mock location.
1110  * @details The mock location is a testing function to make location API and callback deliver a mock location
1111  *          set by location_manager_set_mock_location() instead of real positioning data even in the other applications.
1112  * @since_tizen 3.0
1113  * @privlevel public
1114  * @privilege %http://tizen.org/privilege/location
1115  * @remarks The mock location can only be enabled if developer mode is enabled.
1116  * @param[in] enable The value to set
1117  * @return @c 0 on success,
1118  *         otherwise a negative error value
1119  * @retval #LOCATIONS_ERROR_NONE Successful
1120  * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1121  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED Permission denied
1122  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1123  * @see location_manager_is_enabled_mock_location()
1124  * @see location_manager_set_mock_location()
1125  * @see location_manager_clear_mock_location()
1126  */
1127 int location_manager_enable_mock_location(const bool enable);
1128
1129
1130 /**
1131  * @brief Sets a mock location for the given location method.
1132  * @details The location sets the given altitude, latitude, longitude, climb, direction, speed, level, horizontal, and vertical accuracy.
1133  * @since_tizen 3.0
1134  * @privlevel public
1135  * @privilege %http://tizen.org/privilege/location
1136  * @param[in] manager The location manager handle
1137  * @param[in] latitude The current latitude [-90.0 ~ 90.0] (degrees)
1138  * @param[in] longitude The current longitude [-180.0 ~ 180.0] (degrees)
1139  * @param[in] altitude The current altitude (meters)
1140  * @param[in] speed The speed (km/h)
1141  * @param[in] direction The direction, degrees from the north [0.0 ~ 360.0]
1142  * @param[in] accuracy The horizontal accuracy (meters)
1143  * @return @c 0 on success,
1144  *         otherwise a negative error value
1145  * @retval #LOCATIONS_ERROR_NONE Successful
1146  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1147  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1148  * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1149  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1150  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1151  * @see location_manager_create()
1152  * @see location_manager_is_enabled_mock_location()
1153  * @see location_manager_enable_mock_location()
1154  * @see location_manager_clear_mock_location()
1155  */
1156 int location_manager_set_mock_location(location_manager_h manager, const double latitude, const double longitude, const double altitude, const double speed, const double direction, const double accuracy);
1157
1158
1159 /**
1160  * @brief Clears a mock location.
1161  * @since_tizen 3.0
1162  * @privlevel public
1163  * @privilege %http://tizen.org/privilege/location
1164  * @param[in] manager The location manager handle
1165  * @return @c 0 on success,
1166  *         otherwise a negative error value
1167  * @retval #LOCATIONS_ERROR_NONE Successful
1168  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1169  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1170  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1171  * @retval #LOCATIONS_ERROR_SETTING_OFF MOCK location is not enabled
1172  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1173  * @see location_manager_create()
1174  * @see location_manager_is_enabled_mock_location()
1175  * @see location_manager_enable_mock_location()
1176  * @see location_manager_set_mock_location()
1177  */
1178 int location_manager_clear_mock_location(location_manager_h manager);
1179
1180
1181 /**
1182  * @}
1183  */
1184
1185
1186 /*
1187  * GPS Status & Satellites
1188  */
1189
1190
1191 /**
1192  * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE
1193  * @{
1194  */
1195
1196
1197 /**
1198  * @brief Called once for each satellite in range.
1199  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1200  * @param[in] azimuth The azimuth of the satellite (degrees)
1201  * @param[in] elevation The elevation of the satellite (meters)
1202  * @param[in] prn The PRN of the satellite
1203  * @param[in] snr The SNR of the satellite [dB]
1204  * @param[in] is_active The flag signaling if satellite is in use
1205  * @param[in] user_data The user data passed from the foreach function
1206  * @return @c true to continue with the next iteration of the loop, \n
1207  *         @c false to break out of the loop
1208  * @pre gps_status_foreach_satellites_in_view() will invoke this callback.
1209  * @pre gps_status_foreach_last_satellites_in_view() will invoke this callback.
1210  * @see gps_status_foreach_satellites_in_view()
1211  */
1212 typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data);
1213
1214
1215 /**
1216  * @brief Called at defined interval with updated satellite information.
1217  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1218  * @param[out] num_of_active The last number of active satellites
1219  * @param[out] num_of_inview The last number of satellites in view
1220  * @param[out] timestamp The last timestamp (time when measurement took place or @c 0 if valid)
1221  * @param[in] user_data The user data passed from the call registration function
1222  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb().
1223  * @see location_manager_start()
1224  * @see location_manager_set_position_updated_cb()
1225  */
1226 typedef void(*gps_status_satellite_updated_cb)(int num_of_active, int num_of_inview, time_t timestamp, void *user_data);
1227
1228
1229 /**
1230  * @brief Gets the GPS NMEA data.
1231  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1232  * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1233  *          You must release @a nmea using @c free().
1234  * @param[in] manager The location manager handle
1235  * @param[out] nmea The NMEA data
1236  * @return @c 0 on success,
1237  *         otherwise a negative error value
1238  * @retval #LOCATIONS_ERROR_NONE Successful
1239  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1240  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1241  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1242  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1243  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1244  * @see location_manager_start()
1245  */
1246 int gps_status_get_nmea(location_manager_h manager, char **nmea);
1247
1248
1249 /**
1250  * @brief Gets the information of satellites.
1251  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1252  * @privlevel public
1253  * @privilege %http://tizen.org/privilege/location
1254  * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1255  * @param[in] manager The location manager handle
1256  * @param[out] num_of_active The number of active satellites
1257  * @param[out] num_of_inview The number of satellites in view
1258  * @param[out] timestamp The timestamp (time when measurement took place or @c 0 if valid)
1259  * @return @c 0 on success,
1260  *         otherwise a negative error value
1261  * @retval #LOCATIONS_ERROR_NONE Successful
1262  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1263  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1264  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1265  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1266  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1267  * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1268  * @see gps_status_foreach_satellites_in_view()
1269  */
1270 int gps_status_get_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1271
1272
1273 /**
1274  * @brief Registers a callback function to be invoked at defined interval with updated satellite information.
1275  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1276  * @privlevel public
1277  * @privilege %http://tizen.org/privilege/location
1278  * @param[in] manager The location manager handle
1279  * @param[in] callback The callback function to register
1280  * @param[in] interval The interval [1 ~ 120] (seconds)
1281  * @param[in] user_data The user data to be passed to the callback function
1282  * @return @c 0 on success,
1283  *         otherwise a negative error value
1284  * @retval #LOCATIONS_ERROR_NONE Successful
1285  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1286  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1287  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1288  * @post gps_status_satellite_updated_cb() will be invoked.
1289  * @see gps_status_unset_satellite_updated_cb()
1290  * @see gps_status_satellite_updated_cb()
1291  * @see gps_status_get_satellite()
1292  * @see gps_status_foreach_satellites_in_view()
1293  * @see gps_status_get_last_satellite()
1294  * @see gps_status_foreach_last_satellites_in_view()
1295  */
1296 int gps_status_set_satellite_updated_cb(location_manager_h manager, gps_status_satellite_updated_cb callback, int interval, void *user_data);
1297
1298
1299 /**
1300  * @brief Unregisters the callback function.
1301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1302  * @param[in] manager The location manager handle
1303  * @return @c 0 on success,
1304  *         otherwise a negative error value
1305  * @retval #LOCATIONS_ERROR_NONE Successful
1306  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
1307  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1308  * @see gps_status_set_satellite_updated_cb()
1309  */
1310 int gps_status_unset_satellite_updated_cb(location_manager_h manager);
1311
1312
1313 /**
1314  * @brief Invokes the callback function for each satellite.
1315  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1316  * @privlevel public
1317  * @privilege %http://tizen.org/privilege/location
1318  * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1319  * @param[in] manager The location manager handle
1320  * @param[in] callback The iteration callback function
1321  * @param[in] user_data The user data to be passed to the callback function
1322  * @return @c 0 on success,
1323  *         otherwise a negative error value
1324  * @retval #LOCATIONS_ERROR_NONE Successful
1325  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1326  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1327  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1328  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1329  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1330  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1331  * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1332  * @post It invokes gps_status_get_satellites_cb().
1333  * @see gps_status_get_satellite()
1334  * @see gps_status_get_satellites_cb()
1335  */
1336 int gps_status_foreach_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1337
1338
1339 /**
1340  * @brief Gets the last information of satellites.
1341  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1342  * @privlevel public
1343  * @privilege %http://tizen.org/privilege/location
1344  * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
1345  * @param[in] manager The location manager handle
1346  * @param[out] num_of_active The last number of active satellites
1347  * @param[out] num_of_inview The last number of satellites in view
1348  * @param[out] timestamp The last timestamp (time when last measurement took place or @c 0 if valid)
1349  * @return @c 0 on success,
1350  *         otherwise a negative error value
1351  * @retval #LOCATIONS_ERROR_NONE Successful
1352  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1353  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1354  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1355  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1356  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1357  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1358  * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1359  * @see gps_status_foreach_satellites_in_view()
1360  */
1361 int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
1362
1363
1364 /**
1365  * @brief Invokes the callback function for each last satellite which is recorded.
1366  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1367  * @privlevel public
1368  * @privilege %http://tizen.org/privilege/location
1369  * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
1370  * @param[in] manager The location manager handle
1371  * @param[in] callback The iteration callback function
1372  * @param[in] user_data The user data to be passed to the callback function
1373  * @return @c 0 on success,
1374  *         otherwise a negative error value
1375  * @retval #LOCATIONS_ERROR_NONE Successful
1376  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
1377  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
1378  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
1379  * @retval #LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED The application does not have the privilege to call this method
1380  * @retval #LOCATIONS_ERROR_NOT_SUPPORTED Not supported
1381  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start().
1382  * @pre The gps_status_satellite_updated_cb must be set with gps_status_set_satellite_updated_cb().
1383  * @post It invokes gps_status_get_satellites_cb().
1384  * @see gps_status_get_last_satellite()
1385  * @see gps_status_get_satellites_cb()
1386  */
1387 int gps_status_foreach_last_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
1388
1389
1390 /**
1391  * @}
1392  */
1393 #ifdef __cplusplus
1394 }
1395 #endif
1396
1397 #endif /* __TIZEN_LOCATION_LOCATIONS_H__ */