PassiveMonitoringClient

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 functions
ListenableFuture<Void>

Unregisters the subscription made by setPassiveListenerCallback.
ListenableFuture<Void>

Unregisters the subscription made by setPassiveListenerServiceAsync.
ListenableFuture<Void>

Flushes the sensors for the registered DataTypes.
ListenableFuture<PassiveMonitoringCapabilities>

Returns the PassiveMonitoringCapabilities of this client for this device.
Unit

Subscribes for updates to be periodically delivered to the app via bound callback.
Unit
setPassiveListenerCallback(
    config: PassiveListenerConfig,
    executor: Executor,
    callback: PassiveListenerCallback
)

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

Subscribes for updates to be periodically delivered to the app.

Extension functions
suspend Void

Unregisters the subscription made by PassiveMonitoringClient.setPassiveListenerCallback.
suspend Void

Unregisters the subscription made by setPassiveListenerService.
suspend Void

Flushes the sensors for the registered DataTypes.
suspend PassiveMonitoringCapabilities

Returns the PassiveMonitoringCapabilities of this client for this device.
suspend Void

Subscribes for updates to be periodically delivered to the app.

Public functions

clearPassiveListenerCallbackAsync

Added in 1.0.0
fun clearPassiveListenerCallbackAsync(): ListenableFuture<Void>

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
ListenableFuture<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
fun clearPassiveListenerServiceAsync(): ListenableFuture<Void>

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
ListenableFuture<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
fun flushAsync(): ListenableFuture<Void>

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
ListenableFuture<Void>

a ListenableFuture that will complete when the flush is finished

getCapabilitiesAsync

Added in 1.0.0
fun getCapabilitiesAsync(): ListenableFuture<PassiveMonitoringCapabilities>

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
ListenableFuture<PassiveMonitoringCapabilities>

a ListenableFuture containing the PassiveMonitoringCapabilities for this device

setPassiveListenerCallback

Added in 1.0.0
fun setPassiveListenerCallback(
    config: PassiveListenerConfig,
    callback: PassiveListenerCallback
): Unit

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
config: PassiveListenerConfig

the requested PassiveListenerConfig from the client
callback: PassiveListenerCallback

the PassiveListenerCallback that will receive updates on the main thread

setPassiveListenerCallback

Added in 1.0.0
fun setPassiveListenerCallback(
    config: PassiveListenerConfig,
    executor: Executor,
    callback: PassiveListenerCallback
): Unit

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
config: PassiveListenerConfig

the requested PassiveListenerConfig from the client
executor: Executor

the Executor on which the callback will be invoked
callback: PassiveListenerCallback

the PassiveListenerCallback that will receive updates

setPassiveListenerServiceAsync

Added in 1.0.0
fun setPassiveListenerServiceAsync(
    service: Class<PassiveListenerService>,
    config: PassiveListenerConfig
): ListenableFuture<Void>

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
service: Class<PassiveListenerService>

the PassiveListenerService to bind to
config: PassiveListenerConfig

the PassiveListenerConfig from the client
Returns
ListenableFuture<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

clearPassiveListenerCallback

suspend fun PassiveMonitoringClient.clearPassiveListenerCallback(): Void

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

clearPassiveListenerService

suspend fun PassiveMonitoringClient.clearPassiveListenerService(): Void

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

flush

suspend fun PassiveMonitoringClient.flush(): Void

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

getCapabilities

suspend fun PassiveMonitoringClient.getCapabilities(): PassiveMonitoringCapabilities

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
PassiveMonitoringCapabilities

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

if Health Service fails to process the call

setPassiveListenerService

suspend fun PassiveMonitoringClient.setPassiveListenerService(
    service: Class<PassiveListenerService>,
    config: PassiveListenerConfig
): Void

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
service: Class<PassiveListenerService>

the PassiveListenerService to bind to
config: PassiveListenerConfig

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