| java.lang.Object | |
| ↳ | android.hardware.location.GeofenceHardware |
This class handles geofences managed by various hardware subsystems. It contains the public APIs that is needed to accomplish the task.
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.
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| int | GEOFENCE_ENTERED | The constant to indicate that the user has entered the geofence. | |||||||||
| int | GEOFENCE_ERROR_ID_EXISTS | The constant used to indicate that the geofence id already exists. | |||||||||
| int | GEOFENCE_ERROR_ID_UNKNOWN | The constant used to indicate that the geofence id is unknown. | |||||||||
| int | GEOFENCE_ERROR_INVALID_TRANSITION | The constant used to indicate that the transition requested for the geofence is invalid. | |||||||||
| int | GEOFENCE_ERROR_TOO_MANY_GEOFENCES | The constant used to indicate that too many geofences have been registered. | |||||||||
| int | GEOFENCE_EXITED | The constant to indicate that the user has exited the geofence. | |||||||||
| int | GEOFENCE_FAILURE | The constant used to indicate that the geofence operation has failed. | |||||||||
| int | GEOFENCE_SUCCESS | The constant used to indicate success of the particular geofence call | |||||||||
| int | GEOFENCE_UNCERTAIN | The constant to indicate that the user is uncertain with respect to a geofence. | |||||||||
| int | MONITORING_TYPE_GPS_HARDWARE | Constant for geofence monitoring done by the GPS hardware. | |||||||||
| int | MONITOR_CURRENTLY_AVAILABLE | Constant to indiciate that the monitoring system is currently available for monitoring geofences. | |||||||||
| int | MONITOR_CURRENTLY_UNAVAILABLE | Constant to indiciate that the monitoring system is currently unavailable for monitoring geofences. | |||||||||
| int | MONITOR_UNSUPPORTED | Constant to indiciate that the monitoring system is unsupported for hardware geofence monitoring. | |||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Creates a circular geofence which is monitored by subsystems in the hardware.
| |||||||||||
Returns all the hardware geofence monitoring systems which are supported
Call | |||||||||||
Returns current status of a hardware geofence monitoring system.
| |||||||||||
Pauses the monitoring of a geofence added by
addGeofence(int, int, GeofenceHardwareRequest, GeofenceHardwareCallback) call. | |||||||||||
Register the callback to be notified when the state of a hardware geofence
monitoring system changes.
| |||||||||||
Removes a geofence added by
addGeofence(int, int, GeofenceHardwareRequest, GeofenceHardwareCallback) call. | |||||||||||
Resumes the monitoring of a geofence added by
pauseGeofence(int, int) call. | |||||||||||
Unregister the callback that was used with
registerForMonitorStateChangeCallback(int, GeofenceHardwareMonitorCallback)
to notify when the state of the hardware geofence monitoring system changes. | |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
The constant to indicate that the user has entered the geofence.
The constant used to indicate that the geofence id already exists.
The constant used to indicate that the geofence id is unknown.
The constant used to indicate that the transition requested for the geofence is invalid.
The constant used to indicate that too many geofences have been registered.
The constant to indicate that the user has exited the geofence.
The constant used to indicate that the geofence operation has failed.
The constant used to indicate success of the particular geofence call
The constant to indicate that the user is uncertain with respect to a geofence. nn
Constant for geofence monitoring done by the GPS hardware.
Constant to indiciate that the monitoring system is currently available for monitoring geofences.
Constant to indiciate that the monitoring system is currently unavailable for monitoring geofences.
Constant to indiciate that the monitoring system is unsupported for hardware geofence monitoring.
Creates a circular geofence which is monitored by subsystems in the hardware.
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.
onGeofenceAdd(int, int) will be called with the result of the
add call from the hardware. The 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 ACCESS_FINE_LOCATION permission when
MONITORING_TYPE_GPS_HARDWARE is used.
Requires 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. |
|---|
Returns all the hardware geofence monitoring systems which are supported
Call getStatusOfMonitoringType(int) to know the current state
of a monitoring system.
Requires LOCATION_HARDWARE permission to access
geofencing in hardware.
Returns current status of a hardware geofence monitoring system.
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.
Pauses the monitoring of a geofence added by addGeofence(int, int, GeofenceHardwareRequest, GeofenceHardwareCallback) call.
If this call returns true, it means that the geofence has been sent to the hardware.
onGeofencePause(int, int) will be called with the result of the
pause call from the hardware.
Requires ACCESS_FINE_LOCATION permission when
MONITORING_TYPE_GPS_HARDWARE is used.
Requires 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. |
Register the callback to be notified when the state of a hardware geofence
monitoring system changes. For instance, it can change from
MONITOR_CURRENTLY_AVAILABLE to MONITOR_CURRENTLY_UNAVAILABLE
Requires ACCESS_FINE_LOCATION permission when
MONITORING_TYPE_GPS_HARDWARE is used.
Requires 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 monitor |
|---|---|
| callback | Callback that will be called. |
Removes a geofence added by addGeofence(int, int, GeofenceHardwareRequest, GeofenceHardwareCallback) call.
If this call returns true, it means that the geofence has been sent to the hardware.
onGeofenceRemove(int, int) will be called with the result of the
remove call from the hardware.
Requires ACCESS_FINE_LOCATION permission when
MONITORING_TYPE_GPS_HARDWARE is used.
Requires 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. |
Resumes the monitoring of a geofence added by pauseGeofence(int, int) call.
If this call returns true, it means that the geofence has been sent to the hardware.
onGeofenceResume(int, int) will be called with the result of the
resume call from the hardware.
Requires ACCESS_FINE_LOCATION permission when
MONITORING_TYPE_GPS_HARDWARE is used.
Requires 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 |
Unregister the callback that was used with registerForMonitorStateChangeCallback(int, GeofenceHardwareMonitorCallback)
to notify when the state of the hardware geofence monitoring system changes.
Requires ACCESS_FINE_LOCATION permission when
MONITORING_TYPE_GPS_HARDWARE is used.
Requires 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 monitor |
|---|---|
| callback | Callback that will be called. |