include/locations.h

   1 /*
   2  * Copyright (c) 2011-2013 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_LOCATION_LOCATIONS_H__
  18 #define __TIZEN_LOCATION_LOCATIONS_H__
  19
  20 #include <tizen_type.h>
  21 #include <tizen_error.h>
  22 #include <time.h>
  23 #include <location_bounds.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @addtogroup CAPI_LOCATION_MANAGER_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Enumerations of error code for Location manager.
  36  */
  37 typedef enum
  38 {
  39     LOCATIONS_ERROR_NONE = TIZEN_ERROR_NONE,                                        /**< Successful */
  40     LOCATIONS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,                    /**< Out of memory */
  41     LOCATIONS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,            /**< Invalid parameter */
  42     LOCATIONS_ERROR_INCORRECT_METHOD = TIZEN_ERROR_LOCATION_CLASS | 0x01,         /**< Location manager contains incorrect method for a given call */
  43     LOCATIONS_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_CLASS | 0x02,           /**< Network unavailable */
  44     LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_CLASS | 0x03,    /**< Location service is not available */
  45     LOCATIONS_ERROR_GPS_SETTING_OFF = TIZEN_ERROR_LOCATION_CLASS | 0x04,    /**< GPS/WPS setting is not enabled  */
  46     LOCATIONS_ERROR_SECURITY_RESTRICTED = TIZEN_ERROR_LOCATION_CLASS | 0x05,    /**< Restricted by security system policy */
  47     LOCATIONS_ERROR_ACCESSIBILITY_NOT_ALLOWED = TIZEN_ERROR_LOCATION_CLASS | 0x06,    /**< Location service accessibility is not allowed  */
  48 } location_error_e;
  49
  50 /**
  51  * @brief Location method type.
  52  */
  53 typedef enum
  54 {
  55     LOCATIONS_METHOD_NONE=-1,    /**< Undefined method. */
  56     LOCATIONS_METHOD_HYBRID,    /**< This method selects the best method available at the moment. */
  57     LOCATIONS_METHOD_GPS,       /**< This method uses Global Positioning System. */
  58     LOCATIONS_METHOD_WPS,       /**< This method uses Wifi Positioning System. */
  59     LOCATIONS_METHOD_CPS        /**< This method uses Cellular Positioning System. */
  60 } location_method_e;
  61
  62 /**
  63  * @brief Approximate accuracy level of given information.
  64  */
  65 typedef enum
  66 {
  67     LOCATIONS_ACCURACY_NONE=0,      /**< Invalid data. */
  68     LOCATIONS_ACCURACY_COUNTRY,     /**< Country accuracy level. */
  69     LOCATIONS_ACCURACY_REGION,      /**< Regional accuracy level. */
  70     LOCATIONS_ACCURACY_LOCALITY,    /**< Local accuracy level. */
  71     LOCATIONS_ACCURACY_POSTALCODE,  /**< Postal accuracy level. */
  72     LOCATIONS_ACCURACY_STREET,      /**< Street accuracy level. */
  73     LOCATIONS_ACCURACY_DETAILED,    /**< Detailed accuracy level. */
  74 } location_accuracy_level_e;
  75
  76 /**
  77  * @brief Enumerations of the state of the location service.
  78  */
  79 typedef enum
  80 {
  81     LOCATIONS_SERVICE_DISABLED, /**< Service is disabled */
  82     LOCATIONS_SERVICE_ENABLED  /**< Service is enabled */
  83 } location_service_state_e;
  84
  85 /**
  86  * @brief Enumerations of the location service accessibility state.
  87  */
  88 typedef enum
  89 {
  90     LOCATIONS_ACCESS_STATE_NONE,  /**< Not determined yet */
  91     LOCATIONS_ACCESS_STATE_DENIED,  /**< Access denied */
  92     LOCATIONS_ACCESS_STATE_ALLOWED,  /**< Access authorized */
  93 } location_accessibility_state_e;
  94
  95 /**
  96  * @brief The location manager handle.
  97  */
  98 typedef struct location_manager_s *location_manager_h;
  99
 100 /**
 101  * @}
 102  */
 103 /*
 104  * Location Manager
 105 */
 106 /**
 107  * @addtogroup CAPI_LOCATION_MANAGER_MODULE
 108  * @{
 109  */
 110 /**
 111  * @brief Called at defined interval with updated position information.
 112  * @param[in] latitude  The updated latitude [-90.0 ~ 90.0] (degrees)
 113  * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
 114  * @param[in] altitude  The updated altitude (meters)
 115  * @param[in] timestamp  The timestamp (time when measurement took place or 0 if invalid)
 116  * @param[in] user_data  The user data passed from the call registration function
 117  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
 118  * @see location_manager_start()
 119  * @see location_manager_set_position_updated_cb()
 120  */
 121 typedef void(*location_position_updated_cb)(double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
 122
 123 /**
 124  * @brief Called at defined interval with updated velocity information.
 125  * @param[in] speed  The updated speed (km/h)
 126  * @param[in] direction The updated direction (in degrees from the north)
 127  * @param[in] climb  The updated climb (km/h)
 128  * @param[in] timestamp  The timestamp (time when measurement took place or 0 if invalid)
 129  * @param[in] user_data  The user data passed from the callback registration function
 130  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_velocity_updated_cb()
 131  * @see location_manager_start()
 132  * @see location_manager_set_velocity_updated_cb()
 133  */
 134 typedef void(*location_velocity_updated_cb)(double speed, double direction, double climb, time_t timestamp, void *user_data);
 135
 136 /**
 137  * @brief Called when the state of location service is changed from enabled to disabled or vice versa.
 138  * @param[in] state The service state
 139  * @param[in] user_data  The user data passed from the callback registration function
 140  * @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()
 141  * @see location_manager_start()
 142  * @see location_manager_stop()
 143  * @see location_manager_set_service_state_changed_cb()
 144  * @see #location_service_state_e
 145  */
 146 typedef void(*location_service_state_changed_cb)(location_service_state_e state, void *user_data);
 147
 148 /**
 149  * @brief Called when the user defined zones are entered or exited.
 150  * @param[in] state  The boundary state
 151  * @param[in] latitude  The updated latitude [-90.0 ~ 90.0] (degrees)
 152  * @param[in] longitude The updated longitude [-180.0 ~ 180.0] (degrees)
 153  * @param[in] altitude  The updated altitude (meters)
 154  * @param[in] timestamp  The timestamp (time when measurement took place or 0 if invalid)
 155  * @param[in] user_data  The user data passed from the callback registration function
 156  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_zone_changed_cb()
 157  * @see #location_boundary_state_e
 158  * @see location_manager_start()
 159  * @see location_manager_set_zone_changed_cb()
 160  */
 161 typedef void(*location_zone_changed_cb)(location_boundary_state_e state, double latitude, double longitude, double altitude, time_t timestamp, void *user_data);
 162
 163 /**
 164  * @brief Gets called iteratively to notify you of location bounds.
 165  * @param[in] bounds  The location bounds handle
 166  * @param[in] user_data  The user data passed from the callback registration function
 167  * @pre location_manager_foreach_boundary() will invoke this callback.
 168  * @see location_manager_foreach_boundary()
 169  */
 170 typedef bool(*location_bounds_cb)(location_bounds_h bounds, void *user_data);
 171
 172 /**
 173  * @brief Checks whether the given location method is avaliable or not.
 174  * @param[in] method The location method to be checked
 175  * @return @c true if the specified location method is supported, \n else @c false
 176  * @see location_manager_create()
 177  * @see location_manager_get_method()
 178  */
 179 bool location_manager_is_supported_method(location_method_e method);
 180
 181
 182 /**
 183  * @brief Creates a new location manager.
 184  * @remarks @a manager must be released location_manager_destroy() by you.
 185  * @param[in] method The location method
 186  * @param[out] manager  A location manager handle to be newly created on success
 187  * @return 0 on success, otherwise a negative error value.
 188  * @retval #LOCATIONS_ERROR_NONE Successful
 189  * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
 190  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER   Invalid parameter
 191  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 192  * @see location_manager_destroy()
 193  */
 194 int location_manager_create(location_method_e method, location_manager_h* manager);
 195
 196 /**
 197  * @brief Releases the location manager.
 198  * @param[in] manager The location manager handle
 199  * @return 0 on success, otherwise a negative error value.
 200  * @retval #LOCATIONS_ERROR_NONE Successful
 201  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER   Invalid parameter
 202  * @see location_manager_create()
 203 */
 204 int location_manager_destroy(location_manager_h manager);
 205
 206 /**
 207  * @brief Starts the location service.
 208  *
 209  * @remarks There is no limit on number of location managers for which this function was called.
 210  *
 211  * Calling this function invokes a location service event. When the location service is enabled, the service state change callback
 212  * (set using #location_manager_set_service_state_changed_cb()) notifies the user with #LOCATIONS_SERVICE_ENABLED as
 213  * the first argument, and the service starts. \n
 214
 215  * Started service is a requirement for calling these functions:
 216  *
 217  * location_manager_get_position(), location_manager_get_velocity(), location_manager_get_accuracy(),
 218  * gps_status_get_nmea(), gps_status_get_satellite_count_in_view(), gps_status_foreach_satellites_in_view(), gps_status_get_active_satellite_count().
 219  *
 220  * Once you stop the service, using #location_manager_stop(), you can no longer call the functions listed above.
 221  *
 222  * Starting and stopping the service is in the scope of the given location manager only (if there's more than one manager,
 223  * starting and stopping should be executed for each of them separately).
 224  *
 225  * @param[in]   manager The location manager handle
 226  * @return 0 on success, otherwise a negative error value.
 227  * @retval #LOCATIONS_ERROR_NONE Successful
 228  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 230  * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
 231  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 232  * @post It invokes location_position_updated_cb(), location_velocity_updated_cb(), location_zone_changed_cb(), and location_service_state_changed_cb().
 233  * @see location_manager_stop()
 234  * @see location_manager_get_position()
 235  * @see location_manager_get_velocity()
 236  * @see location_manager_get_accuracy()
 237  * @see location_manager_set_service_state_changed_cb()
 238  * @see location_manager_set_position_updated_cb()
 239  * @see location_position_updated_cb()
 240  * @see location_manager_set_velocity_updated_cb()
 241  * @see location_velocity_updated_cb()
 242  * @see location_manager_set_zone_changed_cb()
 243  * @see location_zone_changed_cb()
 244  */
 245 int location_manager_start(location_manager_h manager);
 246
 247 /**
 248  * @brief Stops the location service.
 249  * @remarks This function initiates the process of stopping the service. When the process is finished, callback set using
 250  * #location_manager_set_service_state_changed_cb() will be called, with #LOCATIONS_SERVICE_DISABLED as first argument.
 251  * When that happens, the service is stopped and the user is notified.
 252  *
 253  * You can stop and start the location manager as needed.
 254  *
 255  * @param[in]   manager The location manager handle
 256  * @return 0 on success, otherwise a negative error value.
 257  * @retval #LOCATIONS_ERROR_NONE Successful
 258  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 259  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 260  * @retval #LOCATIONS_ERROR_NETWORK_FAILED Network failed
 261  * @see location_manager_start()
 262  * @see location_manager_set_service_state_changed_cb()
 263  * @see location_service_state_changed_cb()
 264  */
 265 int location_manager_stop(location_manager_h manager);
 266
 267 /**
 268  * @brief Adds a bounds for a given location manager.
 269  * @param[in] manager The location manager handle
 270  * @param[in] bounds The location bounds handle
 271  * @return 0 on success, otherwise a negative error value.
 272  * @retval #LOCATIONS_ERROR_NONE Successful
 273  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 274  * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
 275  * @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().
 276  * @see location_manager_remove_boundary()
 277  * @see location_manager_set_zone_changed_cb()
 278  * @see location_manager_is_boundary_contains_coordinate()
 279  */
 280 int location_manager_add_boundary(location_manager_h manager, const location_bounds_h bounds);
 281
 282 /**
 283  * @brief Deletes a bounds for a given location manager.
 284  * @param[in] manager The location manager handle
 285  * @param[in] bounds The location bounds handle
 286  * @return 0 on success, otherwise a negative error value.
 287  * @retval #LOCATIONS_ERROR_NONE Successful
 288  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 289  * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
 290  * @see location_manager_add_boundary()
 291  */
 292 int location_manager_remove_boundary(location_manager_h manager, const location_bounds_h bounds);
 293
 294 /**
 295  * @brief  Retrieves all location bounds by invoking a specific callback for each locatoin bounds
 296  * @param[in] manager  The location manager handle
 297  * @param[in] callback The iteration callback
 298  * @param[in] user_data The user data to be passed to the callback function
 299  * @return      0 on success, otherwise a negative error value.
 300  * @retval #LOCATIONS_ERROR_NONE Successful
 301  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid parameter
 302  * @post  location_bounds_cb() will be invoked
 303  * @see location_manager_add_boundary()
 304  * @see location_manager_remove_boundary()
 305  * @see location_bounds_cb()
 306  */
 307 int location_manager_foreach_boundary(location_manager_h manager,  location_bounds_cb callback, void *user_data);
 308
 309 /**
 310  * @brief Gets the given location manager's method.
 311  *
 312  * @param[in]   manager The location manager handle
 313  * @param[out]  method  The location method
 314  * @return 0 on success, otherwise a negative error value.
 315  * @retval  #LOCATIONS_ERROR_NONE                Successful
 316  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER   Invalid parameter
 317  * @see location_manager_create()
 318  */
 319 int location_manager_get_method(location_manager_h manager, location_method_e *method);
 320
 321 /**
 322  * @brief Gets the current position information.
 323  * @details
 324  * The result is current altitude, latitude, and longitude, with a measurement timestamp.
 325  *
 326  * If @a altitude is negative, only altitude and latitude are available (fix status is 2D).
 327  * If @a altitude is positive, fix status is 3D and returned altitude value is the result of measurement.
 328  *
 329  * @param[in]   manager     The location manager handle
 330  * @param[out]  altitude    The current altitude (meters)
 331  * @param[out]  latitude    The current latitude [-90.0 ~ 90.0] (degrees)
 332  * @param[out]  longitude   The current longitude [-180.0 ~ 180.0] (degrees)
 333  * @param[out]  timestamp   The timestamp (time when measurement took place or 0 if valid)
 334  * @return 0 on success, otherwise a negative error value.
 335  * @retval #LOCATIONS_ERROR_NONE Successful
 336  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 337  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 338  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 339  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 340  */
 341 int location_manager_get_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
 342
 343 /**
 344  * @brief Gets the current position information.
 345  * @details
 346  * The result is current altitude, latitude, longitude, climb, direction, speed, level, horizontal and verticalwith a measurement timestamp.
 347  *
 348  * If @a altitude is negative, only altitude and latitude are available (fix status is 2D).
 349  * If @a altitude is positive, fix status is 3D and returned altitude value is the result of measurement.
 350  *
 351  * @param[in]   manager     The location manager handle
 352  * @param[out]  altitude    The current altitude (meters)
 353  * @param[out]  latitude    The current latitude [-90.0 ~ 90.0] (degrees)
 354  * @param[out]  longitude   The current longitude [-180.0 ~ 180.0] (degrees)
 355  * @param[out]  climb       The climb (km/h)
 356  * @param[out]  direction   The direction, degrees from the north
 357  * @param[out]  speed       The speed (km/h)
 358  * @param[out]  level The accuracy level
 359  * @param[out]  horizontal The horizontal accuracy (meters)
 360  * @param[out]  vertical The vertical accuracy (meters)
 361  * @param[out]  timestamp   The timestamp (time when measurement took place or 0 if valid)
 362  * @return 0 on success, otherwise a negative error value.
 363  * @retval #LOCATIONS_ERROR_NONE Successful
 364  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 365  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 366  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 367  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 368  */
 369 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);
 370
 371 /**
 372  * @brief Gets the current velocity information.
 373  * @details
 374  * The result is current climb, direction, and speed, with a measurement timestamp.
 375  *
 376  * @param[in]   manager     The location manager handle
 377  * @param[out]  climb       The climb (km/h)
 378  * @param[out]  direction   The direction, degrees from the north
 379  * @param[out]  speed       The speed (km/h)
 380  * @param[out]  timestamp   The timestamp (time when measurement took place or 0 if invalid)
 381  * @return 0 on success, otherwise a negative error value.
 382  * @retval #LOCATIONS_ERROR_NONE Successful
 383  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 384  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 385  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 386  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 387  */
 388 int location_manager_get_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
 389
 390 /**
 391  * @brief Gets the current accuracy information.
 392  * @param[in]   manager The location manager handle
 393  * @param[out]  level The accuracy level
 394  * @param[out]  horizontal The horizontal accuracy (meters)
 395  * @param[out]  vertical The vertical accuracy (meters)
 396  * @return 0 on success, otherwise a negative error value.
 397  * @retval #LOCATIONS_ERROR_NONE Successful
 398  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 399  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 400  * @retval #LOCATIONS_ERROR_GPS_SETTING_OFF GPS is not enabled
 401  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 402  */
 403 int location_manager_get_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
 404
 405 /**
 406  * @brief Gets the last position information which is recorded.
 407  * @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.
 408  * @details If @a altitude is negative, only altitude and latitude are available (fix status is 2D).
 409  * @details If @a altitude is positive, fix status is 3D and returned altitude value is the result of measurement.
 410  * @param[in]   manager     The location manager handle
 411  * @param[out]  altitude    The last altitude (meters)
 412  * @param[out]  latitude    The last latitude [-90.0 ~ 90.0] (degrees)
 413  * @param[out]  longitude   The last longitude [-180.0 ~ 180.0] (degrees)
 414  * @param[out]  timestamp   The timestamp (time when measurement took place or 0 if invalid)
 415  * @return 0 on success, otherwise a negative error value.
 416  * @retval #LOCATIONS_ERROR_NONE Successful
 417  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 418  * @pre The location manager handle must be created by location_manager_create()
 419  */
 420 int location_manager_get_last_position(location_manager_h manager, double *altitude, double *latitude, double *longitude, time_t *timestamp);
 421
 422 /**
 423  * @brief Gets the last location information.
 424  * @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.
 425  * @details If @a altitude is negative, only altitude and latitude are available (fix status is 2D).
 426  * @details If @a altitude is positive, fix status is 3D and returned altitude value is the result of measurement.
 427  * @param[in]   manager     The location manager handle
 428  * @param[out]  altitude    The current altitude (meters)
 429  * @param[out]  latitude    The current latitude [-90.0 ~ 90.0] (degrees)
 430  * @param[out]  longitude   The current longitude [-180.0 ~ 180.0] (degrees)
 431  * @param[out]  climb       The climb (km/h)
 432  * @param[out]  direction   The direction, degrees from the north
 433  * @param[out]  speed       The speed (km/h)
 434  * @param[out]  level The accuracy level
 435  * @param[out]  horizontal The horizontal accuracy (meters)
 436  * @param[out]  vertical The vertical accuracy (meters)
 437  * @param[out]  timestamp   The timestamp (time when measurement took place or 0 if valid)
 438  * @return 0 on success, otherwise a negative error value.
 439  * @retval #LOCATIONS_ERROR_NONE Successful
 440  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 441  * @pre The location manager handle must be created by location_manager_create()
 442  */
 443 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);
 444
 445
 446 /**
 447  * @brief Gets the last velocity information which is recorded.
 448  * @details
 449  * The @a climb, @a direction and @a speed values should be 0, if there is no record of any previous velocity information.
 450  *
 451  * @param[in]   manager     The location manager handle
 452  * @param[out]  climb       The last climb (km/h)
 453  * @param[out]  direction   The last direction, degrees from the north
 454  * @param[out]  speed       The last speed (km/h)
 455  * @param[out]  timestamp   The timestamp (time when measurement took place or 0 if invalid)
 456  * @return 0 on success, otherwise a negative error value.
 457  * @retval #LOCATIONS_ERROR_NONE Successful
 458  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 459  * @pre The location manager handle must be created by location_manager_create()
 460  */
 461 int location_manager_get_last_velocity(location_manager_h manager, double *climb, double *direction, double *speed, time_t *timestamp);
 462
 463 /**
 464  * @brief Gets the last accuracy information which is recorded.
 465  * @param[in]   manager         The location manager handle
 466  * @param[out]  level           The last accuracy level
 467  * @param[out]  horizontal      The last horizontal accuracy (meters)
 468  * @param[out]  vertical        The last vertical accuracy (meters)
 469  * @return 0 on success, otherwise a negative error value.
 470  * @retval #LOCATIONS_ERROR_NONE Successful
 471  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 472  * @pre The location manager handle must be created by location_manager_create()
 473  */
 474 int location_manager_get_last_accuracy(location_manager_h manager, location_accuracy_level_e *level, double *horizontal, double *vertical);
 475
 476 /**
 477  * @brief Gets the current application's location accessibility status.
 478  * @param[in]   manager The location manager handle
 479  * @param[out] state The current location service accessibility status.
 480  * @return 0 on success, otherwise a negative error value.
 481  * @retval #LOCATIONS_ERROR_NONE Successful
 482  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 483  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 484  */
 485 int location_manager_get_accessibility_state(location_accessibility_state_e* state);
 486
 487 /**
 488  * @brief Registers a callback function to be invoked at defined interval with updated position information.
 489  *
 490  * @param[in]   manager     The location manager handle
 491  * @param[in]   callback    The callback function to register
 492  * @param[in]   interval   The interval [1 ~ 120] (seconds)
 493  * @param[in]   user_data   The user data to be passed to the callback function
 494  * @return 0 on success, otherwise a negative error value.
 495  * @retval  #LOCATIONS_ERROR_NONE               Successful
 496  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 497  * @post  location_position_updated_cb() will be invoked
 498  * @see location_manager_unset_position_updated_cb()
 499  * @see location_position_updated_cb()
 500  */
 501 int location_manager_set_position_updated_cb(location_manager_h manager, location_position_updated_cb callback, int interval, void *user_data);
 502
 503 /**
 504  * @brief       Unregisters the callback function.
 505  *
 506  * @param[in]   manager The location manager handle
 507  * @return  0 on success, otherwise a negative error value.
 508  * @retval  #LOCATIONS_ERROR_NONE               Successful
 509  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 510  * @see location_manager_set_position_updated_cb()
 511  */
 512 int location_manager_unset_position_updated_cb(location_manager_h manager);
 513
 514 /**
 515  * @brief Registers a callback function to be invoked at defined interval with updated velocity information.
 516  *
 517  * @param[in]   manager     The location manager handle
 518  * @param[in]   callback    The callback function to register
 519  * @param[in]   interval   The interval [1 ~ 120] (seconds)
 520  * @param[in]   user_data   The user data to be passed to the callback function
 521  * @return 0 on success, otherwise a negative error value.
 522  * @retval  #LOCATIONS_ERROR_NONE               Successful
 523  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 524  * @post  location_velocity_updated_cb() will be invoked
 525  * @see location_manager_unset_velocity_updated_cb()
 526  * @see location_velocity_updated_cb()
 527  */
 528 int location_manager_set_velocity_updated_cb(location_manager_h manager, location_velocity_updated_cb callback, int interval, void *user_data);
 529
 530 /**
 531  * @brief       Unregisters the callback function.
 532  *
 533  * @param[in]   manager The location manager handle
 534  * @return  0 on success, otherwise a negative error value.
 535  * @retval  #LOCATIONS_ERROR_NONE               Successful
 536  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 537  * @see location_manager_set_velocity_updated_cb()
 538  */
 539 int location_manager_unset_velocity_updated_cb(location_manager_h manager);
 540
 541 /**
 542  * @brief Registers a callback function to be invoked when the  location service state is changed.
 543  *
 544  * @param[in]   manager     The location manager handle
 545  * @param[in]   callback    The callback function to register
 546  * @param[in]   user_data   The user data to be passed to the callback function
 547  * @return  0 on success, otherwise a negative error value.
 548  * @retval  #LOCATIONS_ERROR_NONE               Successful
 549  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 550  * @post  location_service_state_changed_cb() will be invoked
 551  * @see location_manager_unset_service_state_changed_cb()
 552  * @see location_service_state_changed_cb()
 553  * @see location_manager_start()
 554  * @see location_manager_stop()
 555  * @see #location_service_state_e
 556 */
 557 int location_manager_set_service_state_changed_cb(location_manager_h manager, location_service_state_changed_cb callback, void *user_data);
 558
 559 /**
 560  * @brief       Unregisters the callback function.
 561  * @param[in]   manager The location manager handle
 562  * @return  0 on success, otherwise a negative error value.
 563  * @retval  #LOCATIONS_ERROR_NONE               Successful
 564  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 565  * @see location_manager_set_service_state_changed_cb()
 566  */
 567 int location_manager_unset_service_state_changed_cb(location_manager_h manager);
 568
 569 /**
 570  * @brief Registers a callback function to be invoked when the previously set boundary area is entered or left.
 571  *
 572  * @param[in]   manager     The location manager handle
 573  * @param[in]   callback    The callback function to register
 574  * @param[in]   user_data   The user data to be passed to the callback function
 575  * @return  0 on success, otherwise a negative error value.
 576  * @retval  #LOCATIONS_ERROR_NONE               Successful
 577  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 578  * @pre Either location_manager_set_boundary_rect() or location_manager_set_boundary_circle() is called before.
 579  * @post  location_zone_changed_cb() will be invoked
 580  * @see location_manager_unset_zone_changed_cb()
 581  * @see location_zone_changed_cb()
 582  */
 583 int location_manager_set_zone_changed_cb(location_manager_h manager, location_zone_changed_cb callback, void *user_data);
 584
 585 /**
 586  * @brief       Unregisters the callback function.
 587  * @param[in]   manager The location manager handle
 588  * @return 0 on success, otherwise a negative error value.
 589  * @retval  #LOCATIONS_ERROR_NONE       Successful
 590  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 591  * @see location_manager_set_zone_changed_cb()
 592  */
 593 int location_manager_unset_zone_changed_cb(location_manager_h manager);
 594
 595 /**
 596  * @brief Gets the distance in meters between two locations.
 597  * @param[in] start_latitude The starting latitude [-90.0 ~ 90.0] (degrees)
 598  * @param[in] start_longitude The starting longitude [-180.0 ~ 180.0] (degrees)
 599  * @param[in] end_latitude The ending latitude [-90.0 ~ 90.0] (degrees)
 600  * @param[in] end_longitude The ending longitude [-180.0 ~ 180.0] (degrees)
 601  * @param[out] distance   The distance between two locations (meters)
 602  * @return 0 on success, otherwise a negative error value.
 603  * @retval #LOCATIONS_ERROR_NONE Successful
 604  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 605  */
 606 int location_manager_get_distance(double start_latitude, double start_longitude, double end_latitude, double end_longitude, double *distance);
 607
 608 /**
 609  * @brief       Sends command to the server.
 610  * @param[in]   cmd The command string to be sent
 611  * @return 0 on success, otherwise a negative error value.
 612  * @retval  #LOCATIONS_ERROR_NONE       Successful
 613  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 614  */
 615 int location_manager_send_command(const char *cmd);
 616
 617 /**
 618  * @}
 619  */
 620
 621 /*
 622  * GPS Status & Satellites
 623  */
 624
 625 /**
 626  * @addtogroup CAPI_LOCATION_GPS_STATUS_MODULE
 627  * @{
 628  */
 629
 630 /**
 631  * @brief  Called once for each satellite in range.
 632  * @param[in] azimuth   The azimuth of the satellite (degrees)
 633  * @param[in] elevation The elevation of the satellite (meters)
 634  * @param[in] prn       The PRN of the satellite
 635  * @param[in] snr       The SNR of the satellite [dB]
 636  * @param[in] is_active The flag signaling if satellite is in use
 637  * @param[in] user_data  The user data passed from the foreach function
 638  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
 639  * @pre gps_status_foreach_satellites_in_view() will invoke this callback.
 640  * @pre gps_status_foreach_last_satellites_in_view() will invoke this callback.
 641  * @see gps_status_foreach_satellites_in_view()
 642  */
 643 typedef bool(*gps_status_get_satellites_cb)(unsigned int azimuth, unsigned int elevation, unsigned int prn, int snr, bool is_active, void *user_data);
 644
 645 /**
 646  * @brief Called at defined interval with updated satellite information.
 647  * @param[out]  num_of_active   The last number of active satellites
 648  * @param[out]  num_of_inview   The last number of satellites in view
 649  * @param[out]  timestamp   The last timestamp (time when last measurement took place or 0 if invalid)
 650  * @param[in] user_data  The user data passed from the call registration function
 651  * @pre location_manager_start() will invoke this callback if you register this callback using location_manager_set_position_updated_cb()
 652  * @see location_manager_start()
 653  * @see location_manager_set_position_updated_cb()
 654  */
 655 typedef void(*gps_status_satellite_updated_cb)(int num_of_active, int num_of_inview,  time_t timestamp, void *user_data);
 656
 657 /**
 658  * @brief Gets the GPS NMEA data.
 659  * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.\n
 660  * @a nmea must be released with @c free() by you.
 661  * @param[in]   manager The location manager handle
 662  * @param[out]  nmea    The NMEA data
 663  * @return 0 on success, otherwise a negative error value.
 664  * @retval #LOCATIONS_ERROR_NONE Successful
 665  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 666  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 667  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 668  * @retval #LOCATIONS_ERROR_OUT_OF_MEMORY Out of memory
 669  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 670  * @see location_manager_start()
 671  */
 672 int gps_status_get_nmea(location_manager_h manager, char **nmea);
 673
 674 /**
 675  * @brief Gets the information of satellites.
 676  * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
 677  * @param[in]   manager The location manager handle
 678  * @param[out]  num_of_active   The number of active satellites
 679  * @param[out]  num_of_inview   The number of satellites in view
 680  * @param[out]  timestamp   The timestamp (time when measurement took place or 0 if invalid)
 681  * @return 0 on success, otherwise a negative error value.
 682  * @retval #LOCATIONS_ERROR_NONE Successful
 683  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 684  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 685  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 686  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 687  * @see   gps_status_foreach_satellites_in_view()
 688  */
 689 int  gps_status_get_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
 690
 691 /**
 692  * @brief Registers a callback function to be invoked at defined interval with updated satellite information.
 693  *
 694  * @param[in]   manager     The location manager handle
 695  * @param[in]   callback    The callback function to register
 696  * @param[in]   interval   The interval [1 ~ 120] (seconds)
 697  * @param[in]   user_data   The user data to be passed to the callback function
 698  * @return 0 on success, otherwise a negative error value.
 699  * @retval  #LOCATIONS_ERROR_NONE               Successful
 700  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 701  * @post  gps_status_satellite_updated_cb() will be invoked
 702  * @see gps_status_unset_satellite_updated_cb()
 703  * @see gps_status_satellite_updated_cb()
 704  */
 705 int gps_status_set_satellite_updated_cb(location_manager_h manager, gps_status_satellite_updated_cb callback, int interval, void *user_data);
 706
 707 /**
 708  * @brief       Unregisters the callback function.
 709  *
 710  * @param[in]   manager The location manager handle
 711  * @return  0 on success, otherwise a negative error value.
 712  * @retval  #LOCATIONS_ERROR_NONE               Successful
 713  * @retval  #LOCATIONS_ERROR_INVALID_PARAMETER  Invalid parameter
 714  * @see gps_status_set_satellite_updated_cb()
 715  */
 716 int gps_status_unset_satellite_updated_cb(location_manager_h manager);
 717
 718 /**
 719  * @brief Invokes the callback function for each satellite.
 720  * @remarks This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
 721  * @param[in]   manager     The location manager handle
 722  * @param[in]   callback    The iteration callback function
 723  * @param[in]   user_data   The user data to be passed to the callback function
 724  * @return 0 on success, otherwise a negative error value.
 725  * @retval #LOCATIONS_ERROR_NONE Successful
 726  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 727  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 728  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 729  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 730  * @post  It invokes gps_status_get_satellites_cb().
 731  * @see   gps_status_get_satellite()
 732  * @see   gps_status_get_satellites_cb()
 733  */
 734 int  gps_status_foreach_satellites_in_view (location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
 735
 736 /**
 737  * @brief Gets the last information of satellites.
 738  * @remarks This call is valid only for location managers with #LOCATIONS_METHOD_GPS method.
 739  * @param[in]   manager The location manager handle
 740  * @param[out]  num_of_active   The last number of active satellites
 741  * @param[out]  num_of_inview   The last number of satellites in view
 742  * @param[out]  timestamp   The last timestamp (time when last measurement took place or 0 if invalid)
 743  * @return 0 on success, otherwise a negative error value.
 744  * @retval #LOCATIONS_ERROR_NONE Successful
 745  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 746  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 747  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 748  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 749  * @see   gps_status_foreach_satellites_in_view()
 750  */
 751 int gps_status_get_last_satellite(location_manager_h manager, int *num_of_active, int *num_of_inview, time_t *timestamp);
 752
 753 /**
 754  * @brief Invokes the callback function for each last satellite which is recorded.
 755  * @remarks  This function is valid only for location managers with the #LOCATIONS_METHOD_GPS method.
 756  * @param[in]   manager     The location manager handle
 757  * @param[in]   callback    The iteration callback function
 758  * @param[in]   user_data   The user data to be passed to the callback function
 759  * @return 0 on success, otherwise a negative error value.
 760  * @retval #LOCATIONS_ERROR_NONE Successful
 761  * @retval #LOCATIONS_ERROR_INVALID_PARAMETER Invalid argument
 762  * @retval #LOCATIONS_ERROR_INCORRECT_METHOD Incorrect method
 763  * @retval #LOCATIONS_ERROR_SERVICE_NOT_AVAILABLE Service not available
 764  * @pre The location service state must be #LOCATIONS_SERVICE_ENABLED with location_manager_start()
 765  * @post  It invokes gps_status_get_satellites_cb().
 766  * @see   gps_status_get_last_satellite()
 767  * @see   gps_status_get_satellites_cb()
 768  */
 769 int gps_status_foreach_last_satellites_in_view(location_manager_h manager, gps_status_get_satellites_cb callback, void *user_data);
 770
 771 /**
 772  * @}
 773  */
 774 #ifdef __cplusplus
 775 }
 776 #endif
 777
 778 #endif /* __TIZEN_LOCATION_LOCATIONS_H__ */