1 /* 2 * Copyright (C) 2010 The Android Open Source Project 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 ANDROID_INCLUDE_HARDWARE_GPS_H 18 #define ANDROID_INCLUDE_HARDWARE_GPS_H 19 20 #include <stdint.h> 21 #include <sys/cdefs.h> 22 #include <sys/types.h> 23 #include <pthread.h> 24 #include <sys/socket.h> 25 #include <stdbool.h> 26 27 #include <hardware/hardware.h> 28 29 __BEGIN_DECLS 30 31 /** 32 * The id of this module 33 */ 34 #define GPS_HARDWARE_MODULE_ID "gps" 35 36 37 /** Milliseconds since January 1, 1970 */ 38 typedef int64_t GpsUtcTime; 39 40 /** Maximum number of SVs for gps_sv_status_callback(). */ 41 #define GPS_MAX_SVS 32 42 /** Maximum number of SVs for gps_sv_status_callback(). */ 43 #define GNSS_MAX_SVS 64 44 45 /** Maximum number of Measurements in gps_measurement_callback(). */ 46 #define GPS_MAX_MEASUREMENT 32 47 48 /** Maximum number of Measurements in gnss_measurement_callback(). */ 49 #define GNSS_MAX_MEASUREMENT 64 50 51 /** Requested operational mode for GPS operation. */ 52 typedef uint32_t GpsPositionMode; 53 /* IMPORTANT: Note that the following values must match 54 * constants in GpsLocationProvider.java. */ 55 /** Mode for running GPS standalone (no assistance). */ 56 #define GPS_POSITION_MODE_STANDALONE 0 57 /** AGPS MS-Based mode. */ 58 #define GPS_POSITION_MODE_MS_BASED 1 59 /** 60 * AGPS MS-Assisted mode. This mode is not maintained by the platform anymore. 61 * It is strongly recommended to use GPS_POSITION_MODE_MS_BASED instead. 62 */ 63 #define GPS_POSITION_MODE_MS_ASSISTED 2 64 65 /** Requested recurrence mode for GPS operation. */ 66 typedef uint32_t GpsPositionRecurrence; 67 /* IMPORTANT: Note that the following values must match 68 * constants in GpsLocationProvider.java. */ 69 /** Receive GPS fixes on a recurring basis at a specified period. */ 70 #define GPS_POSITION_RECURRENCE_PERIODIC 0 71 /** Request a single shot GPS fix. */ 72 #define GPS_POSITION_RECURRENCE_SINGLE 1 73 74 /** GPS status event values. */ 75 typedef uint16_t GpsStatusValue; 76 /* IMPORTANT: Note that the following values must match 77 * constants in GpsLocationProvider.java. */ 78 /** GPS status unknown. */ 79 #define GPS_STATUS_NONE 0 80 /** GPS has begun navigating. */ 81 #define GPS_STATUS_SESSION_BEGIN 1 82 /** GPS has stopped navigating. */ 83 #define GPS_STATUS_SESSION_END 2 84 /** GPS has powered on but is not navigating. */ 85 #define GPS_STATUS_ENGINE_ON 3 86 /** GPS is powered off. */ 87 #define GPS_STATUS_ENGINE_OFF 4 88 89 /** Flags to indicate which values are valid in a GpsLocation. */ 90 typedef uint16_t GpsLocationFlags; 91 /* IMPORTANT: Note that the following values must match 92 * constants in GpsLocationProvider.java. */ 93 /** GpsLocation has valid latitude and longitude. */ 94 #define GPS_LOCATION_HAS_LAT_LONG 0x0001 95 /** GpsLocation has valid altitude. */ 96 #define GPS_LOCATION_HAS_ALTITUDE 0x0002 97 /** GpsLocation has valid speed. */ 98 #define GPS_LOCATION_HAS_SPEED 0x0004 99 /** GpsLocation has valid bearing. */ 100 #define GPS_LOCATION_HAS_BEARING 0x0008 101 /** GpsLocation has valid accuracy. */ 102 #define GPS_LOCATION_HAS_ACCURACY 0x0010 103 104 /** Flags for the gps_set_capabilities callback. */ 105 106 /** 107 * GPS HAL schedules fixes for GPS_POSITION_RECURRENCE_PERIODIC mode. If this is 108 * not set, then the framework will use 1000ms for min_interval and will start 109 * and call start() and stop() to schedule the GPS. 110 */ 111 #define GPS_CAPABILITY_SCHEDULING (1 << 0) 112 /** GPS supports MS-Based AGPS mode */ 113 #define GPS_CAPABILITY_MSB (1 << 1) 114 /** GPS supports MS-Assisted AGPS mode */ 115 #define GPS_CAPABILITY_MSA (1 << 2) 116 /** GPS supports single-shot fixes */ 117 #define GPS_CAPABILITY_SINGLE_SHOT (1 << 3) 118 /** GPS supports on demand time injection */ 119 #define GPS_CAPABILITY_ON_DEMAND_TIME (1 << 4) 120 /** GPS supports Geofencing */ 121 #define GPS_CAPABILITY_GEOFENCING (1 << 5) 122 /** GPS supports Measurements. */ 123 #define GPS_CAPABILITY_MEASUREMENTS (1 << 6) 124 /** GPS supports Navigation Messages */ 125 #define GPS_CAPABILITY_NAV_MESSAGES (1 << 7) 126 127 /** 128 * Flags used to specify which aiding data to delete when calling 129 * delete_aiding_data(). 130 */ 131 typedef uint16_t GpsAidingData; 132 /* IMPORTANT: Note that the following values must match 133 * constants in GpsLocationProvider.java. */ 134 #define GPS_DELETE_EPHEMERIS 0x0001 135 #define GPS_DELETE_ALMANAC 0x0002 136 #define GPS_DELETE_POSITION 0x0004 137 #define GPS_DELETE_TIME 0x0008 138 #define GPS_DELETE_IONO 0x0010 139 #define GPS_DELETE_UTC 0x0020 140 #define GPS_DELETE_HEALTH 0x0040 141 #define GPS_DELETE_SVDIR 0x0080 142 #define GPS_DELETE_SVSTEER 0x0100 143 #define GPS_DELETE_SADATA 0x0200 144 #define GPS_DELETE_RTI 0x0400 145 #define GPS_DELETE_CELLDB_INFO 0x8000 146 #define GPS_DELETE_ALL 0xFFFF 147 148 /** AGPS type */ 149 typedef uint16_t AGpsType; 150 #define AGPS_TYPE_SUPL 1 151 #define AGPS_TYPE_C2K 2 152 153 typedef uint16_t AGpsSetIDType; 154 #define AGPS_SETID_TYPE_NONE 0 155 #define AGPS_SETID_TYPE_IMSI 1 156 #define AGPS_SETID_TYPE_MSISDN 2 157 158 typedef uint16_t ApnIpType; 159 #define APN_IP_INVALID 0 160 #define APN_IP_IPV4 1 161 #define APN_IP_IPV6 2 162 #define APN_IP_IPV4V6 3 163 164 /** 165 * String length constants 166 */ 167 #define GPS_NI_SHORT_STRING_MAXLEN 256 168 #define GPS_NI_LONG_STRING_MAXLEN 2048 169 170 /** 171 * GpsNiType constants 172 */ 173 typedef uint32_t GpsNiType; 174 #define GPS_NI_TYPE_VOICE 1 175 #define GPS_NI_TYPE_UMTS_SUPL 2 176 #define GPS_NI_TYPE_UMTS_CTRL_PLANE 3 177 178 /** 179 * GpsNiNotifyFlags constants 180 */ 181 typedef uint32_t GpsNiNotifyFlags; 182 /** NI requires notification */ 183 #define GPS_NI_NEED_NOTIFY 0x0001 184 /** NI requires verification */ 185 #define GPS_NI_NEED_VERIFY 0x0002 186 /** NI requires privacy override, no notification/minimal trace */ 187 #define GPS_NI_PRIVACY_OVERRIDE 0x0004 188 189 /** 190 * GPS NI responses, used to define the response in 191 * NI structures 192 */ 193 typedef int GpsUserResponseType; 194 #define GPS_NI_RESPONSE_ACCEPT 1 195 #define GPS_NI_RESPONSE_DENY 2 196 #define GPS_NI_RESPONSE_NORESP 3 197 198 /** 199 * NI data encoding scheme 200 */ 201 typedef int GpsNiEncodingType; 202 #define GPS_ENC_NONE 0 203 #define GPS_ENC_SUPL_GSM_DEFAULT 1 204 #define GPS_ENC_SUPL_UTF8 2 205 #define GPS_ENC_SUPL_UCS2 3 206 #define GPS_ENC_UNKNOWN -1 207 208 /** AGPS status event values. */ 209 typedef uint16_t AGpsStatusValue; 210 /** GPS requests data connection for AGPS. */ 211 #define GPS_REQUEST_AGPS_DATA_CONN 1 212 /** GPS releases the AGPS data connection. */ 213 #define GPS_RELEASE_AGPS_DATA_CONN 2 214 /** AGPS data connection initiated */ 215 #define GPS_AGPS_DATA_CONNECTED 3 216 /** AGPS data connection completed */ 217 #define GPS_AGPS_DATA_CONN_DONE 4 218 /** AGPS data connection failed */ 219 #define GPS_AGPS_DATA_CONN_FAILED 5 220 221 typedef uint16_t AGpsRefLocationType; 222 #define AGPS_REF_LOCATION_TYPE_GSM_CELLID 1 223 #define AGPS_REF_LOCATION_TYPE_UMTS_CELLID 2 224 #define AGPS_REF_LOCATION_TYPE_MAC 3 225 #define AGPS_REF_LOCATION_TYPE_LTE_CELLID 4 226 227 /* Deprecated, to be removed in the next Android release. */ 228 #define AGPS_REG_LOCATION_TYPE_MAC 3 229 230 /** Network types for update_network_state "type" parameter */ 231 #define AGPS_RIL_NETWORK_TYPE_MOBILE 0 232 #define AGPS_RIL_NETWORK_TYPE_WIFI 1 233 #define AGPS_RIL_NETWORK_TYPE_MOBILE_MMS 2 234 #define AGPS_RIL_NETWORK_TYPE_MOBILE_SUPL 3 235 #define AGPS_RIL_NETWORK_TTYPE_MOBILE_DUN 4 236 #define AGPS_RIL_NETWORK_TTYPE_MOBILE_HIPRI 5 237 #define AGPS_RIL_NETWORK_TTYPE_WIMAX 6 238 239 /* The following typedef together with its constants below are deprecated, and 240 * will be removed in the next release. */ 241 typedef uint16_t GpsClockFlags; 242 #define GPS_CLOCK_HAS_LEAP_SECOND (1<<0) 243 #define GPS_CLOCK_HAS_TIME_UNCERTAINTY (1<<1) 244 #define GPS_CLOCK_HAS_FULL_BIAS (1<<2) 245 #define GPS_CLOCK_HAS_BIAS (1<<3) 246 #define GPS_CLOCK_HAS_BIAS_UNCERTAINTY (1<<4) 247 #define GPS_CLOCK_HAS_DRIFT (1<<5) 248 #define GPS_CLOCK_HAS_DRIFT_UNCERTAINTY (1<<6) 249 250 /** 251 * Flags to indicate what fields in GnssClock are valid. 252 */ 253 typedef uint16_t GnssClockFlags; 254 /** A valid 'leap second' is stored in the data structure. */ 255 #define GNSS_CLOCK_HAS_LEAP_SECOND (1<<0) 256 /** A valid 'time uncertainty' is stored in the data structure. */ 257 #define GNSS_CLOCK_HAS_TIME_UNCERTAINTY (1<<1) 258 /** A valid 'full bias' is stored in the data structure. */ 259 #define GNSS_CLOCK_HAS_FULL_BIAS (1<<2) 260 /** A valid 'bias' is stored in the data structure. */ 261 #define GNSS_CLOCK_HAS_BIAS (1<<3) 262 /** A valid 'bias uncertainty' is stored in the data structure. */ 263 #define GNSS_CLOCK_HAS_BIAS_UNCERTAINTY (1<<4) 264 /** A valid 'drift' is stored in the data structure. */ 265 #define GNSS_CLOCK_HAS_DRIFT (1<<5) 266 /** A valid 'drift uncertainty' is stored in the data structure. */ 267 #define GNSS_CLOCK_HAS_DRIFT_UNCERTAINTY (1<<6) 268 269 /* The following typedef together with its constants below are deprecated, and 270 * will be removed in the next release. */ 271 typedef uint8_t GpsClockType; 272 #define GPS_CLOCK_TYPE_UNKNOWN 0 273 #define GPS_CLOCK_TYPE_LOCAL_HW_TIME 1 274 #define GPS_CLOCK_TYPE_GPS_TIME 2 275 276 /* The following typedef together with its constants below are deprecated, and 277 * will be removed in the next release. */ 278 typedef uint32_t GpsMeasurementFlags; 279 #define GPS_MEASUREMENT_HAS_SNR (1<<0) 280 #define GPS_MEASUREMENT_HAS_ELEVATION (1<<1) 281 #define GPS_MEASUREMENT_HAS_ELEVATION_UNCERTAINTY (1<<2) 282 #define GPS_MEASUREMENT_HAS_AZIMUTH (1<<3) 283 #define GPS_MEASUREMENT_HAS_AZIMUTH_UNCERTAINTY (1<<4) 284 #define GPS_MEASUREMENT_HAS_PSEUDORANGE (1<<5) 285 #define GPS_MEASUREMENT_HAS_PSEUDORANGE_UNCERTAINTY (1<<6) 286 #define GPS_MEASUREMENT_HAS_CODE_PHASE (1<<7) 287 #define GPS_MEASUREMENT_HAS_CODE_PHASE_UNCERTAINTY (1<<8) 288 #define GPS_MEASUREMENT_HAS_CARRIER_FREQUENCY (1<<9) 289 #define GPS_MEASUREMENT_HAS_CARRIER_CYCLES (1<<10) 290 #define GPS_MEASUREMENT_HAS_CARRIER_PHASE (1<<11) 291 #define GPS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY (1<<12) 292 #define GPS_MEASUREMENT_HAS_BIT_NUMBER (1<<13) 293 #define GPS_MEASUREMENT_HAS_TIME_FROM_LAST_BIT (1<<14) 294 #define GPS_MEASUREMENT_HAS_DOPPLER_SHIFT (1<<15) 295 #define GPS_MEASUREMENT_HAS_DOPPLER_SHIFT_UNCERTAINTY (1<<16) 296 #define GPS_MEASUREMENT_HAS_USED_IN_FIX (1<<17) 297 #define GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE (1<<18) 298 299 /** 300 * Flags to indicate what fields in GnssMeasurement are valid. 301 */ 302 typedef uint32_t GnssMeasurementFlags; 303 /** A valid 'snr' is stored in the data structure. */ 304 #define GNSS_MEASUREMENT_HAS_SNR (1<<0) 305 /** A valid 'carrier frequency' is stored in the data structure. */ 306 #define GNSS_MEASUREMENT_HAS_CARRIER_FREQUENCY (1<<9) 307 /** A valid 'carrier cycles' is stored in the data structure. */ 308 #define GNSS_MEASUREMENT_HAS_CARRIER_CYCLES (1<<10) 309 /** A valid 'carrier phase' is stored in the data structure. */ 310 #define GNSS_MEASUREMENT_HAS_CARRIER_PHASE (1<<11) 311 /** A valid 'carrier phase uncertainty' is stored in the data structure. */ 312 #define GNSS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY (1<<12) 313 314 /* The following typedef together with its constants below are deprecated, and 315 * will be removed in the next release. */ 316 typedef uint8_t GpsLossOfLock; 317 #define GPS_LOSS_OF_LOCK_UNKNOWN 0 318 #define GPS_LOSS_OF_LOCK_OK 1 319 #define GPS_LOSS_OF_LOCK_CYCLE_SLIP 2 320 321 /* The following typedef together with its constants below are deprecated, and 322 * will be removed in the next release. Use GnssMultipathIndicator instead. 323 */ 324 typedef uint8_t GpsMultipathIndicator; 325 #define GPS_MULTIPATH_INDICATOR_UNKNOWN 0 326 #define GPS_MULTIPATH_INDICATOR_DETECTED 1 327 #define GPS_MULTIPATH_INDICATOR_NOT_USED 2 328 329 /** 330 * Enumeration of available values for the GNSS Measurement's multipath 331 * indicator. 332 */ 333 typedef uint8_t GnssMultipathIndicator; 334 /** The indicator is not available or unknown. */ 335 #define GNSS_MULTIPATH_INDICATOR_UNKNOWN 0 336 /** The measurement is indicated to be affected by multipath. */ 337 #define GNSS_MULTIPATH_INDICATOR_PRESENT 1 338 /** The measurement is indicated to be not affected by multipath. */ 339 #define GNSS_MULTIPATH_INDICATOR_NOT_PRESENT 2 340 341 /* The following typedef together with its constants below are deprecated, and 342 * will be removed in the next release. */ 343 typedef uint16_t GpsMeasurementState; 344 #define GPS_MEASUREMENT_STATE_UNKNOWN 0 345 #define GPS_MEASUREMENT_STATE_CODE_LOCK (1<<0) 346 #define GPS_MEASUREMENT_STATE_BIT_SYNC (1<<1) 347 #define GPS_MEASUREMENT_STATE_SUBFRAME_SYNC (1<<2) 348 #define GPS_MEASUREMENT_STATE_TOW_DECODED (1<<3) 349 #define GPS_MEASUREMENT_STATE_MSEC_AMBIGUOUS (1<<4) 350 351 /** 352 * Flags indicating the GNSS measurement state. 353 * 354 * The expected behavior here is for GPS HAL to set all the flags that applies. 355 * For example, if the state for a satellite is only C/A code locked and bit 356 * synchronized, and there is still millisecond ambiguity, the state should be 357 * set as: 358 * 359 * GNSS_MEASUREMENT_STATE_CODE_LOCK | GNSS_MEASUREMENT_STATE_BIT_SYNC | 360 * GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS 361 * 362 * If GNSS is still searching for a satellite, the corresponding state should be 363 * set to GNSS_MEASUREMENT_STATE_UNKNOWN(0). 364 */ 365 typedef uint32_t GnssMeasurementState; 366 #define GNSS_MEASUREMENT_STATE_UNKNOWN 0 367 #define GNSS_MEASUREMENT_STATE_CODE_LOCK (1<<0) 368 #define GNSS_MEASUREMENT_STATE_BIT_SYNC (1<<1) 369 #define GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC (1<<2) 370 #define GNSS_MEASUREMENT_STATE_TOW_DECODED (1<<3) 371 #define GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS (1<<4) 372 #define GNSS_MEASUREMENT_STATE_SYMBOL_SYNC (1<<5) 373 #define GNSS_MEASUREMENT_STATE_GLO_STRING_SYNC (1<<6) 374 #define GNSS_MEASUREMENT_STATE_GLO_TOD_DECODED (1<<7) 375 #define GNSS_MEASUREMENT_STATE_BDS_D2_BIT_SYNC (1<<8) 376 #define GNSS_MEASUREMENT_STATE_BDS_D2_SUBFRAME_SYNC (1<<9) 377 #define GNSS_MEASUREMENT_STATE_GAL_E1BC_CODE_LOCK (1<<10) 378 #define GNSS_MEASUREMENT_STATE_GAL_E1C_2ND_CODE_LOCK (1<<11) 379 #define GNSS_MEASUREMENT_STATE_GAL_E1B_PAGE_SYNC (1<<12) 380 #define GNSS_MEASUREMENT_STATE_SBAS_SYNC (1<<13) 381 382 /* The following typedef together with its constants below are deprecated, and 383 * will be removed in the next release. */ 384 typedef uint16_t GpsAccumulatedDeltaRangeState; 385 #define GPS_ADR_STATE_UNKNOWN 0 386 #define GPS_ADR_STATE_VALID (1<<0) 387 #define GPS_ADR_STATE_RESET (1<<1) 388 #define GPS_ADR_STATE_CYCLE_SLIP (1<<2) 389 390 /** 391 * Flags indicating the Accumulated Delta Range's states. 392 */ 393 typedef uint16_t GnssAccumulatedDeltaRangeState; 394 #define GNSS_ADR_STATE_UNKNOWN 0 395 #define GNSS_ADR_STATE_VALID (1<<0) 396 #define GNSS_ADR_STATE_RESET (1<<1) 397 #define GNSS_ADR_STATE_CYCLE_SLIP (1<<2) 398 399 /* The following typedef together with its constants below are deprecated, and 400 * will be removed in the next release. */ 401 typedef uint8_t GpsNavigationMessageType; 402 #define GPS_NAVIGATION_MESSAGE_TYPE_UNKNOWN 0 403 #define GPS_NAVIGATION_MESSAGE_TYPE_L1CA 1 404 #define GPS_NAVIGATION_MESSAGE_TYPE_L2CNAV 2 405 #define GPS_NAVIGATION_MESSAGE_TYPE_L5CNAV 3 406 #define GPS_NAVIGATION_MESSAGE_TYPE_CNAV2 4 407 408 /** 409 * Enumeration of available values to indicate the GNSS Navigation message 410 * types. 411 * 412 * For convenience, first byte is the GnssConstellationType on which that signal 413 * is typically transmitted 414 */ 415 typedef int16_t GnssNavigationMessageType; 416 417 #define GNSS_NAVIGATION_MESSAGE_TYPE_UNKNOWN 0 418 /** GPS L1 C/A message contained in the structure. */ 419 #define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L1CA 0x0101 420 /** GPS L2-CNAV message contained in the structure. */ 421 #define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L2CNAV 0x0102 422 /** GPS L5-CNAV message contained in the structure. */ 423 #define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L5CNAV 0x0103 424 /** GPS CNAV-2 message contained in the structure. */ 425 #define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_CNAV2 0x0104 426 /** Glonass L1 CA message contained in the structure. */ 427 #define GNSS_NAVIGATION_MESSAGE_TYPE_GLO_L1CA 0x0301 428 /** Beidou D1 message contained in the structure. */ 429 #define GNSS_NAVIGATION_MESSAGE_TYPE_BDS_D1 0x0501 430 /** Beidou D2 message contained in the structure. */ 431 #define GNSS_NAVIGATION_MESSAGE_TYPE_BDS_D2 0x0502 432 /** Galileo I/NAV message contained in the structure. */ 433 #define GNSS_NAVIGATION_MESSAGE_TYPE_GAL_I 0x0601 434 /** Galileo F/NAV message contained in the structure. */ 435 #define GNSS_NAVIGATION_MESSAGE_TYPE_GAL_F 0x0602 436 437 /** 438 * Status of Navigation Message 439 * When a message is received properly without any parity error in its navigation words, the 440 * status should be set to NAV_MESSAGE_STATUS_PARITY_PASSED. But if a message is received 441 * with words that failed parity check, but GPS is able to correct those words, the status 442 * should be set to NAV_MESSAGE_STATUS_PARITY_REBUILT. 443 * No need to send any navigation message that contains words with parity error and cannot be 444 * corrected. 445 */ 446 typedef uint16_t NavigationMessageStatus; 447 #define NAV_MESSAGE_STATUS_UNKNOWN 0 448 #define NAV_MESSAGE_STATUS_PARITY_PASSED (1<<0) 449 #define NAV_MESSAGE_STATUS_PARITY_REBUILT (1<<1) 450 451 /* This constant is deprecated, and will be removed in the next release. */ 452 #define NAV_MESSAGE_STATUS_UNKONW 0 453 454 /** 455 * Flags that indicate information about the satellite 456 */ 457 typedef uint8_t GnssSvFlags; 458 #define GNSS_SV_FLAGS_NONE 0 459 #define GNSS_SV_FLAGS_HAS_EPHEMERIS_DATA (1 << 0) 460 #define GNSS_SV_FLAGS_HAS_ALMANAC_DATA (1 << 1) 461 #define GNSS_SV_FLAGS_USED_IN_FIX (1 << 2) 462 463 /** 464 * Constellation type of GnssSvInfo 465 */ 466 typedef uint8_t GnssConstellationType; 467 #define GNSS_CONSTELLATION_UNKNOWN 0 468 #define GNSS_CONSTELLATION_GPS 1 469 #define GNSS_CONSTELLATION_SBAS 2 470 #define GNSS_CONSTELLATION_GLONASS 3 471 #define GNSS_CONSTELLATION_QZSS 4 472 #define GNSS_CONSTELLATION_BEIDOU 5 473 #define GNSS_CONSTELLATION_GALILEO 6 474 475 /** 476 * Name for the GPS XTRA interface. 477 */ 478 #define GPS_XTRA_INTERFACE "gps-xtra" 479 480 /** 481 * Name for the GPS DEBUG interface. 482 */ 483 #define GPS_DEBUG_INTERFACE "gps-debug" 484 485 /** 486 * Name for the AGPS interface. 487 */ 488 #define AGPS_INTERFACE "agps" 489 490 /** 491 * Name of the Supl Certificate interface. 492 */ 493 #define SUPL_CERTIFICATE_INTERFACE "supl-certificate" 494 495 /** 496 * Name for NI interface 497 */ 498 #define GPS_NI_INTERFACE "gps-ni" 499 500 /** 501 * Name for the AGPS-RIL interface. 502 */ 503 #define AGPS_RIL_INTERFACE "agps_ril" 504 505 /** 506 * Name for the GPS_Geofencing interface. 507 */ 508 #define GPS_GEOFENCING_INTERFACE "gps_geofencing" 509 510 /** 511 * Name of the GPS Measurements interface. 512 */ 513 #define GPS_MEASUREMENT_INTERFACE "gps_measurement" 514 515 /** 516 * Name of the GPS navigation message interface. 517 */ 518 #define GPS_NAVIGATION_MESSAGE_INTERFACE "gps_navigation_message" 519 520 /** 521 * Name of the GNSS/GPS configuration interface. 522 */ 523 #define GNSS_CONFIGURATION_INTERFACE "gnss_configuration" 524 525 526 /** Represents a location. */ 527 typedef struct { 528 /** set to sizeof(GpsLocation) */ 529 size_t size; 530 /** Contains GpsLocationFlags bits. */ 531 uint16_t flags; 532 /** Represents latitude in degrees. */ 533 double latitude; 534 /** Represents longitude in degrees. */ 535 double longitude; 536 /** 537 * Represents altitude in meters above the WGS 84 reference ellipsoid. 538 */ 539 double altitude; 540 /** Represents speed in meters per second. */ 541 float speed; 542 /** Represents heading in degrees. */ 543 float bearing; 544 /** Represents expected accuracy in meters. */ 545 float accuracy; 546 /** Timestamp for the location fix. */ 547 GpsUtcTime timestamp; 548 } GpsLocation; 549 550 /** Represents the status. */ 551 typedef struct { 552 /** set to sizeof(GpsStatus) */ 553 size_t size; 554 GpsStatusValue status; 555 } GpsStatus; 556 557 /** 558 * Legacy struct to represents SV information. 559 * Deprecated, to be removed in the next Android release. 560 * Use GnssSvInfo instead. 561 */ 562 typedef struct { 563 /** set to sizeof(GpsSvInfo) */ 564 size_t size; 565 /** Pseudo-random number for the SV. */ 566 int prn; 567 /** Signal to noise ratio. */ 568 float snr; 569 /** Elevation of SV in degrees. */ 570 float elevation; 571 /** Azimuth of SV in degrees. */ 572 float azimuth; 573 } GpsSvInfo; 574 575 typedef struct { 576 /** set to sizeof(GnssSvInfo) */ 577 size_t size; 578 579 /** 580 * Pseudo-random number for the SV, or FCN/OSN number for Glonass. The 581 * distinction is made by looking at constellation field. Values should be 582 * in the range of: 583 * 584 * - GPS: 1-32 585 * - SBAS: 120-151, 183-192 586 * - GLONASS: 1-24, the orbital slot number (OSN), if known. Or, if not: 587 * 93-106, the frequency channel number (FCN) (-7 to +6) offset by + 100 588 * i.e. report an FCN of -7 as 93, FCN of 0 as 100, and FCN of +6 as 106. 589 * - QZSS: 193-200 590 * - Galileo: 1-36 591 * - Beidou: 1-37 592 */ 593 int16_t svid; 594 595 /** 596 * Defines the constellation of the given SV. Value should be one of those 597 * GNSS_CONSTELLATION_* constants 598 */ 599 GnssConstellationType constellation; 600 601 /** 602 * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. 603 * It contains the measured C/N0 value for the signal at the antenna port. 604 * 605 * This is a mandatory value. 606 */ 607 float c_n0_dbhz; 608 609 /** Elevation of SV in degrees. */ 610 float elevation; 611 612 /** Azimuth of SV in degrees. */ 613 float azimuth; 614 615 /** 616 * Contains additional data about the given SV. Value should be one of those 617 * GNSS_SV_FLAGS_* constants 618 */ 619 GnssSvFlags flags; 620 621 } GnssSvInfo; 622 623 /** 624 * Legacy struct to represents SV status. 625 * Deprecated, to be removed in the next Android release. 626 * Use GnssSvStatus instead. 627 */ 628 typedef struct { 629 /** set to sizeof(GpsSvStatus) */ 630 size_t size; 631 int num_svs; 632 GpsSvInfo sv_list[GPS_MAX_SVS]; 633 uint32_t ephemeris_mask; 634 uint32_t almanac_mask; 635 uint32_t used_in_fix_mask; 636 } GpsSvStatus; 637 638 /** 639 * Represents SV status. 640 */ 641 typedef struct { 642 /** set to sizeof(GnssSvStatus) */ 643 size_t size; 644 645 /** Number of GPS SVs currently visible, refers to the SVs stored in sv_list */ 646 int num_svs; 647 /** 648 * Pointer to an array of SVs information for all GNSS constellations, 649 * except GPS, which is reported using sv_list 650 */ 651 GnssSvInfo gnss_sv_list[GNSS_MAX_SVS]; 652 653 } GnssSvStatus; 654 655 /* CellID for 2G, 3G and LTE, used in AGPS. */ 656 typedef struct { 657 AGpsRefLocationType type; 658 /** Mobile Country Code. */ 659 uint16_t mcc; 660 /** Mobile Network Code .*/ 661 uint16_t mnc; 662 /** Location Area Code in 2G, 3G and LTE. In 3G lac is discarded. In LTE, 663 * lac is populated with tac, to ensure that we don't break old clients that 664 * might rely in the old (wrong) behavior. 665 */ 666 uint16_t lac; 667 /** Cell id in 2G. Utran Cell id in 3G. Cell Global Id EUTRA in LTE. */ 668 uint32_t cid; 669 /** Tracking Area Code in LTE. */ 670 uint16_t tac; 671 /** Physical Cell id in LTE (not used in 2G and 3G) */ 672 uint16_t pcid; 673 } AGpsRefLocationCellID; 674 675 typedef struct { 676 uint8_t mac[6]; 677 } AGpsRefLocationMac; 678 679 /** Represents ref locations */ 680 typedef struct { 681 AGpsRefLocationType type; 682 union { 683 AGpsRefLocationCellID cellID; 684 AGpsRefLocationMac mac; 685 } u; 686 } AGpsRefLocation; 687 688 /** 689 * Callback with location information. Can only be called from a thread created 690 * by create_thread_cb. 691 */ 692 typedef void (* gps_location_callback)(GpsLocation* location); 693 694 /** 695 * Callback with status information. Can only be called from a thread created by 696 * create_thread_cb. 697 */ 698 typedef void (* gps_status_callback)(GpsStatus* status); 699 700 /** 701 * Legacy callback with SV status information. 702 * Can only be called from a thread created by create_thread_cb. 703 * 704 * This callback is deprecated, and will be removed in the next release. Use 705 * gnss_sv_status_callback() instead. 706 */ 707 typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info); 708 709 /** 710 * Callback with SV status information. 711 * Can only be called from a thread created by create_thread_cb. 712 */ 713 typedef void (* gnss_sv_status_callback)(GnssSvStatus* sv_info); 714 715 /** 716 * Callback for reporting NMEA sentences. Can only be called from a thread 717 * created by create_thread_cb. 718 */ 719 typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length); 720 721 /** 722 * Callback to inform framework of the GPS engine's capabilities. Capability 723 * parameter is a bit field of GPS_CAPABILITY_* flags. 724 */ 725 typedef void (* gps_set_capabilities)(uint32_t capabilities); 726 727 /** 728 * Callback utility for acquiring the GPS wakelock. This can be used to prevent 729 * the CPU from suspending while handling GPS events. 730 */ 731 typedef void (* gps_acquire_wakelock)(); 732 733 /** Callback utility for releasing the GPS wakelock. */ 734 typedef void (* gps_release_wakelock)(); 735 736 /** Callback for requesting NTP time */ 737 typedef void (* gps_request_utc_time)(); 738 739 /** 740 * Callback for creating a thread that can call into the Java framework code. 741 * This must be used to create any threads that report events up to the 742 * framework. 743 */ 744 typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg); 745 746 /** 747 * Provides information about how new the underlying GPS/GNSS hardware and 748 * software is. 749 * 750 * This information will be available for Android Test Applications. If a GPS 751 * HAL does not provide this information, it will be considered "2015 or 752 * earlier". 753 * 754 * If a GPS HAL does provide this information, then newer years will need to 755 * meet newer CTS standards. E.g. if the date are 2016 or above, then N+ level 756 * GpsMeasurement support will be verified. 757 */ 758 typedef struct { 759 /** Set to sizeof(GnssSystemInfo) */ 760 size_t size; 761 /* year in which the last update was made to the underlying hardware/firmware 762 * used to capture GNSS signals, e.g. 2016 */ 763 uint16_t year_of_hw; 764 } GnssSystemInfo; 765 766 /** 767 * Callback to inform framework of the engine's hardware version information. 768 */ 769 typedef void (*gnss_set_system_info)(const GnssSystemInfo* info); 770 771 /** New GPS callback structure. */ 772 typedef struct { 773 /** set to sizeof(GpsCallbacks) */ 774 size_t size; 775 gps_location_callback location_cb; 776 gps_status_callback status_cb; 777 gps_sv_status_callback sv_status_cb; 778 gps_nmea_callback nmea_cb; 779 gps_set_capabilities set_capabilities_cb; 780 gps_acquire_wakelock acquire_wakelock_cb; 781 gps_release_wakelock release_wakelock_cb; 782 gps_create_thread create_thread_cb; 783 gps_request_utc_time request_utc_time_cb; 784 785 gnss_set_system_info set_system_info_cb; 786 gnss_sv_status_callback gnss_sv_status_cb; 787 } GpsCallbacks; 788 789 /** Represents the standard GPS interface. */ 790 typedef struct { 791 /** set to sizeof(GpsInterface) */ 792 size_t size; 793 /** 794 * Opens the interface and provides the callback routines 795 * to the implementation of this interface. 796 */ 797 int (*init)( GpsCallbacks* callbacks ); 798 799 /** Starts navigating. */ 800 int (*start)( void ); 801 802 /** Stops navigating. */ 803 int (*stop)( void ); 804 805 /** Closes the interface. */ 806 void (*cleanup)( void ); 807 808 /** Injects the current time. */ 809 int (*inject_time)(GpsUtcTime time, int64_t timeReference, 810 int uncertainty); 811 812 /** 813 * Injects current location from another location provider (typically cell 814 * ID). Latitude and longitude are measured in degrees expected accuracy is 815 * measured in meters 816 */ 817 int (*inject_location)(double latitude, double longitude, float accuracy); 818 819 /** 820 * Specifies that the next call to start will not use the 821 * information defined in the flags. GPS_DELETE_ALL is passed for 822 * a cold start. 823 */ 824 void (*delete_aiding_data)(GpsAidingData flags); 825 826 /** 827 * min_interval represents the time between fixes in milliseconds. 828 * preferred_accuracy represents the requested fix accuracy in meters. 829 * preferred_time represents the requested time to first fix in milliseconds. 830 * 831 * 'mode' parameter should be one of GPS_POSITION_MODE_MS_BASED 832 * or GPS_POSITION_MODE_STANDALONE. 833 * It is allowed by the platform (and it is recommended) to fallback to 834 * GPS_POSITION_MODE_MS_BASED if GPS_POSITION_MODE_MS_ASSISTED is passed in, and 835 * GPS_POSITION_MODE_MS_BASED is supported. 836 */ 837 int (*set_position_mode)(GpsPositionMode mode, GpsPositionRecurrence recurrence, 838 uint32_t min_interval, uint32_t preferred_accuracy, uint32_t preferred_time); 839 840 /** Get a pointer to extension information. */ 841 const void* (*get_extension)(const char* name); 842 } GpsInterface; 843 844 /** 845 * Callback to request the client to download XTRA data. The client should 846 * download XTRA data and inject it by calling inject_xtra_data(). Can only be 847 * called from a thread created by create_thread_cb. 848 */ 849 typedef void (* gps_xtra_download_request)(); 850 851 /** Callback structure for the XTRA interface. */ 852 typedef struct { 853 gps_xtra_download_request download_request_cb; 854 gps_create_thread create_thread_cb; 855 } GpsXtraCallbacks; 856 857 /** Extended interface for XTRA support. */ 858 typedef struct { 859 /** set to sizeof(GpsXtraInterface) */ 860 size_t size; 861 /** 862 * Opens the XTRA interface and provides the callback routines 863 * to the implementation of this interface. 864 */ 865 int (*init)( GpsXtraCallbacks* callbacks ); 866 /** Injects XTRA data into the GPS. */ 867 int (*inject_xtra_data)( char* data, int length ); 868 } GpsXtraInterface; 869 870 /** Extended interface for DEBUG support. */ 871 typedef struct { 872 /** set to sizeof(GpsDebugInterface) */ 873 size_t size; 874 875 /** 876 * This function should return any information that the native 877 * implementation wishes to include in a bugreport. 878 */ 879 size_t (*get_internal_state)(char* buffer, size_t bufferSize); 880 } GpsDebugInterface; 881 882 /* 883 * Represents the status of AGPS augmented to support IPv4 and IPv6. 884 */ 885 typedef struct { 886 /** set to sizeof(AGpsStatus) */ 887 size_t size; 888 889 AGpsType type; 890 AGpsStatusValue status; 891 892 /** 893 * Must be set to a valid IPv4 address if the field 'addr' contains an IPv4 894 * address, or set to INADDR_NONE otherwise. 895 */ 896 uint32_t ipaddr; 897 898 /** 899 * Must contain the IPv4 (AF_INET) or IPv6 (AF_INET6) address to report. 900 * Any other value of addr.ss_family will be rejected. 901 */ 902 struct sockaddr_storage addr; 903 } AGpsStatus; 904 905 /** 906 * Callback with AGPS status information. Can only be called from a thread 907 * created by create_thread_cb. 908 */ 909 typedef void (* agps_status_callback)(AGpsStatus* status); 910 911 /** Callback structure for the AGPS interface. */ 912 typedef struct { 913 agps_status_callback status_cb; 914 gps_create_thread create_thread_cb; 915 } AGpsCallbacks; 916 917 /** 918 * Extended interface for AGPS support, it is augmented to enable to pass 919 * extra APN data. 920 */ 921 typedef struct { 922 /** set to sizeof(AGpsInterface) */ 923 size_t size; 924 925 /** 926 * Opens the AGPS interface and provides the callback routines to the 927 * implementation of this interface. 928 */ 929 void (*init)(AGpsCallbacks* callbacks); 930 /** 931 * Deprecated. 932 * If the HAL supports AGpsInterface_v2 this API will not be used, see 933 * data_conn_open_with_apn_ip_type for more information. 934 */ 935 int (*data_conn_open)(const char* apn); 936 /** 937 * Notifies that the AGPS data connection has been closed. 938 */ 939 int (*data_conn_closed)(); 940 /** 941 * Notifies that a data connection is not available for AGPS. 942 */ 943 int (*data_conn_failed)(); 944 /** 945 * Sets the hostname and port for the AGPS server. 946 */ 947 int (*set_server)(AGpsType type, const char* hostname, int port); 948 949 /** 950 * Notifies that a data connection is available and sets the name of the 951 * APN, and its IP type, to be used for SUPL connections. 952 */ 953 int (*data_conn_open_with_apn_ip_type)( 954 const char* apn, 955 ApnIpType apnIpType); 956 } AGpsInterface; 957 958 /** Error codes associated with certificate operations */ 959 #define AGPS_CERTIFICATE_OPERATION_SUCCESS 0 960 #define AGPS_CERTIFICATE_ERROR_GENERIC -100 961 #define AGPS_CERTIFICATE_ERROR_TOO_MANY_CERTIFICATES -101 962 963 /** A data structure that represents an X.509 certificate using DER encoding */ 964 typedef struct { 965 size_t length; 966 u_char* data; 967 } DerEncodedCertificate; 968 969 /** 970 * A type definition for SHA1 Fingerprints used to identify X.509 Certificates 971 * The Fingerprint is a digest of the DER Certificate that uniquely identifies it. 972 */ 973 typedef struct { 974 u_char data[20]; 975 } Sha1CertificateFingerprint; 976 977 /** AGPS Interface to handle SUPL certificate operations */ 978 typedef struct { 979 /** set to sizeof(SuplCertificateInterface) */ 980 size_t size; 981 982 /** 983 * Installs a set of Certificates used for SUPL connections to the AGPS server. 984 * If needed the HAL should find out internally any certificates that need to be removed to 985 * accommodate the certificates to install. 986 * The certificates installed represent a full set of valid certificates needed to connect to 987 * AGPS SUPL servers. 988 * The list of certificates is required, and all must be available at the same time, when trying 989 * to establish a connection with the AGPS Server. 990 * 991 * Parameters: 992 * certificates - A pointer to an array of DER encoded certificates that are need to be 993 * installed in the HAL. 994 * length - The number of certificates to install. 995 * Returns: 996 * AGPS_CERTIFICATE_OPERATION_SUCCESS if the operation is completed successfully 997 * AGPS_CERTIFICATE_ERROR_TOO_MANY_CERTIFICATES if the HAL cannot store the number of 998 * certificates attempted to be installed, the state of the certificates stored should 999 * remain the same as before on this error case. 1000 * 1001 * IMPORTANT: 1002 * If needed the HAL should find out internally the set of certificates that need to be 1003 * removed to accommodate the certificates to install. 1004 */ 1005 int (*install_certificates) ( const DerEncodedCertificate* certificates, size_t length ); 1006 1007 /** 1008 * Notifies the HAL that a list of certificates used for SUPL connections are revoked. It is 1009 * expected that the given set of certificates is removed from the internal store of the HAL. 1010 * 1011 * Parameters: 1012 * fingerprints - A pointer to an array of SHA1 Fingerprints to identify the set of 1013 * certificates to revoke. 1014 * length - The number of fingerprints provided. 1015 * Returns: 1016 * AGPS_CERTIFICATE_OPERATION_SUCCESS if the operation is completed successfully. 1017 * 1018 * IMPORTANT: 1019 * If any of the certificates provided (through its fingerprint) is not known by the HAL, 1020 * it should be ignored and continue revoking/deleting the rest of them. 1021 */ 1022 int (*revoke_certificates) ( const Sha1CertificateFingerprint* fingerprints, size_t length ); 1023 } SuplCertificateInterface; 1024 1025 /** Represents an NI request */ 1026 typedef struct { 1027 /** set to sizeof(GpsNiNotification) */ 1028 size_t size; 1029 1030 /** 1031 * An ID generated by HAL to associate NI notifications and UI 1032 * responses 1033 */ 1034 int notification_id; 1035 1036 /** 1037 * An NI type used to distinguish different categories of NI 1038 * events, such as GPS_NI_TYPE_VOICE, GPS_NI_TYPE_UMTS_SUPL, ... 1039 */ 1040 GpsNiType ni_type; 1041 1042 /** 1043 * Notification/verification options, combinations of GpsNiNotifyFlags constants 1044 */ 1045 GpsNiNotifyFlags notify_flags; 1046 1047 /** 1048 * Timeout period to wait for user response. 1049 * Set to 0 for no time out limit. 1050 */ 1051 int timeout; 1052 1053 /** 1054 * Default response when time out. 1055 */ 1056 GpsUserResponseType default_response; 1057 1058 /** 1059 * Requestor ID 1060 */ 1061 char requestor_id[GPS_NI_SHORT_STRING_MAXLEN]; 1062 1063 /** 1064 * Notification message. It can also be used to store client_id in some cases 1065 */ 1066 char text[GPS_NI_LONG_STRING_MAXLEN]; 1067 1068 /** 1069 * Client name decoding scheme 1070 */ 1071 GpsNiEncodingType requestor_id_encoding; 1072 1073 /** 1074 * Client name decoding scheme 1075 */ 1076 GpsNiEncodingType text_encoding; 1077 1078 /** 1079 * A pointer to extra data. Format: 1080 * key_1 = value_1 1081 * key_2 = value_2 1082 */ 1083 char extras[GPS_NI_LONG_STRING_MAXLEN]; 1084 1085 } GpsNiNotification; 1086 1087 /** 1088 * Callback with NI notification. Can only be called from a thread created by 1089 * create_thread_cb. 1090 */ 1091 typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification); 1092 1093 /** GPS NI callback structure. */ 1094 typedef struct 1095 { 1096 /** 1097 * Sends the notification request from HAL to GPSLocationProvider. 1098 */ 1099 gps_ni_notify_callback notify_cb; 1100 gps_create_thread create_thread_cb; 1101 } GpsNiCallbacks; 1102 1103 /** 1104 * Extended interface for Network-initiated (NI) support. 1105 */ 1106 typedef struct 1107 { 1108 /** set to sizeof(GpsNiInterface) */ 1109 size_t size; 1110 1111 /** Registers the callbacks for HAL to use. */ 1112 void (*init) (GpsNiCallbacks *callbacks); 1113 1114 /** Sends a response to HAL. */ 1115 void (*respond) (int notif_id, GpsUserResponseType user_response); 1116 } GpsNiInterface; 1117 1118 struct gps_device_t { 1119 struct hw_device_t common; 1120 1121 /** 1122 * Set the provided lights to the provided values. 1123 * 1124 * Returns: 0 on succes, error code on failure. 1125 */ 1126 const GpsInterface* (*get_gps_interface)(struct gps_device_t* dev); 1127 }; 1128 1129 #define AGPS_RIL_REQUEST_SETID_IMSI (1<<0L) 1130 #define AGPS_RIL_REQUEST_SETID_MSISDN (1<<1L) 1131 1132 #define AGPS_RIL_REQUEST_REFLOC_CELLID (1<<0L) 1133 #define AGPS_RIL_REQUEST_REFLOC_MAC (1<<1L) 1134 1135 typedef void (*agps_ril_request_set_id)(uint32_t flags); 1136 typedef void (*agps_ril_request_ref_loc)(uint32_t flags); 1137 1138 typedef struct { 1139 agps_ril_request_set_id request_setid; 1140 agps_ril_request_ref_loc request_refloc; 1141 gps_create_thread create_thread_cb; 1142 } AGpsRilCallbacks; 1143 1144 /** Extended interface for AGPS_RIL support. */ 1145 typedef struct { 1146 /** set to sizeof(AGpsRilInterface) */ 1147 size_t size; 1148 /** 1149 * Opens the AGPS interface and provides the callback routines 1150 * to the implementation of this interface. 1151 */ 1152 void (*init)( AGpsRilCallbacks* callbacks ); 1153 1154 /** 1155 * Sets the reference location. 1156 */ 1157 void (*set_ref_location) (const AGpsRefLocation *agps_reflocation, size_t sz_struct); 1158 /** 1159 * Sets the set ID. 1160 */ 1161 void (*set_set_id) (AGpsSetIDType type, const char* setid); 1162 1163 /** 1164 * Send network initiated message. 1165 */ 1166 void (*ni_message) (uint8_t *msg, size_t len); 1167 1168 /** 1169 * Notify GPS of network status changes. 1170 * These parameters match values in the android.net.NetworkInfo class. 1171 */ 1172 void (*update_network_state) (int connected, int type, int roaming, const char* extra_info); 1173 1174 /** 1175 * Notify GPS of network status changes. 1176 * These parameters match values in the android.net.NetworkInfo class. 1177 */ 1178 void (*update_network_availability) (int avaiable, const char* apn); 1179 } AGpsRilInterface; 1180 1181 /** 1182 * GPS Geofence. 1183 * There are 3 states associated with a Geofence: Inside, Outside, Unknown. 1184 * There are 3 transitions: ENTERED, EXITED, UNCERTAIN. 1185 * 1186 * An example state diagram with confidence level: 95% and Unknown time limit 1187 * set as 30 secs is shown below. (confidence level and Unknown time limit are 1188 * explained latter) 1189 * ____________________________ 1190 * | Unknown (30 secs) | 1191 * """""""""""""""""""""""""""" 1192 * ^ | | ^ 1193 * UNCERTAIN| |ENTERED EXITED| |UNCERTAIN 1194 * | v v | 1195 * ________ EXITED _________ 1196 * | Inside | -----------> | Outside | 1197 * | | <----------- | | 1198 * """""""" ENTERED """"""""" 1199 * 1200 * Inside state: We are 95% confident that the user is inside the geofence. 1201 * Outside state: We are 95% confident that the user is outside the geofence 1202 * Unknown state: Rest of the time. 1203 * 1204 * The Unknown state is better explained with an example: 1205 * 1206 * __________ 1207 * | c| 1208 * | ___ | _______ 1209 * | |a| | | b | 1210 * | """ | """"""" 1211 * | | 1212 * """""""""" 1213 * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy 1214 * circle reported by the GPS subsystem. Now with regard to "b", the system is 1215 * confident that the user is outside. But with regard to "a" is not confident 1216 * whether it is inside or outside the geofence. If the accuracy remains the 1217 * same for a sufficient period of time, the UNCERTAIN transition would be 1218 * triggered with the state set to Unknown. If the accuracy improves later, an 1219 * appropriate transition should be triggered. This "sufficient period of time" 1220 * is defined by the parameter in the add_geofence_area API. 1221 * In other words, Unknown state can be interpreted as a state in which the 1222 * GPS subsystem isn't confident enough that the user is either inside or 1223 * outside the Geofence. It moves to Unknown state only after the expiry of the 1224 * timeout. 1225 * 1226 * The geofence callback needs to be triggered for the ENTERED and EXITED 1227 * transitions, when the GPS system is confident that the user has entered 1228 * (Inside state) or exited (Outside state) the Geofence. An implementation 1229 * which uses a value of 95% as the confidence is recommended. The callback 1230 * should be triggered only for the transitions requested by the 1231 * add_geofence_area call. 1232 * 1233 * Even though the diagram and explanation talks about states and transitions, 1234 * the callee is only interested in the transistions. The states are mentioned 1235 * here for illustrative purposes. 1236 * 1237 * Startup Scenario: When the device boots up, if an application adds geofences, 1238 * and then we get an accurate GPS location fix, it needs to trigger the 1239 * appropriate (ENTERED or EXITED) transition for every Geofence it knows about. 1240 * By default, all the Geofences will be in the Unknown state. 1241 * 1242 * When the GPS system is unavailable, gps_geofence_status_callback should be 1243 * called to inform the upper layers of the same. Similarly, when it becomes 1244 * available the callback should be called. This is a global state while the 1245 * UNKNOWN transition described above is per geofence. 1246 * 1247 * An important aspect to note is that users of this API (framework), will use 1248 * other subsystems like wifi, sensors, cell to handle Unknown case and 1249 * hopefully provide a definitive state transition to the third party 1250 * application. GPS Geofence will just be a signal indicating what the GPS 1251 * subsystem knows about the Geofence. 1252 * 1253 */ 1254 #define GPS_GEOFENCE_ENTERED (1<<0L) 1255 #define GPS_GEOFENCE_EXITED (1<<1L) 1256 #define GPS_GEOFENCE_UNCERTAIN (1<<2L) 1257 1258 #define GPS_GEOFENCE_UNAVAILABLE (1<<0L) 1259 #define GPS_GEOFENCE_AVAILABLE (1<<1L) 1260 1261 #define GPS_GEOFENCE_OPERATION_SUCCESS 0 1262 #define GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES -100 1263 #define GPS_GEOFENCE_ERROR_ID_EXISTS -101 1264 #define GPS_GEOFENCE_ERROR_ID_UNKNOWN -102 1265 #define GPS_GEOFENCE_ERROR_INVALID_TRANSITION -103 1266 #define GPS_GEOFENCE_ERROR_GENERIC -149 1267 1268 /** 1269 * The callback associated with the geofence. 1270 * Parameters: 1271 * geofence_id - The id associated with the add_geofence_area. 1272 * location - The current GPS location. 1273 * transition - Can be one of GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED, 1274 * GPS_GEOFENCE_UNCERTAIN. 1275 * timestamp - Timestamp when the transition was detected. 1276 * 1277 * The callback should only be called when the caller is interested in that 1278 * particular transition. For instance, if the caller is interested only in 1279 * ENTERED transition, then the callback should NOT be called with the EXITED 1280 * transition. 1281 * 1282 * IMPORTANT: If a transition is triggered resulting in this callback, the GPS 1283 * subsystem will wake up the application processor, if its in suspend state. 1284 */ 1285 typedef void (*gps_geofence_transition_callback) (int32_t geofence_id, GpsLocation* location, 1286 int32_t transition, GpsUtcTime timestamp); 1287 1288 /** 1289 * The callback associated with the availability of the GPS system for geofencing 1290 * monitoring. If the GPS system determines that it cannot monitor geofences 1291 * because of lack of reliability or unavailability of the GPS signals, it will 1292 * call this callback with GPS_GEOFENCE_UNAVAILABLE parameter. 1293 * 1294 * Parameters: 1295 * status - GPS_GEOFENCE_UNAVAILABLE or GPS_GEOFENCE_AVAILABLE. 1296 * last_location - Last known location. 1297 */ 1298 typedef void (*gps_geofence_status_callback) (int32_t status, GpsLocation* last_location); 1299 1300 /** 1301 * The callback associated with the add_geofence call. 1302 * 1303 * Parameter: 1304 * geofence_id - Id of the geofence. 1305 * status - GPS_GEOFENCE_OPERATION_SUCCESS 1306 * GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES - geofence limit has been reached. 1307 * GPS_GEOFENCE_ERROR_ID_EXISTS - geofence with id already exists 1308 * GPS_GEOFENCE_ERROR_INVALID_TRANSITION - the monitorTransition contains an 1309 * invalid transition 1310 * GPS_GEOFENCE_ERROR_GENERIC - for other errors. 1311 */ 1312 typedef void (*gps_geofence_add_callback) (int32_t geofence_id, int32_t status); 1313 1314 /** 1315 * The callback associated with the remove_geofence call. 1316 * 1317 * Parameter: 1318 * geofence_id - Id of the geofence. 1319 * status - GPS_GEOFENCE_OPERATION_SUCCESS 1320 * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id 1321 * GPS_GEOFENCE_ERROR_GENERIC for others. 1322 */ 1323 typedef void (*gps_geofence_remove_callback) (int32_t geofence_id, int32_t status); 1324 1325 1326 /** 1327 * The callback associated with the pause_geofence call. 1328 * 1329 * Parameter: 1330 * geofence_id - Id of the geofence. 1331 * status - GPS_GEOFENCE_OPERATION_SUCCESS 1332 * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id 1333 * GPS_GEOFENCE_ERROR_INVALID_TRANSITION - 1334 * when monitor_transitions is invalid 1335 * GPS_GEOFENCE_ERROR_GENERIC for others. 1336 */ 1337 typedef void (*gps_geofence_pause_callback) (int32_t geofence_id, int32_t status); 1338 1339 /** 1340 * The callback associated with the resume_geofence call. 1341 * 1342 * Parameter: 1343 * geofence_id - Id of the geofence. 1344 * status - GPS_GEOFENCE_OPERATION_SUCCESS 1345 * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id 1346 * GPS_GEOFENCE_ERROR_GENERIC for others. 1347 */ 1348 typedef void (*gps_geofence_resume_callback) (int32_t geofence_id, int32_t status); 1349 1350 typedef struct { 1351 gps_geofence_transition_callback geofence_transition_callback; 1352 gps_geofence_status_callback geofence_status_callback; 1353 gps_geofence_add_callback geofence_add_callback; 1354 gps_geofence_remove_callback geofence_remove_callback; 1355 gps_geofence_pause_callback geofence_pause_callback; 1356 gps_geofence_resume_callback geofence_resume_callback; 1357 gps_create_thread create_thread_cb; 1358 } GpsGeofenceCallbacks; 1359 1360 /** Extended interface for GPS_Geofencing support */ 1361 typedef struct { 1362 /** set to sizeof(GpsGeofencingInterface) */ 1363 size_t size; 1364 1365 /** 1366 * Opens the geofence interface and provides the callback routines 1367 * to the implementation of this interface. 1368 */ 1369 void (*init)( GpsGeofenceCallbacks* callbacks ); 1370 1371 /** 1372 * Add a geofence area. This api currently supports circular geofences. 1373 * Parameters: 1374 * geofence_id - The id for the geofence. If a geofence with this id 1375 * already exists, an error value (GPS_GEOFENCE_ERROR_ID_EXISTS) 1376 * should be returned. 1377 * latitude, longtitude, radius_meters - The lat, long and radius 1378 * (in meters) for the geofence 1379 * last_transition - The current state of the geofence. For example, if 1380 * the system already knows that the user is inside the geofence, 1381 * this will be set to GPS_GEOFENCE_ENTERED. In most cases, it 1382 * will be GPS_GEOFENCE_UNCERTAIN. 1383 * monitor_transition - Which transitions to monitor. Bitwise OR of 1384 * GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and 1385 * GPS_GEOFENCE_UNCERTAIN. 1386 * notification_responsiveness_ms - Defines the best-effort description 1387 * of how soon should the callback be called when the transition 1388 * associated with the Geofence is triggered. For instance, if set 1389 * to 1000 millseconds with GPS_GEOFENCE_ENTERED, the callback 1390 * should be called 1000 milliseconds within entering the geofence. 1391 * This parameter is defined in milliseconds. 1392 * NOTE: This is not to be confused with the rate that the GPS is 1393 * polled at. It is acceptable to dynamically vary the rate of 1394 * sampling the GPS for power-saving reasons; thus the rate of 1395 * sampling may be faster or slower than this. 1396 * unknown_timer_ms - The time limit after which the UNCERTAIN transition 1397 * should be triggered. This parameter is defined in milliseconds. 1398 * See above for a detailed explanation. 1399 */ 1400 void (*add_geofence_area) (int32_t geofence_id, double latitude, double longitude, 1401 double radius_meters, int last_transition, int monitor_transitions, 1402 int notification_responsiveness_ms, int unknown_timer_ms); 1403 1404 /** 1405 * Pause monitoring a particular geofence. 1406 * Parameters: 1407 * geofence_id - The id for the geofence. 1408 */ 1409 void (*pause_geofence) (int32_t geofence_id); 1410 1411 /** 1412 * Resume monitoring a particular geofence. 1413 * Parameters: 1414 * geofence_id - The id for the geofence. 1415 * monitor_transitions - Which transitions to monitor. Bitwise OR of 1416 * GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and 1417 * GPS_GEOFENCE_UNCERTAIN. 1418 * This supersedes the value associated provided in the 1419 * add_geofence_area call. 1420 */ 1421 void (*resume_geofence) (int32_t geofence_id, int monitor_transitions); 1422 1423 /** 1424 * Remove a geofence area. After the function returns, no notifications 1425 * should be sent. 1426 * Parameter: 1427 * geofence_id - The id for the geofence. 1428 */ 1429 void (*remove_geofence_area) (int32_t geofence_id); 1430 } GpsGeofencingInterface; 1431 1432 /** 1433 * Legacy struct to represent an estimate of the GPS clock time. 1434 * Deprecated, to be removed in the next Android release. 1435 * Use GnssClock instead. 1436 */ 1437 typedef struct { 1438 /** set to sizeof(GpsClock) */ 1439 size_t size; 1440 GpsClockFlags flags; 1441 int16_t leap_second; 1442 GpsClockType type; 1443 int64_t time_ns; 1444 double time_uncertainty_ns; 1445 int64_t full_bias_ns; 1446 double bias_ns; 1447 double bias_uncertainty_ns; 1448 double drift_nsps; 1449 double drift_uncertainty_nsps; 1450 } GpsClock; 1451 1452 /** 1453 * Represents an estimate of the GPS clock time. 1454 */ 1455 typedef struct { 1456 /** set to sizeof(GnssClock) */ 1457 size_t size; 1458 1459 /** 1460 * A set of flags indicating the validity of the fields in this data 1461 * structure. 1462 */ 1463 GnssClockFlags flags; 1464 1465 /** 1466 * Leap second data. 1467 * The sign of the value is defined by the following equation: 1468 * utc_time_ns = time_ns - (full_bias_ns + bias_ns) - leap_second * 1469 * 1,000,000,000 1470 * 1471 * If the data is available 'flags' must contain GNSS_CLOCK_HAS_LEAP_SECOND. 1472 */ 1473 int16_t leap_second; 1474 1475 /** 1476 * The GNSS receiver internal clock value. This is the local hardware clock 1477 * value. 1478 * 1479 * For local hardware clock, this value is expected to be monotonically 1480 * increasing while the hardware clock remains power on. (For the case of a 1481 * HW clock that is not continuously on, see the 1482 * hw_clock_discontinuity_count field). The receiver's estimate of GPS time 1483 * can be derived by substracting the sum of full_bias_ns and bias_ns (when 1484 * available) from this value. 1485 * 1486 * This GPS time is expected to be the best estimate of current GPS time 1487 * that GNSS receiver can achieve. 1488 * 1489 * Sub-nanosecond accuracy can be provided by means of the 'bias_ns' field. 1490 * The value contains the 'time uncertainty' in it. 1491 * 1492 * This field is mandatory. 1493 */ 1494 int64_t time_ns; 1495 1496 /** 1497 * 1-Sigma uncertainty associated with the clock's time in nanoseconds. 1498 * The uncertainty is represented as an absolute (single sided) value. 1499 * 1500 * If the data is available, 'flags' must contain 1501 * GNSS_CLOCK_HAS_TIME_UNCERTAINTY. This value is effectively zero (it is 1502 * the reference local clock, by which all other times and time 1503 * uncertainties are measured.) (And thus this field can be not provided, 1504 * per GNSS_CLOCK_HAS_TIME_UNCERTAINTY flag, or provided & set to 0.) 1505 */ 1506 double time_uncertainty_ns; 1507 1508 /** 1509 * The difference between hardware clock ('time' field) inside GPS receiver 1510 * and the true GPS time since 0000Z, January 6, 1980, in nanoseconds. 1511 * 1512 * The sign of the value is defined by the following equation: 1513 * local estimate of GPS time = time_ns - (full_bias_ns + bias_ns) 1514 * 1515 * This value is mandatory if the receiver has estimated GPS time. If the 1516 * computed time is for a non-GPS constellation, the time offset of that 1517 * constellation to GPS has to be applied to fill this value. The error 1518 * estimate for the sum of this and the bias_ns is the bias_uncertainty_ns, 1519 * and the caller is responsible for using this uncertainty (it can be very 1520 * large before the GPS time has been solved for.) If the data is available 1521 * 'flags' must contain GNSS_CLOCK_HAS_FULL_BIAS. 1522 */ 1523 int64_t full_bias_ns; 1524 1525 /** 1526 * Sub-nanosecond bias. 1527 * The error estimate for the sum of this and the full_bias_ns is the 1528 * bias_uncertainty_ns 1529 * 1530 * If the data is available 'flags' must contain GNSS_CLOCK_HAS_BIAS. If GPS 1531 * has computed a position fix. This value is mandatory if the receiver has 1532 * estimated GPS time. 1533 */ 1534 double bias_ns; 1535 1536 /** 1537 * 1-Sigma uncertainty associated with the local estimate of GPS time (clock 1538 * bias) in nanoseconds. The uncertainty is represented as an absolute 1539 * (single sided) value. 1540 * 1541 * If the data is available 'flags' must contain 1542 * GNSS_CLOCK_HAS_BIAS_UNCERTAINTY. This value is mandatory if the receiver 1543 * has estimated GPS time. 1544 */ 1545 double bias_uncertainty_ns; 1546 1547 /** 1548 * The clock's drift in nanoseconds (per second). 1549 * 1550 * A positive value means that the frequency is higher than the nominal 1551 * frequency, and that the (full_bias_ns + bias_ns) is growing more positive 1552 * over time. 1553 * 1554 * The value contains the 'drift uncertainty' in it. 1555 * If the data is available 'flags' must contain GNSS_CLOCK_HAS_DRIFT. 1556 * 1557 * This value is mandatory if the receiver has estimated GNSS time 1558 */ 1559 double drift_nsps; 1560 1561 /** 1562 * 1-Sigma uncertainty associated with the clock's drift in nanoseconds (per second). 1563 * The uncertainty is represented as an absolute (single sided) value. 1564 * 1565 * If the data is available 'flags' must contain 1566 * GNSS_CLOCK_HAS_DRIFT_UNCERTAINTY. If GPS has computed a position fix this 1567 * field is mandatory and must be populated. 1568 */ 1569 double drift_uncertainty_nsps; 1570 1571 /** 1572 * When there are any discontinuities in the HW clock, this field is 1573 * mandatory. 1574 * 1575 * A "discontinuity" is meant to cover the case of a switch from one source 1576 * of clock to another. A single free-running crystal oscillator (XO) 1577 * should generally not have any discontinuities, and this can be set and 1578 * left at 0. 1579 * 1580 * If, however, the time_ns value (HW clock) is derived from a composite of 1581 * sources, that is not as smooth as a typical XO, or is otherwise stopped & 1582 * restarted, then this value shall be incremented each time a discontinuity 1583 * occurs. (E.g. this value may start at zero at device boot-up and 1584 * increment each time there is a change in clock continuity. In the 1585 * unlikely event that this value reaches full scale, rollover (not 1586 * clamping) is required, such that this value continues to change, during 1587 * subsequent discontinuity events.) 1588 * 1589 * While this number stays the same, between GnssClock reports, it can be 1590 * safely assumed that the time_ns value has been running continuously, e.g. 1591 * derived from a single, high quality clock (XO like, or better, that's 1592 * typically used during continuous GNSS signal sampling.) 1593 * 1594 * It is expected, esp. during periods where there are few GNSS signals 1595 * available, that the HW clock be discontinuity-free as long as possible, 1596 * as this avoids the need to use (waste) a GNSS measurement to fully 1597 * re-solve for the GPS clock bias and drift, when using the accompanying 1598 * measurements, from consecutive GnssData reports. 1599 */ 1600 uint32_t hw_clock_discontinuity_count; 1601 1602 } GnssClock; 1603 1604 /** 1605 * Legacy struct to represent a GPS Measurement, it contains raw and computed 1606 * information. 1607 * Deprecated, to be removed in the next Android release. 1608 * Use GnssMeasurement instead. 1609 */ 1610 typedef struct { 1611 /** set to sizeof(GpsMeasurement) */ 1612 size_t size; 1613 GpsMeasurementFlags flags; 1614 int8_t prn; 1615 double time_offset_ns; 1616 GpsMeasurementState state; 1617 int64_t received_gps_tow_ns; 1618 int64_t received_gps_tow_uncertainty_ns; 1619 double c_n0_dbhz; 1620 double pseudorange_rate_mps; 1621 double pseudorange_rate_uncertainty_mps; 1622 GpsAccumulatedDeltaRangeState accumulated_delta_range_state; 1623 double accumulated_delta_range_m; 1624 double accumulated_delta_range_uncertainty_m; 1625 double pseudorange_m; 1626 double pseudorange_uncertainty_m; 1627 double code_phase_chips; 1628 double code_phase_uncertainty_chips; 1629 float carrier_frequency_hz; 1630 int64_t carrier_cycles; 1631 double carrier_phase; 1632 double carrier_phase_uncertainty; 1633 GpsLossOfLock loss_of_lock; 1634 int32_t bit_number; 1635 int16_t time_from_last_bit_ms; 1636 double doppler_shift_hz; 1637 double doppler_shift_uncertainty_hz; 1638 GpsMultipathIndicator multipath_indicator; 1639 double snr_db; 1640 double elevation_deg; 1641 double elevation_uncertainty_deg; 1642 double azimuth_deg; 1643 double azimuth_uncertainty_deg; 1644 bool used_in_fix; 1645 } GpsMeasurement; 1646 1647 /** 1648 * Represents a GNSS Measurement, it contains raw and computed information. 1649 * 1650 * Independence - All signal measurement information (e.g. sv_time, 1651 * pseudorange_rate, multipath_indicator) reported in this struct should be 1652 * based on GNSS signal measurements only. You may not synthesize measurements 1653 * by calculating or reporting expected measurements based on known or estimated 1654 * position, velocity, or time. 1655 */ 1656 typedef struct { 1657 /** set to sizeof(GpsMeasurement) */ 1658 size_t size; 1659 1660 /** A set of flags indicating the validity of the fields in this data structure. */ 1661 GnssMeasurementFlags flags; 1662 1663 /** 1664 * Satellite vehicle ID number, as defined in GnssSvInfo::svid 1665 * This is a mandatory value. 1666 */ 1667 int16_t svid; 1668 1669 /** 1670 * Defines the constellation of the given SV. Value should be one of those 1671 * GNSS_CONSTELLATION_* constants 1672 */ 1673 GnssConstellationType constellation; 1674 1675 /** 1676 * Time offset at which the measurement was taken in nanoseconds. 1677 * The reference receiver's time is specified by GpsData::clock::time_ns and should be 1678 * interpreted in the same way as indicated by GpsClock::type. 1679 * 1680 * The sign of time_offset_ns is given by the following equation: 1681 * measurement time = GpsClock::time_ns + time_offset_ns 1682 * 1683 * It provides an individual time-stamp for the measurement, and allows sub-nanosecond accuracy. 1684 * This is a mandatory value. 1685 */ 1686 double time_offset_ns; 1687 1688 /** 1689 * Per satellite sync state. It represents the current sync state for the associated satellite. 1690 * Based on the sync state, the 'received GPS tow' field should be interpreted accordingly. 1691 * 1692 * This is a mandatory value. 1693 */ 1694 GnssMeasurementState state; 1695 1696 /** 1697 * The received GNSS Time-of-Week at the measurement time, in nanoseconds. 1698 * Ensure that this field is independent (see comment at top of 1699 * GnssMeasurement struct.) 1700 * 1701 * For GPS & QZSS, this is: 1702 * Received GPS Time-of-Week at the measurement time, in nanoseconds. 1703 * The value is relative to the beginning of the current GPS week. 1704 * 1705 * Given the highest sync state that can be achieved, per each satellite, valid range 1706 * for this field can be: 1707 * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN 1708 * C/A code lock : [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set 1709 * Bit sync : [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set 1710 * Subframe sync : [ 0 6s ] : GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC is set 1711 * TOW decoded : [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set 1712 * 1713 * Note well: if there is any ambiguity in integer millisecond, 1714 * GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS should be set accordingly, in the 'state' field. 1715 * 1716 * This value must be populated if 'state' != GNSS_MEASUREMENT_STATE_UNKNOWN. 1717 * 1718 * For Glonass, this is: 1719 * Received Glonass time of day, at the measurement time in nanoseconds. 1720 * 1721 * Given the highest sync state that can be achieved, per each satellite, valid range for 1722 * this field can be: 1723 * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN 1724 * C/A code lock : [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set 1725 * Symbol sync : [ 0 10ms ] : GNSS_MEASUREMENT_STATE_SYMBOL_SYNC is set 1726 * Bit sync : [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set 1727 * String sync : [ 0 2s ] : GNSS_MEASUREMENT_STATE_GLO_STRING_SYNC is set 1728 * Time of day : [ 0 1day ] : GNSS_MEASUREMENT_STATE_GLO_TOD_DECODED is set 1729 * 1730 * For Beidou, this is: 1731 * Received Beidou time of week, at the measurement time in nanoseconds. 1732 * 1733 * Given the highest sync state that can be achieved, per each satellite, valid range for 1734 * this field can be: 1735 * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN 1736 * C/A code lock: [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set 1737 * Bit sync (D2): [ 0 2ms ] : GNSS_MEASUREMENT_STATE_BDS_D2_BIT_SYNC is set 1738 * Bit sync (D1): [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set 1739 * Subframe (D2): [ 0 0.6s ] : GNSS_MEASUREMENT_STATE_BDS_D2_SUBFRAME_SYNC is set 1740 * Subframe (D1): [ 0 6s ] : GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC is set 1741 * Time of week : [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set 1742 * 1743 * For Galileo, this is: 1744 * Received Galileo time of week, at the measurement time in nanoseconds. 1745 * 1746 * E1BC code lock : [ 0 4ms ] : GNSS_MEASUREMENT_STATE_GAL_E1BC_CODE_LOCK is set 1747 * E1C 2nd code lock: [ 0 100ms ] : 1748 * GNSS_MEASUREMENT_STATE_GAL_E1C_2ND_CODE_LOCK is set 1749 * 1750 * E1B page : [ 0 2s ] : GNSS_MEASUREMENT_STATE_GAL_E1B_PAGE_SYNC is set 1751 * Time of week: [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set 1752 * 1753 * For SBAS, this is: 1754 * Received SBAS time, at the measurement time in nanoseconds. 1755 * 1756 * Given the highest sync state that can be achieved, per each satellite, 1757 * valid range for this field can be: 1758 * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN 1759 * C/A code lock: [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set 1760 * Symbol sync : [ 0 2ms ] : GNSS_MEASUREMENT_STATE_SYMBOL_SYNC is set 1761 * Message : [ 0 1s ] : GNSS_MEASUREMENT_STATE_SBAS_SYNC is set 1762 */ 1763 int64_t received_sv_time_in_ns; 1764 1765 /** 1766 * 1-Sigma uncertainty of the Received GPS Time-of-Week in nanoseconds. 1767 * 1768 * This value must be populated if 'state' != GPS_MEASUREMENT_STATE_UNKNOWN. 1769 */ 1770 int64_t received_sv_time_uncertainty_in_ns; 1771 1772 /** 1773 * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. 1774 * It contains the measured C/N0 value for the signal at the antenna port. 1775 * 1776 * This is a mandatory value. 1777 */ 1778 double c_n0_dbhz; 1779 1780 /** 1781 * Pseudorange rate at the timestamp in m/s. The correction of a given 1782 * Pseudorange Rate value includes corrections for receiver and satellite 1783 * clock frequency errors. Ensure that this field is independent (see 1784 * comment at top of GnssMeasurement struct.) 1785 * 1786 * It is mandatory to provide the 'uncorrected' 'pseudorange rate', and provide GpsClock's 1787 * 'drift' field as well (When providing the uncorrected pseudorange rate, do not apply the 1788 * corrections described above.) 1789 * 1790 * The value includes the 'pseudorange rate uncertainty' in it. 1791 * A positive 'uncorrected' value indicates that the SV is moving away from the receiver. 1792 * 1793 * The sign of the 'uncorrected' 'pseudorange rate' and its relation to the sign of 'doppler 1794 * shift' is given by the equation: 1795 * pseudorange rate = -k * doppler shift (where k is a constant) 1796 * 1797 * This should be the most accurate pseudorange rate available, based on 1798 * fresh signal measurements from this channel. 1799 * 1800 * It is mandatory that this value be provided at typical carrier phase PRR 1801 * quality (few cm/sec per second of uncertainty, or better) - when signals 1802 * are sufficiently strong & stable, e.g. signals from a GPS simulator at >= 1803 * 35 dB-Hz. 1804 */ 1805 double pseudorange_rate_mps; 1806 1807 /** 1808 * 1-Sigma uncertainty of the pseudorange_rate_mps. 1809 * The uncertainty is represented as an absolute (single sided) value. 1810 * 1811 * This is a mandatory value. 1812 */ 1813 double pseudorange_rate_uncertainty_mps; 1814 1815 /** 1816 * Accumulated delta range's state. It indicates whether ADR is reset or there is a cycle slip 1817 * (indicating loss of lock). 1818 * 1819 * This is a mandatory value. 1820 */ 1821 GnssAccumulatedDeltaRangeState accumulated_delta_range_state; 1822 1823 /** 1824 * Accumulated delta range since the last channel reset in meters. 1825 * A positive value indicates that the SV is moving away from the receiver. 1826 * 1827 * The sign of the 'accumulated delta range' and its relation to the sign of 'carrier phase' 1828 * is given by the equation: 1829 * accumulated delta range = -k * carrier phase (where k is a constant) 1830 * 1831 * This value must be populated if 'accumulated delta range state' != GPS_ADR_STATE_UNKNOWN. 1832 * However, it is expected that the data is only accurate when: 1833 * 'accumulated delta range state' == GPS_ADR_STATE_VALID. 1834 */ 1835 double accumulated_delta_range_m; 1836 1837 /** 1838 * 1-Sigma uncertainty of the accumulated delta range in meters. 1839 * This value must be populated if 'accumulated delta range state' != GPS_ADR_STATE_UNKNOWN. 1840 */ 1841 double accumulated_delta_range_uncertainty_m; 1842 1843 /** 1844 * Carrier frequency at which codes and messages are modulated, it can be L1 or L2. 1845 * If the field is not set, the carrier frequency is assumed to be L1. 1846 * 1847 * If the data is available, 'flags' must contain 1848 * GNSS_MEASUREMENT_HAS_CARRIER_FREQUENCY. 1849 */ 1850 float carrier_frequency_hz; 1851 1852 /** 1853 * The number of full carrier cycles between the satellite and the receiver. 1854 * The reference frequency is given by the field 'carrier_frequency_hz'. 1855 * Indications of possible cycle slips and resets in the accumulation of 1856 * this value can be inferred from the accumulated_delta_range_state flags. 1857 * 1858 * If the data is available, 'flags' must contain 1859 * GNSS_MEASUREMENT_HAS_CARRIER_CYCLES. 1860 */ 1861 int64_t carrier_cycles; 1862 1863 /** 1864 * The RF phase detected by the receiver, in the range [0.0, 1.0]. 1865 * This is usually the fractional part of the complete carrier phase measurement. 1866 * 1867 * The reference frequency is given by the field 'carrier_frequency_hz'. 1868 * The value contains the 'carrier-phase uncertainty' in it. 1869 * 1870 * If the data is available, 'flags' must contain 1871 * GNSS_MEASUREMENT_HAS_CARRIER_PHASE. 1872 */ 1873 double carrier_phase; 1874 1875 /** 1876 * 1-Sigma uncertainty of the carrier-phase. 1877 * If the data is available, 'flags' must contain 1878 * GNSS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY. 1879 */ 1880 double carrier_phase_uncertainty; 1881 1882 /** 1883 * An enumeration that indicates the 'multipath' state of the event. 1884 * 1885 * The multipath Indicator is intended to report the presence of overlapping 1886 * signals that manifest as distorted correlation peaks. 1887 * 1888 * - if there is a distorted correlation peak shape, report that multipath 1889 * is GNSS_MULTIPATH_INDICATOR_PRESENT. 1890 * - if there is not a distorted correlation peak shape, report 1891 * GNSS_MULTIPATH_INDICATOR_NOT_PRESENT 1892 * - if signals are too weak to discern this information, report 1893 * GNSS_MULTIPATH_INDICATOR_UNKNOWN 1894 * 1895 * Example: when doing the standardized overlapping Multipath Performance 1896 * test (3GPP TS 34.171) the Multipath indicator should report 1897 * GNSS_MULTIPATH_INDICATOR_PRESENT for those signals that are tracked, and 1898 * contain multipath, and GNSS_MULTIPATH_INDICATOR_NOT_PRESENT for those 1899 * signals that are tracked and do not contain multipath. 1900 */ 1901 GnssMultipathIndicator multipath_indicator; 1902 1903 /** 1904 * Signal-to-noise ratio at correlator output in dB. 1905 * If the data is available, 'flags' must contain GNSS_MEASUREMENT_HAS_SNR. 1906 * This is the power ratio of the "correlation peak height above the 1907 * observed noise floor" to "the noise RMS". 1908 */ 1909 double snr_db; 1910 } GnssMeasurement; 1911 1912 /** 1913 * Legacy struct to represents a reading of GPS measurements. 1914 * Deprecated, to be removed in the next Android release. 1915 * Use GnssData instead. 1916 */ 1917 typedef struct { 1918 /** set to sizeof(GpsData) */ 1919 size_t size; 1920 size_t measurement_count; 1921 GpsMeasurement measurements[GPS_MAX_MEASUREMENT]; 1922 1923 /** The GPS clock time reading. */ 1924 GpsClock clock; 1925 } GpsData; 1926 1927 /** 1928 * Represents a reading of GNSS measurements. For devices where GnssSystemInfo's 1929 * year_of_hw is set to 2016+, it is mandatory that these be provided, on 1930 * request, when the GNSS receiver is searching/tracking signals. 1931 * 1932 * - Reporting of GPS constellation measurements is mandatory. 1933 * - Reporting of all tracked constellations are encouraged. 1934 */ 1935 typedef struct { 1936 /** set to sizeof(GnssData) */ 1937 size_t size; 1938 1939 /** Number of measurements. */ 1940 size_t measurement_count; 1941 1942 /** The array of measurements. */ 1943 GnssMeasurement measurements[GNSS_MAX_MEASUREMENT]; 1944 1945 /** The GPS clock time reading. */ 1946 GnssClock clock; 1947 } GnssData; 1948 1949 /** 1950 * The legacy callback for to report measurements from the HAL. 1951 * 1952 * This callback is deprecated, and will be removed in the next release. Use 1953 * gnss_measurement_callback() instead. 1954 * 1955 * Parameters: 1956 * data - A data structure containing the measurements. 1957 */ 1958 typedef void (*gps_measurement_callback) (GpsData* data); 1959 1960 /** 1961 * The callback for to report measurements from the HAL. 1962 * 1963 * Parameters: 1964 * data - A data structure containing the measurements. 1965 */ 1966 typedef void (*gnss_measurement_callback) (GnssData* data); 1967 1968 typedef struct { 1969 /** set to sizeof(GpsMeasurementCallbacks) */ 1970 size_t size; 1971 gps_measurement_callback measurement_callback; 1972 gnss_measurement_callback gnss_measurement_callback; 1973 } GpsMeasurementCallbacks; 1974 1975 #define GPS_MEASUREMENT_OPERATION_SUCCESS 0 1976 #define GPS_MEASUREMENT_ERROR_ALREADY_INIT -100 1977 #define GPS_MEASUREMENT_ERROR_GENERIC -101 1978 1979 /** 1980 * Extended interface for GPS Measurements support. 1981 */ 1982 typedef struct { 1983 /** Set to sizeof(GpsMeasurementInterface) */ 1984 size_t size; 1985 1986 /** 1987 * Initializes the interface and registers the callback routines with the HAL. 1988 * After a successful call to 'init' the HAL must begin to provide updates at its own phase. 1989 * 1990 * Status: 1991 * GPS_MEASUREMENT_OPERATION_SUCCESS 1992 * GPS_MEASUREMENT_ERROR_ALREADY_INIT - if a callback has already been registered without a 1993 * corresponding call to 'close' 1994 * GPS_MEASUREMENT_ERROR_GENERIC - if any other error occurred, it is expected that the HAL 1995 * will not generate any updates upon returning this error code. 1996 */ 1997 int (*init) (GpsMeasurementCallbacks* callbacks); 1998 1999 /** 2000 * Stops updates from the HAL, and unregisters the callback routines. 2001 * After a call to stop, the previously registered callbacks must be considered invalid by the 2002 * HAL. 2003 * If stop is invoked without a previous 'init', this function should perform no work. 2004 */ 2005 void (*close) (); 2006 2007 } GpsMeasurementInterface; 2008 2009 /** 2010 * Legacy struct to represents a GPS navigation message (or a fragment of it). 2011 * Deprecated, to be removed in the next Android release. 2012 * Use GnssNavigationMessage instead. 2013 */ 2014 typedef struct { 2015 /** set to sizeof(GpsNavigationMessage) */ 2016 size_t size; 2017 int8_t prn; 2018 GpsNavigationMessageType type; 2019 NavigationMessageStatus status; 2020 int16_t message_id; 2021 int16_t submessage_id; 2022 size_t data_length; 2023 uint8_t* data; 2024 } GpsNavigationMessage; 2025 2026 /** Represents a GPS navigation message (or a fragment of it). */ 2027 typedef struct { 2028 /** set to sizeof(GnssNavigationMessage) */ 2029 size_t size; 2030 2031 /** 2032 * Satellite vehicle ID number, as defined in GnssSvInfo::svid 2033 * This is a mandatory value. 2034 */ 2035 int16_t svid; 2036 2037 /** 2038 * The type of message contained in the structure. 2039 * This is a mandatory value. 2040 */ 2041 GnssNavigationMessageType type; 2042 2043 /** 2044 * The status of the received navigation message. 2045 * No need to send any navigation message that contains words with parity error and cannot be 2046 * corrected. 2047 */ 2048 NavigationMessageStatus status; 2049 2050 /** 2051 * Message identifier. It provides an index so the complete Navigation 2052 * Message can be assembled. 2053 * 2054 * - For GPS L1 C/A subframe 4 and 5, this value corresponds to the 'frame 2055 * id' of the navigation message, in the range of 1-25 (Subframe 1, 2, 3 2056 * does not contain a 'frame id' and this value can be set to -1.) 2057 * 2058 * - For Glonass L1 C/A, this refers to the frame ID, in the range of 1-5. 2059 * 2060 * - For BeiDou D1, this refers to the frame number in the range of 1-24 2061 * 2062 * - For Beidou D2, this refers to the frame number, in the range of 1-120 2063 * 2064 * - For Galileo F/NAV nominal frame structure, this refers to the subframe 2065 * number, in the range of 1-12 2066 * 2067 * - For Galileo I/NAV nominal frame structure, this refers to the subframe 2068 * number in the range of 1-24 2069 */ 2070 int16_t message_id; 2071 2072 /** 2073 * Sub-message identifier. If required by the message 'type', this value 2074 * contains a sub-index within the current message (or frame) that is being 2075 * transmitted. 2076 * 2077 * - For GPS L1 C/A, BeiDou D1 & BeiDou D2, the submessage id corresponds to 2078 * the subframe number of the navigation message, in the range of 1-5. 2079 * 2080 * - For Glonass L1 C/A, this refers to the String number, in the range from 2081 * 1-15 2082 * 2083 * - For Galileo F/NAV, this refers to the page type in the range 1-6 2084 * 2085 * - For Galileo I/NAV, this refers to the word type in the range 1-10+ 2086 */ 2087 int16_t submessage_id; 2088 2089 /** 2090 * The length of the data (in bytes) contained in the current message. 2091 * If this value is different from zero, 'data' must point to an array of the same size. 2092 * e.g. for L1 C/A the size of the sub-frame will be 40 bytes (10 words, 30 bits/word). 2093 * 2094 * This is a mandatory value. 2095 */ 2096 size_t data_length; 2097 2098 /** 2099 * The data of the reported GPS message. The bytes (or words) specified 2100 * using big endian format (MSB first). 2101 * 2102 * - For GPS L1 C/A, Beidou D1 & Beidou D2, each subframe contains 10 30-bit 2103 * words. Each word (30 bits) should be fit into the last 30 bits in a 2104 * 4-byte word (skip B31 and B32), with MSB first, for a total of 40 2105 * bytes, covering a time period of 6, 6, and 0.6 seconds, respectively. 2106 * 2107 * - For Glonass L1 C/A, each string contains 85 data bits, including the 2108 * checksum. These bits should be fit into 11 bytes, with MSB first (skip 2109 * B86-B88), covering a time period of 2 seconds. 2110 * 2111 * - For Galileo F/NAV, each word consists of 238-bit (sync & tail symbols 2112 * excluded). Each word should be fit into 30-bytes, with MSB first (skip 2113 * B239, B240), covering a time period of 10 seconds. 2114 * 2115 * - For Galileo I/NAV, each page contains 2 page parts, even and odd, with 2116 * a total of 2x114 = 228 bits, (sync & tail excluded) that should be fit 2117 * into 29 bytes, with MSB first (skip B229-B232). 2118 */ 2119 uint8_t* data; 2120 2121 } GnssNavigationMessage; 2122 2123 /** 2124 * The legacy callback to report an available fragment of a GPS navigation 2125 * messages from the HAL. 2126 * 2127 * This callback is deprecated, and will be removed in the next release. Use 2128 * gnss_navigation_message_callback() instead. 2129 * 2130 * Parameters: 2131 * message - The GPS navigation submessage/subframe representation. 2132 */ 2133 typedef void (*gps_navigation_message_callback) (GpsNavigationMessage* message); 2134 2135 /** 2136 * The callback to report an available fragment of a GPS navigation messages from the HAL. 2137 * 2138 * Parameters: 2139 * message - The GPS navigation submessage/subframe representation. 2140 */ 2141 typedef void (*gnss_navigation_message_callback) (GnssNavigationMessage* message); 2142 2143 typedef struct { 2144 /** set to sizeof(GpsNavigationMessageCallbacks) */ 2145 size_t size; 2146 gps_navigation_message_callback navigation_message_callback; 2147 gnss_navigation_message_callback gnss_navigation_message_callback; 2148 } GpsNavigationMessageCallbacks; 2149 2150 #define GPS_NAVIGATION_MESSAGE_OPERATION_SUCCESS 0 2151 #define GPS_NAVIGATION_MESSAGE_ERROR_ALREADY_INIT -100 2152 #define GPS_NAVIGATION_MESSAGE_ERROR_GENERIC -101 2153 2154 /** 2155 * Extended interface for GPS navigation message reporting support. 2156 */ 2157 typedef struct { 2158 /** Set to sizeof(GpsNavigationMessageInterface) */ 2159 size_t size; 2160 2161 /** 2162 * Initializes the interface and registers the callback routines with the HAL. 2163 * After a successful call to 'init' the HAL must begin to provide updates as they become 2164 * available. 2165 * 2166 * Status: 2167 * GPS_NAVIGATION_MESSAGE_OPERATION_SUCCESS 2168 * GPS_NAVIGATION_MESSAGE_ERROR_ALREADY_INIT - if a callback has already been registered 2169 * without a corresponding call to 'close'. 2170 * GPS_NAVIGATION_MESSAGE_ERROR_GENERIC - if any other error occurred, it is expected that 2171 * the HAL will not generate any updates upon returning this error code. 2172 */ 2173 int (*init) (GpsNavigationMessageCallbacks* callbacks); 2174 2175 /** 2176 * Stops updates from the HAL, and unregisters the callback routines. 2177 * After a call to stop, the previously registered callbacks must be considered invalid by the 2178 * HAL. 2179 * If stop is invoked without a previous 'init', this function should perform no work. 2180 */ 2181 void (*close) (); 2182 2183 } GpsNavigationMessageInterface; 2184 2185 /** 2186 * Interface for passing GNSS configuration contents from platform to HAL. 2187 */ 2188 typedef struct { 2189 /** Set to sizeof(GnssConfigurationInterface) */ 2190 size_t size; 2191 2192 /** 2193 * Deliver GNSS configuration contents to HAL. 2194 * Parameters: 2195 * config_data - a pointer to a char array which holds what usually is expected from 2196 file(/etc/gps.conf), i.e., a sequence of UTF8 strings separated by '\n'. 2197 * length - total number of UTF8 characters in configuraiton data. 2198 * 2199 * IMPORTANT: 2200 * GPS HAL should expect this function can be called multiple times. And it may be 2201 * called even when GpsLocationProvider is already constructed and enabled. GPS HAL 2202 * should maintain the existing requests for various callback regardless the change 2203 * in configuration data. 2204 */ 2205 void (*configuration_update) (const char* config_data, int32_t length); 2206 } GnssConfigurationInterface; 2207 2208 __END_DECLS 2209 2210 #endif /* ANDROID_INCLUDE_HARDWARE_GPS_H */ 2211 2212