include/locations.h

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