UpdateInfoService
abstract class UpdateInfoService : Service
| kotlin.Any | ||||
| ↳ | android.content.Context | |||
| ↳ | android.content.ContextWrapper | |||
| ↳ | android.app.Service | |||
| ↳ | androidx.security.state.provider.UpdateInfoService | |||
Base class for implementing the AndroidX Security State Update Provider service.
This abstract class provides the foundational implementation for the IUpdateInfoService AIDL interface. It manages the complexity of serving security update information to client applications, enforcing a consistent contract for data freshness, resource usage, and observability.
Responsibilities
-
IPC Handling: Manages the AIDL binding process and verifies Intent actions.
-
Concurrency Control: Implements Double-Checked Locking to prevent "thundering herd" scenarios where multiple clients trigger parallel network requests.
-
Rate Limiting: Enforces a default throttling policy (e.g., maximum one check per hour) to protect backend infrastructure.
-
Caching: Automatically persists fetched results and freshness metadata to local storage.
Monitoring & Telemetry
To support high-scale hosts that require strict monitoring, this class provides a comprehensive set of observability hooks. Hosts can override these methods to integrate with their own logging infrastructure:
-
onRequestCompleted: Report granular performance metrics (latency, lock contention) and usage. -
onClientConnected/onClientDisconnected: Track service session lifecycles and adoption. -
onFetchFailed: Report backend errors and exceptions. -
dump: Debug internal state viaadb shell.
Host Implementation
Host applications (such as the System Updater, Google Play Store, or OEM-specific updaters) must extend this class and implement the fetchUpdates method to provide the actual network logic.
Manifest Declaration
To expose this service, you must declare it in your AndroidManifest.xml with the exported="true" attribute and an intent-filter for the UPDATE_INFO_SERVICE action:
<service
android:name=".MyUpdateInfoService"
android:exported="true">
<intent-filter>
<action android:name="androidx.security.state.provider.UPDATE_INFO_SERVICE" />
</intent-filter>
</service>
Summary
Public constructors |
|---|
Public functions |
|
|---|---|
open Unit |
dump(fd: FileDescriptor?, writer: PrintWriter?, args: Array<String>?)Dumps the state of the service for debugging (e.g. |
final IBinder? |
Called by the system when a client binds to the particular interface defined by the |
final Boolean |
Called by the system when all clients have disconnected from the particular interface defined by the |
Protected functions |
|
|---|---|
abstract suspend List<UpdateInfo> |
Performs the actual network request to fetch fresh updates from the backend. |
open Int |
Retrieves the UID of the calling process. |
open Unit |
onClientConnected(intent: Intent)Called when a client binds to the particular interface defined by the |
open Unit |
onClientDisconnected(intent: Intent?)Called when all clients have disconnected from the particular interface defined by the |
open Unit |
Callback for handling exceptions that occur during the update check process. |
open Unit |
onRequestCompleted(telemetry: UpdateCheckTelemetry)Called when a request completes. |
open Boolean |
Determines if the local cache is stale and a refresh should be attempted. |
open Boolean |
Checks if the operation should be throttled based on the rate limiter. |
Public constructors
Public functions
dump
open fun dump(fd: FileDescriptor?, writer: PrintWriter?, args: Array<String>?): Unit
Dumps the state of the service for debugging (e.g. adb shell dumpsys activity service).
This implementation provides a snapshot of the internal state, including:
-
Active Request Count: To detect stuck threads or high concurrency.
-
Global Last Check Time: The timestamp of the last successful service-wide sync (Service Health).
-
Throttling Status: Whether the rate limiter is currently blocking network requests.
-
Cached Updates: A complete list of stored updates with detailed metadata (Component, SPL, Provider, Published Date, Last Checked Time).
onBind
final fun onBind(intent: Intent?): IBinder?
Called by the system when a client binds to the particular interface defined by the intent.
This method verifies that the Intent action matches the expected contract (ACTION_BIND). If the action is missing or incorrect, the binding is rejected to ensure the service is not exposed unintentionally.
Lifecycle Note: Because the client library attaches unique data (the package name) to the intent, this method is called for every new client session, allowing the onClientConnected hook to reliably track individual connections.
| Parameters | |
|---|---|
intent: Intent? |
The Intent that was used to bind to this service. |
| Returns | |
|---|---|
IBinder? |
The IBinder interface for clients to interact with the service, or |
onUnbind
final fun onUnbind(intent: Intent?): Boolean
Called by the system when all clients have disconnected from the particular interface defined by the intent.
This method is marked final to enforce the library's lifecycle contract. It performs two critical actions:
-
Triggers the
onClientDisconnectedhook, allowing the host to log the end of the session. -
Returns
false, which forces the Android system to callonBind(and thusonClientConnected) for all future connections. This simplifies telemetry by ensuring a consistent "Connect -> Disconnect" cycle without needing to handle theonRebindedge case.
| Parameters | |
|---|---|
intent: Intent? |
The Intent that was used to bind to this service. |
Protected functions
fetchUpdates
protected abstract suspend fun fetchUpdates(): List<UpdateInfo>
Performs the actual network request to fetch fresh updates from the backend.
Implementations of this method should:
-
Block until the network request completes.
-
Return the list of updates found.
-
Throw an exception if the network request fails (this will be caught and logged).
Note: This method is only called if shouldFetchUpdates returns true and the rate limiter allows the request.
| Returns | |
|---|---|
List<UpdateInfo> |
A list of |
getCallerUid
protected open fun getCallerUid(): Int
Retrieves the UID of the calling process.
The default implementation delegates to android.os.Binder.getCallingUid. Host implementations using a proxy or broker architecture should override this to return the logical client UID instead of the broker's UID, ensuring correct attribution.
onClientConnected
protected open fun onClientConnected(intent: Intent): Unit
Called when a client binds to the particular interface defined by the intent.
This method is invoked during onBind after the Intent action has been verified.
Usage: Override this method to log connection metrics (e.g., "Session Started") or track adoption trends.
Client Identity: The intent passed to this method typically contains the client's package name in the data URI (e.g., package:com.example.client). This allows you to identify which app is starting a session. Note that this value is self-reported by the client library and is useful for aggregate trends but less secure than the UpdateCheckTelemetry.callerUid captured in onRequestCompleted.
Lifecycle: Because the client library attaches unique data to the bind Intent, this method is called for every new client session, enabling accurate session counting.
| Parameters | |
|---|---|
intent: Intent |
The Intent that was used to bind to this service. |
onClientDisconnected
protected open fun onClientDisconnected(intent: Intent?): Unit
Called when all clients have disconnected from the particular interface defined by the intent.
This method is invoked during onUnbind.
Usage: Override this method to log session ends (e.g., "Session Ended") to calculate session duration when paired with onClientConnected. You can also use this to perform per-client resource cleanup.
| Parameters | |
|---|---|
intent: Intent? |
The Intent that was used to bind to this service. It contains the same identification data as passed to |
onFetchFailed
protected open fun onFetchFailed(e: Exception): Unit
Callback for handling exceptions that occur during the update check process.
This method is invoked if any step of the update logic fails, including:
-
Determining cache freshness (
shouldFetchUpdates). -
Recording rate-limit attempts.
-
Fetching data from the backend (
fetchUpdates). -
Persisting the results to local storage.
The default implementation logs the error to Logcat. Hosts can override this to report errors to their own telemetry or crash reporting systems.
| Parameters | |
|---|---|
e: Exception |
The exception thrown during the operation. |
onRequestCompleted
protected open fun onRequestCompleted(telemetry: UpdateCheckTelemetry): Unit
Called when a request completes. Override this to log telemetry.
This hook is called for every request to listAvailableUpdates, regardless of whether it succeeded, failed, was throttled, or was served from the cache.
Usage: Use this hook to log granular performance metrics (latency histograms) and resource usage.
Attribution: The telemetry object contains the UpdateCheckTelemetry.callerUid, which is the Kernel-verified UID of the calling process. This is the authoritative source for attributing load (CPU/Network/Lock Contention) to specific client applications.
| Parameters | |
|---|---|
telemetry: UpdateCheckTelemetry |
The |
shouldFetchUpdates
protected open fun shouldFetchUpdates(): Boolean
Determines if the local cache is stale and a refresh should be attempted.
The default implementation returns true if the data is older than 1 hour. Hosts can override this to implement custom caching policies (e.g., 4 hours, 24 hours).
| Returns | |
|---|---|
Boolean |
|
shouldThrottle
protected open fun shouldThrottle(): Boolean
Checks if the operation should be throttled based on the rate limiter.
The default implementation delegates to an internal rate limiter that enforces a cooling-off period (e.g., one check per hour). Hosts can override this to inject custom rate limiting logic (e.g., battery checks).
| Returns | |
|---|---|
Boolean |
|