Rust 遙測用戶端程式庫 API 參考資料

本頁說明 libsdv_telemetry_rust_wrapper 程式庫中的型別、方法和錯誤處理方式。

TelemetryServiceHolder 介面

用戶端的主要介面是 TelemetryServiceHolder 結構體。這個介面提供全套方法，可管理服務連線、指標設定和資料報表。

服務生命週期管理

這些方法會建立及終止與基礎遙測服務的連線。

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

這個靜態方法會擷取 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 或呼叫 get_ready_reports_info，從通知取得報表 UUID。

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 結構體會做為 report_ready_callback 閉包的引數，而 init 則會在服務初始化期間註冊。其中包含描述指標報表的 ID：

如要進一步擷取指標報表本身 (請參閱 get_metrics_report)，唯一必要的欄位是 report_uuid，而 config_uuid 僅做為來源的額外資訊。