Package: android.hardware.gnss@1.0

IGnssGeofenceCallback

interface IGnssGeofenceCallback

GNSS Geofence.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 GNSS 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 must be triggered with the state set to Unknown.If the accuracy improves later, an appropriate transition must be triggered.This "sufficient period of time" is defined by the parameter in the addGeofenceArea API.In other words, Unknown state can be interpreted as a state in which the GNSS 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 GNSS 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 must be triggered only for the transitions requested by the addGeofenceArea method.

Even though the diagram and explanation talks about states and transitions, the callee is only interested in the transitions.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 GNSS 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 GNSS system is unavailable, gnssGeofenceStatusCb must be called to inform the upper layers of the same.Similarly, when it becomes available the callback must be called.This is a global state while the UNKNOWN transition described above is per geofence.

An important aspect to note is that users of this API(framework), will use other subsystems like wifi, sensors, cell to handle Unknown case and hopefully provide a definitive state transition to the third party application.GNSS Geofence will just be a signal indicating what the GNSS subsystem knows about the Geofence.

Properties

GeofenceTransition

enum GeofenceTransition: int32_t
Details
Members
ENTERED = ( 1 << 0L )
EXITED = ( 1 << 1L )
UNCERTAIN = ( 1 << 2L )
Annotations
export
name="" , value_prefix="GPS_GEOFENCE_"

GeofenceAvailability

enum GeofenceAvailability: int32_t
Details
Members
UNAVAILABLE = ( 1 << 0L )
AVAILABLE = ( 1 << 1L )
Annotations
export
name="" , value_prefix="GPS_GEOFENCE_"

GeofenceStatus

enum GeofenceStatus: int32_t
Details
Members
OPERATION_SUCCESS = 0
ERROR_TOO_MANY_GEOFENCES = -100
ERROR_ID_EXISTS = -101
ERROR_ID_UNKNOWN = -102
ERROR_INVALID_TRANSITION = -103
ERROR_GENERIC = -149
Annotations
export
name="" , value_prefix="GPS_GEOFENCE_"

Methods

gnssGeofenceTransitionCb

gnssGeofenceTransitionCb (int32_t geofenceId, GnssLocation location, GeofenceTransition transition, GnssUtcTime timestamp)

The callback associated with the geofence transition.The callback must 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 must not be called with the EXITED transition.

IMPORTANT:If a transition is triggered resulting in this callback, the GNSS subsystem will wake up the application processor, if its in suspend state.

Details
Parameters
geofenceId
The id associated with the addGeofenceArea.
location
The current GNSS location.
transition
Can be one of ENTERED, EXITED or UNCERTAIN.
timestamp
Timestamp when the transition was detected.

gnssGeofenceStatusCb

gnssGeofenceStatusCb (GeofenceAvailability status, GnssLocation lastLocation)

The callback associated with the availability of the GNSS system for geofencing monitoring.If the GNSS system determines that it cannot monitor geofences because of lack of reliability or unavailability of the GNSS signals, it will call this callback with UNAVAILABLE parameter.

Details
Parameters
status
- UNAVAILABLE or AVAILABLE.
lastLocation
- Last known location.

gnssGeofenceAddCb

gnssGeofenceAddCb (int32_t geofenceId, GeofenceStatus status)

The callback associated with the addGeofence call.

Details
Parameters
geofenceId
Id of the geofence.
status
Will be OPERATION_SUCCESS if the geofence add was successful.Will be ERROR_TOO_MANY_GEOFENCES if the geofence limit has been reached.Will be ERROR_ID_EXISTS if geofence with id already exists.Will be ERROR_INVALID_TRANSITION if the monitorTransition contains an invalid transition.Will be ERROR_GENERIC for other errors.

gnssGeofenceRemoveCb

gnssGeofenceRemoveCb (int32_t geofenceId, GeofenceStatus status)

The callback associated with the removeGeofence call.

Details
Parameters
geofenceId
Id of the geofence.
status
Will return OPERATION_SUCCESS if successful.Will be ERROR_ID_UNKNOWN for invalid id and ERROR_GENERIC for others.

gnssGeofencePauseCb

gnssGeofencePauseCb (int32_t geofenceId, GeofenceStatus status)

The callback associated with the pauseGeofence call.

Details
Parameters
geofenceId
Id of the geofence.
status
Will be OPERATION_SUCCESS if success.Will be ERROR_ID_UNKNOWN for invalid id.Will be ERROR_INVALID_TRANSITION when monitorTransitions is invalid.Will be ERROR_GENERIC for other err errors.

gnssGeofenceResumeCb

gnssGeofenceResumeCb (int32_t geofenceId, GeofenceStatus status)

The callback associated with the resumeGeofence call.

Details
Parameters
geofenceId
- Id of the geofence.
status
Will be OPERATION_SUCCESS if successful.Will be ERROR_ID_UNKNOWN for invalid id and ERROR_GENERIC for others.