TrustedTimeClient

Kotlin |Java

public interface TrustedTimeClient

TrustedTimeClient provides access to time signals backed by Google Play Services' accurate time keeping service.

Methods in this class provide time information in various forms:

Instant, also available as Unix epoch time millis: a point in time that is closely related to UTC. Callers can easily obtain this "current time" directly from this class.
TimeSignal, for more advanced "current time" usecases. TimeSignal represents a time synchronization transaction with an external time server. This holds the information needed to obtain one or more "current time" instances in sequence and their associated error information. Users can also listen for fresh TimeSignal updates.
Ticker and Ticks: these allow elapsed time to be tracked without using a specific clock or time keeping system.

Application code is expected to retain a reference to this from an Android framework object with an appropriate lifecycle for their needs and call dispose when it is no longer needed. If no reference is retained by application code then listeners registered may cease to trigger due to garbage collection. See dispose for more information.

Summary

Public methods
`abstract void`	`addTimeSignalListener(OnNewTimeSignalAvailableListener listener)` Adds a new `OnNewTimeSignalAvailableListener` if it is not already registered with this client instance.
`abstract @Nullable Instant`	`@RequiresApi(api = Build.VERSION_CODES.O) computeCurrentInstant()` Computes the current `Instant` using the latest time signal from an accurate, external time source, or `null` if no external time signal is available.
`abstract @Nullable Long`	`computeCurrentUnixEpochMillis()` Computes the number of milliseconds since the start of the Unix epoch from a trusted, external time source, or `null` if no external time signal is available.
`abstract Task<Void>`	`@CanIgnoreReturnValue dispose()` Disposes of the client after it is no longer needed, deregistering all listeners previously registered against this instance, and freeing internal resources.
`abstract @Nullable TimeSignal`	`getLatestTimeSignal()` Returns the most recent `TimeSignal` or `null` if no external time signal is available.
`abstract void`	`removeTimeSignalListener(OnNewTimeSignalAvailableListener listener)` Removes the given `listener` if it was previously registered with this client instance.

Public methods

addTimeSignalListener

abstract void addTimeSignalListener(OnNewTimeSignalAvailableListener listener)

Adds a new OnNewTimeSignalAvailableListener if it is not already registered with this client instance.

This is a no-op if the listener has been registered with this client instance already, which will be determined using equals and may use hashCode.

The listener will be invoked on the main thread immediately after registration with the latest time signal if one is available. The listener will also be invoked after a new time signal has been made available via getLatestTimeSignal.

Parameters
`OnNewTimeSignalAvailableListener listener`	the listener to notify when a new time signal is available. Listener cannot be not null.

computeCurrentInstant

@RequiresApi(api = Build.VERSION_CODES.O)
abstract @Nullable Instant computeCurrentInstant()

Computes the current Instant using the latest time signal from an accurate, external time source, or null if no external time signal is available.

Shortcut to getLatestTimeSignal().computeCurrentInstant().getInstant() with the necessary null checks.

This method is a replacement for Instant.now(), but unlike that method, it cannot be influenced by the device's system clock. This method is suitable for most cases where "current instant" is needed.

See getLatestTimeSignal to obtain the latest time signal that holds error information, and to enable multiple, monotonically increasing instants to be created from the same time signal.

See computeCurrentUnixEpochMillis for an alternative to use on Android release prior to the introduction of the Instant class.

computeCurrentUnixEpochMillis

abstract @Nullable Long computeCurrentUnixEpochMillis()

Computes the number of milliseconds since the start of the Unix epoch from a trusted, external time source, or null if no external time signal is available.

Shortcut to getLatestTimeSignal().computeCurrentInstant().getInstantMillis() with the necessary null checks.

This method is a replacement for System.currentTimeMillis(), but unlike that method, it cannot be influenced by the device's system clock. This method is suitable for most cases where "current instant" is needed.

See getLatestTimeSignal to obtain the latest time signal that holds error information, and to enable multiple, monotonically increasing instants to be created from the same time signal.

This is also equivalent to computeCurrentInstant().toEpochMillis() with null checks but works on Android releases prior to the introduction of the Instant class.

dispose

@CanIgnoreReturnValue
abstract Task<Void> dispose()

Disposes of the client after it is no longer needed, deregistering all listeners previously registered against this instance, and freeing internal resources. This should be called before abandoning the client instance to avoid registered listeners pinning application code in memory.

The TrustedTimeClient implementation may automatically dispose when it is garbage collected without an explicit call to dispose, but application code must not assume that it will or it won't.

After dispose has completed, the client instance will throw runtime exceptions for all methods except dispose. TimeSignal and other value types returned / delivered to listeners can continue to be used, with the expected accuracy caveats as they age.

The disposal may be asynchronous. Callers are not required to wait for the returned Task to complete, but the client may continue to operate until the returned Task has completed successfully. For example, listeners may still be informed of time signals after this call returns and until the Task completes.

getLatestTimeSignal

abstract @Nullable TimeSignal getLatestTimeSignal()

Returns the most recent TimeSignal or null if no external time signal is available.

Different time signals can have different estimated errors, so sequential calls based on different time signals may not be monotonically increasing.

See TimeSignal for how to calculate instants and preserve error information.

removeTimeSignalListener

abstract void removeTimeSignalListener(OnNewTimeSignalAvailableListener listener)

Removes the given listener if it was previously registered with this client instance.

This is a no-op if the listener was not previously registered, which will be determined using equals and may use hashCode.

Parameters
`OnNewTimeSignalAvailableListener listener`	the listener to be removed. Listener cannot be null.