FileDocCategorySizeDatePackage
GeofenceHardware.javaAPI DocAndroid 5.1 API22884Thu Mar 12 22:22:10 GMT 2015android.hardware.location

GeofenceHardware

public final class GeofenceHardware extends Object
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: {@link #GEOFENCE_ENTERED}, {@link #GEOFENCE_EXITED}, {@link #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 {@link #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, {@link #MONITORING_TYPE_GPS_HARDWARE} uses 95% as a confidence level.

hide

Fields Summary
private IGeofenceHardware
mService
static final int
NUM_MONITORS
public static final int
MONITORING_TYPE_GPS_HARDWARE
Constant for geofence monitoring done by the GPS hardware.
public static final int
MONITORING_TYPE_FUSED_HARDWARE
Constant for geofence monitoring done by the Fused hardware.
public static final int
MONITOR_CURRENTLY_AVAILABLE
Constant to indicate that the monitoring system is currently available for monitoring geofences.
public static final int
MONITOR_CURRENTLY_UNAVAILABLE
Constant to indicate that the monitoring system is currently unavailable for monitoring geofences.
public static final int
MONITOR_UNSUPPORTED
Constant to indicate that the monitoring system is unsupported for hardware geofence monitoring.
public static final int
GEOFENCE_ENTERED
The constant to indicate that the user has entered the geofence.
public static final int
GEOFENCE_EXITED
The constant to indicate that the user has exited the geofence.
public static final int
GEOFENCE_UNCERTAIN
The constant to indicate that the user is uncertain with respect to a geofence.
public static final int
GEOFENCE_SUCCESS
The constant used to indicate success of the particular geofence call
public static final int
GEOFENCE_ERROR_TOO_MANY_GEOFENCES
The constant used to indicate that too many geofences have been registered.
public static final int
GEOFENCE_ERROR_ID_EXISTS
The constant used to indicate that the geofence id already exists.
public static final int
GEOFENCE_ERROR_ID_UNKNOWN
The constant used to indicate that the geofence id is unknown.
public static final int
GEOFENCE_ERROR_INVALID_TRANSITION
The constant used to indicate that the transition requested for the geofence is invalid.
public static final int
GEOFENCE_FAILURE
The constant used to indicate that the geofence operation has failed.
public static final int
GEOFENCE_ERROR_INSUFFICIENT_MEMORY
The constant used to indicate that the operation failed due to insufficient memory.
public static final int
SOURCE_TECHNOLOGY_GNSS
The constant used to indicate that the monitoring system supports GNSS.
public static final int
SOURCE_TECHNOLOGY_WIFI
The constant used to indicate that the monitoring system supports WiFi.
public static final int
SOURCE_TECHNOLOGY_SENSORS
The constant used to indicate that the monitoring system supports Sensors.
public static final int
SOURCE_TECHNOLOGY_CELL
The constant used to indicate that the monitoring system supports Cell.
public static final int
SOURCE_TECHNOLOGY_BLUETOOTH
The constant used to indicate that the monitoring system supports Bluetooth.
private HashMap
mCallbacks
private HashMap
mMonitorCallbacks
Constructors Summary
public GeofenceHardware(IGeofenceHardware service)


       
        mService = service;
Methods Summary
public booleanaddGeofence(int geofenceId, int monitoringType, GeofenceHardwareRequest geofenceRequest, GeofenceHardwareCallback callback)
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. {@link GeofenceHardwareCallback#onGeofenceAdd} will be called with the result of the add call from the hardware. The {@link GeofenceHardwareCallback#onGeofenceAdd} will be called with the following parameters when a transition event occurs.

  • The geofence Id
  • The location object indicating the last known location.
  • The transition associated with the geofence. One of {@link #GEOFENCE_ENTERED}, {@link #GEOFENCE_EXITED}, {@link #GEOFENCE_UNCERTAIN}
  • The timestamp when the geofence transition occured.
  • The monitoring type ({@link #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 {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission when {@link #MONITORING_TYPE_GPS_HARDWARE} is used.

Requires {@link 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 {@link GeofenceHardwareRequest} to set all the characteristics of the geofence. Use the created GeofenceHardwareRequest object in this call.

param
geofenceId The id associated with the geofence.
param
monitoringType The type of the hardware subsystem that should be used to monitor the geofence.
param
geofenceRequest The {@link GeofenceHardwareRequest} object associated with the geofence.
param
callback {@link GeofenceHardwareCallback} that will be use to notify the transition.
return
true when the geofence is successfully sent to the hardware for addition.
throws
IllegalArgumentException when the geofence request type is not supported.

        try {
            if (geofenceRequest.getType() == GeofenceHardwareRequest.GEOFENCE_TYPE_CIRCLE) {
                return mService.addCircularFence(
                        monitoringType,
                        new GeofenceHardwareRequestParcelable(geofenceId, geofenceRequest),
                        getCallbackWrapper(callback));
            } else {
                throw new IllegalArgumentException("Geofence Request type not supported");
            }
        } catch (RemoteException e) {
        }
        return false;
private android.hardware.location.GeofenceHardware$GeofenceHardwareCallbackWrappergetCallbackWrapper(GeofenceHardwareCallback callback)

        synchronized (mCallbacks) {
            GeofenceHardwareCallbackWrapper wrapper = mCallbacks.get(callback);
            if (wrapper == null) {
                wrapper = new GeofenceHardwareCallbackWrapper(callback);
                mCallbacks.put(callback, wrapper);
            }
            return wrapper;
        }
private android.hardware.location.GeofenceHardware$GeofenceHardwareMonitorCallbackWrappergetMonitorCallbackWrapper(GeofenceHardwareMonitorCallback callback)

        synchronized (mMonitorCallbacks) {
            GeofenceHardwareMonitorCallbackWrapper wrapper = mMonitorCallbacks.get(callback);
            if (wrapper == null) {
                wrapper = new GeofenceHardwareMonitorCallbackWrapper(callback);
                mMonitorCallbacks.put(callback, wrapper);
            }
            return wrapper;
        }
public int[]getMonitoringTypes()
Returns all the hardware geofence monitoring systems which are supported

Call {@link #getStatusOfMonitoringType(int)} to know the current state of a monitoring system.

Requires {@link android.Manifest.permission#LOCATION_HARDWARE} permission to access geofencing in hardware.

return
An array of all the monitoring types. An array of length 0 is returned in case of errors.

        try {
            return mService.getMonitoringTypes();
        } catch (RemoteException e) {
        }
        return new int[0];
public intgetStatusOfMonitoringType(int monitoringType)
Returns current status of a hardware geofence monitoring system.

Status can be one of {@link #MONITOR_CURRENTLY_AVAILABLE}, {@link #MONITOR_CURRENTLY_UNAVAILABLE} or {@link #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 {@link #MONITOR_CURRENTLY_AVAILABLE} to {@link #MONITOR_CURRENTLY_UNAVAILABLE}.

param
monitoringType
return
Current status of the monitoring type.

        try {
            return mService.getStatusOfMonitoringType(monitoringType);
        } catch (RemoteException e) {
            return MONITOR_UNSUPPORTED;
        }
public booleanpauseGeofence(int geofenceId, int monitoringType)
Pauses the monitoring of a geofence added by {@link #addGeofence} call.

If this call returns true, it means that the geofence has been sent to the hardware. {@link GeofenceHardwareCallback#onGeofencePause} will be called with the result of the pause call from the hardware.

Requires {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission when {@link #MONITORING_TYPE_GPS_HARDWARE} is used.

Requires {@link 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.

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

        try {
            return mService.pauseGeofence(geofenceId, monitoringType);
        } catch (RemoteException e) {
        }
        return false;
public booleanregisterForMonitorStateChangeCallback(int monitoringType, GeofenceHardwareMonitorCallback callback)
Register the callback to be notified when the state of a hardware geofence monitoring system changes. For instance, it can change from {@link #MONITOR_CURRENTLY_AVAILABLE} to {@link #MONITOR_CURRENTLY_UNAVAILABLE}

Requires {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission when {@link #MONITORING_TYPE_GPS_HARDWARE} is used.

Requires {@link 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.

param
monitoringType Type of the monitor
param
callback Callback that will be called.
return
true on success

        try {
            return mService.registerForMonitorStateChangeCallback(monitoringType,
                    getMonitorCallbackWrapper(callback));
        } catch (RemoteException e) {
        }
        return false;
private voidremoveCallback(GeofenceHardwareCallback callback)

        synchronized (mCallbacks) {
            mCallbacks.remove(callback);
        }
public booleanremoveGeofence(int geofenceId, int monitoringType)
Removes a geofence added by {@link #addGeofence} call.

If this call returns true, it means that the geofence has been sent to the hardware. {@link GeofenceHardwareCallback#onGeofenceRemove} will be called with the result of the remove call from the hardware.

Requires {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission when {@link #MONITORING_TYPE_GPS_HARDWARE} is used.

Requires {@link 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.

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

       try {
           return mService.removeGeofence(geofenceId, monitoringType);
       } catch (RemoteException e) {
       }
       return false;
private voidremoveMonitorCallback(GeofenceHardwareMonitorCallback callback)

        synchronized (mMonitorCallbacks) {
            mMonitorCallbacks.remove(callback);
        }
public booleanresumeGeofence(int geofenceId, int monitoringType, int monitorTransition)
Resumes the monitoring of a geofence added by {@link #pauseGeofence} call.

If this call returns true, it means that the geofence has been sent to the hardware. {@link GeofenceHardwareCallback#onGeofenceResume} will be called with the result of the resume call from the hardware.

Requires {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission when {@link #MONITORING_TYPE_GPS_HARDWARE} is used.

Requires {@link 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.

param
geofenceId The id of the geofence.
param
monitoringType The type of the hardware subsystem that should be used to monitor the geofence.
param
monitorTransition Bitwise OR of {@link #GEOFENCE_ENTERED}, {@link #GEOFENCE_EXITED}, {@link #GEOFENCE_UNCERTAIN}
return
true when the geofence is successfully sent to the hardware for resumption.

        try {
            return mService.resumeGeofence(geofenceId, monitoringType, monitorTransition);
        } catch (RemoteException e) {
        }
        return false;
public booleanunregisterForMonitorStateChangeCallback(int monitoringType, GeofenceHardwareMonitorCallback callback)
Unregister the callback that was used with {@link #registerForMonitorStateChangeCallback} to notify when the state of the hardware geofence monitoring system changes.

Requires {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission when {@link #MONITORING_TYPE_GPS_HARDWARE} is used.

Requires {@link 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.

param
monitoringType Type of the monitor
param
callback Callback that will be called.
return
true on success

        boolean  result = false;
        try {
            result = mService.unregisterForMonitorStateChangeCallback(monitoringType,
                    getMonitorCallbackWrapper(callback));
            if (result) removeMonitorCallback(callback);

        } catch (RemoteException e) {
        }
        return result;