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