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