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