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 */ 36typedef 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. */ 42typedef 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. */ 53typedef 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. */ 62typedef 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. */ 77typedef 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/** GPS supports on demand time injection */ 105#define GPS_CAPABILITY_ON_DEMAND_TIME 0x0000010 106/** GPS supports Geofencing */ 107#define GPS_CAPABILITY_GEOFENCING 0x0000020 108 109/** Flags used to specify which aiding data to delete 110 when calling delete_aiding_data(). */ 111typedef uint16_t GpsAidingData; 112// IMPORTANT: Note that the following values must match 113// constants in GpsLocationProvider.java. 114#define GPS_DELETE_EPHEMERIS 0x0001 115#define GPS_DELETE_ALMANAC 0x0002 116#define GPS_DELETE_POSITION 0x0004 117#define GPS_DELETE_TIME 0x0008 118#define GPS_DELETE_IONO 0x0010 119#define GPS_DELETE_UTC 0x0020 120#define GPS_DELETE_HEALTH 0x0040 121#define GPS_DELETE_SVDIR 0x0080 122#define GPS_DELETE_SVSTEER 0x0100 123#define GPS_DELETE_SADATA 0x0200 124#define GPS_DELETE_RTI 0x0400 125#define GPS_DELETE_CELLDB_INFO 0x8000 126#define GPS_DELETE_ALL 0xFFFF 127 128/** AGPS type */ 129typedef uint16_t AGpsType; 130#define AGPS_TYPE_SUPL 1 131#define AGPS_TYPE_C2K 2 132 133typedef uint16_t AGpsSetIDType; 134#define AGPS_SETID_TYPE_NONE 0 135#define AGPS_SETID_TYPE_IMSI 1 136#define AGPS_SETID_TYPE_MSISDN 2 137 138/** 139 * String length constants 140 */ 141#define GPS_NI_SHORT_STRING_MAXLEN 256 142#define GPS_NI_LONG_STRING_MAXLEN 2048 143 144/** 145 * GpsNiType constants 146 */ 147typedef uint32_t GpsNiType; 148#define GPS_NI_TYPE_VOICE 1 149#define GPS_NI_TYPE_UMTS_SUPL 2 150#define GPS_NI_TYPE_UMTS_CTRL_PLANE 3 151 152/** 153 * GpsNiNotifyFlags constants 154 */ 155typedef uint32_t GpsNiNotifyFlags; 156/** NI requires notification */ 157#define GPS_NI_NEED_NOTIFY 0x0001 158/** NI requires verification */ 159#define GPS_NI_NEED_VERIFY 0x0002 160/** NI requires privacy override, no notification/minimal trace */ 161#define GPS_NI_PRIVACY_OVERRIDE 0x0004 162 163/** 164 * GPS NI responses, used to define the response in 165 * NI structures 166 */ 167typedef int GpsUserResponseType; 168#define GPS_NI_RESPONSE_ACCEPT 1 169#define GPS_NI_RESPONSE_DENY 2 170#define GPS_NI_RESPONSE_NORESP 3 171 172/** 173 * NI data encoding scheme 174 */ 175typedef int GpsNiEncodingType; 176#define GPS_ENC_NONE 0 177#define GPS_ENC_SUPL_GSM_DEFAULT 1 178#define GPS_ENC_SUPL_UTF8 2 179#define GPS_ENC_SUPL_UCS2 3 180#define GPS_ENC_UNKNOWN -1 181 182/** AGPS status event values. */ 183typedef uint16_t AGpsStatusValue; 184/** GPS requests data connection for AGPS. */ 185#define GPS_REQUEST_AGPS_DATA_CONN 1 186/** GPS releases the AGPS data connection. */ 187#define GPS_RELEASE_AGPS_DATA_CONN 2 188/** AGPS data connection initiated */ 189#define GPS_AGPS_DATA_CONNECTED 3 190/** AGPS data connection completed */ 191#define GPS_AGPS_DATA_CONN_DONE 4 192/** AGPS data connection failed */ 193#define GPS_AGPS_DATA_CONN_FAILED 5 194 195#define AGPS_REF_LOCATION_TYPE_GSM_CELLID 1 196#define AGPS_REF_LOCATION_TYPE_UMTS_CELLID 2 197#define AGPS_REG_LOCATION_TYPE_MAC 3 198 199/** Network types for update_network_state "type" parameter */ 200#define AGPS_RIL_NETWORK_TYPE_MOBILE 0 201#define AGPS_RIL_NETWORK_TYPE_WIFI 1 202#define AGPS_RIL_NETWORK_TYPE_MOBILE_MMS 2 203#define AGPS_RIL_NETWORK_TYPE_MOBILE_SUPL 3 204#define AGPS_RIL_NETWORK_TTYPE_MOBILE_DUN 4 205#define AGPS_RIL_NETWORK_TTYPE_MOBILE_HIPRI 5 206#define AGPS_RIL_NETWORK_TTYPE_WIMAX 6 207 208/** 209 * Name for the GPS XTRA interface. 210 */ 211#define GPS_XTRA_INTERFACE "gps-xtra" 212 213/** 214 * Name for the GPS DEBUG interface. 215 */ 216#define GPS_DEBUG_INTERFACE "gps-debug" 217 218/** 219 * Name for the AGPS interface. 220 */ 221#define AGPS_INTERFACE "agps" 222 223/** 224 * Name for NI interface 225 */ 226#define GPS_NI_INTERFACE "gps-ni" 227 228/** 229 * Name for the AGPS-RIL interface. 230 */ 231#define AGPS_RIL_INTERFACE "agps_ril" 232 233/** 234 * Name for the GPS_Geofencing interface. 235 */ 236#define GPS_GEOFENCING_INTERFACE "gps_geofencing" 237 238 239/** Represents a location. */ 240typedef struct { 241 /** set to sizeof(GpsLocation) */ 242 size_t size; 243 /** Contains GpsLocationFlags bits. */ 244 uint16_t flags; 245 /** Represents latitude in degrees. */ 246 double latitude; 247 /** Represents longitude in degrees. */ 248 double longitude; 249 /** Represents altitude in meters above the WGS 84 reference 250 * ellipsoid. */ 251 double altitude; 252 /** Represents speed in meters per second. */ 253 float speed; 254 /** Represents heading in degrees. */ 255 float bearing; 256 /** Represents expected accuracy in meters. */ 257 float accuracy; 258 /** Timestamp for the location fix. */ 259 GpsUtcTime timestamp; 260} GpsLocation; 261 262/** Represents the status. */ 263typedef struct { 264 /** set to sizeof(GpsStatus) */ 265 size_t size; 266 GpsStatusValue status; 267} GpsStatus; 268 269/** Represents SV information. */ 270typedef struct { 271 /** set to sizeof(GpsSvInfo) */ 272 size_t size; 273 /** Pseudo-random number for the SV. */ 274 int prn; 275 /** Signal to noise ratio. */ 276 float snr; 277 /** Elevation of SV in degrees. */ 278 float elevation; 279 /** Azimuth of SV in degrees. */ 280 float azimuth; 281} GpsSvInfo; 282 283/** Represents SV status. */ 284typedef struct { 285 /** set to sizeof(GpsSvStatus) */ 286 size_t size; 287 288 /** Number of SVs currently visible. */ 289 int num_svs; 290 291 /** Contains an array of SV information. */ 292 GpsSvInfo sv_list[GPS_MAX_SVS]; 293 294 /** Represents a bit mask indicating which SVs 295 * have ephemeris data. 296 */ 297 uint32_t ephemeris_mask; 298 299 /** Represents a bit mask indicating which SVs 300 * have almanac data. 301 */ 302 uint32_t almanac_mask; 303 304 /** 305 * Represents a bit mask indicating which SVs 306 * were used for computing the most recent position fix. 307 */ 308 uint32_t used_in_fix_mask; 309} GpsSvStatus; 310 311/* 2G and 3G */ 312/* In 3G lac is discarded */ 313typedef struct { 314 uint16_t type; 315 uint16_t mcc; 316 uint16_t mnc; 317 uint16_t lac; 318 uint32_t cid; 319} AGpsRefLocationCellID; 320 321typedef struct { 322 uint8_t mac[6]; 323} AGpsRefLocationMac; 324 325/** Represents ref locations */ 326typedef struct { 327 uint16_t type; 328 union { 329 AGpsRefLocationCellID cellID; 330 AGpsRefLocationMac mac; 331 } u; 332} AGpsRefLocation; 333 334/** Callback with location information. 335 * Can only be called from a thread created by create_thread_cb. 336 */ 337typedef void (* gps_location_callback)(GpsLocation* location); 338 339/** Callback with status information. 340 * Can only be called from a thread created by create_thread_cb. 341 */ 342typedef void (* gps_status_callback)(GpsStatus* status); 343 344/** Callback with SV status information. 345 * Can only be called from a thread created by create_thread_cb. 346 */ 347typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info); 348 349/** Callback for reporting NMEA sentences. 350 * Can only be called from a thread created by create_thread_cb. 351 */ 352typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length); 353 354/** Callback to inform framework of the GPS engine's capabilities. 355 * Capability parameter is a bit field of GPS_CAPABILITY_* flags. 356 */ 357typedef void (* gps_set_capabilities)(uint32_t capabilities); 358 359/** Callback utility for acquiring the GPS wakelock. 360 * This can be used to prevent the CPU from suspending while handling GPS events. 361 */ 362typedef void (* gps_acquire_wakelock)(); 363 364/** Callback utility for releasing the GPS wakelock. */ 365typedef void (* gps_release_wakelock)(); 366 367/** Callback for requesting NTP time */ 368typedef void (* gps_request_utc_time)(); 369 370/** Callback for creating a thread that can call into the Java framework code. 371 * This must be used to create any threads that report events up to the framework. 372 */ 373typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg); 374 375/** GPS callback structure. */ 376typedef struct { 377 /** set to sizeof(GpsCallbacks) */ 378 size_t size; 379 gps_location_callback location_cb; 380 gps_status_callback status_cb; 381 gps_sv_status_callback sv_status_cb; 382 gps_nmea_callback nmea_cb; 383 gps_set_capabilities set_capabilities_cb; 384 gps_acquire_wakelock acquire_wakelock_cb; 385 gps_release_wakelock release_wakelock_cb; 386 gps_create_thread create_thread_cb; 387 gps_request_utc_time request_utc_time_cb; 388} GpsCallbacks; 389 390 391/** Represents the standard GPS interface. */ 392typedef struct { 393 /** set to sizeof(GpsInterface) */ 394 size_t size; 395 /** 396 * Opens the interface and provides the callback routines 397 * to the implemenation of this interface. 398 */ 399 int (*init)( GpsCallbacks* callbacks ); 400 401 /** Starts navigating. */ 402 int (*start)( void ); 403 404 /** Stops navigating. */ 405 int (*stop)( void ); 406 407 /** Closes the interface. */ 408 void (*cleanup)( void ); 409 410 /** Injects the current time. */ 411 int (*inject_time)(GpsUtcTime time, int64_t timeReference, 412 int uncertainty); 413 414 /** Injects current location from another location provider 415 * (typically cell ID). 416 * latitude and longitude are measured in degrees 417 * expected accuracy is measured in meters 418 */ 419 int (*inject_location)(double latitude, double longitude, float accuracy); 420 421 /** 422 * Specifies that the next call to start will not use the 423 * information defined in the flags. GPS_DELETE_ALL is passed for 424 * a cold start. 425 */ 426 void (*delete_aiding_data)(GpsAidingData flags); 427 428 /** 429 * min_interval represents the time between fixes in milliseconds. 430 * preferred_accuracy represents the requested fix accuracy in meters. 431 * preferred_time represents the requested time to first fix in milliseconds. 432 */ 433 int (*set_position_mode)(GpsPositionMode mode, GpsPositionRecurrence recurrence, 434 uint32_t min_interval, uint32_t preferred_accuracy, uint32_t preferred_time); 435 436 /** Get a pointer to extension information. */ 437 const void* (*get_extension)(const char* name); 438} GpsInterface; 439 440/** Callback to request the client to download XTRA data. 441 * The client should download XTRA data and inject it by calling inject_xtra_data(). 442 * Can only be called from a thread created by create_thread_cb. 443 */ 444typedef void (* gps_xtra_download_request)(); 445 446/** Callback structure for the XTRA interface. */ 447typedef struct { 448 gps_xtra_download_request download_request_cb; 449 gps_create_thread create_thread_cb; 450} GpsXtraCallbacks; 451 452/** Extended interface for XTRA support. */ 453typedef struct { 454 /** set to sizeof(GpsXtraInterface) */ 455 size_t size; 456 /** 457 * Opens the XTRA interface and provides the callback routines 458 * to the implemenation of this interface. 459 */ 460 int (*init)( GpsXtraCallbacks* callbacks ); 461 /** Injects XTRA data into the GPS. */ 462 int (*inject_xtra_data)( char* data, int length ); 463} GpsXtraInterface; 464 465/** Extended interface for DEBUG support. */ 466typedef struct { 467 /** set to sizeof(GpsDebugInterface) */ 468 size_t size; 469 470 /** 471 * This function should return any information that the native 472 * implementation wishes to include in a bugreport. 473 */ 474 size_t (*get_internal_state)(char* buffer, size_t bufferSize); 475} GpsDebugInterface; 476 477/** Represents the status of AGPS. */ 478typedef struct { 479 /** set to sizeof(AGpsStatus) */ 480 size_t size; 481 482 AGpsType type; 483 AGpsStatusValue status; 484 uint32_t ipaddr; 485} AGpsStatus; 486 487/** Callback with AGPS status information. 488 * Can only be called from a thread created by create_thread_cb. 489 */ 490typedef void (* agps_status_callback)(AGpsStatus* status); 491 492/** Callback structure for the AGPS interface. */ 493typedef struct { 494 agps_status_callback status_cb; 495 gps_create_thread create_thread_cb; 496} AGpsCallbacks; 497 498 499/** Extended interface for AGPS support. */ 500typedef struct { 501 /** set to sizeof(AGpsInterface) */ 502 size_t size; 503 504 /** 505 * Opens the AGPS interface and provides the callback routines 506 * to the implemenation of this interface. 507 */ 508 void (*init)( AGpsCallbacks* callbacks ); 509 /** 510 * Notifies that a data connection is available and sets 511 * the name of the APN to be used for SUPL. 512 */ 513 int (*data_conn_open)( const char* apn ); 514 /** 515 * Notifies that the AGPS data connection has been closed. 516 */ 517 int (*data_conn_closed)(); 518 /** 519 * Notifies that a data connection is not available for AGPS. 520 */ 521 int (*data_conn_failed)(); 522 /** 523 * Sets the hostname and port for the AGPS server. 524 */ 525 int (*set_server)( AGpsType type, const char* hostname, int port ); 526} AGpsInterface; 527 528 529/** Represents an NI request */ 530typedef struct { 531 /** set to sizeof(GpsNiNotification) */ 532 size_t size; 533 534 /** 535 * An ID generated by HAL to associate NI notifications and UI 536 * responses 537 */ 538 int notification_id; 539 540 /** 541 * An NI type used to distinguish different categories of NI 542 * events, such as GPS_NI_TYPE_VOICE, GPS_NI_TYPE_UMTS_SUPL, ... 543 */ 544 GpsNiType ni_type; 545 546 /** 547 * Notification/verification options, combinations of GpsNiNotifyFlags constants 548 */ 549 GpsNiNotifyFlags notify_flags; 550 551 /** 552 * Timeout period to wait for user response. 553 * Set to 0 for no time out limit. 554 */ 555 int timeout; 556 557 /** 558 * Default response when time out. 559 */ 560 GpsUserResponseType default_response; 561 562 /** 563 * Requestor ID 564 */ 565 char requestor_id[GPS_NI_SHORT_STRING_MAXLEN]; 566 567 /** 568 * Notification message. It can also be used to store client_id in some cases 569 */ 570 char text[GPS_NI_LONG_STRING_MAXLEN]; 571 572 /** 573 * Client name decoding scheme 574 */ 575 GpsNiEncodingType requestor_id_encoding; 576 577 /** 578 * Client name decoding scheme 579 */ 580 GpsNiEncodingType text_encoding; 581 582 /** 583 * A pointer to extra data. Format: 584 * key_1 = value_1 585 * key_2 = value_2 586 */ 587 char extras[GPS_NI_LONG_STRING_MAXLEN]; 588 589} GpsNiNotification; 590 591/** Callback with NI notification. 592 * Can only be called from a thread created by create_thread_cb. 593 */ 594typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification); 595 596/** GPS NI callback structure. */ 597typedef struct 598{ 599 /** 600 * Sends the notification request from HAL to GPSLocationProvider. 601 */ 602 gps_ni_notify_callback notify_cb; 603 gps_create_thread create_thread_cb; 604} GpsNiCallbacks; 605 606/** 607 * Extended interface for Network-initiated (NI) support. 608 */ 609typedef struct 610{ 611 /** set to sizeof(GpsNiInterface) */ 612 size_t size; 613 614 /** Registers the callbacks for HAL to use. */ 615 void (*init) (GpsNiCallbacks *callbacks); 616 617 /** Sends a response to HAL. */ 618 void (*respond) (int notif_id, GpsUserResponseType user_response); 619} GpsNiInterface; 620 621struct gps_device_t { 622 struct hw_device_t common; 623 624 /** 625 * Set the provided lights to the provided values. 626 * 627 * Returns: 0 on succes, error code on failure. 628 */ 629 const GpsInterface* (*get_gps_interface)(struct gps_device_t* dev); 630}; 631 632#define AGPS_RIL_REQUEST_SETID_IMSI (1<<0L) 633#define AGPS_RIL_REQUEST_SETID_MSISDN (1<<1L) 634 635#define AGPS_RIL_REQUEST_REFLOC_CELLID (1<<0L) 636#define AGPS_RIL_REQUEST_REFLOC_MAC (1<<1L) 637 638typedef void (*agps_ril_request_set_id)(uint32_t flags); 639typedef void (*agps_ril_request_ref_loc)(uint32_t flags); 640 641typedef struct { 642 agps_ril_request_set_id request_setid; 643 agps_ril_request_ref_loc request_refloc; 644 gps_create_thread create_thread_cb; 645} AGpsRilCallbacks; 646 647/** Extended interface for AGPS_RIL support. */ 648typedef struct { 649 /** set to sizeof(AGpsRilInterface) */ 650 size_t size; 651 /** 652 * Opens the AGPS interface and provides the callback routines 653 * to the implemenation of this interface. 654 */ 655 void (*init)( AGpsRilCallbacks* callbacks ); 656 657 /** 658 * Sets the reference location. 659 */ 660 void (*set_ref_location) (const AGpsRefLocation *agps_reflocation, size_t sz_struct); 661 /** 662 * Sets the set ID. 663 */ 664 void (*set_set_id) (AGpsSetIDType type, const char* setid); 665 666 /** 667 * Send network initiated message. 668 */ 669 void (*ni_message) (uint8_t *msg, size_t len); 670 671 /** 672 * Notify GPS of network status changes. 673 * These parameters match values in the android.net.NetworkInfo class. 674 */ 675 void (*update_network_state) (int connected, int type, int roaming, const char* extra_info); 676 677 /** 678 * Notify GPS of network status changes. 679 * These parameters match values in the android.net.NetworkInfo class. 680 */ 681 void (*update_network_availability) (int avaiable, const char* apn); 682} AGpsRilInterface; 683 684/** 685 * GPS Geofence. 686 * There are 3 states associated with a Geofence: Inside, Outside, Unknown. 687 * There are 3 transitions: ENTERED, EXITED, UNCERTAIN. 688 * 689 * An example state diagram with confidence level: 95% and Unknown time limit 690 * set as 30 secs is shown below. (confidence level and Unknown time limit are 691 * explained latter) 692 * ____________________________ 693 * | Unknown (30 secs) | 694 * """""""""""""""""""""""""""" 695 * ^ | | ^ 696 * UNCERTAIN| |ENTERED EXITED| |UNCERTAIN 697 * | v v | 698 * ________ EXITED _________ 699 * | Inside | -----------> | Outside | 700 * | | <----------- | | 701 * """""""" ENTERED """"""""" 702 * 703 * Inside state: We are 95% confident that the user is inside the geofence. 704 * Outside state: We are 95% confident that the user is outside the geofence 705 * Unknown state: Rest of the time. 706 * 707 * The Unknown state is better explained with an example: 708 * 709 * __________ 710 * | c| 711 * | ___ | _______ 712 * | |a| | | b | 713 * | """ | """"""" 714 * | | 715 * """""""""" 716 * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy 717 * circle reported by the GPS subsystem. Now with regard to "b", the system is 718 * confident that the user is outside. But with regard to "a" is not confident 719 * whether it is inside or outside the geofence. If the accuracy remains the 720 * same for a sufficient period of time, the UNCERTAIN transition would be 721 * triggered with the state set to Unknown. If the accuracy improves later, an 722 * appropriate transition should be triggered. This "sufficient period of time" 723 * is defined by the parameter in the add_geofence_area API. 724 * In other words, Unknown state can be interpreted as a state in which the 725 * GPS subsystem isn't confident enough that the user is either inside or 726 * outside the Geofence. It moves to Unknown state only after the expiry of the 727 * timeout. 728 * 729 * The geofence callback needs to be triggered for the ENTERED and EXITED 730 * transitions, when the GPS system is confident that the user has entered 731 * (Inside state) or exited (Outside state) the Geofence. An implementation 732 * which uses a value of 95% as the confidence is recommended. The callback 733 * should be triggered only for the transitions requested by the 734 * add_geofence_area call. 735 * 736 * Even though the diagram and explanation talks about states and transitions, 737 * the callee is only interested in the transistions. The states are mentioned 738 * here for illustrative purposes. 739 * 740 * Startup Scenario: When the device boots up, if an application adds geofences, 741 * and then we get an accurate GPS location fix, it needs to trigger the 742 * appropriate (ENTERED or EXITED) transition for every Geofence it knows about. 743 * By default, all the Geofences will be in the Unknown state. 744 * 745 * When the GPS system is unavailable, gps_geofence_status_callback should be 746 * called to inform the upper layers of the same. Similarly, when it becomes 747 * available the callback should be called. This is a global state while the 748 * UNKNOWN transition described above is per geofence. 749 * 750 * An important aspect to note is that users of this API (framework), will use 751 * other subsystems like wifi, sensors, cell to handle Unknown case and 752 * hopefully provide a definitive state transition to the third party 753 * application. GPS Geofence will just be a signal indicating what the GPS 754 * subsystem knows about the Geofence. 755 * 756 */ 757#define GPS_GEOFENCE_ENTERED (1<<0L) 758#define GPS_GEOFENCE_EXITED (1<<1L) 759#define GPS_GEOFENCE_UNCERTAIN (1<<2L) 760 761#define GPS_GEOFENCE_UNAVAILABLE (1<<0L) 762#define GPS_GEOFENCE_AVAILABLE (1<<1L) 763 764#define GPS_GEOFENCE_OPERATION_SUCCESS 0 765#define GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES -100 766#define GPS_GEOFENCE_ERROR_ID_EXISTS -101 767#define GPS_GEOFENCE_ERROR_ID_UNKNOWN -102 768#define GPS_GEOFENCE_ERROR_INVALID_TRANSITION -103 769#define GPS_GEOFENCE_ERROR_GENERIC -149 770 771/** 772 * The callback associated with the geofence. 773 * Parameters: 774 * geofence_id - The id associated with the add_geofence_area. 775 * location - The current GPS location. 776 * transition - Can be one of GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED, 777 * GPS_GEOFENCE_UNCERTAIN. 778 * timestamp - Timestamp when the transition was detected. 779 * 780 * The callback should only be called when the caller is interested in that 781 * particular transition. For instance, if the caller is interested only in 782 * ENTERED transition, then the callback should NOT be called with the EXITED 783 * transition. 784 * 785 * IMPORTANT: If a transition is triggered resulting in this callback, the GPS 786 * subsystem will wake up the application processor, if its in suspend state. 787 */ 788typedef void (*gps_geofence_transition_callback) (int32_t geofence_id, GpsLocation* location, 789 int32_t transition, GpsUtcTime timestamp); 790 791/** 792 * The callback associated with the availablity of the GPS system for geofencing 793 * monitoring. If the GPS system determines that it cannot monitor geofences 794 * because of lack of reliability or unavailability of the GPS signals, it will 795 * call this callback with GPS_GEOFENCE_UNAVAILABLE parameter. 796 * 797 * Parameters: 798 * status - GPS_GEOFENCE_UNAVAILABLE or GPS_GEOFENCE_AVAILABLE. 799 * last_location - Last known location. 800 */ 801typedef void (*gps_geofence_status_callback) (int32_t status, GpsLocation* last_location); 802 803/** 804 * The callback associated with the add_geofence call. 805 * 806 * Parameter: 807 * geofence_id - Id of the geofence. 808 * status - GPS_GEOFENCE_OPERATION_SUCCESS 809 * GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES - geofence limit has been reached. 810 * GPS_GEOFENCE_ERROR_ID_EXISTS - geofence with id already exists 811 * GPS_GEOFENCE_ERROR_INVALID_TRANSITION - the monitorTransition contains an 812 * invalid transition 813 * GPS_GEOFENCE_ERROR_GENERIC - for other errors. 814 */ 815typedef void (*gps_geofence_add_callback) (int32_t geofence_id, int32_t status); 816 817/** 818 * The callback associated with the remove_geofence call. 819 * 820 * Parameter: 821 * geofence_id - Id of the geofence. 822 * status - GPS_GEOFENCE_OPERATION_SUCCESS 823 * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id 824 * GPS_GEOFENCE_ERROR_GENERIC for others. 825 */ 826typedef void (*gps_geofence_remove_callback) (int32_t geofence_id, int32_t status); 827 828 829/** 830 * The callback associated with the pause_geofence call. 831 * 832 * Parameter: 833 * geofence_id - Id of the geofence. 834 * status - GPS_GEOFENCE_OPERATION_SUCCESS 835 * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id 836 * GPS_GEOFENCE_ERROR_INVALID_TRANSITION - 837 * when monitor_transitions is invalid 838 * GPS_GEOFENCE_ERROR_GENERIC for others. 839 */ 840typedef void (*gps_geofence_pause_callback) (int32_t geofence_id, int32_t status); 841 842/** 843 * The callback associated with the resume_geofence call. 844 * 845 * Parameter: 846 * geofence_id - Id of the geofence. 847 * status - GPS_GEOFENCE_OPERATION_SUCCESS 848 * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id 849 * GPS_GEOFENCE_ERROR_GENERIC for others. 850 */ 851typedef void (*gps_geofence_resume_callback) (int32_t geofence_id, int32_t status); 852 853typedef struct { 854 gps_geofence_transition_callback geofence_transition_callback; 855 gps_geofence_status_callback geofence_status_callback; 856 gps_geofence_add_callback geofence_add_callback; 857 gps_geofence_remove_callback geofence_remove_callback; 858 gps_geofence_pause_callback geofence_pause_callback; 859 gps_geofence_resume_callback geofence_resume_callback; 860 gps_create_thread create_thread_cb; 861} GpsGeofenceCallbacks; 862 863/** Extended interface for GPS_Geofencing support */ 864typedef struct { 865 /** set to sizeof(GpsGeofencingInterface) */ 866 size_t size; 867 868 /** 869 * Opens the geofence interface and provides the callback routines 870 * to the implemenation of this interface. 871 */ 872 void (*init)( GpsGeofenceCallbacks* callbacks ); 873 874 /** 875 * Add a geofence area. This api currently supports circular geofences. 876 * Parameters: 877 * geofence_id - The id for the geofence. If a geofence with this id 878 * already exists, an error value (GPS_GEOFENCE_ERROR_ID_EXISTS) 879 * should be returned. 880 * latitude, longtitude, radius_meters - The lat, long and radius 881 * (in meters) for the geofence 882 * last_transition - The current state of the geofence. For example, if 883 * the system already knows that the user is inside the geofence, 884 * this will be set to GPS_GEOFENCE_ENTERED. In most cases, it 885 * will be GPS_GEOFENCE_UNCERTAIN. 886 * monitor_transition - Which transitions to monitor. Bitwise OR of 887 * GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and 888 * GPS_GEOFENCE_UNCERTAIN. 889 * notification_responsiveness_ms - Defines the best-effort description 890 * of how soon should the callback be called when the transition 891 * associated with the Geofence is triggered. For instance, if set 892 * to 1000 millseconds with GPS_GEOFENCE_ENTERED, the callback 893 * should be called 1000 milliseconds within entering the geofence. 894 * This parameter is defined in milliseconds. 895 * NOTE: This is not to be confused with the rate that the GPS is 896 * polled at. It is acceptable to dynamically vary the rate of 897 * sampling the GPS for power-saving reasons; thus the rate of 898 * sampling may be faster or slower than this. 899 * unknown_timer_ms - The time limit after which the UNCERTAIN transition 900 * should be triggered. This paramter is defined in milliseconds. 901 * See above for a detailed explanation. 902 */ 903 void (*add_geofence_area) (int32_t geofence_id, double latitude, 904 double longitude, double radius_meters, 905 int last_transition, int monitor_transitions, 906 int notification_responsiveness_ms, 907 int unknown_timer_ms); 908 909 /** 910 * Pause monitoring a particular geofence. 911 * Parameters: 912 * geofence_id - The id for the geofence. 913 */ 914 void (*pause_geofence) (int32_t geofence_id); 915 916 /** 917 * Resume monitoring a particular geofence. 918 * Parameters: 919 * geofence_id - The id for the geofence. 920 * monitor_transitions - Which transitions to monitor. Bitwise OR of 921 * GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and 922 * GPS_GEOFENCE_UNCERTAIN. 923 * This supersedes the value associated provided in the 924 * add_geofence_area call. 925 */ 926 void (*resume_geofence) (int32_t geofence_id, int monitor_transitions); 927 928 /** 929 * Remove a geofence area. After the function returns, no notifications 930 * should be sent. 931 * Parameter: 932 * geofence_id - The id for the geofence. 933 */ 934 void (*remove_geofence_area) (int32_t geofence_id); 935} GpsGeofencingInterface; 936__END_DECLS 937 938#endif /* ANDROID_INCLUDE_HARDWARE_GPS_H */ 939 940