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