public interface

# SensorsApi

com.google.android.gms.fitness.SensorsApi

## Class Overview

API which exposes different sources of fitness data in local and connected devices, and delivers live events to listeners.

The API exposes `data sources` from hardware sensors in the local device and in companion devices. It also exposes data sources from applications. Data sources can be queried via `findDataSources(GoogleApiClient, DataSourcesRequest)`

The API supports adding and removing listeners to live data streams from any available data source. It also allows for listening on a `DataType`, in which case the best available data source (or a combination of them) is used.

The Sensors API should be used whenever live updates from a sensor stream need to be pushed to the application (for instance, to update a UI). The `History` API can be used to query historical data in a pull-based model for scenarios where latency isn't critical.

The Sensors API should be accessed from the `Fitness` entry point. Example:

         GoogleApiClient client = new GoogleApiClient.Builder(context)
             .addApi(Fitness.SENSORS_API)
             ...
             .build();
         client.connect();

         PendingResult<Status> pendingResult = Fitness.SensorsApi.add(
             client,
             new SensorRequest.Builder()
                 .setDataType(DataType.TYPE_STEP_COUNT_DELTA)
                 .setSamplingDelay(1, TimeUnit.MINUTES)  // sample once per minute
                 .build(),
             myStepCountListener);

If the application doesn't need live sensor updates, but instead wants persistent recording of historical sensor data, for batch querying, the `Recording` and `History` APIs and should be used instead.

## Summary

Public Methods
abstract PendingResult<Status> | add(GoogleApiClient client, SensorRequest request, OnDataPointListener listener) Adds a data point listener to a sensor data source.
abstract PendingResult<Status> | add(GoogleApiClient client, SensorRequest request, PendingIntent intent) Adds a `PendingIntent` listener to a sensor data source.
abstract PendingResult<DataSourcesResult> | findDataSources(GoogleApiClient client, DataSourcesRequest request) Finds all available data sources, on the device and remotely.
abstract PendingResult<Status> | remove(GoogleApiClient client, OnDataPointListener listener) Removes a listener from a sensor data source.
abstract PendingResult<Status> | remove(GoogleApiClient client, PendingIntent pendingIntent) Removes PendingIntent listener from a sensor data source.

## Public Methods

#### public abstract PendingResult<Status> add (GoogleApiClient client, SensorRequest request, OnDataPointListener listener)

Adds a data point listener to a sensor data source. This method can be called to listen on live updates from a particular data source, or data type (in which case a default data source is used).

Once the add request succeeds, new data points in the data stream are delivered to the specified listener. Historic data is not delivered, but can be queried via the `History API`. When the application is closing, or once live data is no longer needed, the listener should be removed. If necessary, the `Recording API` can be used to persist data for later querying when the application is re-opened in a battery-efficient manner.

This method can be called several times with the same listener to change the desired sampling rate.

##### Parameters

client | an existing GoogleApiClient. It does not need to be connected at the time of this call, but the add operation will be delayed until the connection is complete
request | request specifying the desired data source or data type, as well as the desired parameters for the add request
listener | the listener that will be used to respond to events. The listener object should be saved, since it can be used to remove the registration when live events are no longer needed

##### Throws

SecurityException | if a required permission is missing for the requested `DataType` or `DataSource`.

#### public abstract PendingResult<Status> add (GoogleApiClient client, SensorRequest request, PendingIntent intent)

Adds a `PendingIntent` listener to a sensor data source. This method can be called to listen on live updates from a particular data source, or a data type (in which case a default data source is used).

Once the add request succeeds, new data points in the data stream are delivered to the specified intent. Historic data is not delivered, but can be queried via the `History API`.

Unlike `add(GoogleApiClient, SensorRequest, OnDataPointListener)`, which takes a listener and is intended for fast sampling rates while the application is on the foreground, this method is intended for slower sampling rates without the need for an always-on service.

The application specifies a PendingIntent callback (typically an IntentService) which will be called when new data points are available in the requested stream. When the PendingIntent is called, the application can use `extract(android.content.Intent)` to extract the DataPoint from the intent. See the documentation of `PendingIntent` for more details.

Any previously registered requests that have the same PendingIntent (as defined by `equals(Object)`) will be replaced by this request.

##### Parameters

client | an existing GoogleApiClient. It does not need to be connected at the time of this call, but the add operation will be delayed until the connection is complete
request | request specifying the desired data source or data type, as well as the desired parameters for the add request
intent | a callback intent to be sent for each new data points.

##### Throws

SecurityException | if a required permission is missing for the requested `DataType` or `DataSource`.

#### public abstract PendingResult<DataSourcesResult> findDataSources (GoogleApiClient client, DataSourcesRequest request)

Finds all available data sources, on the device and remotely. Results are returned asynchronously as a PendingResult.

It's not necessary to call this method if an application is interested only in getting the best available data for a data type, regardless of source. In this case, `add(GoogleApiClient, SensorRequest, OnDataPointListener)` can be used with a generic `data type`.

##### Parameters

client | an existing GoogleApiClient. It does not need to be connected at the time of this call, but the find operation will be delayed until the connection is complete.
request | a built request specifying the data sources we’re interested in finding

##### Returns

- a pending result containing the found data sources.

##### Throws

SecurityException | if a required permission is missing for one or more of the requested `DataType`s.

#### public abstract PendingResult<Status> remove (GoogleApiClient client, OnDataPointListener listener)

Removes a listener from a sensor data source. Should be called whenever live updates are no longer needed, such as when the activity that displays live data is paused, stopped, or destroyed.

##### Parameters

client | an existing GoogleApiClient. Must be connected at the time of this call.
listener | the listener that was used in the `add` request.

##### Throws

IllegalStateException | if client is not connected

#### public abstract PendingResult<Status> remove (GoogleApiClient client, PendingIntent pendingIntent)

Removes PendingIntent listener from a sensor data source. Should be called whenever live updates are no longer needed.

##### Parameters

client | an existing GoogleApiClient. Must be connected at the time of this call.
pendingIntent | the PendingIntent that was used in the `add` request or is equal as defined by `equals(Object)`.

##### Throws

IllegalStateException | if client is not connected