Dokumentacja API biblioteki klienta telemetrii Rust

Na tej stronie opisujemy typy, metody i obsługę błędów w bibliotece libsdv_telemetry_rust_wrapper.

Interfejs TelemetryServiceHolder

Głównym interfejsem dla klientów jest struktura TelemetryServiceHolder. Ten interfejs udostępnia pełny zestaw metod zarządzania połączeniem z usługą, konfiguracjami danych i raportami o danych.

Zarządzanie cyklem życia usługi

Te metody nawiązują i zamykają połączenie z usługą telemetrii.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Metoda statyczna, która pobiera bezpieczny wątkowo uchwyt do usługi Telemetry. Jest to wywołanie blokujące, które czeka, aż usługa powiązań telemetrii będzie gotowa. Usługa telemetrii obsługuje tylko 1 instancję TelemetryServiceHolder. Wywołanie tej metody więcej niż raz powoduje nieokreślone lub nieoczekiwane zachowanie.

TelemetryServiceHolder implementuje cechy Send i Sync, co oznacza, że można ją bezpiecznie udostępniać w wątkach, np. poprzez opakowanie jej w instancji Arc. Większość metod TelemetryServiceHolder jest async i może być używana współbieżnie.

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

Inicjuje usługę przez zarejestrowanie wywołań zwrotnych asynchronicznych. Wywołaj tę metodę raz po uzyskaniu wartości TelemetryServiceHolder i przed wykonaniem jakichkolwiek innych działań.

zakończ

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

Grzecznie zamyka połączenie z usługą, czyści zarejestrowanych odbiorców i usuwa powiązane zasoby. Wywołaj tę metodę raz po zakończeniu działania aplikacji.

Zarządzanie konfiguracją danych

Te metody asynchroniczne zarządzają definicją i stanem konfiguracji zbierania danych.

Usługa telemetrii utrzymuje konfiguracje w 2 stanach:

• Nieaktywna:konfiguracja jest weryfikowana i przechowywana na dysku, ale nie jest używana do zbierania danych.
• Aktywna: konfiguracja zbiera dane, a jej komponenty (np. wyzwalacze, wydawcy) są aktywne.

Aby konfiguracje były zachowywane po ponownym uruchomieniu usługi i urządzenia, usługa zapisuje je na dysku urządzenia. Usługa przechowuje wszystkie konfiguracje w 2 katalogach opartych na stanie, weryfikując je i w razie potrzeby aktywując podczas uruchamiania.

add_metrics_config

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

Dodaje do usługi nową konfigurację wskaźników. Konfiguracja musi być podana jako serializowana tablica bajtów. Dodana konfiguracja jest domyślnie nieaktywna.

activate_metrics_config

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

Aktywuje wcześniej dodaną (lub dezaktywowaną) konfigurację danych, rozpoczynając zbieranie danych i raportowanie.

deactivate_metrics_config

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

Zatrzymuje zbieranie danych i raportowanie w przypadku aktywnej konfiguracji danych. Konfiguracja pozostaje w usłudze i można ją później ponownie aktywować.

remove_metrics_config

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

Trwale usuwa konfigurację danych. Jeśli konfiguracja jest aktywna, usługa najpierw ją dezaktywuje.

remove_all_metrics_configs

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

Usuwa wszystkie dotychczasowe konfiguracje danych, dezaktywując te, które są aktywne.

get_active_metrics_config_uuids

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

Wysyła do usługi zapytanie o listę identyfikatorów UUID wszystkich konfiguracji w stanie aktywnym.

get_inactive_metrics_config_uuids

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

Wysyła do usługi zapytanie o listę identyfikatorów UUID wszystkich konfiguracji w stanie nieaktywnym.

Obsługa i pobieranie raportu o danych

Te metody umożliwiają wysyłanie zapytań o dostępne raporty i pobieranie zebranych danych raportu.

get_metrics_report

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

Pobiera pełne dane raportu o rodzajach danych dla konkretnego identyfikatora UUID raportu. Identyfikator UUID raportu możesz uzyskać z powiadomienia, korzystając z metody report_ready_callback lub wywołując metodę get_ready_reports_info.

get_ready_reports_info

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

Wysyła do usługi Telemetry zapytanie o listę wszystkich raportów, które zostały ukończone i są gotowe do pobrania. Jest to przydatne do sprawdzania stanu raportów, jeśli powiadomienie zwrotne zostało pominięte (np. jeśli report_ready_callback zostało zarejestrowane z opóźnieniem).

Podstawowe typy, wywołania zwrotne i obsługa błędów

libsdv_telemetry_rust_wrapper korzysta z zestawu typów niestandardowych do interakcji z usługą telemetrii, zarządzania wywołaniami zwrotnymi asynchronicznymi i obsługi błędów usługi.

Odpowiedzi interfejsu API i typy błędów

Te typy są zwracane bezpośrednio przez metody biblioteki, aby wskazać natychmiastowy sukces lub niepowodzenie żądanej operacji.

TelemetryResult

Większość metod zwraca TelemetryResult<T>, czyli alias standardowego typu Result, wyspecjalizowany pod kątem błędów na poziomie usługi:

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

TelemetryError

Struktura TelemetryError obejmuje wszystkie błędy i zawiera szczegółowe informacje o błędach specyficzne dla usługi:

TelemetryServiceStatusCodes

Wartość liczbowa reprezentująca wynik wywołań interfejsu API i stanów usług wewnętrznych. Te kody są używane zarówno w TelemetryError, jak i w TelemetryServiceStatus. Przykład:

Asynchroniczne typy wywołań zwrotnych

Zarejestrowani odbiorcy (misc_status_callback i report_ready_callback) przekazują te typy do klienta, aby informować go o procesach działających w tle.

TelemetryServiceStatus

Struktura TelemetryServiceStatus służy jako argument dla zamknięcia misc_status_callback funkcji init, która jest rejestrowana podczas inicjowania usługi. Dostarcza asynchroniczne aktualizacje dotyczące stanu usługi i problemów z jej działaniem, np. odłączenia od źródła danych.

StatusDetails

Ten wyliczenie zawiera konkretne konteksty błędów. Jeśli w TelemetryServiceStatus występuje details, jest to jedna z tych wersji:

Każdy wariant wyliczenia zawiera dodatkowe pola, które dostarczają jeszcze więcej kontekstu.

ReportInfo

Struktura ReportInfo służy jako argument dla zamknięcia report_ready_callbackinit, które jest rejestrowane podczas inicjowania usługi. Zawiera identyfikatory opisujące raport danych:

Pole report_uuid jest jedynym polem niezbędnym do dalszego pobierania samego raportu o metrykach (patrz get_metrics_report), a pole config_uuid służy tylko jako dodatkowa informacja o jego źródle.