PassiveMonitoringClient.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 android.app.PendingIntent
import androidx.health.services.client.data.DataType
import androidx.health.services.client.data.PassiveMonitoringCapabilities
import androidx.health.services.client.data.event.Event
import com.google.common.util.concurrent.ListenableFuture
/**
* Client which provides a means to passively monitor data without requiring an ongoing workout.
*
* The lifetimes of registrations made through this client are independent of the lifetime of the
* subscribing app. These registrations are therefore suitable for notifying of ongoing measurements
* or triggered events, regardless of whether or not the subscribing app is currently running, in
* the foreground or engaged in a workout.
*/
public interface PassiveMonitoringClient {
/**
* Subscribes for updates on a set of data types to be periodically delivered to the app.
*
* Data will be batched. Higher frequency updates are available through [ExerciseClient] or
* [MeasureClient].
*
* The provided [PendingIntent] will be invoked periodically with the collected data.
*
* Subscribing apps are responsible for ensuring they can receive the [callbackIntent] by e.g.
* declaring a suitable [android.content.BroadcastReceiver] in their app manifest.
*
* This registration is unique per subscribing app. Subsequent registrations will replace the
* previous registration, if one had been made.
*/
public fun registerDataCallback(
dataTypes: Set<@JvmSuppressWildcards DataType>,
callbackIntent: PendingIntent
): ListenableFuture<Void>
/**
* Subscribes an intent callback (the same way as [PassiveMonitoringClient.registerDataCallback]
* ) and a [PassiveMonitoringCallback] for updates on a set of data types periodically.
*
* The provided [callback] will take priority in receiving updates as long the app is alive and
* the callback can be successfully notified. Otherwise, updates will be delivered to the
* [callbackIntent].
*
* This registration is unique per subscribing app. Subsequent registrations will replace the
* previous registration, if one had been made.
*/
public fun registerDataCallback(
dataTypes: Set<@JvmSuppressWildcards DataType>,
callbackIntent: PendingIntent,
callback: PassiveMonitoringCallback
): ListenableFuture<Void>
/**
* Unregisters the subscription made by [PassiveMonitoringClient.registerDataCallback].
*
* The associated [PendingIntent] will be called one last time with any remaining buffered data.
*/
public fun unregisterDataCallback(): ListenableFuture<Void>
/**
* Registers for notification of the [event] being triggered.
*
* The provided [PendingIntent] will be sent whenever [event] is triggered.
*
* Subscribing apps are responsible for ensuring they can receive the [callbackIntent] by e.g.
* declaring a suitable [android.content.BroadcastReceiver] in their app manifest.
*
* Registration of multiple events is possible except where there already exists an event that
* is equal, as per the definition of [Event.equals], in which case the existing registration
* for that event will be replaced.
*/
public fun registerEventCallback(
event: Event,
callbackIntent: PendingIntent
): ListenableFuture<Void>
/** Unregisters the subscription for the given [Event]. */
public fun unregisterEventCallback(event: Event): ListenableFuture<Void>
/** Returns the [PassiveMonitoringCapabilities] of this client for the device. */
public val capabilities: ListenableFuture<PassiveMonitoringCapabilities>
}