MeasureClient

public 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 methods
abstract @NonNull ListenableFuture<@NonNull MeasureCapabilities>

Returns the MeasureCapabilities of this client for the device.
abstract void
registerMeasureCallback(
    @NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType,
    @NonNull MeasureCallback callback
)

Registers the app for live measurement of the specified DeltaDataType.
abstract void
registerMeasureCallback(
    @NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType,
    @NonNull Executor executor,
    @NonNull MeasureCallback callback
)

Same as registerMeasureCallback, except the callback is called on the given Executor.
abstract @NonNull ListenableFuture<@NonNull Void>

Unregisters the given MeasureCallback for updates of the given DeltaDataType.

Extension functions
default final @NonNull MeasureCapabilities

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

Unregisters the given MeasureCallback for updates of the given DeltaDataType.

Public methods

getCapabilitiesAsync

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

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
@NonNull ListenableFuture<@NonNull MeasureCapabilities>

a ListenableFuture containing the MeasureCapabilities for this device

registerMeasureCallback

Added in 1.0.0
abstract void registerMeasureCallback(
    @NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType,
    @NonNull MeasureCallback callback
)

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
@NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType

the DeltaDataType that needs to be measured
@NonNull MeasureCallback callback

the MeasureCallback to receive updates from Health Services

registerMeasureCallback

Added in 1.0.0
abstract void registerMeasureCallback(
    @NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType,
    @NonNull Executor executor,
    @NonNull MeasureCallback callback
)

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

Parameters
@NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType

the DeltaDataType that needs to be measured
@NonNull Executor executor

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

the MeasureCallback to receive updates from Health Services

unregisterMeasureCallbackAsync

Added in 1.0.0
abstract @NonNull ListenableFuture<@NonNull Void> unregisterMeasureCallbackAsync(
    @NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType,
    @NonNull MeasureCallback callback
)

Unregisters the given MeasureCallback for updates of the given DeltaDataType.

Parameters
@NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType

the DeltaDataType that needs to be unregistered
@NonNull MeasureCallback callback

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

Extension functions

MeasureClientExtensionKt.getCapabilities

default final @NonNull MeasureCapabilities MeasureClientExtensionKt.getCapabilities(
    @NonNull MeasureClient receiver
)

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
@NonNull MeasureCapabilities

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

if Health Service fails to process the call

MeasureClientExtensionKt.unregisterMeasureCallback

default final @NonNull Void MeasureClientExtensionKt.unregisterMeasureCallback(
    @NonNull MeasureClient receiver,
    @NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType,
    @NonNull MeasureCallback callback
)

Unregisters the given MeasureCallback for updates of the given DeltaDataType.

Parameters
@NonNull DeltaDataType<@NonNull ?, @NonNull ?> dataType

the DeltaDataType that needs to be unregistered
@NonNull MeasureCallback callback

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

if Health Service fails to process the call