API-Referenz zur Telemetrie-Clientbibliothek für Rust

Auf dieser Seite werden die Typen, Methoden und die Fehlerbehandlung in der libsdv_telemetry_rust_wrapper-Bibliothek beschrieben.

Schnittstelle TelemetryServiceHolder

Die primäre Schnittstelle für Clients ist die TelemetryServiceHolder-Struktur. Diese Schnittstelle bietet alle Methoden zum Verwalten der Dienstverbindung, der Messwertkonfigurationen und der Datenberichte.

Verwaltung des Dienstlebenszyklus

Mit diesen Methoden wird die Verbindung zum zugrunde liegenden Telemetriedienst hergestellt und beendet.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Eine statische Methode, die ein threadsicheres Handle für den Telemetriedienst abruft. Dies ist ein blockierender Aufruf, der wartet, bis der Telemetrie-Binder-Dienst bereit ist. Der Telemetriedienst unterstützt nur eine Instanz von TelemetryServiceHolder. Wenn Sie diese Methode mehrmals aufrufen, kann dies zu undefiniertem oder unerwartetem Verhalten führen.

TelemetryServiceHolder implementiert die Traits Send und Sync. Das bedeutet, dass sie sicher über Threads hinweg geteilt werden kann, z. B. durch Wrapping in einer Instanz von Arc. Die meisten Methoden von TelemetryServiceHolder sind async und können gleichzeitig verwendet werden.

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

Initialisiert den Dienst durch Registrieren asynchroner Callbacks. Rufen Sie diese Methode einmal auf, nachdem Sie die TelemetryServiceHolder erhalten haben und bevor Sie andere Interaktionen ausführen.

Abschließen

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

Fährt die Dienstverbindung ordnungsgemäß herunter, löscht registrierte Listener und bereinigt zugehörige Ressourcen. Rufen Sie diese Methode einmal auf, wenn die App beendet wird.

Verwaltung von Messwertkonfigurationen

Mit diesen asynchronen Methoden werden die Definition und der Status von Konfigurationen für die Datenerhebung verwaltet.

Der Telemetriedienst verwaltet Konfigurationen in zwei Status:

• Inaktiv:Die Konfiguration wird validiert und auf der Festplatte gespeichert, aber nicht für die Datenerhebung verwendet.
• Aktiv:Mit der Konfiguration werden Daten erhoben und die zugehörigen Komponenten (z. B. Trigger und Publisher) sind aktiv.

Damit Konfigurationen bei Dienstneustarts und Geräteneustarts beibehalten werden, speichert der Dienst sie auf der Festplatte des Geräts. Der Dienst speichert alle Konfigurationen in zwei statusbasierten Verzeichnissen, validiert sie und aktiviert sie bei Bedarf beim Starten des Geräts.

add_metrics_config

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

Fügt dem Dienst eine neue Messwertkonfiguration hinzu. Die Konfiguration muss als serialisiertes Byte-Array angegeben werden. Die hinzugefügte Konfiguration ist standardmäßig inaktiv.

activate_metrics_config

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

Aktiviert eine zuvor hinzugefügte (oder deaktivierte) Messwertkonfiguration und startet die Datenerhebung und Berichterstellung.

deactivate_metrics_config

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

Die Datenerhebung und Berichterstellung für eine aktive Messwertkonfiguration werden beendet. Die Konfiguration bleibt im Dienst erhalten und kann später reaktiviert werden.

remove_metrics_config

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

Entfernt eine Messwertkonfiguration dauerhaft. Wenn die Konfiguration aktiv ist, wird sie vom Dienst zuerst deaktiviert.

remove_all_metrics_configs

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

Entfernt alle vorhandenen Messwertkonfigurationen und deaktiviert alle aktiven.

get_active_metrics_config_uuids

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

Fragt den Dienst nach einer Liste von UUIDs für alle Konfigurationen im aktiven Status ab.

get_inactive_metrics_config_uuids

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

Fragt den Dienst nach einer Liste von UUIDs für alle Konfigurationen im inaktiven Status ab.

Messwertberichte verarbeiten und abrufen

Mit diesen Methoden können Sie verfügbare Berichte abfragen und die erhobenen Berichtsdaten abrufen.

get_metrics_report

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

Ruft die vollständigen Messwertberichtsdaten für eine bestimmte Berichts-UUID ab. Sie können die UUID des Berichts aus einer Benachrichtigung abrufen, indem Sie report_ready_callback verwenden oder get_ready_reports_info aufrufen.

get_ready_reports_info

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

Fragt den Telemetriedienst nach einer Liste aller Berichte ab, die abgeschlossen und zum Abrufen bereit sind. Das ist nützlich, um den Status von Berichten zu prüfen, wenn eine Callback-Benachrichtigung verpasst wurde (z. B. wenn report_ready_callback zu spät registriert wurde).

Kerntypen, Rückrufe und Fehlerbehandlung

Die libsdv_telemetry_rust_wrapper verwendet eine Reihe benutzerdefinierter Typen, um mit dem Telemetriedienst zu interagieren, asynchrone Callbacks zu verwalten und Dienstfehler zu verarbeiten.

API-Antwort- und Fehlertypen

Diese Typen werden direkt von Bibliotheksmethoden zurückgegeben, um den unmittelbaren Erfolg oder Misserfolg des angeforderten Vorgangs anzugeben.

TelemetryResult

Die meisten Methoden geben ein TelemetryResult<T> zurück, das ein Alias für den Standardtyp Result ist und für Fehler auf Dienstebene verwendet wird:

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

TelemetryError

Die TelemetryError-Struktur kapselt alle Fehler und enthält detaillierte, dienstspezifische Fehlerinformationen:

TelemetryServiceStatusCodes

Eine numerische Aufzählung, die das Ergebnis von API-Aufrufen und internen Dienststatus darstellt. Diese Codes werden sowohl in TelemetryError als auch in TelemetryServiceStatus verwendet. Beispiel:

Asynchrone Callback-Typen

Die registrierten Listener (misc_status_callback und report_ready_callback) übergeben diese Typen an den Client, um Updates zu Hintergrundprozessen bereitzustellen.

TelemetryServiceStatus

Die TelemetryServiceStatus-Struktur dient als Argument für den misc_status_callback-Closure von init, der während der Dienstinitialisierung registriert wird. Es bietet asynchrone Updates zum Zustand des Dienstes und zu Laufzeitproblemen, z. B. zur Trennung von einer Datenquelle.

StatusDetails

Diese Enumeration umfasst bestimmte Fehlerkontexte. Wenn details in TelemetryServiceStatus vorhanden ist, handelt es sich um eine der folgenden Varianten:

Jede Enum-Variante enthält zusätzliche Felder, die noch mehr Kontext liefern.

ReportInfo

Die ReportInfo-Struktur dient als Argument für den report_ready_callback-Closure von init, der bei der Dienstinitialisierung registriert wird. Sie enthält die Kennzeichnungen, die einen Messwertbericht beschreiben:

Das Feld report_uuid ist das einzige, das für den weiteren Abruf des Berichts mit den Messwerten erforderlich ist (siehe get_metrics_report). config_uuid dient nur als zusätzliche Information zur Quelle.