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