1 /* Copyright (c) 2017 The Linux Foundation. All rights reserved. 2 * 3 * Redistribution and use in source and binary forms, with or without 4 * modification, are permitted provided that the following conditions are 5 * met: 6 * * Redistributions of source code must retain the above copyright 7 * notice, this list of conditions and the following disclaimer. 8 * * Redistributions in binary form must reproduce the above 9 * copyright notice, this list of conditions and the following 10 * disclaimer in the documentation and/or other materials provided 11 * with the distribution. 12 * * Neither the name of The Linux Foundation nor the names of its 13 * contributors may be used to endorse or promote products derived 14 * from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 20 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 26 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 #ifndef LOCATION_H 30 #define LOCATION_H 31 32 #include <stdint.h> 33 #include <functional> 34 35 #define GNSS_NI_REQUESTOR_MAX 256 36 #define GNSS_NI_MESSAGE_ID_MAX 2048 37 #define GNSS_SV_MAX 64 38 #define GNSS_MEASUREMENTS_MAX 64 39 40 typedef enum { 41 LOCATION_ERROR_SUCCESS = 0, 42 LOCATION_ERROR_GENERAL_FAILURE, 43 LOCATION_ERROR_CALLBACK_MISSING, 44 LOCATION_ERROR_INVALID_PARAMETER, 45 LOCATION_ERROR_ID_EXISTS, 46 LOCATION_ERROR_ID_UNKNOWN, 47 LOCATION_ERROR_ALREADY_STARTED, 48 LOCATION_ERROR_GEOFENCES_AT_MAX, 49 LOCATION_ERROR_NOT_SUPPORTED 50 } LocationError; 51 52 // Flags to indicate which values are valid in a Location 53 typedef uint16_t LocationFlagsMask; 54 typedef enum { 55 LOCATION_HAS_LAT_LONG_BIT = (1<<0), // location has valid latitude and longitude 56 LOCATION_HAS_ALTITUDE_BIT = (1<<1), // location has valid altitude 57 LOCATION_HAS_SPEED_BIT = (1<<2), // location has valid speed 58 LOCATION_HAS_BEARING_BIT = (1<<3), // location has valid bearing 59 LOCATION_HAS_ACCURACY_BIT = (1<<4), // location has valid accuracy 60 } LocationFlagsBits; 61 62 typedef uint16_t LocationTechnologyMask; 63 typedef enum { 64 LOCATION_TECHNOLOGY_GNSS_BIT = (1<<0), // location was calculated using GNSS 65 LOCATION_TECHNOLOGY_CELL_BIT = (1<<1), // location was calculated using Cell 66 LOCATION_TECHNOLOGY_WIFI_BIT = (1<<2), // location was calculated using WiFi 67 LOCATION_TECHNOLOGY_SENSORS_BIT = (1<<3), // location was calculated using Sensors 68 } LocationTechnologyBits; 69 70 typedef enum { 71 LOCATION_RELIABILITY_NOT_SET = 0, 72 LOCATION_RELIABILITY_VERY_LOW, 73 LOCATION_RELIABILITY_LOW, 74 LOCATION_RELIABILITY_MEDIUM, 75 LOCATION_RELIABILITY_HIGH, 76 } LocationReliability; 77 78 typedef uint32_t GnssLocationInfoFlagMask; 79 typedef enum { 80 GNSS_LOCATION_INFO_ALTITUDE_MEAN_SEA_LEVEL_BIT = (1<<0), // valid altitude mean sea level 81 GNSS_LOCATION_INFO_DOP_BIT = (1<<1), // valid pdop, hdop, and vdop 82 GNSS_LOCATION_INFO_MAGNETIC_DEVIATION_BIT = (1<<2), // valid magnetic deviation 83 GNSS_LOCATION_INFO_VER_ACCURACY_BIT = (1<<3), // valid vertical accuracy 84 GNSS_LOCATION_INFO_SPEED_ACCURACY_BIT = (1<<4), // valid speed accuracy 85 GNSS_LOCATION_INFO_BEARING_ACCURACY_BIT = (1<<5), // valid bearing accuracy 86 GNSS_LOCATION_INFO_HOR_RELIABILITY_BIT = (1<<6), // valid horizontal reliability 87 GNSS_LOCATION_INFO_VER_RELIABILITY_BIT = (1<<7), // valid vertical reliability 88 GNSS_LOCATION_INFO_HOR_ACCURACY_ELIP_SEMI_MAJOR_BIT = (1<<8), // valid elipsode semi major 89 GNSS_LOCATION_INFO_HOR_ACCURACY_ELIP_SEMI_MINOR_BIT = (1<<9), // valid elipsode semi minor 90 GNSS_LOCATION_INFO_HOR_ACCURACY_ELIP_AZIMUTH_BIT = (1<<10),// valid accuracy elipsode azimuth 91 } GnssLocationInfoFlagBits; 92 93 typedef enum { 94 GEOFENCE_BREACH_ENTER = 0, 95 GEOFENCE_BREACH_EXIT, 96 GEOFENCE_BREACH_DWELL_IN, 97 GEOFENCE_BREACH_DWELL_OUT, 98 GEOFENCE_BREACH_UNKNOWN, 99 } GeofenceBreachType; 100 101 typedef uint16_t GeofenceBreachTypeMask; 102 typedef enum { 103 GEOFENCE_BREACH_ENTER_BIT = (1<<0), 104 GEOFENCE_BREACH_EXIT_BIT = (1<<1), 105 GEOFENCE_BREACH_DWELL_IN_BIT = (1<<2), 106 GEOFENCE_BREACH_DWELL_OUT_BIT = (1<<3), 107 } GeofenceBreachTypeBits; 108 109 typedef enum { 110 GEOFENCE_STATUS_AVAILABILE_NO = 0, 111 GEOFENCE_STATUS_AVAILABILE_YES, 112 } GeofenceStatusAvailable; 113 114 typedef uint32_t LocationCapabilitiesMask; 115 typedef enum { 116 // supports startTracking API with minInterval param 117 LOCATION_CAPABILITIES_TIME_BASED_TRACKING_BIT = (1<<0), 118 // supports startBatching API with minInterval param 119 LOCATION_CAPABILITIES_TIME_BASED_BATCHING_BIT = (1<<1), 120 // supports startTracking API with minDistance param 121 LOCATION_CAPABILITIES_DISTANCE_BASED_TRACKING_BIT = (1<<2), 122 // supports startBatching API with minDistance param 123 LOCATION_CAPABILITIES_DISTANCE_BASED_BATCHING_BIT = (1<<3), 124 // supports addGeofences API 125 LOCATION_CAPABILITIES_GEOFENCE_BIT = (1<<4), 126 // supports GnssMeasurementsCallback 127 LOCATION_CAPABILITIES_GNSS_MEASUREMENTS_BIT = (1<<5), 128 // supports startTracking/startBatching API with LocationOptions.mode of MSB (Ms Based) 129 LOCATION_CAPABILITIES_GNSS_MSB_BIT = (1<<6), 130 // supports startTracking/startBatching API with LocationOptions.mode of MSA (MS Assisted) 131 LOCATION_CAPABILITIES_GNSS_MSA_BIT = (1<<7), 132 } LocationCapabilitiesBits; 133 134 typedef enum { 135 LOCATION_TECHNOLOGY_TYPE_GNSS = 0, 136 } LocationTechnologyType; 137 138 // Configures how GPS is locked when GPS is disabled (through GnssDisable) 139 typedef enum { 140 GNSS_CONFIG_GPS_LOCK_NONE = 0, // gps is not locked when GPS is disabled (GnssDisable) 141 GNSS_CONFIG_GPS_LOCK_MO, // gps mobile originated (MO) is locked when GPS is disabled 142 GNSS_CONFIG_GPS_LOCK_NI, // gps network initiated (NI) is locked when GPS is disabled 143 GNSS_CONFIG_GPS_LOCK_MO_AND_NI,// gps MO and NI is locked when GPS is disabled 144 } GnssConfigGpsLock; 145 146 // SUPL version 147 typedef enum { 148 GNSS_CONFIG_SUPL_VERSION_1_0_0 = 1, 149 GNSS_CONFIG_SUPL_VERSION_2_0_0, 150 GNSS_CONFIG_SUPL_VERSION_2_0_2, 151 } GnssConfigSuplVersion; 152 153 // LTE Positioning Profile 154 typedef enum { 155 GNSS_CONFIG_LPP_PROFILE_RRLP_ON_LTE = 0, // RRLP on LTE (Default) 156 GNSS_CONFIG_LPP_PROFILE_USER_PLANE, // LPP User Plane (UP) on LTE 157 GNSS_CONFIG_LPP_PROFILE_CONTROL_PLANE, // LPP_Control_Plane (CP) 158 GNSS_CONFIG_LPP_PROFILE_USER_PLANE_AND_CONTROL_PLANE, // Both LPP UP and CP 159 } GnssConfigLppProfile; 160 161 // Technology for LPPe Control Plane 162 typedef uint16_t GnssConfigLppeControlPlaneMask; 163 typedef enum { 164 GNSS_CONFIG_LPPE_CONTROL_PLANE_DBH_BIT = (1<<0), // DBH 165 GNSS_CONFIG_LPPE_CONTROL_PLANE_WLAN_AP_MEASUREMENTS_BIT = (1<<1), // WLAN_AP_MEASUREMENTS 166 } GnssConfigLppeControlPlaneBits; 167 168 // Technology for LPPe User Plane 169 typedef uint16_t GnssConfigLppeUserPlaneMask; 170 typedef enum { 171 GNSS_CONFIG_LPPE_USER_PLANE_DBH_BIT = (1<<0), // DBH 172 GNSS_CONFIG_LPPE_USER_PLANE_WLAN_AP_MEASUREMENTS_BIT = (1<<1), // WLAN_AP_MEASUREMENTS 173 } GnssConfigLppeUserPlaneBits; 174 175 // Positioning Protocol on A-GLONASS system 176 typedef uint16_t GnssConfigAGlonassPositionProtocolMask; 177 typedef enum { 178 GNSS_CONFIG_RRC_CONTROL_PLANE_BIT = (1<<0), // RRC Control Plane 179 GNSS_CONFIG_RRLP_USER_PLANE_BIT = (1<<1), // RRLP User Plane 180 GNSS_CONFIG_LLP_USER_PLANE_BIT = (1<<2), // LPP User Plane 181 GNSS_CONFIG_LLP_CONTROL_PLANE_BIT = (1<<3), // LPP Control Plane 182 } GnssConfigAGlonassPositionProtocolBits; 183 184 typedef enum { 185 GNSS_CONFIG_EMERGENCY_PDN_FOR_EMERGENCY_SUPL_NO = 0, 186 GNSS_CONFIG_EMERGENCY_PDN_FOR_EMERGENCY_SUPL_YES, 187 } GnssConfigEmergencyPdnForEmergencySupl; 188 189 typedef enum { 190 GNSS_CONFIG_SUPL_EMERGENCY_SERVICES_NO = 0, 191 GNSS_CONFIG_SUPL_EMERGENCY_SERVICES_YES, 192 } GnssConfigSuplEmergencyServices; 193 194 typedef uint16_t GnssConfigSuplModeMask; 195 typedef enum { 196 GNSS_CONFIG_SUPL_MODE_MSB = (1<<0), 197 GNSS_CONFIG_SUPL_MODE_MSA = (1<<1), 198 } GnssConfigSuplModeBits; 199 200 typedef uint32_t GnssConfigFlagsMask; 201 typedef enum { 202 GNSS_CONFIG_FLAGS_GPS_LOCK_VALID_BIT = (1<<0), 203 GNSS_CONFIG_FLAGS_SUPL_VERSION_VALID_BIT = (1<<1), 204 GNSS_CONFIG_FLAGS_SET_ASSISTANCE_DATA_VALID_BIT = (1<<2), 205 GNSS_CONFIG_FLAGS_LPP_PROFILE_VALID_BIT = (1<<3), 206 GNSS_CONFIG_FLAGS_LPPE_CONTROL_PLANE_VALID_BIT = (1<<4), 207 GNSS_CONFIG_FLAGS_LPPE_USER_PLANE_VALID_BIT = (1<<5), 208 GNSS_CONFIG_FLAGS_AGLONASS_POSITION_PROTOCOL_VALID_BIT = (1<<6), 209 GNSS_CONFIG_FLAGS_EM_PDN_FOR_EM_SUPL_VALID_BIT = (1<<7), 210 GNSS_CONFIG_FLAGS_SUPL_EM_SERVICES_BIT = (1<<8), 211 GNSS_CONFIG_FLAGS_SUPL_MODE_BIT = (1<<9), 212 } GnssConfigFlagsBits; 213 214 typedef enum { 215 GNSS_NI_ENCODING_TYPE_NONE = 0, 216 GNSS_NI_ENCODING_TYPE_GSM_DEFAULT, 217 GNSS_NI_ENCODING_TYPE_UTF8, 218 GNSS_NI_ENCODING_TYPE_UCS2, 219 } GnssNiEncodingType; 220 221 typedef enum { 222 GNSS_NI_TYPE_VOICE = 0, 223 GNSS_NI_TYPE_SUPL, 224 GNSS_NI_TYPE_CONTROL_PLANE, 225 GNSS_NI_TYPE_EMERGENCY_SUPL 226 } GnssNiType; 227 228 typedef uint16_t GnssNiOptionsMask; 229 typedef enum { 230 GNSS_NI_OPTIONS_NOTIFICATION = (1<<0), 231 GNSS_NI_OPTIONS_VERIFICATION = (1<<1), 232 GNSS_NI_OPTIONS_PRIVACY_OVERRIDE = (1<<2), 233 } GnssNiOptionsBits; 234 235 typedef enum { 236 GNSS_NI_RESPONSE_ACCEPT = 1, 237 GNSS_NI_RESPONSE_DENY, 238 GNSS_NI_RESPONSE_NO_RESPONSE, 239 GNSS_NI_RESPONSE_IGNORE, 240 } GnssNiResponse; 241 242 typedef enum { 243 GNSS_SV_TYPE_UNKNOWN = 0, 244 GNSS_SV_TYPE_GPS, 245 GNSS_SV_TYPE_SBAS, 246 GNSS_SV_TYPE_GLONASS, 247 GNSS_SV_TYPE_QZSS, 248 GNSS_SV_TYPE_BEIDOU, 249 GNSS_SV_TYPE_GALILEO, 250 } GnssSvType; 251 252 typedef uint16_t GnssSvOptionsMask; 253 typedef enum { 254 GNSS_SV_OPTIONS_HAS_EPHEMER_BIT = (1<<0), 255 GNSS_SV_OPTIONS_HAS_ALMANAC_BIT = (1<<1), 256 GNSS_SV_OPTIONS_USED_IN_FIX_BIT = (1<<2), 257 } GnssSvOptionsBits; 258 259 typedef enum { 260 GNSS_ASSISTANCE_TYPE_SUPL = 0, 261 GNSS_ASSISTANCE_TYPE_C2K, 262 } GnssAssistanceType; 263 264 typedef enum { 265 GNSS_SUPL_MODE_STANDALONE = 0, 266 GNSS_SUPL_MODE_MSB, 267 GNSS_SUPL_MODE_MSA, 268 } GnssSuplMode; 269 270 typedef uint16_t GnssMeasurementsAdrStateMask; 271 typedef enum { 272 GNSS_MEASUREMENTS_ACCUMULATED_DELTA_RANGE_STATE_UNKNOWN = 0, 273 GNSS_MEASUREMENTS_ACCUMULATED_DELTA_RANGE_STATE_VALID_BIT = (1<<0), 274 GNSS_MEASUREMENTS_ACCUMULATED_DELTA_RANGE_STATE_RESET_BIT = (1<<1), 275 GNSS_MEASUREMENTS_ACCUMULATED_DELTA_RANGE_STATE_CYCLE_SLIP_BIT = (1<<2), 276 } GnssMeasurementsAdrStateBits; 277 278 typedef uint32_t GnssMeasurementsDataFlagsMask; 279 typedef enum { 280 GNSS_MEASUREMENTS_DATA_SV_ID_BIT = (1<<0), 281 GNSS_MEASUREMENTS_DATA_SV_TYPE_BIT = (1<<1), 282 GNSS_MEASUREMENTS_DATA_STATE_BIT = (1<<2), 283 GNSS_MEASUREMENTS_DATA_RECEIVED_SV_TIME_BIT = (1<<3), 284 GNSS_MEASUREMENTS_DATA_RECEIVED_SV_TIME_UNCERTAINTY_BIT = (1<<4), 285 GNSS_MEASUREMENTS_DATA_CARRIER_TO_NOISE_BIT = (1<<5), 286 GNSS_MEASUREMENTS_DATA_PSEUDORANGE_RATE_BIT = (1<<6), 287 GNSS_MEASUREMENTS_DATA_PSEUDORANGE_RATE_UNCERTAINTY_BIT = (1<<7), 288 GNSS_MEASUREMENTS_DATA_ADR_STATE_BIT = (1<<8), 289 GNSS_MEASUREMENTS_DATA_ADR_BIT = (1<<9), 290 GNSS_MEASUREMENTS_DATA_ADR_UNCERTAINTY_BIT = (1<<10), 291 GNSS_MEASUREMENTS_DATA_CARRIER_FREQUENCY_BIT = (1<<11), 292 GNSS_MEASUREMENTS_DATA_CARRIER_CYCLES_BIT = (1<<12), 293 GNSS_MEASUREMENTS_DATA_CARRIER_PHASE_BIT = (1<<13), 294 GNSS_MEASUREMENTS_DATA_CARRIER_PHASE_UNCERTAINTY_BIT = (1<<14), 295 GNSS_MEASUREMENTS_DATA_MULTIPATH_INDICATOR_BIT = (1<<15), 296 GNSS_MEASUREMENTS_DATA_SIGNAL_TO_NOISE_RATIO_BIT = (1<<16), 297 } GnssMeasurementsDataFlagsBits; 298 299 typedef uint32_t GnssMeasurementsStateMask; 300 typedef enum { 301 GNSS_MEASUREMENTS_STATE_UNKNOWN_BIT = 0, 302 GNSS_MEASUREMENTS_STATE_CODE_LOCK_BIT = (1<<0), 303 GNSS_MEASUREMENTS_STATE_BIT_SYNC_BIT = (1<<1), 304 GNSS_MEASUREMENTS_STATE_SUBFRAME_SYNC_BIT = (1<<2), 305 GNSS_MEASUREMENTS_STATE_TOW_DECODED_BIT = (1<<3), 306 GNSS_MEASUREMENTS_STATE_MSEC_AMBIGUOUS_BIT = (1<<4), 307 GNSS_MEASUREMENTS_STATE_SYMBOL_SYNC_BIT = (1<<5), 308 GNSS_MEASUREMENTS_STATE_GLO_STRING_SYNC_BIT = (1<<6), 309 GNSS_MEASUREMENTS_STATE_GLO_TOD_DECODED_BIT = (1<<7), 310 GNSS_MEASUREMENTS_STATE_BDS_D2_BIT_SYNC_BIT = (1<<8), 311 GNSS_MEASUREMENTS_STATE_BDS_D2_SUBFRAME_SYNC_BIT = (1<<9), 312 GNSS_MEASUREMENTS_STATE_GAL_E1BC_CODE_LOCK_BIT = (1<<10), 313 GNSS_MEASUREMENTS_STATE_GAL_E1C_2ND_CODE_LOCK_BIT = (1<<11), 314 GNSS_MEASUREMENTS_STATE_GAL_E1B_PAGE_SYNC_BIT = (1<<12), 315 GNSS_MEASUREMENTS_STATE_SBAS_SYNC_BIT = (1<<13), 316 } GnssMeasurementsStateBits; 317 318 typedef enum { 319 GNSS_MEASUREMENTS_MULTIPATH_INDICATOR_UNKNOWN = 0, 320 GNSS_MEASUREMENTS_MULTIPATH_INDICATOR_PRESENT, 321 GNSS_MEASUREMENTS_MULTIPATH_INDICATOR_NOT_PRESENT, 322 } GnssMeasurementsMultipathIndicator; 323 324 typedef uint32_t GnssMeasurementsClockFlagsMask; 325 typedef enum { 326 GNSS_MEASUREMENTS_CLOCK_FLAGS_LEAP_SECOND_BIT = (1<<0), 327 GNSS_MEASUREMENTS_CLOCK_FLAGS_TIME_BIT = (1<<1), 328 GNSS_MEASUREMENTS_CLOCK_FLAGS_TIME_UNCERTAINTY_BIT = (1<<2), 329 GNSS_MEASUREMENTS_CLOCK_FLAGS_FULL_BIAS_BIT = (1<<3), 330 GNSS_MEASUREMENTS_CLOCK_FLAGS_BIAS_BIT = (1<<4), 331 GNSS_MEASUREMENTS_CLOCK_FLAGS_BIAS_UNCERTAINTY_BIT = (1<<5), 332 GNSS_MEASUREMENTS_CLOCK_FLAGS_DRIFT_BIT = (1<<6), 333 GNSS_MEASUREMENTS_CLOCK_FLAGS_DRIFT_UNCERTAINTY_BIT = (1<<7), 334 GNSS_MEASUREMENTS_CLOCK_FLAGS_HW_CLOCK_DISCONTINUITY_COUNT_BIT = (1<<8), 335 } GnssMeasurementsClockFlagsBits; 336 337 typedef uint32_t GnssAidingDataSvMask; 338 typedef enum { 339 GNSS_AIDING_DATA_SV_EPHEMERIS = (1<<0), // ephemeris 340 GNSS_AIDING_DATA_SV_ALMANAC = (1<<1), // almanac 341 GNSS_AIDING_DATA_SV_HEALTH = (1<<2), // health 342 GNSS_AIDING_DATA_SV_DIRECTION = (1<<3), // direction 343 GNSS_AIDING_DATA_SV_STEER = (1<<4), // steer 344 GNSS_AIDING_DATA_SV_ALMANAC_CORR = (1<<5), // almanac correction 345 GNSS_AIDING_DATA_SV_BLACKLIST = (1<<6), // blacklist SVs 346 GNSS_AIDING_DATA_SV_SA_DATA = (1<<7), // sensitivity assistance data 347 GNSS_AIDING_DATA_SV_NO_EXIST = (1<<8), // SV does not exist 348 GNSS_AIDING_DATA_SV_IONOSPHERE = (1<<9), // ionosphere correction 349 GNSS_AIDING_DATA_SV_TIME = (1<<10),// reset satellite time 350 } GnssAidingDataSvBits; 351 352 typedef uint32_t GnssAidingDataSvTypeMask; 353 typedef enum { 354 GNSS_AIDING_DATA_SV_TYPE_GPS = (1<<0), 355 GNSS_AIDING_DATA_SV_TYPE_GLONASS = (1<<1), 356 GNSS_AIDING_DATA_SV_TYPE_QZSS = (1<<2), 357 GNSS_AIDING_DATA_SV_TYPE_BEIDOU = (1<<3), 358 GNSS_AIDING_DATA_SV_TYPE_GALILEO = (1<<4), 359 } GnssAidingDataSvTypeBits; 360 361 typedef struct { 362 GnssAidingDataSvMask svMask; // bitwise OR of GnssAidingDataSvBits 363 GnssAidingDataSvTypeMask svTypeMask; // bitwise OR of GnssAidingDataSvTypeBits 364 } GnssAidingDataSv; 365 366 typedef uint32_t GnssAidingDataCommonMask; 367 typedef enum { 368 GNSS_AIDING_DATA_COMMON_POSITION = (1<<0), // position estimate 369 GNSS_AIDING_DATA_COMMON_TIME = (1<<1), // reset all clock values 370 GNSS_AIDING_DATA_COMMON_UTC = (1<<2), // UTC estimate 371 GNSS_AIDING_DATA_COMMON_RTI = (1<<3), // RTI 372 GNSS_AIDING_DATA_COMMON_FREQ_BIAS_EST = (1<<4), // frequency bias estimate 373 GNSS_AIDING_DATA_COMMON_CELLDB = (1<<5), // all celldb info 374 } GnssAidingDataCommonBits; 375 376 typedef struct { 377 GnssAidingDataCommonMask mask; // bitwise OR of GnssAidingDataCommonBits 378 } GnssAidingDataCommon; 379 380 typedef struct { 381 bool deleteAll; // if true, delete all aiding data and ignore other params 382 GnssAidingDataSv sv; // SV specific aiding data 383 GnssAidingDataCommon common; // common aiding data 384 } GnssAidingData; 385 386 typedef struct { 387 size_t size; // set to sizeof(Location) 388 LocationFlagsMask flags; // bitwise OR of LocationFlagsBits to mark which params are valid 389 uint64_t timestamp; // UTC timestamp for location fix, milliseconds since January 1, 1970 390 double latitude; // in degrees 391 double longitude; // in degrees 392 double altitude; // in meters above the WGS 84 reference ellipsoid 393 float speed; // in meters per second 394 float bearing; // in degrees; range [0, 360) 395 float accuracy; // in meters 396 LocationTechnologyMask techMask; 397 } Location; 398 399 typedef struct { 400 size_t size; // set to sizeof(LocationOptions) 401 uint32_t minInterval; // in milliseconds 402 uint32_t minDistance; // in meters. if minDistance > 0, gnssSvCallback/gnssNmeaCallback/ 403 // gnssMeasurementsCallback may not be called 404 GnssSuplMode mode; // Standalone/MS-Based/MS-Assisted 405 } LocationOptions; 406 407 typedef struct { 408 size_t size; // set to sizeof(GeofenceOption) 409 GeofenceBreachTypeMask breachTypeMask; // bitwise OR of GeofenceBreachTypeBits 410 uint32_t responsiveness; // in milliseconds 411 uint32_t dwellTime; // in seconds 412 } GeofenceOption; 413 414 typedef struct { 415 size_t size; // set to sizeof(GeofenceInfo) 416 double latitude; // in degrees 417 double longitude; // in degrees 418 double radius; // in meters 419 } GeofenceInfo; 420 421 typedef struct { 422 size_t size; // set to sizeof(GeofenceBreachNotification) 423 size_t count; // number of ids in array 424 uint32_t* ids; // array of ids that have breached 425 Location location; // location associated with breach 426 GeofenceBreachType type; // type of breach 427 uint64_t timestamp; // timestamp of breach 428 } GeofenceBreachNotification; 429 430 typedef struct { 431 size_t size; // set to sizeof(GeofenceBreachNotification) 432 GeofenceStatusAvailable available; // GEOFENCE_STATUS_AVAILABILE_NO/_YES 433 LocationTechnologyType techType; // GNSS 434 } GeofenceStatusNotification; 435 436 typedef struct { 437 size_t size; // set to sizeof(GnssLocationInfo) 438 GnssLocationInfoFlagMask flags; // bitwise OR of GnssLocationInfoBits for param validity 439 float altitudeMeanSeaLevel; // altitude wrt mean sea level 440 float pdop; // position dilusion of precision 441 float hdop; // horizontal dilusion of precision 442 float vdop; // vertical dilusion of precision 443 float magneticDeviation; // magnetic deviation 444 float verAccuracy; // vertical accuracy in meters 445 float speedAccuracy; // speed accuracy in meters/second 446 float bearingAccuracy; // bearing accuracy in degrees (0 to 359.999) 447 LocationReliability horReliability; // horizontal reliability 448 LocationReliability verReliability; // vertical reliability 449 float horUncEllipseSemiMajor; // horizontal elliptical accuracy semi-major axis 450 float horUncEllipseSemiMinor; // horizontal elliptical accuracy semi-minor axis 451 float horUncEllipseOrientAzimuth; // horizontal elliptical accuracy azimuth 452 } GnssLocationInfoNotification; 453 454 typedef struct { 455 size_t size; // set to sizeof(GnssNiNotification) 456 GnssNiType type; // type of NI (Voice, SUPL, Control Plane) 457 GnssNiOptionsMask options; // bitwise OR of GnssNiOptionsBits 458 uint32_t timeout; // time (seconds) to wait for user input 459 GnssNiResponse timeoutResponse; // the response that should be sent when timeout expires 460 char requestor[GNSS_NI_REQUESTOR_MAX]; // the requestor that is making the request 461 GnssNiEncodingType requestorEncoding; // the encoding type for requestor 462 char message[GNSS_NI_MESSAGE_ID_MAX]; // the message to show user 463 GnssNiEncodingType messageEncoding; // the encoding type for message 464 char extras[GNSS_NI_MESSAGE_ID_MAX]; 465 } GnssNiNotification; 466 467 typedef struct { 468 size_t size; // set to sizeof(GnssSv) 469 uint16_t svId; // Unique Identifier 470 GnssSvType type; // type of SV (GPS, SBAS, GLONASS, QZSS, BEIDOU, GALILEO) 471 float cN0Dbhz; // signal strength 472 float elevation; // elevation of SV (in degrees) 473 float azimuth; // azimuth of SV (in degrees) 474 GnssSvOptionsMask gnssSvOptionsMask; // Bitwise OR of GnssSvOptionsBits 475 } GnssSv; 476 477 typedef struct { 478 size_t size; // set to sizeof(GnssConfigSetAssistanceServer) 479 GnssAssistanceType type; // SUPL or C2K 480 const char* hostName; // null terminated string 481 uint32_t port; // port of server 482 } GnssConfigSetAssistanceServer; 483 484 typedef struct { 485 size_t size; // set to sizeof(GnssMeasurementsData) 486 GnssMeasurementsDataFlagsMask flags; // bitwise OR of GnssMeasurementsDataFlagsBits 487 int16_t svId; 488 GnssSvType svType; 489 double timeOffsetNs; 490 GnssMeasurementsStateMask stateMask; // bitwise OR of GnssMeasurementsStateBits 491 int64_t receivedSvTimeNs; 492 int64_t receivedSvTimeUncertaintyNs; 493 double carrierToNoiseDbHz; 494 double pseudorangeRateMps; 495 double pseudorangeRateUncertaintyMps; 496 GnssMeasurementsAdrStateMask adrStateMask; // bitwise OR of GnssMeasurementsAdrStateBits 497 double adrMeters; 498 double adrUncertaintyMeters; 499 float carrierFrequencyHz; 500 int64_t carrierCycles; 501 double carrierPhase; 502 double carrierPhaseUncertainty; 503 GnssMeasurementsMultipathIndicator multipathIndicator; 504 double signalToNoiseRatioDb; 505 } GnssMeasurementsData; 506 507 typedef struct { 508 size_t size; // set to sizeof(GnssMeasurementsClock) 509 GnssMeasurementsClockFlagsMask flags; // bitwise OR of GnssMeasurementsClockFlagsBits 510 int16_t leapSecond; 511 int64_t timeNs; 512 double timeUncertaintyNs; 513 int64_t fullBiasNs; 514 double biasNs; 515 double biasUncertaintyNs; 516 double driftNsps; 517 double driftUncertaintyNsps; 518 uint32_t hwClockDiscontinuityCount; 519 } GnssMeasurementsClock; 520 521 typedef struct { 522 size_t size; // set to sizeof(GnssSvNotification) 523 size_t count; // number of SVs in the GnssSv array 524 GnssSv gnssSvs[GNSS_SV_MAX]; // information on a number of SVs 525 } GnssSvNotification; 526 527 typedef struct { 528 size_t size; // set to sizeof(GnssNmeaNotification) 529 uint64_t timestamp; // timestamp 530 const char* nmea; // nmea text 531 size_t length; // length of the nmea text 532 } GnssNmeaNotification; 533 534 typedef struct { 535 size_t size; // set to sizeof(GnssMeasurementsNotification) 536 size_t count; // number of items in GnssMeasurements array 537 GnssMeasurementsData measurements[GNSS_MEASUREMENTS_MAX]; 538 GnssMeasurementsClock clock; // clock 539 } GnssMeasurementsNotification; 540 541 typedef struct { 542 size_t size; // set to sizeof(GnssConfig) 543 GnssConfigFlagsMask flags; // bitwise OR of GnssConfigFlagsBits to mark which params are valid 544 GnssConfigGpsLock gpsLock; 545 GnssConfigSuplVersion suplVersion; 546 GnssConfigSetAssistanceServer assistanceServer; 547 GnssConfigLppProfile lppProfile; 548 GnssConfigLppeControlPlaneMask lppeControlPlaneMask; 549 GnssConfigLppeUserPlaneMask lppeUserPlaneMask; 550 GnssConfigAGlonassPositionProtocolMask aGlonassPositionProtocolMask; 551 GnssConfigEmergencyPdnForEmergencySupl emergencyPdnForEmergencySupl; 552 GnssConfigSuplEmergencyServices suplEmergencyServices; 553 GnssConfigSuplModeMask suplModeMask; //bitwise OR of GnssConfigSuplModeBits 554 } GnssConfig; 555 556 /* Provides the capabilities of the system 557 capabilities callback is called once soon after createInstance is called */ 558 typedef std::function<void( 559 LocationCapabilitiesMask capabilitiesMask // bitwise OR of LocationCapabilitiesBits 560 )> capabilitiesCallback; 561 562 /* Used by tracking, batching, and miscellanous APIs 563 responseCallback is called for every Tracking, Batching API, and Miscellanous API */ 564 typedef std::function<void( 565 LocationError err, // if not SUCCESS, then id is not valid 566 uint32_t id // id to be associated to the request 567 )> responseCallback; 568 569 /* Used by APIs that gets more than one LocationError in it's response 570 collectiveResponseCallback is called for every geofence API call. 571 ids array and LocationError array are only valid until collectiveResponseCallback returns. */ 572 typedef std::function<void( 573 size_t count, // number of locations in arrays 574 LocationError* errs, // array of LocationError associated to the request 575 uint32_t* ids // array of ids to be associated to the request 576 )> collectiveResponseCallback; 577 578 /* Used for startTracking API, optional can be NULL 579 trackingCallback is called when delivering a location in a tracking session 580 broadcasted to all clients, no matter if a session has started by client */ 581 typedef std::function<void( 582 Location location 583 )> trackingCallback; 584 585 /* Used for startBatching API, optional can be NULL 586 batchingCallback is called when delivering locations in a batching session. 587 broadcasted to all clients, no matter if a session has started by client */ 588 typedef std::function<void( 589 size_t count, // number of locations in array 590 Location* location // array of locations 591 )> batchingCallback; 592 593 /* Gives GNSS Location information, optional can be NULL 594 gnssLocationInfoCallback is called only during a tracking session 595 broadcasted to all clients, no matter if a session has started by client */ 596 typedef std::function<void( 597 GnssLocationInfoNotification gnssLocationInfoNotification 598 )> gnssLocationInfoCallback; 599 600 /* Used for addGeofences API, optional can be NULL 601 geofenceBreachCallback is called when any number of geofences have a state change */ 602 typedef std::function<void( 603 GeofenceBreachNotification geofenceBreachNotification 604 )> geofenceBreachCallback; 605 606 /* Used for addGeofences API, optional can be NULL 607 geofenceStatusCallback is called when any number of geofences have a status change */ 608 typedef std::function<void( 609 GeofenceStatusNotification geofenceStatusNotification 610 )> geofenceStatusCallback; 611 612 /* Network Initiated request, optional can be NULL 613 This callback should be responded to by calling gnssNiResponse */ 614 typedef std::function<void( 615 uint32_t id, // id that should be used to respond by calling gnssNiResponse 616 GnssNiNotification gnssNiNotification 617 )> gnssNiCallback; 618 619 /* Gives GNSS SV information, optional can be NULL 620 gnssSvCallback is called only during a tracking session 621 broadcasted to all clients, no matter if a session has started by client */ 622 typedef std::function<void( 623 GnssSvNotification gnssSvNotification 624 )> gnssSvCallback; 625 626 /* Gives GNSS NMEA data, optional can be NULL 627 gnssNmeaCallback is called only during a tracking session 628 broadcasted to all clients, no matter if a session has started by client */ 629 typedef std::function<void( 630 GnssNmeaNotification gnssNmeaNotification 631 )> gnssNmeaCallback; 632 633 /* Gives GNSS Measurements information, optional can be NULL 634 gnssMeasurementsCallback is called only during a tracking session 635 broadcasted to all clients, no matter if a session has started by client */ 636 typedef std::function<void( 637 GnssMeasurementsNotification gnssMeasurementsNotification 638 )> gnssMeasurementsCallback; 639 640 typedef struct { 641 size_t size; // set to sizeof(LocationCallbacks) 642 capabilitiesCallback capabilitiesCb; // mandatory 643 responseCallback responseCb; // mandatory 644 collectiveResponseCallback collectiveResponseCb; // mandatory 645 trackingCallback trackingCb; // optional 646 batchingCallback batchingCb; // optional 647 geofenceBreachCallback geofenceBreachCb; // optional 648 geofenceStatusCallback geofenceStatusCb; // optional 649 gnssLocationInfoCallback gnssLocationInfoCb; // optional 650 gnssNiCallback gnssNiCb; // optional 651 gnssSvCallback gnssSvCb; // optional 652 gnssNmeaCallback gnssNmeaCb; // optional 653 gnssMeasurementsCallback gnssMeasurementsCb; // optional 654 } LocationCallbacks; 655 656 class LocationAPI 657 { 658 private: 659 LocationAPI(); 660 ~LocationAPI(); 661 662 public: 663 /* creates an instance to LocationAPI object. 664 Will return NULL if mandatory parameters are invalid or if the maximum number 665 of instances have been reached */ 666 static LocationAPI* createInstance(LocationCallbacks&); 667 668 /* destroy/cleans up the instance, which should be called when LocationAPI object is 669 no longer needed. LocationAPI* returned from createInstance will no longer valid 670 after destroy is called */ 671 void destroy(); 672 673 /* updates/changes the callbacks that will be called. 674 mandatory callbacks must be present for callbacks to be successfully updated 675 no return value */ 676 void updateCallbacks(LocationCallbacks&); 677 678 /* ================================== TRACKING ================================== */ 679 680 /* startTracking starts a tracking session, which returns a session id that will be 681 used by the other tracking APIs and also in the responseCallback to match command 682 with response. locations are reported on the trackingCallback passed in createInstance 683 periodically according to LocationOptions. 684 responseCallback returns: 685 LOCATION_ERROR_SUCCESS if session was successfully started 686 LOCATION_ERROR_ALREADY_STARTED if a startTracking session is already in progress 687 LOCATION_ERROR_CALLBACK_MISSING if no trackingCallback was passed in createInstance 688 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameter is invalid */ 689 uint32_t startTracking(LocationOptions&); // returns session id 690 691 /* stopTracking stops a tracking session associated with id parameter. 692 responseCallback returns: 693 LOCATION_ERROR_SUCCESS if successful 694 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */ 695 void stopTracking(uint32_t id); 696 697 /* updateTrackingOptions changes the LocationOptions of a tracking session associated with id 698 responseCallback returns: 699 LOCATION_ERROR_SUCCESS if successful 700 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameters are invalid 701 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */ 702 void updateTrackingOptions(uint32_t id, LocationOptions&); 703 704 /* ================================== BATCHING ================================== */ 705 706 /* startBatching starts a batching session, which returns a session id that will be 707 used by the other batching APIs and also in the responseCallback to match command 708 with response. locations are reported on the batchingCallback passed in createInstance 709 periodically according to LocationOptions. A batching session starts tracking on 710 the low power processor and delivers them in batches by the batchingCallback when 711 the batch is full or when getBatchedLocations is called. This allows for the processor 712 that calls this API to sleep when the low power processor can batch locations in the 713 backgroup and wake up the processor calling the API only when the batch is full, thus 714 saving power 715 responseCallback returns: 716 LOCATION_ERROR_SUCCESS if session was successful 717 LOCATION_ERROR_ALREADY_STARTED if a startBatching session is already in progress 718 LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback was passed in createInstance 719 LOCATION_ERROR_INVALID_PARAMETER if a parameter is invalid 720 LOCATION_ERROR_NOT_SUPPORTED if batching is not supported */ 721 uint32_t startBatching(LocationOptions&); // returns session id 722 723 /* stopBatching stops a batching session associated with id parameter. 724 responseCallback returns: 725 LOCATION_ERROR_SUCCESS if successful 726 LOCATION_ERROR_ID_UNKNOWN if id is not associated with batching session */ 727 void stopBatching(uint32_t id); 728 729 /* updateBatchingOptions changes the LocationOptions of a batching session associated with id 730 responseCallback returns: 731 LOCATION_ERROR_SUCCESS if successful 732 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameters are invalid 733 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */ 734 void updateBatchingOptions(uint32_t id, LocationOptions&); 735 736 /* getBatchedLocations gets a number of locations that are currently stored/batched 737 on the low power processor, delivered by the batchingCallback passed in createInstance. 738 Location are then deleted from the batch stored on the low power processor. 739 responseCallback returns: 740 LOCATION_ERROR_SUCCESS if successful, will be followed by batchingCallback call 741 LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback was passed in createInstance 742 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */ 743 void getBatchedLocations(uint32_t id, size_t count); 744 745 /* ================================== GEOFENCE ================================== */ 746 747 /* addGeofences adds any number of geofences and returns an array of geofence ids that 748 will be used by the other geofence APIs and also in the collectiveResponseCallback to 749 match command with response. The geofenceBreachCallback will deliver the status of each 750 geofence according to the GeofenceOption for each. The geofence id array returned will 751 be valid until the collectiveResponseCallback is called and has returned. 752 collectiveResponseCallback returns: 753 LOCATION_ERROR_SUCCESS if session was successful 754 LOCATION_ERROR_CALLBACK_MISSING if no geofenceBreachCallback 755 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 756 LOCATION_ERROR_NOT_SUPPORTED if geofence is not supported */ 757 uint32_t* addGeofences(size_t count, GeofenceOption*, GeofenceInfo*); // returns id array 758 759 /* removeGeofences removes any number of geofences. Caller should delete ids array after 760 removeGeofences returneds. 761 collectiveResponseCallback returns: 762 LOCATION_ERROR_SUCCESS if successful 763 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ 764 void removeGeofences(size_t count, uint32_t* ids); 765 766 /* modifyGeofences modifies any number of geofences. Caller should delete ids array after 767 modifyGeofences returns. 768 collectiveResponseCallback returns: 769 LOCATION_ERROR_SUCCESS if successful 770 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session 771 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid */ 772 void modifyGeofences(size_t count, uint32_t* ids, GeofenceOption* options); 773 774 /* pauseGeofences pauses any number of geofences, which is similar to removeGeofences, 775 only that they can be resumed at any time. Caller should delete ids array after 776 pauseGeofences returns. 777 collectiveResponseCallback returns: 778 LOCATION_ERROR_SUCCESS if successful 779 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ 780 void pauseGeofences(size_t count, uint32_t* ids); 781 782 /* resumeGeofences resumes any number of geofences that are currently paused. Caller should 783 delete ids array after resumeGeofences returns. 784 collectiveResponseCallback returns: 785 LOCATION_ERROR_SUCCESS if successful 786 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ 787 void resumeGeofences(size_t count, uint32_t* ids); 788 789 /* ================================== GNSS ====================================== */ 790 791 /* gnssNiResponse is called in response to a gnssNiCallback. 792 responseCallback returns: 793 LOCATION_ERROR_SUCCESS if session was successful 794 LOCATION_ERROR_INVALID_PARAMETER if any parameters in GnssNiResponse are invalid 795 LOCATION_ERROR_ID_UNKNOWN if id does not match a gnssNiCallback */ 796 void gnssNiResponse(uint32_t id, GnssNiResponse response); 797 }; 798 799 typedef struct { 800 size_t size; // set to sizeof(LocationControlCallbacks) 801 responseCallback responseCb; // mandatory 802 collectiveResponseCallback collectiveResponseCb; // mandatory 803 } LocationControlCallbacks; 804 805 class LocationControlAPI 806 { 807 private: 808 LocationControlAPI(); 809 ~LocationControlAPI(); 810 811 public: 812 /* creates an instance to LocationControlAPI object. 813 Will return NULL if mandatory parameters are invalid or if the maximum number 814 of instances have been reached. Only once instance allowed */ 815 static LocationControlAPI* createInstance(LocationControlCallbacks&); 816 817 /* destroy/cleans up the instance, which should be called when LocationControlAPI object is 818 no longer needed. LocationControlAPI* returned from createInstance will no longer valid 819 after destroy is called */ 820 void destroy(); 821 822 /* enable will enable specific location technology to be used for calculation locations and 823 will effectively start a control session if call is successful, which returns a session id 824 that will be returned in responseCallback to match command with response. The session id is 825 also needed to call the disable command. 826 This effect is global for all clients of LocationAPI 827 responseCallback returns: 828 LOCATION_ERROR_SUCCESS if successful 829 LOCATION_ERROR_ALREADY_STARTED if an enable was already called for this techType 830 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 831 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ 832 uint32_t enable(LocationTechnologyType techType); 833 834 /* disable will disable specific location technology to be used for calculation locations and 835 effectively ends the control session if call is successful. 836 id parameter is the session id that was returned in enable responseCallback for techType. 837 The session id is no longer valid after disable's responseCallback returns success. 838 This effect is global for all clients of LocationAPI 839 responseCallback returns: 840 LOCATION_ERROR_SUCCESS if successful 841 LOCATION_ERROR_ID_UNKNOWN if id was not returned from responseCallback from enable 842 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ 843 void disable(uint32_t id); 844 845 /* gnssUpdateConfig updates the gnss specific configuration, which returns a session id array 846 with an id for each of the bits set in GnssConfig.flags, order from low bits to high bits. 847 The response for each config that is set will be returned in collectiveResponseCallback. 848 The session id array returned will be valid until the collectiveResponseCallback is called 849 and has returned. This effect is global for all clients of LocationAPI 850 collectiveResponseCallback returns: 851 LOCATION_ERROR_SUCCESS if session was successful 852 LOCATION_ERROR_INVALID_PARAMETER if any other parameters are invalid 853 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ 854 uint32_t* gnssUpdateConfig(GnssConfig config); 855 856 /* delete specific gnss aiding data for testing, which returns a session id 857 that will be returned in responseCallback to match command with response. 858 Only allowed in userdebug builds. This effect is global for all clients of LocationAPI 859 responseCallback returns: 860 LOCATION_ERROR_SUCCESS if successful 861 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 862 LOCATION_ERROR_NOT_SUPPORTED if build is not userdebug */ 863 uint32_t gnssDeleteAidingData(GnssAidingData& data); 864 }; 865 866 #endif /* LOCATION_H */ 867
