Riferimento API della libreria client di telemetria Rust

Questa pagina descrive i tipi, i metodi e la gestione degli errori nella libreria libsdv_telemetry_rust_wrapper.

Interfaccia TelemetryServiceHolder

L'interfaccia principale per i client è la struttura TelemetryServiceHolder. Questa interfaccia fornisce l'insieme completo di metodi per la gestione della connessione al servizio, delle configurazioni delle metriche e dei report sui dati.

Gestione del ciclo di vita dei servizi

Questi metodi stabiliscono e terminano la connessione con il servizio di telemetria sottostante.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Un metodo statico che recupera un handle thread-safe per il servizio di telemetria. Si tratta di una chiamata di blocco che attende che il servizio di binder di telemetria sia pronto. Il servizio di telemetria supporta una sola istanza di TelemetryServiceHolder. Chiamare questo metodo più di una volta causa un comportamento indefinito o imprevisto.

TelemetryServiceHolder implementa i tratti Send e Sync, il che significa che può essere condiviso in modo sicuro tra i thread, ad esempio racchiudendolo in un'istanza di Arc. La maggior parte dei metodi di TelemetryServiceHolder sono async e possono essere utilizzati contemporaneamente.

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

Inizializza il servizio registrando i callback asincroni. Chiama questo metodo una volta dopo aver ottenuto TelemetryServiceHolder e prima di qualsiasi altra interazione.

fine

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

Chiude normalmente la connessione al servizio, cancella i listener registrati e pulisce le risorse associate. Chiama questo metodo una volta quando l'app termina.

Gestione della configurazione delle metriche

Questi metodi asincroni gestiscono la definizione e lo stato delle configurazioni di raccolta dei dati.

Il servizio di telemetria gestisce le configurazioni in due stati:

• Non attivo:la configurazione viene convalidata e archiviata su disco, ma non viene utilizzata per la raccolta dei dati.
• Attiva:la configurazione raccoglie dati e i suoi componenti (ad esempio trigger e publisher) sono attivi.

Per garantire che le configurazioni vengano mantenute dopo i riavvii del servizio e i riavvii del dispositivo, il servizio le memorizza sul disco del dispositivo. Il servizio memorizza tutte le configurazioni in due directory basate sullo stato, con la convalida e, se necessario, l'attivazione all'avvio.

add_metrics_config

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

Aggiunge una nuova configurazione delle metriche al servizio. La configurazione deve essere fornita come array di byte serializzato. La configurazione aggiunta è inattiva per impostazione predefinita.

activate_metrics_config

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

Attiva una configurazione delle metriche aggiunta (o disattivata) in precedenza, avviando la raccolta dei dati e la generazione di report.

deactivate_metrics_config

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

Interrompe la raccolta dei dati e la generazione di report per una configurazione delle metriche attiva. La configurazione rimane nel servizio e può essere riattivata in un secondo momento.

remove_metrics_config

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

Rimuove definitivamente una configurazione delle metriche. Se la configurazione è attiva, il servizio la disattiva prima.

remove_all_metrics_configs

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

Rimuove tutte le configurazioni delle metriche esistenti, disattivando quelle attive.

get_active_metrics_config_uuids

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

Esegue una query sul servizio per un elenco di UUID per tutte le configurazioni nello stato attivo.

get_inactive_metrics_config_uuids

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

Esegue una query sul servizio per un elenco di UUID per tutte le configurazioni nello stato inattivo.

Gestione e recupero dei report sulle metriche

Questi metodi ti consentono di eseguire query per i report disponibili e recuperare i dati dei report raccolti.

get_metrics_report

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

Recupera i dati completi del report sulle metriche per un UUID report specifico. Puoi ottenere l'UUID del report da una notifica utilizzando report_ready_callback o chiamando get_ready_reports_info.

get_ready_reports_info

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

Esegue una query sul servizio di telemetria per un elenco di tutti i report completati e pronti per il recupero. Ciò è utile per controllare lo stato dei report se una notifica di callback non è stata ricevuta (ad esempio, se report_ready_callback è stato registrato in ritardo).

Tipi principali, callback e gestione degli errori

libsdv_telemetry_rust_wrapper utilizza un insieme di tipi personalizzati per interagire con il servizio di telemetria, gestire i callback asincroni e gestire gli errori del servizio.

Tipi di risposta ed errore dell'API

Questi tipi vengono restituiti direttamente dai metodi della libreria per indicare l'esito positivo o negativo immediato dell'operazione richiesta.

TelemetryResult

La maggior parte dei metodi restituisce un TelemetryResult<T>, che è un alias per il tipo Result standard, specializzato per gli errori a livello di servizio:

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

TelemetryError

La struct TelemetryError incapsula tutti gli errori e fornisce informazioni dettagliate sugli errori specifici del servizio:

TelemetryServiceStatusCodes

Un'enumerazione numerica che rappresenta il risultato delle chiamate API e degli stati del servizio interno. Questi codici vengono utilizzati sia in TelemetryError che in TelemetryServiceStatus. Ad esempio:

Tipi di callback asincroni

I listener registrati (misc_status_callback e report_ready_callback) passano questi tipi al client per fornire aggiornamenti sui processi in background.

TelemetryServiceStatus

La struct TelemetryServiceStatus funge da argomento per la chiusura misc_status_callback di init, che viene registrata durante l'inizializzazione del servizio. Fornisce aggiornamenti asincroni sullo stato e sui problemi di runtime del servizio, ad esempio la disconnessione da un'origine dati.

statusDetails

Questo enum racchiude contesti di errore specifici. Se details è presente in TelemetryServiceStatus, è una delle seguenti varianti:

Ogni variante dell'enumerazione contiene campi aggiuntivi che forniscono ancora più contesto.

ReportInfo

La struct ReportInfo funge da argomento per la chiusura report_ready_callback di init, che viene registrata durante l'inizializzazione del servizio. Contiene gli identificatori che descrivono un report sulle metriche:

Il campo report_uuid è l'unico necessario per il recupero successivo del report sulle metriche stesso (vedi get_metrics_report), mentre config_uuid funge solo da informazione aggiuntiva sulla sua origine.