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