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 25 #include <hardware/hardware.h> 26 27 __BEGIN_DECLS 28 29 /** 30 * The id of this module 31 */ 32 #define GPS_HARDWARE_MODULE_ID "gps" 33 34 35 /** Milliseconds since January 1, 1970 */ 36 typedef int64_t GpsUtcTime; 37 38 /** Maximum number of SVs for gps_sv_status_callback(). */ 39 #define GPS_MAX_SVS 32 40 41 /** Requested operational mode for GPS operation. */ 42 typedef uint32_t GpsPositionMode; 43 // IMPORTANT: Note that the following values must match 44 // constants in GpsLocationProvider.java. 45 /** Mode for running GPS standalone (no assistance). */ 46 #define GPS_POSITION_MODE_STANDALONE 0 47 /** AGPS MS-Based mode. */ 48 #define GPS_POSITION_MODE_MS_BASED 1 49 /** AGPS MS-Assisted mode. */ 50 #define GPS_POSITION_MODE_MS_ASSISTED 2 51 52 /** Requested recurrence mode for GPS operation. */ 53 typedef uint32_t GpsPositionRecurrence; 54 // IMPORTANT: Note that the following values must match 55 // constants in GpsLocationProvider.java. 56 /** Receive GPS fixes on a recurring basis at a specified period. */ 57 #define GPS_POSITION_RECURRENCE_PERIODIC 0 58 /** Request a single shot GPS fix. */ 59 #define GPS_POSITION_RECURRENCE_SINGLE 1 60 61 /** GPS status event values. */ 62 typedef uint16_t GpsStatusValue; 63 // IMPORTANT: Note that the following values must match 64 // constants in GpsLocationProvider.java. 65 /** GPS status unknown. */ 66 #define GPS_STATUS_NONE 0 67 /** GPS has begun navigating. */ 68 #define GPS_STATUS_SESSION_BEGIN 1 69 /** GPS has stopped navigating. */ 70 #define GPS_STATUS_SESSION_END 2 71 /** GPS has powered on but is not navigating. */ 72 #define GPS_STATUS_ENGINE_ON 3 73 /** GPS is powered off. */ 74 #define GPS_STATUS_ENGINE_OFF 4 75 76 /** Flags to indicate which values are valid in a GpsLocation. */ 77 typedef uint16_t GpsLocationFlags; 78 // IMPORTANT: Note that the following values must match 79 // constants in GpsLocationProvider.java. 80 /** GpsLocation has valid latitude and longitude. */ 81 #define GPS_LOCATION_HAS_LAT_LONG 0x0001 82 /** GpsLocation has valid altitude. */ 83 #define GPS_LOCATION_HAS_ALTITUDE 0x0002 84 /** GpsLocation has valid speed. */ 85 #define GPS_LOCATION_HAS_SPEED 0x0004 86 /** GpsLocation has valid bearing. */ 87 #define GPS_LOCATION_HAS_BEARING 0x0008 88 /** GpsLocation has valid accuracy. */ 89 #define GPS_LOCATION_HAS_ACCURACY 0x0010 90 91 /** Flags for the gps_set_capabilities callback. */ 92 93 /** GPS HAL schedules fixes for GPS_POSITION_RECURRENCE_PERIODIC mode. 94 If this is not set, then the framework will use 1000ms for min_interval 95 and will start and call start() and stop() to schedule the GPS. 96 */ 97 #define GPS_CAPABILITY_SCHEDULING 0x0000001 98 /** GPS supports MS-Based AGPS mode */ 99 #define GPS_CAPABILITY_MSB 0x0000002 100 /** GPS supports MS-Assisted AGPS mode */ 101 #define GPS_CAPABILITY_MSA 0x0000004 102 /** GPS supports single-shot fixes */ 103 #define GPS_CAPABILITY_SINGLE_SHOT 0x0000008 104 105 /** Flags used to specify which aiding data to delete 106 when calling delete_aiding_data(). */ 107 typedef uint16_t GpsAidingData; 108 // IMPORTANT: Note that the following values must match 109 // constants in GpsLocationProvider.java. 110 #define GPS_DELETE_EPHEMERIS 0x0001 111 #define GPS_DELETE_ALMANAC 0x0002 112 #define GPS_DELETE_POSITION 0x0004 113 #define GPS_DELETE_TIME 0x0008 114 #define GPS_DELETE_IONO 0x0010 115 #define GPS_DELETE_UTC 0x0020 116 #define GPS_DELETE_HEALTH 0x0040 117 #define GPS_DELETE_SVDIR 0x0080 118 #define GPS_DELETE_SVSTEER 0x0100 119 #define GPS_DELETE_SADATA 0x0200 120 #define GPS_DELETE_RTI 0x0400 121 #define GPS_DELETE_CELLDB_INFO 0x8000 122 #define GPS_DELETE_ALL 0xFFFF 123 124 /** AGPS type */ 125 typedef uint16_t AGpsType; 126 #define AGPS_TYPE_SUPL 1 127 #define AGPS_TYPE_C2K 2 128 129 typedef uint16_t AGpsSetIDType; 130 #define AGPS_SETID_TYPE_NONE 0 131 #define AGPS_SETID_TYPE_IMSI 1 132 #define AGPS_SETID_TYPE_MSISDN 2 133 134 /** 135 * String length constants 136 */ 137 #define GPS_NI_SHORT_STRING_MAXLEN 256 138 #define GPS_NI_LONG_STRING_MAXLEN 2048 139 140 /** 141 * GpsNiType constants 142 */ 143 typedef uint32_t GpsNiType; 144 #define GPS_NI_TYPE_VOICE 1 145 #define GPS_NI_TYPE_UMTS_SUPL 2 146 #define GPS_NI_TYPE_UMTS_CTRL_PLANE 3 147 148 /** 149 * GpsNiNotifyFlags constants 150 */ 151 typedef uint32_t GpsNiNotifyFlags; 152 /** NI requires notification */ 153 #define GPS_NI_NEED_NOTIFY 0x0001 154 /** NI requires verification */ 155 #define GPS_NI_NEED_VERIFY 0x0002 156 /** NI requires privacy override, no notification/minimal trace */ 157 #define GPS_NI_PRIVACY_OVERRIDE 0x0004 158 159 /** 160 * GPS NI responses, used to define the response in 161 * NI structures 162 */ 163 typedef int GpsUserResponseType; 164 #define GPS_NI_RESPONSE_ACCEPT 1 165 #define GPS_NI_RESPONSE_DENY 2 166 #define GPS_NI_RESPONSE_NORESP 3 167 168 /** 169 * NI data encoding scheme 170 */ 171 typedef int GpsNiEncodingType; 172 #define GPS_ENC_NONE 0 173 #define GPS_ENC_SUPL_GSM_DEFAULT 1 174 #define GPS_ENC_SUPL_UTF8 2 175 #define GPS_ENC_SUPL_UCS2 3 176 #define GPS_ENC_UNKNOWN -1 177 178 /** AGPS status event values. */ 179 typedef uint16_t AGpsStatusValue; 180 /** GPS requests data connection for AGPS. */ 181 #define GPS_REQUEST_AGPS_DATA_CONN 1 182 /** GPS releases the AGPS data connection. */ 183 #define GPS_RELEASE_AGPS_DATA_CONN 2 184 /** AGPS data connection initiated */ 185 #define GPS_AGPS_DATA_CONNECTED 3 186 /** AGPS data connection completed */ 187 #define GPS_AGPS_DATA_CONN_DONE 4 188 /** AGPS data connection failed */ 189 #define GPS_AGPS_DATA_CONN_FAILED 5 190 191 #define AGPS_REF_LOCATION_TYPE_GSM_CELLID 1 192 #define AGPS_REF_LOCATION_TYPE_UMTS_CELLID 2 193 #define AGPS_REG_LOCATION_TYPE_MAC 3 194 195 /** Network types for update_network_state "type" parameter */ 196 #define AGPS_RIL_NETWORK_TYPE_MOBILE 0 197 #define AGPS_RIL_NETWORK_TYPE_WIFI 1 198 #define AGPS_RIL_NETWORK_TYPE_MOBILE_MMS 2 199 #define AGPS_RIL_NETWORK_TYPE_MOBILE_SUPL 3 200 #define AGPS_RIL_NETWORK_TTYPE_MOBILE_DUN 4 201 #define AGPS_RIL_NETWORK_TTYPE_MOBILE_HIPRI 5 202 #define AGPS_RIL_NETWORK_TTYPE_WIMAX 6 203 204 /** 205 * Name for the GPS XTRA interface. 206 */ 207 #define GPS_XTRA_INTERFACE "gps-xtra" 208 209 /** 210 * Name for the GPS DEBUG interface. 211 */ 212 #define GPS_DEBUG_INTERFACE "gps-debug" 213 214 /** 215 * Name for the AGPS interface. 216 */ 217 #define AGPS_INTERFACE "agps" 218 219 /** 220 * Name for NI interface 221 */ 222 #define GPS_NI_INTERFACE "gps-ni" 223 224 /** 225 * Name for the AGPS-RIL interface. 226 */ 227 #define AGPS_RIL_INTERFACE "agps_ril" 228 229 /** Represents a location. */ 230 typedef struct { 231 /** set to sizeof(GpsLocation) */ 232 size_t size; 233 /** Contains GpsLocationFlags bits. */ 234 uint16_t flags; 235 /** Represents latitude in degrees. */ 236 double latitude; 237 /** Represents longitude in degrees. */ 238 double longitude; 239 /** Represents altitude in meters above the WGS 84 reference 240 * ellipsoid. */ 241 double altitude; 242 /** Represents speed in meters per second. */ 243 float speed; 244 /** Represents heading in degrees. */ 245 float bearing; 246 /** Represents expected accuracy in meters. */ 247 float accuracy; 248 /** Timestamp for the location fix. */ 249 GpsUtcTime timestamp; 250 } GpsLocation; 251 252 /** Represents the status. */ 253 typedef struct { 254 /** set to sizeof(GpsStatus) */ 255 size_t size; 256 GpsStatusValue status; 257 } GpsStatus; 258 259 /** Represents SV information. */ 260 typedef struct { 261 /** set to sizeof(GpsSvInfo) */ 262 size_t size; 263 /** Pseudo-random number for the SV. */ 264 int prn; 265 /** Signal to noise ratio. */ 266 float snr; 267 /** Elevation of SV in degrees. */ 268 float elevation; 269 /** Azimuth of SV in degrees. */ 270 float azimuth; 271 } GpsSvInfo; 272 273 /** Represents SV status. */ 274 typedef struct { 275 /** set to sizeof(GpsSvStatus) */ 276 size_t size; 277 278 /** Number of SVs currently visible. */ 279 int num_svs; 280 281 /** Contains an array of SV information. */ 282 GpsSvInfo sv_list[GPS_MAX_SVS]; 283 284 /** Represents a bit mask indicating which SVs 285 * have ephemeris data. 286 */ 287 uint32_t ephemeris_mask; 288 289 /** Represents a bit mask indicating which SVs 290 * have almanac data. 291 */ 292 uint32_t almanac_mask; 293 294 /** 295 * Represents a bit mask indicating which SVs 296 * were used for computing the most recent position fix. 297 */ 298 uint32_t used_in_fix_mask; 299 } GpsSvStatus; 300 301 /* 2G and 3G */ 302 /* In 3G lac is discarded */ 303 typedef struct { 304 uint16_t type; 305 uint16_t mcc; 306 uint16_t mnc; 307 uint16_t lac; 308 uint32_t cid; 309 } AGpsRefLocationCellID; 310 311 typedef struct { 312 uint8_t mac[6]; 313 } AGpsRefLocationMac; 314 315 /** Represents ref locations */ 316 typedef struct { 317 uint16_t type; 318 union { 319 AGpsRefLocationCellID cellID; 320 AGpsRefLocationMac mac; 321 } u; 322 } AGpsRefLocation; 323 324 /** Callback with location information. 325 * Can only be called from a thread created by create_thread_cb. 326 */ 327 typedef void (* gps_location_callback)(GpsLocation* location); 328 329 /** Callback with status information. 330 * Can only be called from a thread created by create_thread_cb. 331 */ 332 typedef void (* gps_status_callback)(GpsStatus* status); 333 334 /** Callback with SV status information. 335 * Can only be called from a thread created by create_thread_cb. 336 */ 337 typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info); 338 339 /** Callback for reporting NMEA sentences. 340 * Can only be called from a thread created by create_thread_cb. 341 */ 342 typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length); 343 344 /** Callback to inform framework of the GPS engine's capabilities. 345 * Capability parameter is a bit field of GPS_CAPABILITY_* flags. 346 */ 347 typedef void (* gps_set_capabilities)(uint32_t capabilities); 348 349 /** Callback utility for acquiring the GPS wakelock. 350 * This can be used to prevent the CPU from suspending while handling GPS events. 351 */ 352 typedef void (* gps_acquire_wakelock)(); 353 354 /** Callback utility for releasing the GPS wakelock. */ 355 typedef void (* gps_release_wakelock)(); 356 357 /** Callback for creating a thread that can call into the Java framework code. 358 * This must be used to create any threads that report events up to the framework. 359 */ 360 typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg); 361 362 /** GPS callback structure. */ 363 typedef struct { 364 /** set to sizeof(GpsCallbacks) */ 365 size_t size; 366 gps_location_callback location_cb; 367 gps_status_callback status_cb; 368 gps_sv_status_callback sv_status_cb; 369 gps_nmea_callback nmea_cb; 370 gps_set_capabilities set_capabilities_cb; 371 gps_acquire_wakelock acquire_wakelock_cb; 372 gps_release_wakelock release_wakelock_cb; 373 gps_create_thread create_thread_cb; 374 } GpsCallbacks; 375 376 377 /** Represents the standard GPS interface. */ 378 typedef struct { 379 /** set to sizeof(GpsInterface) */ 380 size_t size; 381 /** 382 * Opens the interface and provides the callback routines 383 * to the implemenation of this interface. 384 */ 385 int (*init)( GpsCallbacks* callbacks ); 386 387 /** Starts navigating. */ 388 int (*start)( void ); 389 390 /** Stops navigating. */ 391 int (*stop)( void ); 392 393 /** Closes the interface. */ 394 void (*cleanup)( void ); 395 396 /** Injects the current time. */ 397 int (*inject_time)(GpsUtcTime time, int64_t timeReference, 398 int uncertainty); 399 400 /** Injects current location from another location provider 401 * (typically cell ID). 402 * latitude and longitude are measured in degrees 403 * expected accuracy is measured in meters 404 */ 405 int (*inject_location)(double latitude, double longitude, float accuracy); 406 407 /** 408 * Specifies that the next call to start will not use the 409 * information defined in the flags. GPS_DELETE_ALL is passed for 410 * a cold start. 411 */ 412 void (*delete_aiding_data)(GpsAidingData flags); 413 414 /** 415 * min_interval represents the time between fixes in milliseconds. 416 * preferred_accuracy represents the requested fix accuracy in meters. 417 * preferred_time represents the requested time to first fix in milliseconds. 418 */ 419 int (*set_position_mode)(GpsPositionMode mode, GpsPositionRecurrence recurrence, 420 uint32_t min_interval, uint32_t preferred_accuracy, uint32_t preferred_time); 421 422 /** Get a pointer to extension information. */ 423 const void* (*get_extension)(const char* name); 424 } GpsInterface; 425 426 /** Callback to request the client to download XTRA data. 427 * The client should download XTRA data and inject it by calling inject_xtra_data(). 428 * Can only be called from a thread created by create_thread_cb. 429 */ 430 typedef void (* gps_xtra_download_request)(); 431 432 /** Callback structure for the XTRA interface. */ 433 typedef struct { 434 gps_xtra_download_request download_request_cb; 435 gps_create_thread create_thread_cb; 436 } GpsXtraCallbacks; 437 438 /** Extended interface for XTRA support. */ 439 typedef struct { 440 /** set to sizeof(GpsXtraInterface) */ 441 size_t size; 442 /** 443 * Opens the XTRA interface and provides the callback routines 444 * to the implemenation of this interface. 445 */ 446 int (*init)( GpsXtraCallbacks* callbacks ); 447 /** Injects XTRA data into the GPS. */ 448 int (*inject_xtra_data)( char* data, int length ); 449 } GpsXtraInterface; 450 451 /** Extended interface for DEBUG support. */ 452 typedef struct { 453 /** set to sizeof(GpsDebugInterface) */ 454 size_t size; 455 456 /** 457 * This function should return any information that the native 458 * implementation wishes to include in a bugreport. 459 */ 460 size_t (*get_internal_state)(char* buffer, size_t bufferSize); 461 } GpsDebugInterface; 462 463 /** Represents the status of AGPS. */ 464 typedef struct { 465 /** set to sizeof(AGpsStatus) */ 466 size_t size; 467 468 AGpsType type; 469 AGpsStatusValue status; 470 } AGpsStatus; 471 472 /** Callback with AGPS status information. 473 * Can only be called from a thread created by create_thread_cb. 474 */ 475 typedef void (* agps_status_callback)(AGpsStatus* status); 476 477 /** Callback structure for the AGPS interface. */ 478 typedef struct { 479 agps_status_callback status_cb; 480 gps_create_thread create_thread_cb; 481 } AGpsCallbacks; 482 483 484 /** Extended interface for AGPS support. */ 485 typedef struct { 486 /** set to sizeof(AGpsInterface) */ 487 size_t size; 488 489 /** 490 * Opens the AGPS interface and provides the callback routines 491 * to the implemenation of this interface. 492 */ 493 void (*init)( AGpsCallbacks* callbacks ); 494 /** 495 * Notifies that a data connection is available and sets 496 * the name of the APN to be used for SUPL. 497 */ 498 int (*data_conn_open)( const char* apn ); 499 /** 500 * Notifies that the AGPS data connection has been closed. 501 */ 502 int (*data_conn_closed)(); 503 /** 504 * Notifies that a data connection is not available for AGPS. 505 */ 506 int (*data_conn_failed)(); 507 /** 508 * Sets the hostname and port for the AGPS server. 509 */ 510 int (*set_server)( AGpsType type, const char* hostname, int port ); 511 } AGpsInterface; 512 513 514 /** Represents an NI request */ 515 typedef struct { 516 /** set to sizeof(GpsNiNotification) */ 517 size_t size; 518 519 /** 520 * An ID generated by HAL to associate NI notifications and UI 521 * responses 522 */ 523 int notification_id; 524 525 /** 526 * An NI type used to distinguish different categories of NI 527 * events, such as GPS_NI_TYPE_VOICE, GPS_NI_TYPE_UMTS_SUPL, ... 528 */ 529 GpsNiType ni_type; 530 531 /** 532 * Notification/verification options, combinations of GpsNiNotifyFlags constants 533 */ 534 GpsNiNotifyFlags notify_flags; 535 536 /** 537 * Timeout period to wait for user response. 538 * Set to 0 for no time out limit. 539 */ 540 int timeout; 541 542 /** 543 * Default response when time out. 544 */ 545 GpsUserResponseType default_response; 546 547 /** 548 * Requestor ID 549 */ 550 char requestor_id[GPS_NI_SHORT_STRING_MAXLEN]; 551 552 /** 553 * Notification message. It can also be used to store client_id in some cases 554 */ 555 char text[GPS_NI_LONG_STRING_MAXLEN]; 556 557 /** 558 * Client name decoding scheme 559 */ 560 GpsNiEncodingType requestor_id_encoding; 561 562 /** 563 * Client name decoding scheme 564 */ 565 GpsNiEncodingType text_encoding; 566 567 /** 568 * A pointer to extra data. Format: 569 * key_1 = value_1 570 * key_2 = value_2 571 */ 572 char extras[GPS_NI_LONG_STRING_MAXLEN]; 573 574 } GpsNiNotification; 575 576 /** Callback with NI notification. 577 * Can only be called from a thread created by create_thread_cb. 578 */ 579 typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification); 580 581 /** GPS NI callback structure. */ 582 typedef struct 583 { 584 /** 585 * Sends the notification request from HAL to GPSLocationProvider. 586 */ 587 gps_ni_notify_callback notify_cb; 588 gps_create_thread create_thread_cb; 589 } GpsNiCallbacks; 590 591 /** 592 * Extended interface for Network-initiated (NI) support. 593 */ 594 typedef struct 595 { 596 /** set to sizeof(GpsNiInterface) */ 597 size_t size; 598 599 /** Registers the callbacks for HAL to use. */ 600 void (*init) (GpsNiCallbacks *callbacks); 601 602 /** Sends a response to HAL. */ 603 void (*respond) (int notif_id, GpsUserResponseType user_response); 604 } GpsNiInterface; 605 606 struct gps_device_t { 607 struct hw_device_t common; 608 609 /** 610 * Set the provided lights to the provided values. 611 * 612 * Returns: 0 on succes, error code on failure. 613 */ 614 const GpsInterface* (*get_gps_interface)(struct gps_device_t* dev); 615 }; 616 617 #define AGPS_RIL_REQUEST_SETID_IMSI (1<<0L) 618 #define AGPS_RIL_REQUEST_SETID_MSISDN (1<<1L) 619 620 #define AGPS_RIL_REQUEST_REFLOC_CELLID (1<<0L) 621 #define AGPS_RIL_REQUEST_REFLOC_MAC (1<<1L) 622 623 typedef void (*agps_ril_request_set_id)(uint32_t flags); 624 typedef void (*agps_ril_request_ref_loc)(uint32_t flags); 625 626 typedef struct { 627 agps_ril_request_set_id request_setid; 628 agps_ril_request_ref_loc request_refloc; 629 gps_create_thread create_thread_cb; 630 } AGpsRilCallbacks; 631 632 /** Extended interface for AGPS_RIL support. */ 633 typedef struct { 634 /** set to sizeof(AGpsRilInterface) */ 635 size_t size; 636 /** 637 * Opens the AGPS interface and provides the callback routines 638 * to the implemenation of this interface. 639 */ 640 void (*init)( AGpsRilCallbacks* callbacks ); 641 642 /** 643 * Sets the reference location. 644 */ 645 void (*set_ref_location) (const AGpsRefLocation *agps_reflocation, size_t sz_struct); 646 /** 647 * Sets the set ID. 648 */ 649 void (*set_set_id) (AGpsSetIDType type, const char* setid); 650 651 /** 652 * Send network initiated message. 653 */ 654 void (*ni_message) (uint8_t *msg, size_t len); 655 656 /** 657 * Notify GPS of network status changes. 658 * These parameters match values in the android.net.NetworkInfo class. 659 */ 660 void (*update_network_state) (int connected, int type, int roaming, const char* extra_info); 661 } AGpsRilInterface; 662 663 __END_DECLS 664 665 #endif /* ANDROID_INCLUDE_HARDWARE_GPS_H */ 666 667