xref: /hardware/libhardware/include/hardware/fused_location.h

/*
 * Copyright (C) 2013 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef ANDROID_INCLUDE_HARDWARE_FUSED_LOCATION_H
#define ANDROID_INCLUDE_HARDWARE_FUSED_LOCATION_H

#include <hardware/hardware.h>


/**
 * This header file defines the interface of the Fused Location Provider.
 * Fused Location Provider is designed to fuse data from various sources
 * like GPS, Wifi, Cell, Sensors, Bluetooth etc to provide a fused location to the
 * upper layers. The advantage of doing fusion in hardware is power savings.
 * The goal is to do this without waking up the AP to get additional data.
 * The software implementation of FLP will decide when to use
 * the hardware fused location. Other location features like geofencing will
 * also be implemented using fusion in hardware.
 */
__BEGIN_DECLS

#define FLP_HEADER_VERSION          1
#define FLP_MODULE_API_VERSION_0_1  HARDWARE_MODULE_API_VERSION(0, 1)
#define FLP_DEVICE_API_VERSION_0_1  HARDWARE_DEVICE_API_VERSION_2(0, 1, FLP_HEADER_VERSION)

/**
 * The id of this module
 */
#define FUSED_LOCATION_HARDWARE_MODULE_ID "flp"

/**
 * Name for the FLP location interface
 */
#define FLP_LOCATION_INTERFACE     "flp_location"

/**
 * Name for the FLP location interface
 */
#define FLP_DIAGNOSTIC_INTERFACE     "flp_diagnostic"

/**
 * Name for the FLP_Geofencing interface.
 */
#define FLP_GEOFENCING_INTERFACE   "flp_geofencing"

/**
 * Name for the FLP_device context interface.
 */
#define FLP_DEVICE_CONTEXT_INTERFACE   "flp_device_context"

/**
 * Constants to indicate the various subsystems
 * that will be used.
 */
#define FLP_TECH_MASK_GNSS      (1U<<0)
#define FLP_TECH_MASK_WIFI      (1U<<1)
#define FLP_TECH_MASK_SENSORS   (1U<<2)
#define FLP_TECH_MASK_CELL      (1U<<3)
#define FLP_TECH_MASK_BLUETOOTH (1U<<4)

/**
 * Set when your implementation can produce GNNS-derived locations,
 * for use with flp_capabilities_callback.
 *
 * GNNS is a required capability for a particular feature to be used
 * (batching or geofencing).  If not supported that particular feature
 * won't be used by the upper layer.
 */
#define CAPABILITY_GNSS         (1U<<0)
/**
 * Set when your implementation can produce WiFi-derived locations, for
 * use with flp_capabilities_callback.
 */
#define CAPABILITY_WIFI         (1U<<1)
/**
 * Set when your implementation can produce cell-derived locations, for
 * use with flp_capabilities_callback.
 */
#define CAPABILITY_CELL         (1U<<3)

/**
 * Status to return in flp_status_callback when your implementation transitions
 * from being unsuccessful in determining location to being successful.
 */
#define FLP_STATUS_LOCATION_AVAILABLE         0
/**
 * Status to return in flp_status_callback when your implementation transitions
 * from being successful in determining location to being unsuccessful.
 */
#define FLP_STATUS_LOCATION_UNAVAILABLE       1

/**
 * This constant is used with the batched locations
 * APIs. Batching is mandatory when FLP implementation
 * is supported. If the flag is set, the hardware implementation
 * will wake up the application processor when the FIFO is full,
 * If the flag is not set, the hardware implementation will drop
 * the oldest data when the FIFO is full.
 */
#define FLP_BATCH_WAKEUP_ON_FIFO_FULL        0x0000001

/**
 * While batching, the implementation should not call the
 * flp_location_callback on every location fix. However,
 * sometimes in high power mode, the system might need
 * a location callback every single time the location
 * fix has been obtained. This flag controls that option.
 * Its the responsibility of the upper layers (caller) to switch
 * it off, if it knows that the AP might go to sleep.
 * When this bit is on amidst a batching session, batching should
 * continue while location fixes are reported in real time.
 */
#define FLP_BATCH_CALLBACK_ON_LOCATION_FIX   0x0000002

/** Flags to indicate which values are valid in a FlpLocation. */
typedef uint16_t FlpLocationFlags;

// IMPORTANT: Note that the following values must match
// constants in the corresponding java file.

/** FlpLocation has valid latitude and longitude. */
#define FLP_LOCATION_HAS_LAT_LONG   (1U<<0)
/** FlpLocation has valid altitude. */
#define FLP_LOCATION_HAS_ALTITUDE   (1U<<1)
/** FlpLocation has valid speed. */
#define FLP_LOCATION_HAS_SPEED      (1U<<2)
/** FlpLocation has valid bearing. */
#define FLP_LOCATION_HAS_BEARING    (1U<<4)
/** FlpLocation has valid accuracy. */
#define FLP_LOCATION_HAS_ACCURACY   (1U<<8)


typedef int64_t FlpUtcTime;

/** Represents a location. */
typedef struct {
    /** set to sizeof(FlpLocation) */
    size_t          size;

    /** Flags associated with the location object. */
    FlpLocationFlags flags;

    /** Represents latitude in degrees. */
    double          latitude;

    /** Represents longitude in degrees. */
    double          longitude;

    /**
     * Represents altitude in meters above the WGS 84 reference
     * ellipsoid. */
    double          altitude;

    /** Represents speed in meters per second. */
    float           speed;

    /** Represents heading in degrees. */
    float           bearing;

    /** Represents expected accuracy in meters. */
    float           accuracy;

    /** Timestamp for the location fix. */
    FlpUtcTime      timestamp;

    /** Sources used, will be Bitwise OR of the FLP_TECH_MASK bits. */
    uint32_t         sources_used;
} FlpLocation;

typedef enum {
    ASSOCIATE_JVM,
    DISASSOCIATE_JVM,
} ThreadEvent;

/**
 *  Callback with location information.
 *  Can only be called from a thread associated to JVM using set_thread_event_cb.
 *  Parameters:
 *     num_locations is the number of batched locations available.
 *     location is the pointer to an array of pointers to location objects.
 */
typedef void (*flp_location_callback)(int32_t num_locations, FlpLocation** location);

/**
 * Callback utility for acquiring a wakelock.
 * This can be used to prevent the CPU from suspending while handling FLP events.
 */
typedef void (*flp_acquire_wakelock)();

/**
 * Callback utility for releasing the FLP wakelock.
 */
typedef void (*flp_release_wakelock)();

/**
 * Callback for associating a thread that can call into the Java framework code.
 * This must be used to initialize any threads that report events up to the framework.
 * Return value:
 *      FLP_RESULT_SUCCESS on success.
 *      FLP_RESULT_ERROR if the association failed in the current thread.
 */
typedef int (*flp_set_thread_event)(ThreadEvent event);

/**
 * Callback for technologies supported by this implementation.
 *
 * Parameters: capabilities is a bitmask of FLP_CAPABILITY_* values describing
 * which features your implementation supports.  You should support
 * CAPABILITY_GNSS at a minimum for your implementation to be utilized.  You can
 * return 0 in FlpGeofenceCallbacks to indicate you don't support geofencing,
 * or 0 in FlpCallbacks to indicate you don't support location batching.
 */
typedef void (*flp_capabilities_callback)(int capabilities);

/**
 * Callback with status information on the ability to compute location.
 * To avoid waking up the application processor you should only send
 * changes in status (you shouldn't call this method twice in a row
 * with the same status value).  As a guideline you should not call this
 * more frequently then the requested batch period set with period_ns
 * in FlpBatchOptions.  For example if period_ns is set to 5 minutes and
 * the status changes many times in that interval, you should only report
 * one status change every 5 minutes.
 *
 * Parameters:
 *     status is one of FLP_STATUS_LOCATION_AVAILABLE
 *     or FLP_STATUS_LOCATION_UNAVAILABLE.
 */
typedef void (*flp_status_callback)(int32_t status);

/** FLP callback structure. */
typedef struct {
    /** set to sizeof(FlpCallbacks) */
    size_t      size;
    flp_location_callback location_cb;
    flp_acquire_wakelock acquire_wakelock_cb;
    flp_release_wakelock release_wakelock_cb;
    flp_set_thread_event set_thread_event_cb;
    flp_capabilities_callback flp_capabilities_cb;
    flp_status_callback flp_status_cb;
} FlpCallbacks;


/** Options with the batching FLP APIs */
typedef struct {
    /**
     * Maximum power in mW that the underlying implementation
     * can use for this batching call.
     * If max_power_allocation_mW is 0, only fixes that are generated
     * at no additional cost of power shall be reported.
     */
    double max_power_allocation_mW;

    /** Bitwise OR of the FLP_TECH_MASKS to use */
    uint32_t sources_to_use;

    /**
     * FLP_BATCH_WAKEUP_ON_FIFO_FULL - If set the hardware
     * will wake up the AP when the buffer is full. If not set, the
     * hardware will drop the oldest location object.
     *
     * FLP_BATCH_CALLBACK_ON_LOCATION_FIX - If set the location
     * callback will be called every time there is a location fix.
     * Its the responsibility of the upper layers (caller) to switch
     * it off, if it knows that the AP might go to sleep. When this
     * bit is on amidst a batching session, batching should continue
     * while location fixes are reported in real time.
     *
     * Other flags to be bitwised ORed in the future.
     */
    uint32_t flags;

    /**
     * Frequency with which location needs to be batched in nano
     * seconds.
     */
    int64_t period_ns;

    /**
     * The smallest displacement between reported locations in meters.
     *
     * If set to 0, then you should report locations at the requested
     * interval even if the device is stationary.  If positive, you
     * can use this parameter as a hint to save power (e.g. throttling
     * location period if the user hasn't traveled close to the displacement
     * threshold).  Even small positive values can be interpreted to mean
     * that you don't have to compute location when the device is stationary.
     *
     * There is no need to filter location delivery based on this parameter.
     * Locations can be delivered even if they have a displacement smaller than
     * requested. This parameter can safely be ignored at the cost of potential
     * power savings.
     */
    float smallest_displacement_meters;
} FlpBatchOptions;

#define FLP_RESULT_SUCCESS                       0
#define FLP_RESULT_ERROR                        -1
#define FLP_RESULT_INSUFFICIENT_MEMORY          -2
#define FLP_RESULT_TOO_MANY_GEOFENCES           -3
#define FLP_RESULT_ID_EXISTS                    -4
#define FLP_RESULT_ID_UNKNOWN                   -5
#define FLP_RESULT_INVALID_GEOFENCE_TRANSITION  -6

/**
 * Represents the standard FLP interface.
 */
typedef struct {
    /**
     * set to sizeof(FlpLocationInterface)
     */
    size_t size;

    /**
     * Opens the interface and provides the callback routines
     * to the implementation of this interface.  Once called you should respond
     * by calling the flp_capabilities_callback in FlpCallbacks to
     * specify the capabilities that your implementation supports.
     */
    int (*init)(FlpCallbacks* callbacks );

    /**
     * Return the batch size (in number of FlpLocation objects)
     * available in the hardware.  Note, different HW implementations
     * may have different sample sizes.  This shall return number
     * of samples defined in the format of FlpLocation.
     * This will be used by the upper layer, to decide on the batching
     * interval and whether the AP should be woken up or not.
     */
    int (*get_batch_size)();

    /**
     * Start batching locations. This API is primarily used when the AP is
     * asleep and the device can batch locations in the hardware.
     *   flp_location_callback is used to return the locations. When the buffer
     * is full and FLP_BATCH_WAKEUP_ON_FIFO_FULL is used, the AP is woken up.
     * When the buffer is full and FLP_BATCH_WAKEUP_ON_FIFO_FULL is not set,
     * the oldest location object is dropped. In this case the  AP will not be
     * woken up. The upper layer will use get_batched_location
     * API to explicitly ask for the location.
     *   If FLP_BATCH_CALLBACK_ON_LOCATION_FIX is set, the implementation
     * will call the flp_location_callback every single time there is a location
     * fix. This overrides FLP_BATCH_WAKEUP_ON_FIFO_FULL flag setting.
     * It's the responsibility of the upper layers (caller) to switch
     * it off, if it knows that the AP might go to sleep. This is useful
     * for nagivational applications when the system is in high power mode.
     * Parameters:
     *    id - Id for the request.
     *    options - See FlpBatchOptions struct definition.
     * Return value:
     *    FLP_RESULT_SUCCESS on success, FLP_RESULT_INSUFFICIENT_MEMORY,
     *    FLP_RESULT_ID_EXISTS, FLP_RESULT_ERROR on failure.
     */
    int (*start_batching)(int id, FlpBatchOptions* options);

    /**
     * Update FlpBatchOptions associated with a batching request.
     * When a batching operation is in progress and a batching option
     * such as FLP_BATCH_WAKEUP_ON_FIFO_FULL needs to be updated, this API
     * will be used. For instance, this can happen when the AP is awake and
     * the maps application is being used.
     * Parameters:
     *    id - Id of an existing batch request.
     *    new_options - Updated FlpBatchOptions
     * Return value:
     *    FLP_RESULT_SUCCESS on success, FLP_RESULT_ID_UNKNOWN,
     *    FLP_RESULT_ERROR on error.
     */
    int (*update_batching_options)(int id, FlpBatchOptions* new_options);

    /**
     * Stop batching.
     * Parameters:
     *    id - Id for the request.
     * Return Value:
     *    FLP_RESULT_SUCCESS on success, FLP_RESULT_ID_UNKNOWN or
     *    FLP_RESULT_ERROR on failure.
     */
    int (*stop_batching)(int id);

    /**
     * Closes the interface. If any batch operations are in progress,
     * they should be stopped.
     */
    void (*cleanup)();

    /**
     * Get the fused location that was batched.
     *   flp_location_callback is used to return the location. The location object
     * is dropped from the buffer only when the buffer is full. Do not remove it
     * from the buffer just because it has been returned using the callback.
     * In other words, when there is no new location object, two calls to
     * get_batched_location(1) should return the same location object.
     * Parameters:
     *      last_n_locations - Number of locations to get. This can be one or many.
     *      If the last_n_locations is 1, you get the latest location known to the
     *      hardware.
     */
    void (*get_batched_location)(int last_n_locations);

    /**
     * Injects current location from another location provider
     * latitude and longitude are measured in degrees
     * expected accuracy is measured in meters
     * Parameters:
     *      location - The location object being injected.
     * Return value: FLP_RESULT_SUCCESS or FLP_RESULT_ERROR.
     */
    int  (*inject_location)(FlpLocation* location);

    /**
     * Get a pointer to extension information.
     */
    const void* (*get_extension)(const char* name);

    /**
     * Retrieve all batched locations currently stored and clear the buffer.
     * flp_location_callback MUST be called in response, even if there are
     * no locations to flush (in which case num_locations should be 0).
     * Subsequent calls to get_batched_location or flush_batched_locations
     * should not return any of the locations returned in this call.
     */
    void (*flush_batched_locations)();
} FlpLocationInterface;

struct flp_device_t {
    struct hw_device_t common;

    /**
     * Get a handle to the FLP Interface.
     */
    const FlpLocationInterface* (*get_flp_interface)(struct flp_device_t* dev);
};

/**
 * Callback for reports diagnostic data into the Java framework code.
*/
typedef void (*report_data)(char* data, int length);

/**
 * FLP diagnostic callback structure.
 * Currently, not used - but this for future extension.
 */
typedef struct {
    /** set to sizeof(FlpDiagnosticCallbacks) */
    size_t      size;

    flp_set_thread_event set_thread_event_cb;

    /** reports diagnostic data into the Java framework code */
    report_data data_cb;
} FlpDiagnosticCallbacks;

/** Extended interface for diagnostic support. */
typedef struct {
    /** set to sizeof(FlpDiagnosticInterface) */
    size_t          size;

    /**
     * Opens the diagnostic interface and provides the callback routines
     * to the implemenation of this interface.
     */
    void  (*init)(FlpDiagnosticCallbacks* callbacks);

    /**
     * Injects diagnostic data into the FLP subsystem.
     * Return 0 on success, -1 on error.
     **/
    int  (*inject_data)(char* data, int length );
} FlpDiagnosticInterface;

/**
 * Context setting information.
 * All these settings shall be injected to FLP HAL at FLP init time.
 * Following that, only the changed setting need to be re-injected
 * upon changes.
 */

#define FLP_DEVICE_CONTEXT_GPS_ENABLED                     (1U<<0)
#define FLP_DEVICE_CONTEXT_AGPS_ENABLED                    (1U<<1)
#define FLP_DEVICE_CONTEXT_NETWORK_POSITIONING_ENABLED     (1U<<2)
#define FLP_DEVICE_CONTEXT_WIFI_CONNECTIVITY_ENABLED       (1U<<3)
#define FLP_DEVICE_CONTEXT_WIFI_POSITIONING_ENABLED        (1U<<4)
#define FLP_DEVICE_CONTEXT_HW_NETWORK_POSITIONING_ENABLED  (1U<<5)
#define FLP_DEVICE_CONTEXT_AIRPLANE_MODE_ON                (1U<<6)
#define FLP_DEVICE_CONTEXT_DATA_ENABLED                    (1U<<7)
#define FLP_DEVICE_CONTEXT_ROAMING_ENABLED                 (1U<<8)
#define FLP_DEVICE_CONTEXT_CURRENTLY_ROAMING               (1U<<9)
#define FLP_DEVICE_CONTEXT_SENSOR_ENABLED                  (1U<<10)
#define FLP_DEVICE_CONTEXT_BLUETOOTH_ENABLED               (1U<<11)
#define FLP_DEVICE_CONTEXT_CHARGER_ON                      (1U<<12)

/** Extended interface for device context support. */
typedef struct {
    /** set to sizeof(FlpDeviceContextInterface) */
    size_t          size;

    /**
     * Injects debug data into the FLP subsystem.
     * Return 0 on success, -1 on error.
     **/
    int  (*inject_device_context)(uint32_t enabledMask);
} FlpDeviceContextInterface;


/**
 * There are 3 states associated with a Geofence: Inside, Outside, Unknown.
 * There are 3 transitions: ENTERED, EXITED, UNCERTAIN.
 *
 * An example state diagram with confidence level: 95% and Unknown time limit
 * set as 30 secs is shown below. (confidence level and Unknown time limit are
 * explained latter)
 *                         ____________________________
 *                        |       Unknown (30 secs)   |
 *                         """"""""""""""""""""""""""""
 *                            ^ |                  |  ^
 *                   UNCERTAIN| |ENTERED     EXITED|  |UNCERTAIN
 *                            | v                  v  |
 *                        ________    EXITED     _________
 *                       | Inside | -----------> | Outside |
 *                       |        | <----------- |         |
 *                        """"""""    ENTERED    """""""""
 *
 * Inside state: We are 95% confident that the user is inside the geofence.
 * Outside state: We are 95% confident that the user is outside the geofence
 * Unknown state: Rest of the time.
 *
 * The Unknown state is better explained with an example:
 *
 *                            __________
 *                           |         c|
 *                           |  ___     |    _______
 *                           |  |a|     |   |   b   |
 *                           |  """     |    """""""
 *                           |          |
 *                            """"""""""
 * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy
 * circle reported by the FLP subsystem. Now with regard to "b", the system is
 * confident that the user is outside. But with regard to "a" is not confident
 * whether it is inside or outside the geofence. If the accuracy remains the
 * same for a sufficient period of time, the UNCERTAIN transition would be
 * triggered with the state set to Unknown. If the accuracy improves later, an
 * appropriate transition should be triggered.  This "sufficient period of time"
 * is defined by the parameter in the add_geofence_area API.
 *     In other words, Unknown state can be interpreted as a state in which the
 * FLP subsystem isn't confident enough that the user is either inside or
 * outside the Geofence. It moves to Unknown state only after the expiry of the
 * timeout.
 *
 * The geofence callback needs to be triggered for the ENTERED and EXITED
 * transitions, when the FLP system is confident that the user has entered
 * (Inside state) or exited (Outside state) the Geofence. An implementation
 * which uses a value of 95% as the confidence is recommended. The callback
 * should be triggered only for the transitions requested by the
 * add_geofence_area call.
 *
 * Even though the diagram and explanation talks about states and transitions,
 * the callee is only interested in the transistions. The states are mentioned
 * here for illustrative purposes.
 *
 * Startup Scenario: When the device boots up, if an application adds geofences,
 * and then we get an accurate FLP location fix, it needs to trigger the
 * appropriate (ENTERED or EXITED) transition for every Geofence it knows about.
 * By default, all the Geofences will be in the Unknown state.
 *
 * When the FLP system is unavailable, flp_geofence_status_callback should be
 * called to inform the upper layers of the same. Similarly, when it becomes
 * available the callback should be called. This is a global state while the
 * UNKNOWN transition described above is per geofence.
 *
 */
#define FLP_GEOFENCE_TRANSITION_ENTERED     (1L<<0)
#define FLP_GEOFENCE_TRANSITION_EXITED      (1L<<1)
#define FLP_GEOFENCE_TRANSITION_UNCERTAIN   (1L<<2)

#define FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE (1L<<0)
#define FLP_GEOFENCE_MONITOR_STATUS_AVAILABLE   (1L<<1)

/**
 * The callback associated with the geofence.
 * Parameters:
 *      geofence_id - The id associated with the add_geofence_area.
 *      location    - The current location as determined by the FLP subsystem.
 *      transition  - Can be one of FLP_GEOFENCE_TRANSITION_ENTERED, FLP_GEOFENCE_TRANSITION_EXITED,
 *                    FLP_GEOFENCE_TRANSITION_UNCERTAIN.
 *      timestamp   - Timestamp when the transition was detected; -1 if not available.
 *      sources_used - Bitwise OR of FLP_TECH_MASK flags indicating which
 *                     subsystems were used.
 *
 * The callback should only be called when the caller is interested in that
 * particular transition. For instance, if the caller is interested only in
 * ENTERED transition, then the callback should NOT be called with the EXITED
 * transition.
 *
 * IMPORTANT: If a transition is triggered resulting in this callback, the
 * subsystem will wake up the application processor, if its in suspend state.
 */
typedef void (*flp_geofence_transition_callback) (int32_t geofence_id,  FlpLocation* location,
        int32_t transition, FlpUtcTime timestamp, uint32_t sources_used);

/**
 * The callback associated with the availablity of one the sources used for geofence
 * monitoring by the FLP sub-system For example, if the GPS system determines that it cannot
 * monitor geofences because of lack of reliability or unavailability of the GPS signals,
 * it will call this callback with FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE parameter and the
 * source set to FLP_TECH_MASK_GNSS.
 *
 * Parameters:
 *  status - FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE or FLP_GEOFENCE_MONITOR_STATUS_AVAILABLE.
 *  source - One of the FLP_TECH_MASKS
 *  last_location - Last known location.
 */
typedef void (*flp_geofence_monitor_status_callback) (int32_t status, uint32_t source,
                                                      FlpLocation* last_location);

/**
 * The callback associated with the add_geofence call.
 *
 * Parameter:
 * geofence_id - Id of the geofence.
 * result - FLP_RESULT_SUCCESS
 *          FLP_RESULT_ERROR_TOO_MANY_GEOFENCES  - geofence limit has been reached.
 *          FLP_RESULT_ID_EXISTS  - geofence with id already exists
 *          FLP_RESULT_INVALID_GEOFENCE_TRANSITION - the monitorTransition contains an
 *              invalid transition
 *          FLP_RESULT_ERROR - for other errors.
 */
typedef void (*flp_geofence_add_callback) (int32_t geofence_id, int32_t result);

/**
 * The callback associated with the remove_geofence call.
 *
 * Parameter:
 * geofence_id - Id of the geofence.
 * result - FLP_RESULT_SUCCESS
 *          FLP_RESULT_ID_UNKNOWN - for invalid id
 *          FLP_RESULT_ERROR for others.
 */
typedef void (*flp_geofence_remove_callback) (int32_t geofence_id, int32_t result);


/**
 * The callback associated with the pause_geofence call.
 *
 * Parameter:
 * geofence_id - Id of the geofence.
 * result - FLP_RESULT_SUCCESS
 *          FLP_RESULT__ID_UNKNOWN - for invalid id
 *          FLP_RESULT_INVALID_TRANSITION -
 *                    when monitor_transitions is invalid
 *          FLP_RESULT_ERROR for others.
 */
typedef void (*flp_geofence_pause_callback) (int32_t geofence_id, int32_t result);

/**
 * The callback associated with the resume_geofence call.
 *
 * Parameter:
 * geofence_id - Id of the geofence.
 * result - FLP_RESULT_SUCCESS
 *          FLP_RESULT_ID_UNKNOWN - for invalid id
 *          FLP_RESULT_ERROR for others.
 */
typedef void (*flp_geofence_resume_callback) (int32_t geofence_id, int32_t result);

typedef struct {
    /** set to sizeof(FlpGeofenceCallbacks) */
    size_t size;
    flp_geofence_transition_callback geofence_transition_callback;
    flp_geofence_monitor_status_callback geofence_status_callback;
    flp_geofence_add_callback geofence_add_callback;
    flp_geofence_remove_callback geofence_remove_callback;
    flp_geofence_pause_callback geofence_pause_callback;
    flp_geofence_resume_callback geofence_resume_callback;
    flp_set_thread_event set_thread_event_cb;
    flp_capabilities_callback flp_capabilities_cb;
} FlpGeofenceCallbacks;


/** Type of geofence */
typedef enum {
    TYPE_CIRCLE = 0,
} GeofenceType;

/** Circular geofence is represented by lat / long / radius */
typedef struct {
    double latitude;
    double longitude;
    double radius_m;
} GeofenceCircle;

/** Represents the type of geofence and data */
typedef struct {
    GeofenceType type;
    union {
        GeofenceCircle circle;
    } geofence;
} GeofenceData;

/** Geofence Options */
typedef struct {
   /**
    * The current state of the geofence. For example, if
    * the system already knows that the user is inside the geofence,
    * this will be set to FLP_GEOFENCE_TRANSITION_ENTERED. In most cases, it
    * will be FLP_GEOFENCE_TRANSITION_UNCERTAIN. */
    int last_transition;

   /**
    * Transitions to monitor. Bitwise OR of
    * FLP_GEOFENCE_TRANSITION_ENTERED, FLP_GEOFENCE_TRANSITION_EXITED and
    * FLP_GEOFENCE_TRANSITION_UNCERTAIN.
    */
    int monitor_transitions;

   /**
    * Defines the best-effort description
    * of how soon should the callback be called when the transition
    * associated with the Geofence is triggered. For instance, if set
    * to 1000 millseconds with FLP_GEOFENCE_TRANSITION_ENTERED, the callback
    * should be called 1000 milliseconds within entering the geofence.
    * This parameter is defined in milliseconds.
    * NOTE: This is not to be confused with the rate that the GPS is
    * polled at. It is acceptable to dynamically vary the rate of
    * sampling the GPS for power-saving reasons; thus the rate of
    * sampling may be faster or slower than this.
    */
    int notification_responsivenes_ms;

   /**
    * The time limit after which the UNCERTAIN transition
    * should be triggered. This paramter is defined in milliseconds.
    */
    int unknown_timer_ms;

    /**
     * The sources to use for monitoring geofences. Its a BITWISE-OR
     * of FLP_TECH_MASK flags.
     */
    uint32_t sources_to_use;
} GeofenceOptions;

/** Geofence struct */
typedef struct {
    int32_t geofence_id;
    GeofenceData* data;
    GeofenceOptions* options;
} Geofence;

/** Extended interface for FLP_Geofencing support */
typedef struct {
   /** set to sizeof(FlpGeofencingInterface) */
   size_t          size;

   /**
    * Opens the geofence interface and provides the callback routines
    * to the implemenation of this interface.  Once called you should respond
    * by calling the flp_capabilities_callback in FlpGeofenceCallbacks to
    * specify the capabilities that your implementation supports.
    */
   void  (*init)( FlpGeofenceCallbacks* callbacks );

   /**
    * Add a list of geofences.
    * Parameters:
    *     number_of_geofences - The number of geofences that needed to be added.
    *     geofences - Pointer to array of pointers to Geofence structure.
    */
   void (*add_geofences) (int32_t number_of_geofences, Geofence** geofences);

   /**
    * Pause monitoring a particular geofence.
    * Parameters:
    *   geofence_id - The id for the geofence.
    */
   void (*pause_geofence) (int32_t geofence_id);

   /**
    * Resume monitoring a particular geofence.
    * Parameters:
    *   geofence_id - The id for the geofence.
    *   monitor_transitions - Which transitions to monitor. Bitwise OR of
    *       FLP_GEOFENCE_TRANSITION_ENTERED, FLP_GEOFENCE_TRANSITION_EXITED and
    *       FLP_GEOFENCE_TRANSITION_UNCERTAIN.
    *       This supersedes the value associated provided in the
    *       add_geofence_area call.
    */
   void (*resume_geofence) (int32_t geofence_id, int monitor_transitions);

   /**
    * Modify a particular geofence option.
    * Parameters:
    *    geofence_id - The id for the geofence.
    *    options - Various options associated with the geofence. See
    *        GeofenceOptions structure for details.
    */
   void (*modify_geofence_option) (int32_t geofence_id, GeofenceOptions* options);

   /**
    * Remove a list of geofences. After the function returns, no notifications
    * should be sent.
    * Parameter:
    *     number_of_geofences - The number of geofences that needed to be added.
    *     geofence_id - Pointer to array of geofence_ids to be removed.
    */
   void (*remove_geofences) (int32_t number_of_geofences, int32_t* geofence_id);
} FlpGeofencingInterface;

__END_DECLS

#endif /* ANDROID_INCLUDE_HARDWARE_FLP_H */