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