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>
}