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.DataType
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 [DataType].
     *
     * The callback will be called on the main application thread. To move calls to an alternative
     * thread use [registerCallback].
     *
     * Even if data is registered for live capture, it can still be sent out in batches depending on
     * the application processor state.
     *
     * Registering a [DataType] 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 [DataType] 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 [unregisterCallback] is
     * called.
     *
     * If the same [callback] is already registered for the given [DataType], this operation is a
     * no-op.
     */
    public fun registerCallback(
        dataType: DataType,
        callback: MeasureCallback
    ): ListenableFuture<Void>

    /** Same as [registerCallback], except the [callback] is called on the given [Executor]. */
    public fun registerCallback(
        dataType: DataType,
        callback: MeasureCallback,
        executor: Executor
    ): ListenableFuture<Void>

    /** Unregisters the given [MeasureCallback] for updates of the given [DataType]. */
    public fun unregisterCallback(
        dataType: DataType,
        callback: MeasureCallback
    ): ListenableFuture<Void>

    /** Returns the [MeasureCapabilities] of this client for the device. */
    public val capabilities: ListenableFuture<MeasureCapabilities>
}