public interface

# SettingsApi

com.google.android.gms.location.SettingsApi

## Class Overview

The main entry point for interacting with the location settings-enabler APIs.

This API makes it easy for an app to ensure that the device's system settings are properly configured for the app's location needs.

When making a request to location services, the device's system settings may be in a state that prevents an app from obtaining the location data that it needs. For example, GPS or Wi-Fi scanning may be switched off. This intent makes it easy to:

- Determine if the relevant system settings are enabled on the device to carry out the desired location request.
- Optionally, invoke a dialog that allows the user to enable the necessary location settings with a single tap.

To use this API, first create a GoogleApiClient which supports at least `LocationServices.API`. Then connect the client to Google Play services:

     mGoogleApiClient = new GoogleApiClient.Builder(context)
         .addApi(LocationServices.API)
         .addConnectionCallbacks(this)
         .addOnConnectionFailedListener(this)
         .build()
     ...
     mGoogleApiClient.connect();

Then create a `LocationSettingsRequest.Builder` and add all of the `LocationRequests` that the app will be using:

     LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder()
         .addLocationRequest(mLocationRequestHighAccuracy)
         .addLocationRequest(mLocationRequestBalancedPowerAccuracy);

If the client is using BLE scans to derive location, it can request that BLE be enabled by calling `setNeedBle(boolean)`:

     builder.setNeedBle(true);

Then check whether current location settings are satisfied:

     PendingResult<LocationSettingsResult> result =
             LocationServices.SettingsApi.checkLocationSettings(mGoogleClient, builder.build());

When the `PendingResult` returns, the client can check the location settings by looking at the status code from the `LocationSettingsResult` object. The client can also retrieve the current state of the relevant location settings by calling `getLocationSettingsStates()`:

     result.setResultCallback(new ResultCallback<LocationSettingsResult>() {
         @Override
         public void onResult(LocationSettingsResult result) {
             final Status status = result.getStatus();
             final LocationSettingsStates = result.getLocationSettingsStates();
             switch (status.getStatusCode()) {
                 case LocationSettingsStatusCodes.SUCCESS:
                     // All location settings are satisfied. The client can initialize location
                     // requests here.
                     ...
                     break;
                 case LocationSettingsStatusCodes.RESOLUTION_REQUIRED:
                     // Location settings are not satisfied. But could be fixed by showing the user
                     // a dialog.
                     try {
                         // Show the dialog by calling startResolutionForResult(),
                         // and check the result in onActivityResult().
                         status.startResolutionForResult(
                             OuterClass.this,
                             REQUEST_CHECK_SETTINGS);
                     } catch (SendIntentException e) {
                         // Ignore the error.
                     }
                     break;
                 case LocationSettingsStatusCodes.SETTINGS_CHANGE_UNAVAILABLE:
                     // Location settings are not satisfied. However, we have no way to fix the
                     // settings so we won't show the dialog.
                     ...
                     break;
             }
         }
     });

If the status code is `RESOLUTION_REQUIRED`, the client can call `startResolutionForResult(Activity, int)` to bring up a dialog, asking for user's permission to modify the location settings to satisfy those requests. The result of the dialog will be returned via `onActivityResult(int, int, Intent)`. If the client is interested in which location providers are available, it can retrieve a `LocationSettingsStates` from the `Intent` by calling `fromIntent(Intent)`:

     @Override
     protected void onActivityResult(int requestCode, int resultCode, Intent data) {
         final LocationSettingsStates states = LocationSettingsStates.fromIntent(intent);
         switch (requestCode) {
             case REQUEST_CHECK_SETTINGS:
                 switch (resultCode) {
                     case Activity.RESULT_OK:
                         // All required changes were successfully made
                         ...
                         break;
                     case Activity.RESULT_CANCELED:
                         // The user was asked to change settings, but chose not to
                         ...
                         break;
                     default:
                         break;
                 }
                 break;
         }
     }

## Summary

Public Methods
abstract PendingResult<LocationSettingsResult> | checkLocationSettings(GoogleApiClient client, LocationSettingsRequest locationSettingsRequest) Checks if the relevant system settings are enabled on the device to carry out the desired location requests.

## Public Methods

#### public abstract PendingResult<LocationSettingsResult> checkLocationSettings (GoogleApiClient client, LocationSettingsRequest locationSettingsRequest)

Checks if the relevant system settings are enabled on the device to carry out the desired location requests.

##### Parameters

client | an existing GoogleApiClient. It does not need to be connected at the time of this call, but the result will be delayed until the connection is complete.
locationSettingsRequest | an object that contains all the location requirements that the client is interested in.

##### Returns

- result containing the status of the request.