public interface

# GeofencingApi

com.google.android.gms.location.GeofencingApi

## Class Overview

The main entry point for interacting with the geofencing APIs.

The methods must be used in conjunction with a `GoogleApiClient`. E.g.

     new GoogleApiClient.Builder(context)
         .addApi(LocationServices.API)
         .addConnectionCallbacks(this)
         .addOnConnectionFailedListener(this)
         .build()

All methods are thread safe.

## Summary

Public Methods
abstract PendingResult<Status> | addGeofences(GoogleApiClient client, GeofencingRequest geofencingRequest, PendingIntent pendingIntent) Sets alerts to be notified when the device enters or exits one of the specified geofences.
abstract PendingResult<Status> | addGeofences(GoogleApiClient client, List<Geofence> geofences, PendingIntent pendingIntent) This method is deprecated. use `addGeofences(GoogleApiClient, GeofencingRequest, PendingIntent)` instead.
abstract PendingResult<Status> | removeGeofences(GoogleApiClient client, List<String> geofenceRequestIds) Removes geofences by their request IDs.
abstract PendingResult<Status> | removeGeofences(GoogleApiClient client, PendingIntent pendingIntent) Removes all geofences associated with the given `pendingIntent`.

## Public Methods

#### public abstract PendingResult<Status> addGeofences (GoogleApiClient client, 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.

`Status` is returned when geofences are successfully added or failed to be added. 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(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

client | an existing GoogleApiClient. It must be connected at the time of this call, which is normally achieved by calling `connect()` and waiting for `onConnected(Bundle)` to be called.
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 abstract PendingResult<Status> addGeofences (GoogleApiClient client, List<Geofence> geofences, PendingIntent pendingIntent)

This method is deprecated.
use `addGeofences(GoogleApiClient, GeofencingRequest, PendingIntent)` instead.

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.

`Status` is returned when geofences are successfully added or failed to be added. 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(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

client | An existing GoogleApiClient. It must be connected at the time of this call, which is normally achieved by calling `connect()` and waiting for `onConnected(Bundle)` to be called.
geofences | a list of geofences to be added. The geofences must be created using `Geofence.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
IllegalArgumentException | if `geofences` is `null` or empty
NullPointerException | if `intent` or `listener` is `null`

#### public abstract PendingResult<Status> removeGeofences (GoogleApiClient client, List<String> geofenceRequestIds)

Removes geofences by their request IDs. Request ID is specified when you create a `Geofence` by calling `setRequestId(String)`.

`Status` is returned when geofences are successfully removed or fail to be removed. Refer to `GeofenceStatusCodes` for possible errors when removing geofences.

This method requires `ACCESS_FINE_LOCATION`.

##### Parameters

client | An existing GoogleApiClient. It must be connected at the time of this call, which is normally achieved by calling `connect()` and waiting for `onConnected(Bundle)` to be called.
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 abstract PendingResult<Status> removeGeofences (GoogleApiClient client, 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(GoogleApiClient, List, PendingIntent)` and thus the removal operation will remove nothing.

`Status` is returned when geofences are successfully removed or fail to be removed. Refer to `GeofenceStatusCodes` for possible errors when removing geofences.

This method requires `ACCESS_FINE_LOCATION`.

##### Parameters

client | An existing GoogleApiClient. It must be connected at the time of this call, which is normally achieved by calling `connect()` and waiting for `onConnected(Bundle)` to be called.
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