PassiveMonitoringClient

public interface PassiveMonitoringClient

Client which provides a means to passively monitor data without requiring an ongoing workout.

The lifetimes of registrations made through this client are independent of the lifetime of the subscribing app. These registrations are therefore suitable for notifying of ongoing measurements or triggered passive goals, regardless of whether or not the subscribing app is currently running, in the foreground or engaged in a workout.

Summary

Public methods
abstract @NonNull ListenableFuture<@NonNull Void>

Unregisters the subscription made by setPassiveListenerCallback.
abstract @NonNull ListenableFuture<@NonNull Void>

Unregisters the subscription made by setPassiveListenerServiceAsync.
abstract @NonNull ListenableFuture<@NonNull Void>

Flushes the sensors for the registered DataTypes.
abstract @NonNull ListenableFuture<@NonNull PassiveMonitoringCapabilities>

Returns the PassiveMonitoringCapabilities of this client for this device.
abstract void

Subscribes for updates to be periodically delivered to the app via bound callback.
abstract void

Subscribes for updates to be periodically delivered to the app via bound callback.
abstract @NonNull ListenableFuture<@NonNull Void>

Subscribes for updates to be periodically delivered to the app.

Extension functions
default final @NonNull Void

Unregisters the subscription made by PassiveMonitoringClient.setPassiveListenerCallback.
default final @NonNull Void

Unregisters the subscription made by setPassiveListenerService.
default final @NonNull Void

Flushes the sensors for the registered DataTypes.
default final @NonNull PassiveMonitoringCapabilities

Returns the PassiveMonitoringCapabilities of this client for this device.
default final @NonNull Void

Subscribes for updates to be periodically delivered to the app.

Public methods

clearPassiveListenerCallbackAsync

Added in 1.0.0
abstract @NonNull ListenableFuture<@NonNull Void> clearPassiveListenerCallbackAsync()

Unregisters the subscription made by setPassiveListenerCallback.

Data will not be delivered after this call so if clients care about any pending batched data they should call flush before unregistering.

Returns
@NonNull ListenableFuture<@NonNull Void>

a ListenableFuture that completes when the un-registration succeeds in Health Services. This is a no-op if the callback has already been unregistered

clearPassiveListenerServiceAsync

Added in 1.0.0
abstract @NonNull ListenableFuture<@NonNull Void> clearPassiveListenerServiceAsync()

Unregisters the subscription made by setPassiveListenerServiceAsync.

Data will not be delivered after this call so if clients care about any pending batched data they should call flush before unregistering.

Returns
@NonNull ListenableFuture<@NonNull Void>

a ListenableFuture that completes when the un-registration succeeds in Health Services. This is a no-op if the callback has already been unregistered

flushAsync

Added in 1.0.0
abstract @NonNull ListenableFuture<@NonNull Void> flushAsync()

Flushes the sensors for the registered DataTypes.

If no listener has been registered by this client, this will be a no-op. This call should be used sparingly and will be subject to throttling by Health Services.

Returns
@NonNull ListenableFuture<@NonNull Void>

a ListenableFuture that will complete when the flush is finished

getCapabilitiesAsync

Added in 1.0.0
abstract @NonNull ListenableFuture<@NonNull PassiveMonitoringCapabilities> getCapabilitiesAsync()

Returns the PassiveMonitoringCapabilities of this client for this device.

This can be used to determine what DataTypes this device supports for passive monitoring and goals. Clients should use the capabilities to inform their requests since Health Services will typically reject requests made for DataTypes which are not supported.

Returns
@NonNull ListenableFuture<@NonNull PassiveMonitoringCapabilities>

a ListenableFuture containing the PassiveMonitoringCapabilities for this device

setPassiveListenerCallback

Added in 1.0.0
abstract void setPassiveListenerCallback(
    @NonNull PassiveListenerConfig config,
    @NonNull PassiveListenerCallback callback
)

Subscribes for updates to be periodically delivered to the app via bound callback.

Data updates are sent on generation (they will not be batched) and will be delivered until the DataType is unregistered, either by explicitly calling clearPassiveListenerCallbackAsync or by registering again without that DataType included in the request. Higher frequency updates are available through ExerciseClient or MeasureClient.

The provided callback will take priority in receiving updates as long the app is alive and the callback can be successfully notified. Otherwise, the request will automatically be unregistered.

This registration is unique per subscribing app and operates independently from setPassiveListenerServiceAsync (each channel will receive its own stream of data). Subsequent registrations will replace the previous registration, if one had been made. The client is responsible for ensuring that their requested PassiveListenerConfig is supported on this device by checking the PassiveMonitoringCapabilities. The returned future will fail if the request is not supported on the current device or the client does not have the required permissions for the request.

This call completes when the registration succeeds in Health Services. If the request is not supported on this device or the calling app lacks permissions, then PassiveListenerCallback.onRegistrationFailed will be invoked on the provided callback.

Parameters
@NonNull PassiveListenerConfig config

the requested PassiveListenerConfig from the client
@NonNull PassiveListenerCallback callback

the PassiveListenerCallback that will receive updates on the main thread

setPassiveListenerCallback

Added in 1.0.0
abstract void setPassiveListenerCallback(
    @NonNull PassiveListenerConfig config,
    @NonNull Executor executor,
    @NonNull PassiveListenerCallback callback
)

Subscribes for updates to be periodically delivered to the app via bound callback.

Data updates are sent on generation (they will not be batched) and will be delivered until the DataType is unregistered, either by explicitly calling clearPassiveListenerCallbackAsync or by registering again without that DataType included in the request. Higher frequency updates are available through ExerciseClient or MeasureClient.

The provided callback will take priority in receiving updates as long the app is alive and the callback can be successfully notified. Otherwise, the request will automatically be unregistered.

This registration is unique per subscribing app and operates independently from setPassiveListenerServiceAsync (each channel will receive its own stream of data). Subsequent registrations will replace the previous registration, if one had been made. The client is responsible for ensuring that their requested PassiveListenerConfig is supported on this device by checking the PassiveMonitoringCapabilities. The returned future will fail if the request is not supported on the current device or the client does not have the required permissions for the request.

This call completes when the registration succeeds in Health Services. If the request is not supported on this device or the calling app lacks permissions, then PassiveListenerCallback.onRegistrationFailed will be invoked on the provided callback.

Parameters
@NonNull PassiveListenerConfig config

the requested PassiveListenerConfig from the client
@NonNull Executor executor

the Executor on which the callback will be invoked
@NonNull PassiveListenerCallback callback

the PassiveListenerCallback that will receive updates

setPassiveListenerServiceAsync

Added in 1.0.0
abstract @NonNull ListenableFuture<@NonNull Void> setPassiveListenerServiceAsync(
    @NonNull Class<@NonNull PassiveListenerService> service,
    @NonNull PassiveListenerConfig config
)

Subscribes for updates to be periodically delivered to the app.

Data updates will be batched and delivered from the point of initial registration and will continue to be delivered until the DataType is unregistered, either by explicitly calling clearPassiveListenerServiceAsync or by registering again without that DataType included in the request. Higher frequency updates are available through ExerciseClient or MeasureClient. Any requested goal, user activity, or health event updates will not be batched.

Health Services will automatically bind to the provided PassiveListenerService to send the update. Clients are responsible for defining the service in their app manifest. They should also require the com.google.android.wearable.healthservices.permission.PASSIVE_DATA_BINDING permission in their app manifest service definition in order to ensure that Health Services is the source of the binding.

This registration is unique per subscribing app. Subsequent registrations will replace the previous registration, if one had been made. The client is responsible for ensuring that their requested PassiveListenerConfig is supported on this device by checking the PassiveMonitoringCapabilities. The returned future will fail if the request is not supported on the current device or the client does not have the required permissions for the request.

Parameters
@NonNull Class<@NonNull PassiveListenerService> service

the PassiveListenerService to bind to
@NonNull PassiveListenerConfig config

the PassiveListenerConfig from the client
Returns
@NonNull ListenableFuture<@NonNull Void>

a ListenableFuture that completes when the registration succeeds in Health Services or fails when the request is not supported on the current device or the client does not have the required permissions for the request

Extension functions

PassiveMonitoringClientExtensionKt.clearPassiveListenerCallback

default final @NonNull Void PassiveMonitoringClientExtensionKt.clearPassiveListenerCallback(
    @NonNull PassiveMonitoringClient receiver
)

Unregisters the subscription made by PassiveMonitoringClient.setPassiveListenerCallback.

Data will not be delivered after this call so if clients care about any pending batched data they should call flush before unregistering.

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

PassiveMonitoringClientExtensionKt.clearPassiveListenerService

default final @NonNull Void PassiveMonitoringClientExtensionKt.clearPassiveListenerService(
    @NonNull PassiveMonitoringClient receiver
)

Unregisters the subscription made by setPassiveListenerService.

Data will not be delivered after this call so if clients care about any pending batched data they should call flush before unregistering.

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

PassiveMonitoringClientExtensionKt.flush

default final @NonNull Void PassiveMonitoringClientExtensionKt.flush(
    @NonNull PassiveMonitoringClient receiver
)

Flushes the sensors for the registered DataTypes.

If no listener has been registered by this client, this will be a no-op. This call should be used sparingly and will be subject to throttling by Health Services.

Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

PassiveMonitoringClientExtensionKt.getCapabilities

default final @NonNull PassiveMonitoringCapabilities PassiveMonitoringClientExtensionKt.getCapabilities(
    @NonNull PassiveMonitoringClient receiver
)

Returns the PassiveMonitoringCapabilities of this client for this device.

This can be used to determine what DataTypes this device supports for passive monitoring and goals. Clients should use the capabilities to inform their requests since Health Services will typically reject requests made for DataTypes which are not supported.

Returns
@NonNull PassiveMonitoringCapabilities

a PassiveMonitoringCapabilities for this device
Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call

PassiveMonitoringClientExtensionKt.setPassiveListenerService

default final @NonNull Void PassiveMonitoringClientExtensionKt.setPassiveListenerService(
    @NonNull PassiveMonitoringClient receiver,
    @NonNull Class<@NonNull PassiveListenerService> service,
    @NonNull PassiveListenerConfig config
)

Subscribes for updates to be periodically delivered to the app.

Data updates will be batched and delivered from the point of initial registration and will continue to be delivered until the DataType is unregistered, either by explicitly calling clearPassiveListenerService or by registering again without that DataType included in the request. Higher frequency updates are available through ExerciseClient or MeasureClient. Any requested goal, user activity, or health event updates will not be batched.

Health Services will automatically bind to the provided PassiveListenerService to send the update. Clients are responsible for defining the service in their app manifest. They should also require the com.google.android.wearable.healthservices.permission.PASSIVE_DATA_BINDING permission in their app manifest service definition in order to ensure that Health Services is the source of the binding.

This registration is unique per subscribing app. Subsequent registrations will replace the previous registration, if one had been made. The client is responsible for ensuring that their requested PassiveListenerConfig is supported on this device by checking the PassiveMonitoringCapabilities. The returned future will fail if the request is not supported on the current device or the client does not have the required permissions for the request.

Parameters
@NonNull Class<@NonNull PassiveListenerService> service

the PassiveListenerService to bind to
@NonNull PassiveListenerConfig config

the PassiveListenerConfig from the client
Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call
java.lang.SecurityException

if calling app does not have the required permissions