include/locations.h

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