Rust telemetry client library API reference

This page describes the types, methods, and error handling in the libsdv_telemetry_rust_wrapper library.

TelemetryServiceHolder interface

The primary interface for clients is the TelemetryServiceHolder struct. This interface provides the full set of methods for managing the service connection, metrics configurations, and data reports.

Service lifecycle management

These methods establish and terminate the connection with the underlying Telemetry service.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

A static method that retrieves a thread-safe handle to the Telemetry service. This is a blocking call that waits until the telemetry binder service is ready. The Telemetry service supports only a single instance of the TelemetryServiceHolder. Calling this method more than once causes undefined or unexpected behavior.

TelemetryServiceHolder implements Send and Sync traits, meaning it can be safely shared across threads, for example, by wrapping it in an instance of Arc. Most of TelemetryServiceHolder's methods are async and can be used concurrently.

init

pub async fn init(
    &self,
    misc_status_callback: impl Fn(TelemetryServiceStatus) + Send + Sync + 'static,
    report_ready_callback: impl Fn(ReportInfo) + Send + Sync + 'static,
) -> TelemetryResult<()>

Initializes the service by registering asynchronous callbacks. Call this method once after obtaining the TelemetryServiceHolder and before any other interactions.

finish

pub fn finish(&self) -> TelemetryResult<()>

Gracefully shuts down the service connection, clears registered listeners, and cleans up associated resources. Call this method once when the app terminates.

Metrics configuration management

These asynchronous methods manage the definition and state of data collection configurations.

The Telemetry service maintains configurations in two states:

• Inactive: The configuration is validated and stored on disk but isn't used for data collection.
• Active: The configuration collects data, and its components (triggers, publishers, for example) are active.

To ensure configurations persist across service restarts and device reboots, the service stores them on the device's disk. The service stores all configurations in two state-based directories, validating and, if necessary, activating them on boot.

add_metrics_config

pub async fn add_metrics_config(&self, serialized_config: &[u8]) -> TelemetryResult<String>

Adds a new metrics configuration to the service. The configuration must be provided as a serialized byte array. The added configuration is inactive by default.

activate_metrics_config

pub async fn activate_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

Activates a previously added (or deactivated) metrics configuration, starting its data collection and reporting.

deactivate_metrics_config

pub async fn deactivate_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

Stops data collection and reporting for an active metrics configuration. The configuration remains in the service and can be re-activated later.

remove_metrics_config

pub async fn remove_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

Removes a metrics configuration permanently. If the configuration is active, the service deactivates it first.

remove_all_metrics_configs

pub async fn remove_all_metrics_configs(&self) -> TelemetryResult<String>

Removes all existing metrics configurations, deactivating any that are active.

get_active_metrics_config_uuids

pub async fn get_active_metrics_config_uuids(&self) -> TelemetryResult<Vec<String>>

Queries the service for a list of UUIDs for all configurations in the active state.

get_inactive_metrics_config_uuids

pub async fn get_inactive_metrics_config_uuids(&self) -> TelemetryResult<Vec<String>>

Queries the service for a list of UUIDs for all configurations in the inactive state.

Metrics report handling and retrieval

These methods let you query for available reports and retrieve the collected report data.

get_metrics_report

pub async fn get_metrics_report(&self, report_uuid: &str) -> TelemetryResult<MetricsReport>

Retrieves the full metrics report data for a specific report UUID. You can get the report UUID from a notification by using the report_ready_callback or by calling get_ready_reports_info.

get_ready_reports_info

pub async fn get_ready_reports_info(&self) -> TelemetryResult<Vec<ReportInfo>>

Queries the Telemetry service for a list of all reports that are completed and ready for retrieval. This is useful for checking the state of reports if a callback notification was missed (for example, if report_ready_callback was registered late).

Core types, callbacks, and error handling

The libsdv_telemetry_rust_wrapper uses a set of custom types to interact with the Telemetry service, manage asynchronous callbacks, and handle service errors.

API response and error types

These types are returned directly by library methods to indicate the immediate success or failure of the requested operation.

TelemetryResult

Most methods return a TelemetryResult<T>, which is an alias for the standard Result type, specialized for service-level errors:

pub type TelemetryResult<T> = Result<T, TelemetryError>;

TelemetryError

The TelemetryError struct encapsulates all failures and provides detailed, service-specific error information:

TelemetryServiceStatusCodes

A numeric enumeration representing the outcome of API calls and internal service states. These codes are used in both TelemetryError and TelemetryServiceStatus. For example:

Asynchronous callback types

The registered listeners (misc_status_callback and report_ready_callback) pass these types to the client to provide updates on background processes.

TelemetryServiceStatus

The TelemetryServiceStatus struct serves as an argument for the misc_status_callback closure of init, which is registered during service initialization. It provides asynchronous updates about the service's health and runtime issues, for example, disconnection from a data source.

StatusDetails

This enum wraps specific error contexts. If details is present in TelemetryServiceStatus, it's one of the following variants:

Each enum variant contains additional fields providing even more context.

ReportInfo

The ReportInfo struct serves as an argument for the report_ready_callback closure of init, which is registered during service initialization. It contains the identifiers describing a metrics report:

The report_uuid field is the only necessary for further retrieval of the metrics report itself (see get_metrics_report), while config_uuid serves only as additional information on its source.