MeasureClient

interface MeasureClient

Client which provides a way to make measurements of health data on a device.

This is optimized for apps to register live callbacks on data which may be sampled at a faster rate; this is not meant to be used for long-lived subscriptions to data (for this, consider using ExerciseClient or PassiveMonitoringClient depending on your use case).

Existing subscriptions made with the PassiveMonitoringClient are also expected to get the data generated by this client.

Summary

Public functions
ListenableFuture<MeasureCapabilities>

Returns the MeasureCapabilities of this client for the device.
Unit
registerMeasureCallback(
    dataType: DeltaDataType<*, *>,
    callback: MeasureCallback
)

Registers the app for live measurement of the specified DeltaDataType.
Unit
registerMeasureCallback(
    dataType: DeltaDataType<*, *>,
    executor: Executor,
    callback: MeasureCallback
)

Same as registerMeasureCallback, except the callback is called on the given Executor.
ListenableFuture<Void>
unregisterMeasureCallbackAsync(
    dataType: DeltaDataType<*, *>,
    callback: MeasureCallback
)

Unregisters the given MeasureCallback for updates of the given DeltaDataType.

Extension functions
suspend MeasureCapabilities

Returns the MeasureCapabilities of this client for the device.
suspend Void
MeasureClient.unregisterMeasureCallback(
    dataType: DeltaDataType<*, *>,
    callback: MeasureCallback
)

Unregisters the given MeasureCallback for updates of the given DeltaDataType.

Public functions

getCapabilitiesAsync

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

Returns the MeasureCapabilities of this client for the device.

This can be used to determine what DeltaDataTypes this device supports for live measurement. Clients should use the capabilities to inform their requests since Health Services will typically reject requests made for DeltaDataTypes which are not enabled for measurement.

Returns
ListenableFuture<MeasureCapabilities>

a ListenableFuture containing the MeasureCapabilities for this device

registerMeasureCallback

Added in 1.0.0
fun registerMeasureCallback(
    dataType: DeltaDataType<*, *>,
    callback: MeasureCallback
): Unit

Registers the app for live measurement of the specified DeltaDataType.

The callback will be called on the main application thread. To move calls to an alternative thread use registerMeasureCallback.

Even if data is registered for live capture, it can still be sent out in batches depending on the application processor state.

Registering a DeltaDataType for live measurement capture is expected to increase the sample rate on the associated sensor(s); this is typically used for one-off measurements. Do not use this method for background capture or workout tracking. The client is responsible for ensuring that their requested DeltaDataType is supported on this device by checking the MeasureCapabilities. The returned future will fail if the request is not supported on a given device.

The callback will continue to be called until the app is killed or unregisterMeasureCallbackAsync is called.

If the same callback is already registered for the given DeltaDataType, this operation is a no-op.

Parameters
dataType: DeltaDataType<*, *>

the DeltaDataType that needs to be measured
callback: MeasureCallback

the MeasureCallback to receive updates from Health Services

registerMeasureCallback

Added in 1.0.0
fun registerMeasureCallback(
    dataType: DeltaDataType<*, *>,
    executor: Executor,
    callback: MeasureCallback
): Unit

Same as registerMeasureCallback, except the callback is called on the given Executor.

Parameters
dataType: DeltaDataType<*, *>

the DeltaDataType that needs to be measured
executor: Executor

the Executor on which callback will be invoked
callback: MeasureCallback

the MeasureCallback to receive updates from Health Services

unregisterMeasureCallbackAsync

Added in 1.0.0
fun unregisterMeasureCallbackAsync(
    dataType: DeltaDataType<*, *>,
    callback: MeasureCallback
): ListenableFuture<Void>

Unregisters the given MeasureCallback for updates of the given DeltaDataType.

Parameters
dataType: DeltaDataType<*, *>

the DeltaDataType that needs to be unregistered
callback: MeasureCallback

the MeasureCallback which was used in registration
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.

Extension functions

getCapabilities

suspend fun MeasureClient.getCapabilities(): MeasureCapabilities

Returns the MeasureCapabilities of this client for the device.

This can be used to determine what DeltaDataTypes this device supports for live measurement. Clients should use the capabilities to inform their requests since Health Services will typically reject requests made for DeltaDataTypes which are not enabled for measurement.

Returns
MeasureCapabilities

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

if Health Service fails to process the call

unregisterMeasureCallback

suspend fun MeasureClient.unregisterMeasureCallback(
    dataType: DeltaDataType<*, *>,
    callback: MeasureCallback
): Void

Unregisters the given MeasureCallback for updates of the given DeltaDataType.

Parameters
dataType: DeltaDataType<*, *>

the DeltaDataType that needs to be unregistered
callback: MeasureCallback

the MeasureCallback which was used in registration
Throws
androidx.health.services.client.HealthServicesException

if Health Service fails to process the call