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