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