The main entry point for interacting with the geofencing APIs.
Get an instance of this client via
getGeofencingClient(Activity)
.
All methods are thread safe.
Inherited Field Summary
Public Method Summary
Task<Void> |
addGeofences(GeofencingRequest
geofencingRequest, PendingIntent
pendingIntent)
Sets alerts to be notified when the device enters or exits one of the specified
geofences.
|
Task<Void> | |
Task<Void> |
removeGeofences(PendingIntent
pendingIntent)
Removes all geofences associated with the given
pendingIntent .
|
Inherited Method Summary
Public Methods
public Task<Void> addGeofences (GeofencingRequest geofencingRequest, PendingIntent pendingIntent)
Sets alerts to be notified when the device enters or exits one of the specified
geofences. If an existing geofence with the same request ID is already registered, the
old geofence is replaced by the new one, and the new PendingIntent
is used
to generate intents for alerts.
Task
is
completed when geofences are successfully added or failed to be added. Upon failure, an
ApiException
will be set on the Task
. Refer to
GeofenceStatusCodes
for possible errors when adding geofences.
When a geofence transition (for example, entering or exiting) matches one of the
transition filter (see
setTransitionTypes(int)
) in the given geofence list, an intent is generated
using the given pending intent. You can call
fromIntent(android.content.Intent)
to get the transition type, geofences
that triggered this intent and the location that triggered the geofence transition.
In case network location provider is disabled by the user, the geofence service will
stop updating, all registered geofences will be removed and an intent is generated by
the provided pending intent. In this case, the GeofencingEvent
created from this intent represents an error event, where hasError()
returns true
and
getErrorCode()
returns
GEOFENCE_NOT_AVAILABLE
.
This method requires
ACCESS_FINE_LOCATION
.
Parameters
geofencingRequest | geofencing request that include a list of geofences to be added and related
triggering behavior. The request must be created using
GeofencingRequest.Builder . |
---|---|
pendingIntent | a pending intent that will be used to generate an intent when matched geofence transition is observed |
Throws
SecurityException | if the app does not have
ACCESS_FINE_LOCATION permission |
---|---|
NullPointerException | if geofencingRequest or pendingIntent is
null |
public Task<Void> removeGeofences (List<String> geofenceRequestIds)
Removes geofences by their request IDs. Request ID is specified when you create a
Geofence
by calling
setRequestId(String)
.
Task
is
completed when geofences are successfully removed or fail to be removed. Upon failure,
an ApiException
will be set on the Task
. Refer to
GeofenceStatusCodes
for possible errors when removing geofences.
This method requires
ACCESS_FINE_LOCATION
.
Parameters
geofenceRequestIds | a list of request IDs of geofences that need to be removed |
---|
Throws
IllegalArgumentException | if geofenceRequestIds is null or empty |
---|---|
SecurityException | if the app does not have
ACCESS_FINE_LOCATION permission |
NullPointerException | if listener is null |
public Task<Void> removeGeofences (PendingIntent pendingIntent)
Removes all geofences associated with the given pendingIntent
.
Warning:
equals(Object)
is used for comparison. Please use FLAG_UPDATE_CURRENT
rather than FLAG_CANCEL_CURRENT
when creating the pending intent, otherwise you will not get the same pending intent
you provided to
addGeofences(GeofencingRequest, PendingIntent)
and thus the removal
operation will remove nothing.
Task
is
completed when geofences are successfully removed or fail to be removed. Upon failure,
an ApiException
will be set on the Task
. Refer to
GeofenceStatusCodes
for possible errors when removing geofences.
This method requires
ACCESS_FINE_LOCATION
.
Parameters
pendingIntent | the pending intent associated with the geofences that need to be removed. |
---|
Throws
SecurityException | if the app does not have
ACCESS_FINE_LOCATION permission |
---|---|
NullPointerException | if intent or listener is null |