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