ExerciseClientExtensionKt
public final class ExerciseClientExtensionKt
Summary
Public methods |
|
|---|---|
static final @NonNull Void |
addGoalToActiveExercise(Adds an |
static final @NonNull Void |
clearUpdateCallback(Clears the callback set using |
static final @NonNull Void |
endExercise(@NonNull ExerciseClient receiver)Ends the current exercise, if it has been started. |
static final @NonNull Void |
flush(@NonNull ExerciseClient receiver)Flushes the sensors for the active exercise. |
static final @NonNull ExerciseCapabilities |
getCapabilities(@NonNull ExerciseClient receiver)Returns the |
static final @NonNull ExerciseInfo |
getCurrentExerciseInfo(@NonNull ExerciseClient receiver)Returns the current |
static final @NonNull Void |
markLap(@NonNull ExerciseClient receiver)Ends the current lap, calls |
static final @NonNull Void |
overrideAutoPauseAndResumeForActiveExercise(Enables or disables auto pause/resume for the current exercise. |
static final @NonNull Void |
overrideBatchingModesForActiveExercise(Sets the batching mode for the current exercise synchronously. |
static final @NonNull Void |
pauseExercise(@NonNull ExerciseClient receiver)Pauses the current exercise, if it is currently started. |
static final void |
prepareExercise(Prepares for a new exercise. |
static final @NonNull Void |
removeGoalFromActiveExercise(Removes an exercise goal for an active exercise. |
static final @NonNull Void |
resumeExercise(@NonNull ExerciseClient receiver)Resumes the current exercise, if it is currently paused. |
static final void |
startExercise(Starts a new exercise. |
static final @NonNull Void |
updateExerciseTypeConfig(Updates the configurable exercise type attributes for the current exercise. |
Public methods
addGoalToActiveExercise
public static final @NonNull Void addGoalToActiveExercise(
@NonNull ExerciseClient receiver,
@NonNull ExerciseGoal<@NonNull ?> exerciseGoal
)
Adds an ExerciseGoal for an active exercise.
Goals apply to only active exercises owned by the client, and will be invalidated once the exercise is complete.
| Parameters | |
|---|---|
@NonNull ExerciseGoal<@NonNull ?> exerciseGoal |
the |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if Health Service fails to process the call |
clearUpdateCallback
public static final @NonNull Void clearUpdateCallback(
@NonNull ExerciseClient receiver,
@NonNull ExerciseUpdateCallback callback
)
Clears the callback set using ExerciseClient.setUpdateCallback.
If this callback is not already registered then this will be a no-op.
| Parameters | |
|---|---|
@NonNull ExerciseUpdateCallback callback |
the |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if Health Service fails to process the call |
endExercise
public static final @NonNull Void endExercise(@NonNull ExerciseClient receiver)
Ends the current exercise, if it has been started.
Health Services will flush and then shut down the active sensors and return an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.USER_END to the ExerciseUpdateCallback. If the exercise has already ended then this call fails with a HealthServicesException.
No additional metrics will be produced for the exercise and any on device persisted data about the exercise will be deleted after the summary has been sent back.
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if exercise has already ended or if Health Service fails to process the call |
flush
public static final @NonNull Void flush(@NonNull ExerciseClient receiver)
Flushes the sensors for the active exercise. This call should be used sparingly and will be subject to throttling by Health Services.
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if the Health Service fails to process the request |
getCapabilities
public static final @NonNull ExerciseCapabilities getCapabilities(@NonNull ExerciseClient receiver)
Returns the ExerciseCapabilities of this client for the device.
This can be used to determine what ExerciseTypes and DataTypes this device supports. Clients should use the capabilities to inform their requests since Health Services will typically reject requests made for DataTypes or features (such as auto-pause) which are not enabled for the rejected ExerciseType.
| Returns | |
|---|---|
@NonNull ExerciseCapabilities |
a the |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if Health Service fails to process the call |
getCurrentExerciseInfo
public static final @NonNull ExerciseInfo getCurrentExerciseInfo(@NonNull ExerciseClient receiver)
Returns the current ExerciseInfo.
This can be used by clients to determine if they or another app already owns an active exercise being tracked by Health Services. For example, if an app is killed and it learns it owns the active exercise it can register a new ExerciseUpdateCallback and pick tracking up from where it left off.
| Returns | |
|---|---|
@NonNull ExerciseInfo |
a |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if Health Service fails to process the call |
markLap
public static final @NonNull Void markLap(@NonNull ExerciseClient receiver)
Ends the current lap, calls ExerciseUpdateCallback.onLapSummaryReceived with data spanning the marked lap and starts a new lap. If the exercise supports laps this method can be called at any point after an exercise has been started and before it has been ended regardless of the exercise status.
The metrics in the lap summary will start from either the start time of the exercise or the last time a lap was marked to the time this method is being called.
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
If there's no exercise being tracked or if Health Service fails to process the call |
overrideAutoPauseAndResumeForActiveExercise
public static final @NonNull Void overrideAutoPauseAndResumeForActiveExercise(
@NonNull ExerciseClient receiver,
boolean enabled
)
Enables or disables auto pause/resume for the current exercise.
| Parameters | |
|---|---|
boolean enabled |
a boolean to indicate if should be enabled or disabled |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if Health Service fails to process the call |
overrideBatchingModesForActiveExercise
public static final @NonNull Void overrideBatchingModesForActiveExercise(
@NonNull ExerciseClient receiver,
@NonNull Set<@NonNull BatchingMode> batchingModes
)
Sets the batching mode for the current exercise synchronously.
| Parameters | |
|---|---|
@NonNull Set<@NonNull BatchingMode> batchingModes |
|
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if an exercise is not active for this app or Health Service fails to process the call |
pauseExercise
public static final @NonNull Void pauseExercise(@NonNull ExerciseClient receiver)
Pauses the current exercise, if it is currently started.
Before transitioning to ExerciseState.USER_PAUSED, Health Services will flush and return the sensor data. While the exercise is paused, active time and cumulative metrics such as distance will not accumulate. Instantaneous measurements such as speed and heart rate will continue to update if requested in the ExerciseConfig.
Note that GPS and other sensors may be stopped when the exercise is paused in order to conserve battery. This may happen immediately, or after some time. (The exact behavior is hardware dependent.) Should this happen, access will automatically resume when the exercise is resumed.
If the exercise is already paused then this method has no effect. If the exercise has ended then HealthServicesException is thrown.
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if the exercise has ended or if Health Service fails to process the call |
prepareExercise
public static final void prepareExercise(
@NonNull ExerciseClient receiver,
@NonNull WarmUpConfig configuration
)
Prepares for a new exercise.
Once called, Health Services will warmup the sensors based on the ExerciseType and requested DataTypes.
If the calling app already has an active exercise in progress or if it does not have the required permissions, then this call throws HealthServicesException. If another app owns the active exercise then this call will succeed.
Sensors available for warmup are GPS DataType.LOCATION and HeartRate DataType.HEART_RATE_BPM. Other DataTypes requested for warmup based on exercise capabilities will be a no-op for the prepare stage.
The DataType availability can be obtained through the ExerciseUpdateCallback.onAvailabilityChanged callback. ExerciseUpdates with the supported DataType DataPoint will also be returned in the ExerciseState.PREPARING state, though no aggregation will occur until the exercise is started.
If an app is actively preparing and another app starts tracking an active exercise then the preparing app should expect to receive an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.AUTO_END_SUPERSEDED to the ExerciseUpdateCallback indicating that their session has been superseded and ended. At that point no additional updates to availability or data will be sent until the app calls prepareExercise again.
| Parameters | |
|---|---|
@NonNull WarmUpConfig configuration |
the |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if the calling app already has an active exercise in progress or if Health Service fails to process the call |
java.lang.SecurityException |
if the calling app does not have the required permissions |
removeGoalFromActiveExercise
public static final @NonNull Void removeGoalFromActiveExercise(
@NonNull ExerciseClient receiver,
@NonNull ExerciseGoal<@NonNull ?> exerciseGoal
)
Removes an exercise goal for an active exercise.
Takes into account equivalent milestones (i.e. milestones which are not equal but are different representation of a common milestone. e.g. milestone A for every 2kms, currently at threshold of 10kms, and milestone B for every 2kms, currently at threshold of 8kms).
| Parameters | |
|---|---|
@NonNull ExerciseGoal<@NonNull ?> exerciseGoal |
the |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if Health Service fails to process the call |
resumeExercise
public static final @NonNull Void resumeExercise(@NonNull ExerciseClient receiver)
Resumes the current exercise, if it is currently paused.
Once resumed active time and cumulative metrics such as distance will resume accumulating.
If the exercise has been started but is not currently paused this method has no effect. If the exercise has ended then HealthServicesException is thrown.
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if the exercise has ended or if Health Service fails to process the call |
startExercise
public static final void startExercise(
@NonNull ExerciseClient receiver,
@NonNull ExerciseConfig configuration
)
Starts a new exercise.
Once started, Health Services will begin collecting data associated with the exercise.
Since Health Services only allows a single active exercise at a time, this will terminate any active exercise currently in progress before starting the new one. If this occurs, clients can expect to receive an ExerciseUpdate with ExerciseState.ENDED, indicating that their exercise has been superseded and that no additional updates will be sent. Clients can use getCurrentExerciseInfo (described below) to check if they or another app has an active exercise in-progress.
The exercise will be terminated and clients can expect to receive an ExerciseUpdate with ExerciseState.ENDED along with the reason ExerciseEndReason.AUTO_END_MISSING_LISTENER (indicating that their exercise has been automatically ended due to the lack of callback) if there is ever a five minute period where no ExerciseUpdateCallback is registered. A notable example is if the process with the registered ExerciseUpdateCallback dies and does not re-register the ExerciseUpdateCallback within five minutes.
Clients should only request ExerciseTypes, DataTypes, goals, and auto-pause enabled that matches the ExerciseCapabilities returned by getCapabilities since Health Services will reject requests asking for unsupported configurations.
| Parameters | |
|---|---|
@NonNull ExerciseConfig configuration |
the |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if Health Service fails to process the call |
java.lang.SecurityException |
if the calling app does not have the required permissions |
updateExerciseTypeConfig
public static final @NonNull Void updateExerciseTypeConfig(
@NonNull ExerciseClient receiver,
@NonNull ExerciseTypeConfig exerciseTypeConfig
)
Updates the configurable exercise type attributes for the current exercise.
This can be used to update the configurable attributes for the ongoing exercise, as defined in ExerciseTypeConfig.
| Parameters | |
|---|---|
@NonNull ExerciseTypeConfig exerciseTypeConfig |
configuration containing the new values for the configurable attributes |
| Throws | |
|---|---|
androidx.health.services.client.HealthServicesException |
if Health Service fails to process the call |