Rust テレメトリー クライアント ライブラリ API リファレンス

このページでは、libsdv_telemetry_rust_wrapper ライブラリの型、メソッド、エラー処理について説明します。

TelemetryServiceHolder インターフェース

クライアントのプライマリ インターフェースは TelemetryServiceHolder 構造体です。このインターフェースは、サービス接続、指標の構成、データレポートを管理するためのメソッドの完全なセットを提供します。

サービスのライフサイクル管理

これらのメソッドは、基盤となるテレメトリー サービスとの接続を確立して終了します。

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

テレメトリー サービスへのスレッドセーフ ハンドルを取得する静的メソッド。 これは、テレメトリー バインダー サービスの準備が整うまで待機するブロッキング呼び出しです。 テレメトリー サービスは、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 を取得したら、他の操作を行う前にこのメソッドを 1 回呼び出します。

finish

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

サービス接続を正常にシャットダウンし、登録済みのリスナーをクリアして、関連するリソースをクリーンアップします。アプリが終了するときにこのメソッドを 1 回呼び出します。

指標の構成管理

これらの非同期メソッドは、データの収集構成の定義と状態を管理します。

テレメトリー サービスは、構成を次の 2 つの状態に維持します。

• 非アクティブ: 構成は検証されてディスクに保存されますが、データの収集には使用されません。
• アクティブ: 構成はデータを収集し、そのコンポーネント（トリガー、パブリッシャーなど）はアクティブです。

サービスの再起動やデバイスの再起動後も構成が維持されるように、サービスはデバイスのディスクに構成を保存します。サービスはすべての構成を 2 つの状態ベースのディレクトリに保存し、起動時に検証して、必要に応じてアクティブにします。

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 の完全な指標レポートデータを取得します。レポート UUID は、report_ready_callback を使用して通知から取得するか、get_ready_reports_info を呼び出して取得できます。

get_ready_reports_info

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

完了して取得できる状態になっているすべてのレポートのリストについて、テレメトリー サービスにクエリを実行します。これは、コールバック通知が欠落した場合（たとえば、report_ready_callback が遅れて登録された場合）に、レポートの状態を確認するのに役立ちます。

コアタイプ、コールバック、エラー処理

libsdv_telemetry_rust_wrapper は、テレメトリー サービスとのやり取り、非同期コールバックの管理、サービス エラーの処理に一連のカスタムタイプを使用します。

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 構造体は、サービス初期化時に登録される misc_status_callback クロージャの init の引数として機能します。サービスの健全性とランタイムの問題（データソースからの切断など）に関する非同期更新を提供します。

StatusDetails

この enum は特定のエラー コンテキストをラップします。 TelemetryServiceStatus に details が存在する場合、 次のいずれかのバリアントになります。

各 enum バリアントには、さらに多くのコンテキストを提供する追加のフィールドが含まれています。

ReportInfo

ReportInfo 構造体は、サービス初期化時に登録される report_ready_callback クロージャの引数として機能します。init指標レポートを記述する識別子が含まれています。

report_uuid フィールドは、 指標レポート自体の取得（get_metrics_report を参照）に必要な唯一のフィールドですが、 config_uuid はソースに関する追加情報としてのみ機能します。