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