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. */
120typedef 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
137typedef int64_t FlpUtcTime;
138
139/** Represents a location. */
140typedef 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
174typedef 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 */
186typedef 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 */
192typedef void (*flp_acquire_wakelock)();
193
194/**
195 * Callback utility for releasing the FLP wakelock.
196 */
197typedef 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 */
206typedef 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 */
217typedef 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 */
233typedef void (*flp_status_callback)(int32_t status);
234
235/** FLP callback structure. */
236typedef 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 */
249typedef 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 */
312typedef 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
430struct 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*/
442typedef void (*report_data)(char* data, int length);
443
444/**
445 * FLP diagnostic callback structure.
446 * Currently, not used - but this for future extension.
447 */
448typedef 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. */
459typedef 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. */
498typedef 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 */
602typedef 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 */
617typedef 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 */
632typedef 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 */
643typedef 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 */
657typedef 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 */
668typedef void (*flp_geofence_resume_callback) (int32_t geofence_id, int32_t result);
669
670typedef 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 */
685typedef enum {
686    TYPE_CIRCLE = 0,
687} GeofenceType;
688
689/** Circular geofence is represented by lat / long / radius */
690typedef struct {
691    double latitude;
692    double longitude;
693    double radius_m;
694} GeofenceCircle;
695
696/** Represents the type of geofence and data */
697typedef struct {
698    GeofenceType type;
699    union {
700        GeofenceCircle circle;
701    } geofence;
702} GeofenceData;
703
704/** Geofence Options */
705typedef 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 */
748typedef struct {
749    int32_t geofence_id;
750    GeofenceData* data;
751    GeofenceOptions* options;
752} Geofence;
753
754/** Extended interface for FLP_Geofencing support */
755typedef 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