MeasureClient.kt

/*
 * Copyright (C) 2021 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.health.services.client

import androidx.health.services.client.data.DeltaDataType
import androidx.health.services.client.data.MeasureCapabilities
import com.google.common.util.concurrent.ListenableFuture
import java.util.concurrent.Executor

/**
 * 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.
 */
public interface MeasureClient {
    /**
     * 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.
     *
     * @param dataType the [DeltaDataType] that needs to be measured
     * @param callback the [MeasureCallback] to receive updates from Health Services
     */
    public fun registerMeasureCallback(dataType: DeltaDataType<*, *>, callback: MeasureCallback)

    /**
     * Same as [registerMeasureCallback], except the [callback] is called on the given [Executor].
     *
     * @param dataType the [DeltaDataType] that needs to be measured
     * @param executor the [Executor] on which [callback] will be invoked
     * @param callback the [MeasureCallback] to receive updates from Health Services
     */
    public fun registerMeasureCallback(
        dataType: DeltaDataType<*, *>,
        executor: Executor,
        callback: MeasureCallback
    )

    /**
     * Unregisters the given [MeasureCallback] for updates of the given [DeltaDataType].
     *
     * @param dataType the [DeltaDataType] that needs to be unregistered
     * @param callback the [MeasureCallback] which was used in registration
     * @return a [ListenableFuture] that completes when the un-registration succeeds in Health
     * Services. This is a no-op if the callback has already been unregistered.
     */
    public fun unregisterMeasureCallbackAsync(
        dataType: DeltaDataType<*, *>,
        callback: MeasureCallback
    ): ListenableFuture<Void>

    /**
     * Returns the [MeasureCapabilities] of this client for the device.
     *
     * This can be used to determine what [DeltaDataType]s this device supports for live
     * measurement. Clients should use the capabilities to inform their requests since Health
     * Services will typically reject requests made for [DeltaDataType]s which are not enabled for
     * measurement.
     *
     * @return a [ListenableFuture] containing the [MeasureCapabilities] for this device
     */
    public fun getCapabilitiesAsync(): ListenableFuture<MeasureCapabilities>
}