Rust Telemetry 客户端库 API 参考文档

本页面介绍了 libsdv_telemetry_rust_wrapper 库中的类型、方法和错误处理。

TelemetryServiceHolder 接口

客户端的主要接口是 TelemetryServiceHolder 结构体。此接口提供了一整套用于管理服务连接、指标配置和数据报告的方法。

服务生命周期管理

这些方法用于建立和终止与底层遥测服务的连接。

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

一种静态方法，用于检索 Telemetry 服务的线程安全句柄。这是一个阻塞调用，会一直等待，直到遥测绑定器服务准备就绪。Telemetry 服务仅支持 TelemetryServiceHolder 的单个实例。多次调用此方法会导致未定义或意外的行为。

TelemetryServiceHolder 实现 Send 和 Sync 特征，这意味着它可以安全地跨线程共享，例如通过将其封装在 Arc 的实例中。TelemetryServiceHolder 的大多数方法都是 async，可以并发使用。

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<()>

通过注册异步回调来初始化服务。在获取 TelemetryServiceHolder 之后且在进行任何其他互动之前，调用此方法一次。

完成

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

正常关闭服务连接，清除已注册的监听器，并清理关联的资源。在应用终止时调用此方法一次。

指标配置管理

这些异步方法用于管理数据收集配置的定义和状态。

遥测服务以两种状态维护配置：

• 无效：配置已验证并存储在磁盘上，但未用于数据收集。
• 有效：配置正在收集数据，并且其组件（例如触发器、发布者）处于有效状态。

为确保配置在服务重启和设备重新启动后仍能保留，该服务会将配置存储在设备的磁盘上。该服务将所有配置存储在两个基于状态的目录中，并在启动时验证这些配置，并在必要时激活它们。

add_metrics_config

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

向服务添加新的指标配置。配置必须以序列化字节数组的形式提供。添加的配置默认处于非活动状态。

activate_metrics_config

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

激活之前添加（或停用）的指标配置，开始收集数据并生成报告。

deactivate_metrics_config

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

停止针对有效指标配置收集数据和生成报告。配置仍保留在服务中，并且可以稍后重新启用。

remove_metrics_config

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

永久移除指标配置。如果配置处于有效状态，服务会先将其停用。

remove_all_metrics_configs

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

移除所有现有指标配置，停用所有处于有效状态的指标配置。

get_active_metrics_config_uuids

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

向服务查询处于有效状态的所有配置的 UUID 列表。

get_inactive_metrics_config_uuids

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

向服务查询处于非活跃状态的所有配置的 UUID 列表。

指标报告处理和检索

借助这些方法，您可以查询可用的报告并检索收集的报告数据。

get_metrics_report

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

检索特定报告 UUID 的完整指标报告数据。您可以使用 report_ready_callback 从通知中获取报告 UUID，也可以通过调用 get_ready_reports_info 来获取。

get_ready_reports_info

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

向 Telemetry 服务查询已完成并可供检索的所有报告的列表。如果错过了回调通知（例如，如果 report_ready_callback 注册较晚），此方法可用于检查报告的状态。

核心类型、回调和错误处理

libsdv_telemetry_rust_wrapper 使用一组自定义类型与 Telemetry 服务互动、管理异步回调和处理服务错误。

API 响应和错误类型

这些类型由库方法直接返回，用于指示所请求操作的立即成功或失败。

TelemetryResult

大多数方法都会返回 TelemetryResult<T>，它是标准 Result 类型的别名，专门用于服务级错误：

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

TelemetryError

TelemetryError 结构体封装了所有失败情况，并提供详细的特定于服务的错误信息：

TelemetryServiceStatusCodes

一个数字枚举，表示 API 调用和内部服务状态的结果。这些代码同时用于 TelemetryError 和 TelemetryServiceStatus。例如：

异步回调类型

注册的监听器（misc_status_callback 和 report_ready_callback）会将这些类型传递给客户端，以提供有关后台进程的更新。

TelemetryServiceStatus

TelemetryServiceStatus 结构体用作 init 的 misc_status_callback 闭包的实参，该闭包在服务初始化期间注册。它提供有关服务健康状况和运行时问题的异步更新，例如与数据源断开连接。

StatusDetails

此枚举封装了特定的错误上下文。如果 details 存在于 TelemetryServiceStatus 中，则它是以下变体之一：

每个枚举变体都包含提供更多上下文信息的其他字段。

ReportInfo

ReportInfo 结构体用作 init 的 report_ready_callback 闭包的实参，该闭包在服务初始化期间注册。它包含描述指标报告的标识符：

report_uuid 字段是进一步检索指标报告本身（请参阅 get_metrics_report）的唯一必要字段，而 config_uuid 仅用作有关其来源的附加信息。