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  * 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. */
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. */
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 {
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;
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  */
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  */
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)();
438 
439 struct flp_device_t {
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 
462 
463  /** reports diagnostic data into the Java framework code */
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 );
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);
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;
691 
692 
693 /** Type of geofence */
694 typedef enum {
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;
704 
705 /** Represents the type of geofence and data */
706 typedef struct {
708  union {
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. */
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  */
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  */
742 
743  /**
744  * The time limit after which the UNCERTAIN transition
745  * should be triggered. This paramter is defined in milliseconds.
746  */
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;
755 
756 /** Geofence struct */
757 typedef struct {
758  int32_t geofence_id;
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);
821 
822 __END_DECLS
823 
824 #endif /* ANDROID_INCLUDE_HARDWARE_FLP_H */
825 
flp_geofence_monitor_status_callback geofence_status_callback
double max_power_allocation_mW
int32_t geofence_id
uint32_t sources_to_use
void(* report_data)(char *data, int length)
flp_capabilities_callback flp_capabilities_cb
flp_geofence_add_callback geofence_add_callback
flp_set_thread_event set_thread_event_cb
uint32_t sources_to_use
flp_geofence_pause_callback geofence_pause_callback
double longitude
void(* flp_release_wakelock)()
void(* flp_geofence_resume_callback)(int32_t geofence_id, int32_t result)
void(* flp_status_callback)(int32_t status)
flp_acquire_wakelock acquire_wakelock_cb
GeofenceType
GeofenceCircle circle
flp_geofence_remove_callback geofence_remove_callback
void(* flp_capabilities_callback)(int capabilities)
FlpUtcTime timestamp
flp_capabilities_callback flp_capabilities_cb
flp_set_thread_event set_thread_event_cb
GeofenceOptions * options
uint32_t sources_used
void(* flp_geofence_pause_callback)(int32_t geofence_id, int32_t result)
FlpLocationFlags flags
flp_geofence_resume_callback geofence_resume_callback
void(* flp_geofence_add_callback)(int32_t geofence_id, int32_t result)
uint16_t FlpLocationFlags
ThreadEvent
void(* flp_geofence_monitor_status_callback)(int32_t status, uint32_t source, FlpLocation *last_location)
float smallest_displacement_meters
void(* flp_location_callback)(int32_t num_locations, FlpLocation **location)
void(* flp_acquire_wakelock)()
void(* flp_geofence_transition_callback)(int32_t geofence_id, FlpLocation *location, int32_t transition, FlpUtcTime timestamp, uint32_t sources_used)
flp_location_callback location_cb
int64_t FlpUtcTime
struct hw_device_t common
GeofenceData * data
int(* flp_set_thread_event)(ThreadEvent event)
flp_release_wakelock release_wakelock_cb
GeofenceType type
void(* flp_geofence_remove_callback)(int32_t geofence_id, int32_t result)
int notification_responsivenes_ms
flp_geofence_transition_callback geofence_transition_callback
flp_status_callback flp_status_cb
flp_set_thread_event set_thread_event_cb