public final class GeofenceHardware extends Object
The APIs should not be called directly by the app developers. A higher level api which abstracts the hardware should be used instead. All the checks are done by the higher level public API. Any needed locking should be handled by the higher level API.
There are 3 states associated with a Geofence: Inside, Outside, Unknown.
There are 3 transitions: GEOFENCE_ENTERED
, GEOFENCE_EXITED
,
GEOFENCE_UNCERTAIN
. The APIs only expose the transitions.
Inside state: The hardware subsystem is reasonably confident that the user is inside
the geofence. Outside state: The hardware subsystem is reasonably confident that the user
is outside the geofence Unknown state: Unknown state can be interpreted as a state in which the
monitoring subsystem isn't confident enough that the user is either inside or
outside the Geofence. If the accuracy does not improve for a sufficient period of time,
the GEOFENCE_UNCERTAIN
transition would be triggered. If the accuracy improves later,
an appropriate transition would be triggered. The "reasonably confident" parameter
depends on the hardware system and the positioning algorithms used.
For instance, MONITORING_TYPE_GPS_HARDWARE
uses 95% as a confidence level.
Modifier and Type | Field and Description |
---|---|
static int |
GEOFENCE_ENTERED
The constant to indicate that the user has entered the geofence.
|
static int |
GEOFENCE_ERROR_ID_EXISTS
The constant used to indicate that the geofence id already exists.
|
static int |
GEOFENCE_ERROR_ID_UNKNOWN
The constant used to indicate that the geofence id is unknown.
|
static int |
GEOFENCE_ERROR_INSUFFICIENT_MEMORY
The constant used to indicate that the operation failed due to insufficient memory.
|
static int |
GEOFENCE_ERROR_INVALID_TRANSITION
The constant used to indicate that the transition requested for the geofence is invalid.
|
static int |
GEOFENCE_ERROR_TOO_MANY_GEOFENCES
The constant used to indicate that too many geofences have been registered.
|
static int |
GEOFENCE_EXITED
The constant to indicate that the user has exited the geofence.
|
static int |
GEOFENCE_FAILURE
The constant used to indicate that the geofence operation has failed.
|
static int |
GEOFENCE_SUCCESS
The constant used to indicate success of the particular geofence call
|
static int |
GEOFENCE_UNCERTAIN
The constant to indicate that the user is uncertain with respect to a
geofence.
|
static int |
MONITOR_CURRENTLY_AVAILABLE
Constant to indicate that the monitoring system is currently
available for monitoring geofences.
|
static int |
MONITOR_CURRENTLY_UNAVAILABLE
Constant to indicate that the monitoring system is currently
unavailable for monitoring geofences.
|
static int |
MONITOR_UNSUPPORTED
Constant to indicate that the monitoring system is unsupported
for hardware geofence monitoring.
|
static int |
MONITORING_TYPE_FUSED_HARDWARE
Constant for geofence monitoring done by the Fused hardware.
|
static int |
MONITORING_TYPE_GPS_HARDWARE
Constant for geofence monitoring done by the GPS hardware.
|
static int |
SOURCE_TECHNOLOGY_BLUETOOTH
The constant used to indicate that the monitoring system supports Bluetooth.
|
static int |
SOURCE_TECHNOLOGY_CELL
The constant used to indicate that the monitoring system supports Cell.
|
static int |
SOURCE_TECHNOLOGY_GNSS
The constant used to indicate that the monitoring system supports GNSS.
|
static int |
SOURCE_TECHNOLOGY_SENSORS
The constant used to indicate that the monitoring system supports Sensors.
|
static int |
SOURCE_TECHNOLOGY_WIFI
The constant used to indicate that the monitoring system supports WiFi.
|
Constructor and Description |
---|
GeofenceHardware(IGeofenceHardware service) |
Modifier and Type | Method and Description |
---|---|
boolean |
addGeofence(int geofenceId,
int monitoringType,
GeofenceHardwareRequest geofenceRequest,
GeofenceHardwareCallback callback)
Creates a circular geofence which is monitored by subsystems in the hardware.
|
int[] |
getMonitoringTypes()
Returns all the hardware geofence monitoring systems which are supported
Call
getStatusOfMonitoringType(int) to know the current state
of a monitoring system. |
int |
getStatusOfMonitoringType(int monitoringType)
Returns current status of a hardware geofence monitoring system.
|
boolean |
pauseGeofence(int geofenceId,
int monitoringType)
Pauses the monitoring of a geofence added by
addGeofence(int, int, android.hardware.location.GeofenceHardwareRequest, android.hardware.location.GeofenceHardwareCallback) call. |
boolean |
registerForMonitorStateChangeCallback(int monitoringType,
GeofenceHardwareMonitorCallback callback)
Register the callback to be notified when the state of a hardware geofence
monitoring system changes.
|
boolean |
removeGeofence(int geofenceId,
int monitoringType)
Removes a geofence added by
addGeofence(int, int, android.hardware.location.GeofenceHardwareRequest, android.hardware.location.GeofenceHardwareCallback) call. |
boolean |
resumeGeofence(int geofenceId,
int monitoringType,
int monitorTransition)
Resumes the monitoring of a geofence added by
pauseGeofence(int, int) call. |
boolean |
unregisterForMonitorStateChangeCallback(int monitoringType,
GeofenceHardwareMonitorCallback callback)
Unregister the callback that was used with
registerForMonitorStateChangeCallback(int, android.hardware.location.GeofenceHardwareMonitorCallback)
to notify when the state of the hardware geofence monitoring system changes. |
public static final int MONITORING_TYPE_GPS_HARDWARE
public static final int MONITORING_TYPE_FUSED_HARDWARE
public static final int MONITOR_CURRENTLY_AVAILABLE
public static final int MONITOR_CURRENTLY_UNAVAILABLE
public static final int MONITOR_UNSUPPORTED
public static final int GEOFENCE_ENTERED
public static final int GEOFENCE_EXITED
public static final int GEOFENCE_UNCERTAIN
public static final int GEOFENCE_SUCCESS
public static final int GEOFENCE_ERROR_TOO_MANY_GEOFENCES
public static final int GEOFENCE_ERROR_ID_EXISTS
public static final int GEOFENCE_ERROR_ID_UNKNOWN
public static final int GEOFENCE_ERROR_INVALID_TRANSITION
public static final int GEOFENCE_FAILURE
public static final int GEOFENCE_ERROR_INSUFFICIENT_MEMORY
public static final int SOURCE_TECHNOLOGY_GNSS
public static final int SOURCE_TECHNOLOGY_WIFI
public static final int SOURCE_TECHNOLOGY_SENSORS
public static final int SOURCE_TECHNOLOGY_CELL
public static final int SOURCE_TECHNOLOGY_BLUETOOTH
public int[] getMonitoringTypes()
Call getStatusOfMonitoringType(int)
to know the current state
of a monitoring system.
Requires android.Manifest.permission#LOCATION_HARDWARE
permission to access
geofencing in hardware.
public int getStatusOfMonitoringType(int monitoringType)
Status can be one of MONITOR_CURRENTLY_AVAILABLE
,
MONITOR_CURRENTLY_UNAVAILABLE
or MONITOR_UNSUPPORTED
Some supported hardware monitoring systems might not be available
for monitoring geofences in certain scenarios. For example, when a user
enters a building, the GPS hardware subsystem might not be able monitor
geofences and will change from MONITOR_CURRENTLY_AVAILABLE
to
MONITOR_CURRENTLY_UNAVAILABLE
.
monitoringType
- public boolean addGeofence(int geofenceId, int monitoringType, GeofenceHardwareRequest geofenceRequest, GeofenceHardwareCallback callback)
When the device detects that is has entered, exited or is uncertain about the area specified by the geofence, the given callback will be called.
If this call returns true, it means that the geofence has been sent to the hardware.
GeofenceHardwareCallback.onGeofenceAdd(int, int)
will be called with the result of the
add call from the hardware. The GeofenceHardwareCallback.onGeofenceAdd(int, int)
will be
called with the following parameters when a transition event occurs.
GEOFENCE_ENTERED
, GEOFENCE_EXITED
, GEOFENCE_UNCERTAIN
MONITORING_TYPE_GPS_HARDWARE
is one such example)
that was used.
The geofence will be monitored by the subsystem specified by monitoring_type parameter. The application does not need to hold a wakelock when the monitoring is being done by the underlying hardware subsystem. If the same geofence Id is being monitored by two different monitoring systems, the same id can be used for both calls, as long as the same callback object is used.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION
permission when
MONITORING_TYPE_GPS_HARDWARE
is used.
Requires android.Manifest.permission#LOCATION_HARDWARE
permission to access
geofencing in hardware.
This API should not be called directly by the app developers. A higher level api which abstracts the hardware should be used instead. All the checks are done by the higher level public API. Any needed locking should be handled by the higher level API.
Create a geofence request object using the methods in GeofenceHardwareRequest
to
set all the characteristics of the geofence. Use the created GeofenceHardwareRequest object
in this call.
geofenceId
- The id associated with the geofence.monitoringType
- The type of the hardware subsystem that should be used
to monitor the geofence.geofenceRequest
- The GeofenceHardwareRequest
object associated with the
geofence.callback
- GeofenceHardwareCallback
that will be use to notify the
transition.IllegalArgumentException
- when the geofence request type is not supported.public boolean removeGeofence(int geofenceId, int monitoringType)
addGeofence(int, int, android.hardware.location.GeofenceHardwareRequest, android.hardware.location.GeofenceHardwareCallback)
call.
If this call returns true, it means that the geofence has been sent to the hardware.
GeofenceHardwareCallback.onGeofenceRemove(int, int)
will be called with the result of the
remove call from the hardware.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION
permission when
MONITORING_TYPE_GPS_HARDWARE
is used.
Requires android.Manifest.permission#LOCATION_HARDWARE
permission to access
geofencing in hardware.
This API should not be called directly by the app developers. A higher level api which abstracts the hardware should be used instead. All the checks are done by the higher level public API. Any needed locking should be handled by the higher level API.
geofenceId
- The id of the geofence.monitoringType
- The type of the hardware subsystem that should be used
to monitor the geofence.public boolean pauseGeofence(int geofenceId, int monitoringType)
addGeofence(int, int, android.hardware.location.GeofenceHardwareRequest, android.hardware.location.GeofenceHardwareCallback)
call.
If this call returns true, it means that the geofence has been sent to the hardware.
GeofenceHardwareCallback.onGeofencePause(int, int)
will be called with the result of the
pause call from the hardware.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION
permission when
MONITORING_TYPE_GPS_HARDWARE
is used.
Requires android.Manifest.permission#LOCATION_HARDWARE
permission to access
geofencing in hardware.
This API should not be called directly by the app developers. A higher level api which abstracts the hardware should be used instead. All the checks are done by the higher level public API. Any needed locking should be handled by the higher level API.
geofenceId
- The id of the geofence.monitoringType
- The type of the hardware subsystem that should be used
to monitor the geofence.public boolean resumeGeofence(int geofenceId, int monitoringType, int monitorTransition)
pauseGeofence(int, int)
call.
If this call returns true, it means that the geofence has been sent to the hardware.
GeofenceHardwareCallback.onGeofenceResume(int, int)
will be called with the result of the
resume call from the hardware.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION
permission when
MONITORING_TYPE_GPS_HARDWARE
is used.
Requires android.Manifest.permission#LOCATION_HARDWARE
permission to access
geofencing in hardware.
This API should not be called directly by the app developers. A higher level api which abstracts the hardware should be used instead. All the checks are done by the higher level public API. Any needed locking should be handled by the higher level API.
geofenceId
- The id of the geofence.monitoringType
- The type of the hardware subsystem that should be used
to monitor the geofence.monitorTransition
- Bitwise OR of GEOFENCE_ENTERED
,
GEOFENCE_EXITED
, GEOFENCE_UNCERTAIN
public boolean registerForMonitorStateChangeCallback(int monitoringType, GeofenceHardwareMonitorCallback callback)
MONITOR_CURRENTLY_AVAILABLE
to MONITOR_CURRENTLY_UNAVAILABLE
Requires android.Manifest.permission#ACCESS_FINE_LOCATION
permission when
MONITORING_TYPE_GPS_HARDWARE
is used.
Requires android.Manifest.permission#LOCATION_HARDWARE
permission to access
geofencing in hardware.
This API should not be called directly by the app developers. A higher level api which abstracts the hardware should be used instead. All the checks are done by the higher level public API. Any needed locking should be handled by the higher level API.
The same callback object can be used to be informed of geofence transitions and state changes of the underlying hardware subsystem.
monitoringType
- Type of the monitorcallback
- Callback that will be called.public boolean unregisterForMonitorStateChangeCallback(int monitoringType, GeofenceHardwareMonitorCallback callback)
registerForMonitorStateChangeCallback(int, android.hardware.location.GeofenceHardwareMonitorCallback)
to notify when the state of the hardware geofence monitoring system changes.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION
permission when
MONITORING_TYPE_GPS_HARDWARE
is used.
Requires android.Manifest.permission#LOCATION_HARDWARE
permission to access
geofencing in hardware.
This API should not be called directly by the app developers. A higher level api which abstracts the hardware should be used instead. All the checks are done by the higher level public API. Any needed locking should be handled by the higher level API.
monitoringType
- Type of the monitorcallback
- Callback that will be called.