Android APIs
public final class

GeofenceHardware

extends Object
java.lang.Object
   ↳ android.hardware.location.GeofenceHardware

Class Overview

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.

Summary

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
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, GeofenceHardwareRequest, 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)
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, GeofenceHardwareMonitorCallback) to notify when the state of the hardware geofence monitoring system changes.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int GEOFENCE_ENTERED

Added in API level 18

The constant to indicate that the user has entered the geofence.

Constant Value: 1 (0x00000001)

public static final int GEOFENCE_ERROR_ID_EXISTS

Added in API level 18

The constant used to indicate that the geofence id already exists.

Constant Value: 2 (0x00000002)

public static final int GEOFENCE_ERROR_ID_UNKNOWN

Added in API level 18

The constant used to indicate that the geofence id is unknown.

Constant Value: 3 (0x00000003)

public static final int GEOFENCE_ERROR_INVALID_TRANSITION

Added in API level 18

The constant used to indicate that the transition requested for the geofence is invalid.

Constant Value: 4 (0x00000004)

public static final int GEOFENCE_ERROR_TOO_MANY_GEOFENCES

Added in API level 18

The constant used to indicate that too many geofences have been registered.

Constant Value: 1 (0x00000001)

public static final int GEOFENCE_EXITED

Added in API level 18

The constant to indicate that the user has exited the geofence.

Constant Value: 2 (0x00000002)

public static final int GEOFENCE_FAILURE

Added in API level 18

The constant used to indicate that the geofence operation has failed.

Constant Value: 5 (0x00000005)

public static final int GEOFENCE_SUCCESS

Added in API level 18

The constant used to indicate success of the particular geofence call

Constant Value: 0 (0x00000000)

public static final int GEOFENCE_UNCERTAIN

Added in API level 18

The constant to indicate that the user is uncertain with respect to a geofence. nn

Constant Value: 4 (0x00000004)

public static final int MONITORING_TYPE_GPS_HARDWARE

Added in API level 18

Constant for geofence monitoring done by the GPS hardware.

Constant Value: 0 (0x00000000)

public static final int MONITOR_CURRENTLY_AVAILABLE

Added in API level 18

Constant to indiciate that the monitoring system is currently available for monitoring geofences.

Constant Value: 0 (0x00000000)

public static final int MONITOR_CURRENTLY_UNAVAILABLE

Added in API level 18

Constant to indiciate that the monitoring system is currently unavailable for monitoring geofences.

Constant Value: 1 (0x00000001)

public static final int MONITOR_UNSUPPORTED

Added in API level 18

Constant to indiciate that the monitoring system is unsupported for hardware geofence monitoring.

Constant Value: 2 (0x00000002)

Public Methods

public boolean addGeofence (int geofenceId, int monitoringType, GeofenceHardwareRequest geofenceRequest, GeofenceHardwareCallback callback)

Added in API level 18

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.

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.

Parameters
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.
Returns
  • true when the geofence is successfully sent to the hardware for addition.
Throws
IllegalArgumentException when the geofence request type is not supported.

public int[] getMonitoringTypes ()

Added in API level 18

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
  • An array of all the monitoring types. An array of length 0 is returned in case of errors.

public int getStatusOfMonitoringType (int monitoringType)

Added in API level 18

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.

Returns
  • Current status of the monitoring type.

public boolean pauseGeofence (int geofenceId, int monitoringType)

Added in API level 18

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.

Parameters
geofenceId The id of the geofence.
monitoringType The type of the hardware subsystem that should be used to monitor the geofence.
Returns
  • true when the geofence is successfully sent to the hardware for pausing.

public boolean registerForMonitorStateChangeCallback (int monitoringType, GeofenceHardwareMonitorCallback callback)

Added in API level 18

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.

Parameters
monitoringType Type of the monitor
callback Callback that will be called.
Returns
  • true on success

public boolean removeGeofence (int geofenceId, int monitoringType)

Added in API level 18

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.

Parameters
geofenceId The id of the geofence.
monitoringType The type of the hardware subsystem that should be used to monitor the geofence.
Returns
  • true when the geofence is successfully sent to the hardware for removal. .

public boolean resumeGeofence (int geofenceId, int monitoringType, int monitorTransition)

Added in API level 18

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.

Parameters
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
Returns
  • true when the geofence is successfully sent to the hardware for resumption.

public boolean unregisterForMonitorStateChangeCallback (int monitoringType, GeofenceHardwareMonitorCallback callback)

Added in API level 18

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.

Parameters
monitoringType Type of the monitor
callback Callback that will be called.
Returns
  • true on success