1 /* 2 * Copyright (C) 2013 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_FUSED_LOCATION_H 18 #define ANDROID_INCLUDE_HARDWARE_FUSED_LOCATION_H 19 20 #include <hardware/hardware.h> 21 22 23 /** 24 * This header file defines the interface of the Fused Location Provider. 25 * Fused Location Provider is designed to fuse data from various sources 26 * like GPS, Wifi, Cell, Sensors, Bluetooth etc to provide a fused location to the 27 * upper layers. The advantage of doing fusion in hardware is power savings. 28 * The goal is to do this without waking up the AP to get additional data. 29 * The software implementation of FLP will decide when to use 30 * the hardware fused location. Other location features like geofencing will 31 * also be implemented using fusion in hardware. 32 */ 33 __BEGIN_DECLS 34 35 #define FLP_HEADER_VERSION 1 36 #define FLP_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 37 #define FLP_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, FLP_HEADER_VERSION) 38 39 /** 40 * The id of this module 41 */ 42 #define FUSED_LOCATION_HARDWARE_MODULE_ID "flp" 43 44 /** 45 * Name for the FLP location interface 46 */ 47 #define FLP_LOCATION_INTERFACE "flp_location" 48 49 /** 50 * Name for the FLP location interface 51 */ 52 #define FLP_DIAGNOSTIC_INTERFACE "flp_diagnostic" 53 54 /** 55 * Name for the FLP_Geofencing interface. 56 */ 57 #define FLP_GEOFENCING_INTERFACE "flp_geofencing" 58 59 /** 60 * Name for the FLP_device context interface. 61 */ 62 #define FLP_DEVICE_CONTEXT_INTERFACE "flp_device_context" 63 64 /** 65 * Constants to indicate the various subsystems 66 * that will be used. 67 */ 68 #define FLP_TECH_MASK_GNSS (1U<<0) 69 #define FLP_TECH_MASK_WIFI (1U<<1) 70 #define FLP_TECH_MASK_SENSORS (1U<<2) 71 #define FLP_TECH_MASK_CELL (1U<<3) 72 #define FLP_TECH_MASK_BLUETOOTH (1U<<4) 73 74 /** 75 * Set when your implementation can produce GNNS-derived locations, 76 * for use with flp_capabilities_callback. 77 * 78 * GNNS is a required capability for a particular feature to be used 79 * (batching or geofencing). If not supported that particular feature 80 * won't be used by the upper layer. 81 */ 82 #define CAPABILITY_GNSS (1U<<0) 83 /** 84 * Set when your implementation can produce WiFi-derived locations, for 85 * use with flp_capabilities_callback. 86 */ 87 #define CAPABILITY_WIFI (1U<<1) 88 /** 89 * Set when your implementation can produce cell-derived locations, for 90 * use with flp_capabilities_callback. 91 */ 92 #define CAPABILITY_CELL (1U<<3) 93 94 /** 95 * Status to return in flp_status_callback when your implementation transitions 96 * from being unsuccessful in determining location to being successful. 97 */ 98 #define FLP_STATUS_LOCATION_AVAILABLE 0 99 /** 100 * Status to return in flp_status_callback when your implementation transitions 101 * from being successful in determining location to being unsuccessful. 102 */ 103 #define FLP_STATUS_LOCATION_UNAVAILABLE 1 104 105 /** 106 * This constant is used with the batched locations 107 * APIs. Batching is mandatory when FLP implementation 108 * is supported. If the flag is set, the hardware implementation 109 * will wake up the application processor when the FIFO is full, 110 * If the flag is not set, the hardware implementation will drop 111 * the oldest data when the FIFO is full. 112 */ 113 #define FLP_BATCH_WAKEUP_ON_FIFO_FULL 0x0000001 114 115 /** 116 * While batching, the implementation should not call the 117 * flp_location_callback on every location fix. However, 118 * sometimes in high power mode, the system might need 119 * a location callback every single time the location 120 * fix has been obtained. This flag controls that option. 121 * Its the responsibility of the upper layers (caller) to switch 122 * it off, if it knows that the AP might go to sleep. 123 * When this bit is on amidst a batching session, batching should 124 * continue while location fixes are reported in real time. 125 */ 126 #define FLP_BATCH_CALLBACK_ON_LOCATION_FIX 0x0000002 127 128 /** Flags to indicate which values are valid in a FlpLocation. */ 129 typedef uint16_t FlpLocationFlags; 130 131 // IMPORTANT: Note that the following values must match 132 // constants in the corresponding java file. 133 134 /** FlpLocation has valid latitude and longitude. */ 135 #define FLP_LOCATION_HAS_LAT_LONG (1U<<0) 136 /** FlpLocation has valid altitude. */ 137 #define FLP_LOCATION_HAS_ALTITUDE (1U<<1) 138 /** FlpLocation has valid speed. */ 139 #define FLP_LOCATION_HAS_SPEED (1U<<2) 140 /** FlpLocation has valid bearing. */ 141 #define FLP_LOCATION_HAS_BEARING (1U<<4) 142 /** FlpLocation has valid accuracy. */ 143 #define FLP_LOCATION_HAS_ACCURACY (1U<<8) 144 145 146 typedef int64_t FlpUtcTime; 147 148 /** Represents a location. */ 149 typedef struct { 150 /** set to sizeof(FlpLocation) */ 151 size_t size; 152 153 /** Flags associated with the location object. */ 154 FlpLocationFlags flags; 155 156 /** Represents latitude in degrees. */ 157 double latitude; 158 159 /** Represents longitude in degrees. */ 160 double longitude; 161 162 /** 163 * Represents altitude in meters above the WGS 84 reference 164 * ellipsoid. */ 165 double altitude; 166 167 /** Represents speed in meters per second. */ 168 float speed; 169 170 /** Represents heading in degrees. */ 171 float bearing; 172 173 /** Represents expected accuracy in meters. */ 174 float accuracy; 175 176 /** Timestamp for the location fix. */ 177 FlpUtcTime timestamp; 178 179 /** Sources used, will be Bitwise OR of the FLP_TECH_MASK bits. */ 180 uint32_t sources_used; 181 } FlpLocation; 182 183 typedef enum { 184 ASSOCIATE_JVM, 185 DISASSOCIATE_JVM, 186 } ThreadEvent; 187 188 /** 189 * Callback with location information. 190 * Can only be called from a thread associated to JVM using set_thread_event_cb. 191 * Parameters: 192 * num_locations is the number of batched locations available. 193 * location is the pointer to an array of pointers to location objects. 194 */ 195 typedef void (*flp_location_callback)(int32_t num_locations, FlpLocation** location); 196 197 /** 198 * Callback utility for acquiring a wakelock. 199 * This can be used to prevent the CPU from suspending while handling FLP events. 200 */ 201 typedef void (*flp_acquire_wakelock)(); 202 203 /** 204 * Callback utility for releasing the FLP wakelock. 205 */ 206 typedef void (*flp_release_wakelock)(); 207 208 /** 209 * Callback for associating a thread that can call into the Java framework code. 210 * This must be used to initialize any threads that report events up to the framework. 211 * Return value: 212 * FLP_RESULT_SUCCESS on success. 213 * FLP_RESULT_ERROR if the association failed in the current thread. 214 */ 215 typedef int (*flp_set_thread_event)(ThreadEvent event); 216 217 /** 218 * Callback for technologies supported by this implementation. 219 * 220 * Parameters: capabilities is a bitmask of FLP_CAPABILITY_* values describing 221 * which features your implementation supports. You should support 222 * CAPABILITY_GNSS at a minimum for your implementation to be utilized. You can 223 * return 0 in FlpGeofenceCallbacks to indicate you don't support geofencing, 224 * or 0 in FlpCallbacks to indicate you don't support location batching. 225 */ 226 typedef void (*flp_capabilities_callback)(int capabilities); 227 228 /** 229 * Callback with status information on the ability to compute location. 230 * To avoid waking up the application processor you should only send 231 * changes in status (you shouldn't call this method twice in a row 232 * with the same status value). As a guideline you should not call this 233 * more frequently then the requested batch period set with period_ns 234 * in FlpBatchOptions. For example if period_ns is set to 5 minutes and 235 * the status changes many times in that interval, you should only report 236 * one status change every 5 minutes. 237 * 238 * Parameters: 239 * status is one of FLP_STATUS_LOCATION_AVAILABLE 240 * or FLP_STATUS_LOCATION_UNAVAILABLE. 241 */ 242 typedef void (*flp_status_callback)(int32_t status); 243 244 /** FLP callback structure. */ 245 typedef struct { 246 /** set to sizeof(FlpCallbacks) */ 247 size_t size; 248 flp_location_callback location_cb; 249 flp_acquire_wakelock acquire_wakelock_cb; 250 flp_release_wakelock release_wakelock_cb; 251 flp_set_thread_event set_thread_event_cb; 252 flp_capabilities_callback flp_capabilities_cb; 253 flp_status_callback flp_status_cb; 254 } FlpCallbacks; 255 256 257 /** Options with the batching FLP APIs */ 258 typedef struct { 259 /** 260 * Maximum power in mW that the underlying implementation 261 * can use for this batching call. 262 * If max_power_allocation_mW is 0, only fixes that are generated 263 * at no additional cost of power shall be reported. 264 */ 265 double max_power_allocation_mW; 266 267 /** Bitwise OR of the FLP_TECH_MASKS to use */ 268 uint32_t sources_to_use; 269 270 /** 271 * FLP_BATCH_WAKEUP_ON_FIFO_FULL - If set the hardware 272 * will wake up the AP when the buffer is full. If not set, the 273 * hardware will drop the oldest location object. 274 * 275 * FLP_BATCH_CALLBACK_ON_LOCATION_FIX - If set the location 276 * callback will be called every time there is a location fix. 277 * Its the responsibility of the upper layers (caller) to switch 278 * it off, if it knows that the AP might go to sleep. When this 279 * bit is on amidst a batching session, batching should continue 280 * while location fixes are reported in real time. 281 * 282 * Other flags to be bitwised ORed in the future. 283 */ 284 uint32_t flags; 285 286 /** 287 * Frequency with which location needs to be batched in nano 288 * seconds. 289 */ 290 int64_t period_ns; 291 292 /** 293 * The smallest displacement between reported locations in meters. 294 * 295 * If set to 0, then you should report locations at the requested 296 * interval even if the device is stationary. If positive, you 297 * can use this parameter as a hint to save power (e.g. throttling 298 * location period if the user hasn't traveled close to the displacement 299 * threshold). Even small positive values can be interpreted to mean 300 * that you don't have to compute location when the device is stationary. 301 * 302 * There is no need to filter location delivery based on this parameter. 303 * Locations can be delivered even if they have a displacement smaller than 304 * requested. This parameter can safely be ignored at the cost of potential 305 * power savings. 306 */ 307 float smallest_displacement_meters; 308 } FlpBatchOptions; 309 310 #define FLP_RESULT_SUCCESS 0 311 #define FLP_RESULT_ERROR -1 312 #define FLP_RESULT_INSUFFICIENT_MEMORY -2 313 #define FLP_RESULT_TOO_MANY_GEOFENCES -3 314 #define FLP_RESULT_ID_EXISTS -4 315 #define FLP_RESULT_ID_UNKNOWN -5 316 #define FLP_RESULT_INVALID_GEOFENCE_TRANSITION -6 317 318 /** 319 * Represents the standard FLP interface. 320 */ 321 typedef struct { 322 /** 323 * set to sizeof(FlpLocationInterface) 324 */ 325 size_t size; 326 327 /** 328 * Opens the interface and provides the callback routines 329 * to the implementation of this interface. Once called you should respond 330 * by calling the flp_capabilities_callback in FlpCallbacks to 331 * specify the capabilities that your implementation supports. 332 */ 333 int (*init)(FlpCallbacks* callbacks ); 334 335 /** 336 * Return the batch size (in number of FlpLocation objects) 337 * available in the hardware. Note, different HW implementations 338 * may have different sample sizes. This shall return number 339 * of samples defined in the format of FlpLocation. 340 * This will be used by the upper layer, to decide on the batching 341 * interval and whether the AP should be woken up or not. 342 */ 343 int (*get_batch_size)(); 344 345 /** 346 * Start batching locations. This API is primarily used when the AP is 347 * asleep and the device can batch locations in the hardware. 348 * flp_location_callback is used to return the locations. When the buffer 349 * is full and FLP_BATCH_WAKEUP_ON_FIFO_FULL is used, the AP is woken up. 350 * When the buffer is full and FLP_BATCH_WAKEUP_ON_FIFO_FULL is not set, 351 * the oldest location object is dropped. In this case the AP will not be 352 * woken up. The upper layer will use get_batched_location 353 * API to explicitly ask for the location. 354 * If FLP_BATCH_CALLBACK_ON_LOCATION_FIX is set, the implementation 355 * will call the flp_location_callback every single time there is a location 356 * fix. This overrides FLP_BATCH_WAKEUP_ON_FIFO_FULL flag setting. 357 * It's the responsibility of the upper layers (caller) to switch 358 * it off, if it knows that the AP might go to sleep. This is useful 359 * for nagivational applications when the system is in high power mode. 360 * Parameters: 361 * id - Id for the request. 362 * options - See FlpBatchOptions struct definition. 363 * Return value: 364 * FLP_RESULT_SUCCESS on success, FLP_RESULT_INSUFFICIENT_MEMORY, 365 * FLP_RESULT_ID_EXISTS, FLP_RESULT_ERROR on failure. 366 */ 367 int (*start_batching)(int id, FlpBatchOptions* options); 368 369 /** 370 * Update FlpBatchOptions associated with a batching request. 371 * When a batching operation is in progress and a batching option 372 * such as FLP_BATCH_WAKEUP_ON_FIFO_FULL needs to be updated, this API 373 * will be used. For instance, this can happen when the AP is awake and 374 * the maps application is being used. 375 * Parameters: 376 * id - Id of an existing batch request. 377 * new_options - Updated FlpBatchOptions 378 * Return value: 379 * FLP_RESULT_SUCCESS on success, FLP_RESULT_ID_UNKNOWN, 380 * FLP_RESULT_ERROR on error. 381 */ 382 int (*update_batching_options)(int id, FlpBatchOptions* new_options); 383 384 /** 385 * Stop batching. 386 * Parameters: 387 * id - Id for the request. 388 * Return Value: 389 * FLP_RESULT_SUCCESS on success, FLP_RESULT_ID_UNKNOWN or 390 * FLP_RESULT_ERROR on failure. 391 */ 392 int (*stop_batching)(int id); 393 394 /** 395 * Closes the interface. If any batch operations are in progress, 396 * they should be stopped. 397 */ 398 void (*cleanup)(); 399 400 /** 401 * Get the fused location that was batched. 402 * flp_location_callback is used to return the location. The location object 403 * is dropped from the buffer only when the buffer is full. Do not remove it 404 * from the buffer just because it has been returned using the callback. 405 * In other words, when there is no new location object, two calls to 406 * get_batched_location(1) should return the same location object. 407 * Parameters: 408 * last_n_locations - Number of locations to get. This can be one or many. 409 * If the last_n_locations is 1, you get the latest location known to the 410 * hardware. 411 */ 412 void (*get_batched_location)(int last_n_locations); 413 414 /** 415 * Injects current location from another location provider 416 * latitude and longitude are measured in degrees 417 * expected accuracy is measured in meters 418 * Parameters: 419 * location - The location object being injected. 420 * Return value: FLP_RESULT_SUCCESS or FLP_RESULT_ERROR. 421 */ 422 int (*inject_location)(FlpLocation* location); 423 424 /** 425 * Get a pointer to extension information. 426 */ 427 const void* (*get_extension)(const char* name); 428 429 /** 430 * Retrieve all batched locations currently stored and clear the buffer. 431 * flp_location_callback MUST be called in response, even if there are 432 * no locations to flush (in which case num_locations should be 0). 433 * Subsequent calls to get_batched_location or flush_batched_locations 434 * should not return any of the locations returned in this call. 435 */ 436 void (*flush_batched_locations)(); 437 } FlpLocationInterface; 438 439 struct flp_device_t { 440 struct hw_device_t common; 441 442 /** 443 * Get a handle to the FLP Interface. 444 */ 445 const FlpLocationInterface* (*get_flp_interface)(struct flp_device_t* dev); 446 }; 447 448 /** 449 * Callback for reports diagnostic data into the Java framework code. 450 */ 451 typedef void (*report_data)(char* data, int length); 452 453 /** 454 * FLP diagnostic callback structure. 455 * Currently, not used - but this for future extension. 456 */ 457 typedef struct { 458 /** set to sizeof(FlpDiagnosticCallbacks) */ 459 size_t size; 460 461 flp_set_thread_event set_thread_event_cb; 462 463 /** reports diagnostic data into the Java framework code */ 464 report_data data_cb; 465 } FlpDiagnosticCallbacks; 466 467 /** Extended interface for diagnostic support. */ 468 typedef struct { 469 /** set to sizeof(FlpDiagnosticInterface) */ 470 size_t size; 471 472 /** 473 * Opens the diagnostic interface and provides the callback routines 474 * to the implemenation of this interface. 475 */ 476 void (*init)(FlpDiagnosticCallbacks* callbacks); 477 478 /** 479 * Injects diagnostic data into the FLP subsystem. 480 * Return 0 on success, -1 on error. 481 **/ 482 int (*inject_data)(char* data, int length ); 483 } FlpDiagnosticInterface; 484 485 /** 486 * Context setting information. 487 * All these settings shall be injected to FLP HAL at FLP init time. 488 * Following that, only the changed setting need to be re-injected 489 * upon changes. 490 */ 491 492 #define FLP_DEVICE_CONTEXT_GPS_ENABLED (1U<<0) 493 #define FLP_DEVICE_CONTEXT_AGPS_ENABLED (1U<<1) 494 #define FLP_DEVICE_CONTEXT_NETWORK_POSITIONING_ENABLED (1U<<2) 495 #define FLP_DEVICE_CONTEXT_WIFI_CONNECTIVITY_ENABLED (1U<<3) 496 #define FLP_DEVICE_CONTEXT_WIFI_POSITIONING_ENABLED (1U<<4) 497 #define FLP_DEVICE_CONTEXT_HW_NETWORK_POSITIONING_ENABLED (1U<<5) 498 #define FLP_DEVICE_CONTEXT_AIRPLANE_MODE_ON (1U<<6) 499 #define FLP_DEVICE_CONTEXT_DATA_ENABLED (1U<<7) 500 #define FLP_DEVICE_CONTEXT_ROAMING_ENABLED (1U<<8) 501 #define FLP_DEVICE_CONTEXT_CURRENTLY_ROAMING (1U<<9) 502 #define FLP_DEVICE_CONTEXT_SENSOR_ENABLED (1U<<10) 503 #define FLP_DEVICE_CONTEXT_BLUETOOTH_ENABLED (1U<<11) 504 #define FLP_DEVICE_CONTEXT_CHARGER_ON (1U<<12) 505 506 /** Extended interface for device context support. */ 507 typedef struct { 508 /** set to sizeof(FlpDeviceContextInterface) */ 509 size_t size; 510 511 /** 512 * Injects debug data into the FLP subsystem. 513 * Return 0 on success, -1 on error. 514 **/ 515 int (*inject_device_context)(uint32_t enabledMask); 516 } FlpDeviceContextInterface; 517 518 519 /** 520 * There are 3 states associated with a Geofence: Inside, Outside, Unknown. 521 * There are 3 transitions: ENTERED, EXITED, UNCERTAIN. 522 * 523 * An example state diagram with confidence level: 95% and Unknown time limit 524 * set as 30 secs is shown below. (confidence level and Unknown time limit are 525 * explained latter) 526 * ____________________________ 527 * | Unknown (30 secs) | 528 * """""""""""""""""""""""""""" 529 * ^ | | ^ 530 * UNCERTAIN| |ENTERED EXITED| |UNCERTAIN 531 * | v v | 532 * ________ EXITED _________ 533 * | Inside | -----------> | Outside | 534 * | | <----------- | | 535 * """""""" ENTERED """"""""" 536 * 537 * Inside state: We are 95% confident that the user is inside the geofence. 538 * Outside state: We are 95% confident that the user is outside the geofence 539 * Unknown state: Rest of the time. 540 * 541 * The Unknown state is better explained with an example: 542 * 543 * __________ 544 * | c| 545 * | ___ | _______ 546 * | |a| | | b | 547 * | """ | """"""" 548 * | | 549 * """""""""" 550 * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy 551 * circle reported by the FLP subsystem. Now with regard to "b", the system is 552 * confident that the user is outside. But with regard to "a" is not confident 553 * whether it is inside or outside the geofence. If the accuracy remains the 554 * same for a sufficient period of time, the UNCERTAIN transition would be 555 * triggered with the state set to Unknown. If the accuracy improves later, an 556 * appropriate transition should be triggered. This "sufficient period of time" 557 * is defined by the parameter in the add_geofence_area API. 558 * In other words, Unknown state can be interpreted as a state in which the 559 * FLP subsystem isn't confident enough that the user is either inside or 560 * outside the Geofence. It moves to Unknown state only after the expiry of the 561 * timeout. 562 * 563 * The geofence callback needs to be triggered for the ENTERED and EXITED 564 * transitions, when the FLP system is confident that the user has entered 565 * (Inside state) or exited (Outside state) the Geofence. An implementation 566 * which uses a value of 95% as the confidence is recommended. The callback 567 * should be triggered only for the transitions requested by the 568 * add_geofence_area call. 569 * 570 * Even though the diagram and explanation talks about states and transitions, 571 * the callee is only interested in the transistions. The states are mentioned 572 * here for illustrative purposes. 573 * 574 * Startup Scenario: When the device boots up, if an application adds geofences, 575 * and then we get an accurate FLP location fix, it needs to trigger the 576 * appropriate (ENTERED or EXITED) transition for every Geofence it knows about. 577 * By default, all the Geofences will be in the Unknown state. 578 * 579 * When the FLP system is unavailable, flp_geofence_status_callback should be 580 * called to inform the upper layers of the same. Similarly, when it becomes 581 * available the callback should be called. This is a global state while the 582 * UNKNOWN transition described above is per geofence. 583 * 584 */ 585 #define FLP_GEOFENCE_TRANSITION_ENTERED (1L<<0) 586 #define FLP_GEOFENCE_TRANSITION_EXITED (1L<<1) 587 #define FLP_GEOFENCE_TRANSITION_UNCERTAIN (1L<<2) 588 589 #define FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE (1L<<0) 590 #define FLP_GEOFENCE_MONITOR_STATUS_AVAILABLE (1L<<1) 591 592 /** 593 * The callback associated with the geofence. 594 * Parameters: 595 * geofence_id - The id associated with the add_geofence_area. 596 * location - The current location as determined by the FLP subsystem. 597 * transition - Can be one of FLP_GEOFENCE_TRANSITION_ENTERED, FLP_GEOFENCE_TRANSITION_EXITED, 598 * FLP_GEOFENCE_TRANSITION_UNCERTAIN. 599 * timestamp - Timestamp when the transition was detected; -1 if not available. 600 * sources_used - Bitwise OR of FLP_TECH_MASK flags indicating which 601 * subsystems were used. 602 * 603 * The callback should only be called when the caller is interested in that 604 * particular transition. For instance, if the caller is interested only in 605 * ENTERED transition, then the callback should NOT be called with the EXITED 606 * transition. 607 * 608 * IMPORTANT: If a transition is triggered resulting in this callback, the 609 * subsystem will wake up the application processor, if its in suspend state. 610 */ 611 typedef void (*flp_geofence_transition_callback) (int32_t geofence_id, FlpLocation* location, 612 int32_t transition, FlpUtcTime timestamp, uint32_t sources_used); 613 614 /** 615 * The callback associated with the availablity of one the sources used for geofence 616 * monitoring by the FLP sub-system For example, if the GPS system determines that it cannot 617 * monitor geofences because of lack of reliability or unavailability of the GPS signals, 618 * it will call this callback with FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE parameter and the 619 * source set to FLP_TECH_MASK_GNSS. 620 * 621 * Parameters: 622 * status - FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE or FLP_GEOFENCE_MONITOR_STATUS_AVAILABLE. 623 * source - One of the FLP_TECH_MASKS 624 * last_location - Last known location. 625 */ 626 typedef void (*flp_geofence_monitor_status_callback) (int32_t status, uint32_t source, 627 FlpLocation* last_location); 628 629 /** 630 * The callback associated with the add_geofence call. 631 * 632 * Parameter: 633 * geofence_id - Id of the geofence. 634 * result - FLP_RESULT_SUCCESS 635 * FLP_RESULT_ERROR_TOO_MANY_GEOFENCES - geofence limit has been reached. 636 * FLP_RESULT_ID_EXISTS - geofence with id already exists 637 * FLP_RESULT_INVALID_GEOFENCE_TRANSITION - the monitorTransition contains an 638 * invalid transition 639 * FLP_RESULT_ERROR - for other errors. 640 */ 641 typedef void (*flp_geofence_add_callback) (int32_t geofence_id, int32_t result); 642 643 /** 644 * The callback associated with the remove_geofence call. 645 * 646 * Parameter: 647 * geofence_id - Id of the geofence. 648 * result - FLP_RESULT_SUCCESS 649 * FLP_RESULT_ID_UNKNOWN - for invalid id 650 * FLP_RESULT_ERROR for others. 651 */ 652 typedef void (*flp_geofence_remove_callback) (int32_t geofence_id, int32_t result); 653 654 655 /** 656 * The callback associated with the pause_geofence call. 657 * 658 * Parameter: 659 * geofence_id - Id of the geofence. 660 * result - FLP_RESULT_SUCCESS 661 * FLP_RESULT__ID_UNKNOWN - for invalid id 662 * FLP_RESULT_INVALID_TRANSITION - 663 * when monitor_transitions is invalid 664 * FLP_RESULT_ERROR for others. 665 */ 666 typedef void (*flp_geofence_pause_callback) (int32_t geofence_id, int32_t result); 667 668 /** 669 * The callback associated with the resume_geofence call. 670 * 671 * Parameter: 672 * geofence_id - Id of the geofence. 673 * result - FLP_RESULT_SUCCESS 674 * FLP_RESULT_ID_UNKNOWN - for invalid id 675 * FLP_RESULT_ERROR for others. 676 */ 677 typedef void (*flp_geofence_resume_callback) (int32_t geofence_id, int32_t result); 678 679 typedef struct { 680 /** set to sizeof(FlpGeofenceCallbacks) */ 681 size_t size; 682 flp_geofence_transition_callback geofence_transition_callback; 683 flp_geofence_monitor_status_callback geofence_status_callback; 684 flp_geofence_add_callback geofence_add_callback; 685 flp_geofence_remove_callback geofence_remove_callback; 686 flp_geofence_pause_callback geofence_pause_callback; 687 flp_geofence_resume_callback geofence_resume_callback; 688 flp_set_thread_event set_thread_event_cb; 689 flp_capabilities_callback flp_capabilities_cb; 690 } FlpGeofenceCallbacks; 691 692 693 /** Type of geofence */ 694 typedef enum { 695 TYPE_CIRCLE = 0, 696 } GeofenceType; 697 698 /** Circular geofence is represented by lat / long / radius */ 699 typedef struct { 700 double latitude; 701 double longitude; 702 double radius_m; 703 } GeofenceCircle; 704 705 /** Represents the type of geofence and data */ 706 typedef struct { 707 GeofenceType type; 708 union { 709 GeofenceCircle circle; 710 } geofence; 711 } GeofenceData; 712 713 /** Geofence Options */ 714 typedef struct { 715 /** 716 * The current state of the geofence. For example, if 717 * the system already knows that the user is inside the geofence, 718 * this will be set to FLP_GEOFENCE_TRANSITION_ENTERED. In most cases, it 719 * will be FLP_GEOFENCE_TRANSITION_UNCERTAIN. */ 720 int last_transition; 721 722 /** 723 * Transitions to monitor. Bitwise OR of 724 * FLP_GEOFENCE_TRANSITION_ENTERED, FLP_GEOFENCE_TRANSITION_EXITED and 725 * FLP_GEOFENCE_TRANSITION_UNCERTAIN. 726 */ 727 int monitor_transitions; 728 729 /** 730 * Defines the best-effort description 731 * of how soon should the callback be called when the transition 732 * associated with the Geofence is triggered. For instance, if set 733 * to 1000 millseconds with FLP_GEOFENCE_TRANSITION_ENTERED, the callback 734 * should be called 1000 milliseconds within entering the geofence. 735 * This parameter is defined in milliseconds. 736 * NOTE: This is not to be confused with the rate that the GPS is 737 * polled at. It is acceptable to dynamically vary the rate of 738 * sampling the GPS for power-saving reasons; thus the rate of 739 * sampling may be faster or slower than this. 740 */ 741 int notification_responsivenes_ms; 742 743 /** 744 * The time limit after which the UNCERTAIN transition 745 * should be triggered. This paramter is defined in milliseconds. 746 */ 747 int unknown_timer_ms; 748 749 /** 750 * The sources to use for monitoring geofences. Its a BITWISE-OR 751 * of FLP_TECH_MASK flags. 752 */ 753 uint32_t sources_to_use; 754 } GeofenceOptions; 755 756 /** Geofence struct */ 757 typedef struct { 758 int32_t geofence_id; 759 GeofenceData* data; 760 GeofenceOptions* options; 761 } Geofence; 762 763 /** Extended interface for FLP_Geofencing support */ 764 typedef struct { 765 /** set to sizeof(FlpGeofencingInterface) */ 766 size_t size; 767 768 /** 769 * Opens the geofence interface and provides the callback routines 770 * to the implemenation of this interface. Once called you should respond 771 * by calling the flp_capabilities_callback in FlpGeofenceCallbacks to 772 * specify the capabilities that your implementation supports. 773 */ 774 void (*init)( FlpGeofenceCallbacks* callbacks ); 775 776 /** 777 * Add a list of geofences. 778 * Parameters: 779 * number_of_geofences - The number of geofences that needed to be added. 780 * geofences - Pointer to array of pointers to Geofence structure. 781 */ 782 void (*add_geofences) (int32_t number_of_geofences, Geofence** geofences); 783 784 /** 785 * Pause monitoring a particular geofence. 786 * Parameters: 787 * geofence_id - The id for the geofence. 788 */ 789 void (*pause_geofence) (int32_t geofence_id); 790 791 /** 792 * Resume monitoring a particular geofence. 793 * Parameters: 794 * geofence_id - The id for the geofence. 795 * monitor_transitions - Which transitions to monitor. Bitwise OR of 796 * FLP_GEOFENCE_TRANSITION_ENTERED, FLP_GEOFENCE_TRANSITION_EXITED and 797 * FLP_GEOFENCE_TRANSITION_UNCERTAIN. 798 * This supersedes the value associated provided in the 799 * add_geofence_area call. 800 */ 801 void (*resume_geofence) (int32_t geofence_id, int monitor_transitions); 802 803 /** 804 * Modify a particular geofence option. 805 * Parameters: 806 * geofence_id - The id for the geofence. 807 * options - Various options associated with the geofence. See 808 * GeofenceOptions structure for details. 809 */ 810 void (*modify_geofence_option) (int32_t geofence_id, GeofenceOptions* options); 811 812 /** 813 * Remove a list of geofences. After the function returns, no notifications 814 * should be sent. 815 * Parameter: 816 * number_of_geofences - The number of geofences that needed to be added. 817 * geofence_id - Pointer to array of geofence_ids to be removed. 818 */ 819 void (*remove_geofences) (int32_t number_of_geofences, int32_t* geofence_id); 820 } FlpGeofencingInterface; 821 822 __END_DECLS 823 824 #endif /* ANDROID_INCLUDE_HARDWARE_FLP_H */ 825 826