include/locations.h

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