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 /** 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(). */ 111 typedef 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 */ 129 typedef uint16_t AGpsType; 130 #define AGPS_TYPE_SUPL 1 131 #define AGPS_TYPE_C2K 2 132 133 typedef 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 */ 147 typedef 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 */ 155 typedef 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 */ 167 typedef 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 */ 175 typedef 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. */ 183 typedef 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. */ 240 typedef 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. */ 263 typedef struct { 264 /** set to sizeof(GpsStatus) */ 265 size_t size; 266 GpsStatusValue status; 267 } GpsStatus; 268 269 /** Represents SV information. */ 270 typedef 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. */ 284 typedef 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 */ 313 typedef struct { 314 uint16_t type; 315 uint16_t mcc; 316 uint16_t mnc; 317 uint16_t lac; 318 uint32_t cid; 319 } AGpsRefLocationCellID; 320 321 typedef struct { 322 uint8_t mac[6]; 323 } AGpsRefLocationMac; 324 325 /** Represents ref locations */ 326 typedef 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 */ 337 typedef 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 */ 342 typedef 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 */ 347 typedef 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 */ 352 typedef 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 */ 357 typedef 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 */ 362 typedef void (* gps_acquire_wakelock)(); 363 364 /** Callback utility for releasing the GPS wakelock. */ 365 typedef void (* gps_release_wakelock)(); 366 367 /** Callback for requesting NTP time */ 368 typedef 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 */ 373 typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg); 374 375 /** GPS callback structure. */ 376 typedef 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. */ 392 typedef 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 */ 444 typedef void (* gps_xtra_download_request)(); 445 446 /** Callback structure for the XTRA interface. */ 447 typedef 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. */ 453 typedef 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. */ 466 typedef 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. */ 478 typedef 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 */ 490 typedef void (* agps_status_callback)(AGpsStatus* status); 491 492 /** Callback structure for the AGPS interface. */ 493 typedef struct { 494 agps_status_callback status_cb; 495 gps_create_thread create_thread_cb; 496 } AGpsCallbacks; 497 498 499 /** Extended interface for AGPS support. */ 500 typedef 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 */ 530 typedef 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 */ 594 typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification); 595 596 /** GPS NI callback structure. */ 597 typedef 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 */ 609 typedef 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 621 struct 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 638 typedef void (*agps_ril_request_set_id)(uint32_t flags); 639 typedef void (*agps_ril_request_ref_loc)(uint32_t flags); 640 641 typedef 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. */ 648 typedef 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 */ 788 typedef 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 */ 801 typedef 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 */ 815 typedef 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 */ 826 typedef 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 */ 840 typedef 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 */ 851 typedef void (*gps_geofence_resume_callback) (int32_t geofence_id, int32_t status); 852 853 typedef 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 */ 864 typedef 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
