Documentation de référence de l'API de la bibliothèque cliente de télémétrie Rust

Cette page décrit les types, les méthodes et la gestion des erreurs dans la bibliothèque libsdv_telemetry_rust_wrapper.

Interface TelemetryServiceHolder

L'interface principale pour les clients est la structure TelemetryServiceHolder. Cette interface fournit l'ensemble des méthodes permettant de gérer la connexion au service, les configurations des métriques et les rapports de données.

Gestion du cycle de vie des services

Ces méthodes établissent et mettent fin à la connexion avec le service de télémétrie sous-jacent.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Méthode statique qui récupère un handle thread-safe pour le service de télémétrie. Il s'agit d'un appel bloquant qui attend que le service de liaison de télémétrie soit prêt. Le service de télémétrie n'accepte qu'une seule instance de TelemetryServiceHolder. L'appel de cette méthode plusieurs fois entraîne un comportement indéfini ou inattendu.

TelemetryServiceHolder implémente les traits Send et Sync, ce qui signifie qu'il peut être partagé de manière sécurisée entre les threads, par exemple en l'encapsulant dans une instance de Arc. La plupart des méthodes de TelemetryServiceHolder sont async et peuvent être utilisées simultanément.

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

Initialise le service en enregistrant des rappels asynchrones. Appelez cette méthode une fois après avoir obtenu le TelemetryServiceHolder et avant toute autre interaction.

finish

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

Arrête la connexion au service en douceur, efface les écouteurs enregistrés et nettoie les ressources associées. Appelez cette méthode une fois lorsque l'application se termine.

Gestion de la configuration des métriques

Ces méthodes asynchrones gèrent la définition et l'état des configurations de collecte de données.

Le service de télémétrie conserve les configurations dans deux états :

• Inactive : la configuration est validée et stockée sur le disque, mais n'est pas utilisée pour la collecte de données.
• Active : la configuration collecte des données et ses composants (déclencheurs, éditeurs, par exemple) sont actifs.

Pour que les configurations soient conservées lors des redémarrages du service et de l'appareil, le service les stocke sur le disque de l'appareil. Le service stocke toutes les configurations dans deux répertoires basés sur l'état, en les validant et, si nécessaire, en les activant au démarrage.

add_metrics_config

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

Ajoute une configuration de métriques au service. La configuration doit être fournie sous forme de tableau d'octets sérialisé. La configuration ajoutée est inactive par défaut.

activate_metrics_config

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

Active une configuration de métriques précédemment ajoutée (ou désactivée), en lançant la collecte des données et la création de rapports.

deactivate_metrics_config

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

Arrête la collecte et le reporting des données pour une configuration de métriques active. La configuration reste dans le service et peut être réactivée ultérieurement.

remove_metrics_config

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

Supprime définitivement une configuration de métriques. Si la configuration est active, le service la désactive d'abord.

remove_all_metrics_configs

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

Supprime toutes les configurations de métriques existantes et désactive celles qui sont actives.

get_active_metrics_config_uuids

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

Interroge le service pour obtenir la liste des UUID de toutes les configurations à l'état actif.

get_inactive_metrics_config_uuids

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

Interroge le service pour obtenir la liste des UUID de toutes les configurations à l'état inactif.

Gestion et récupération des rapports sur les métriques

Ces méthodes vous permettent d'interroger les rapports disponibles et de récupérer les données collectées.

get_metrics_report

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

Récupère les données complètes du rapport sur les métriques pour un UUID de rapport spécifique. Vous pouvez obtenir l'UUID du rapport à partir d'une notification à l'aide de report_ready_callback ou en appelant get_ready_reports_info.

get_ready_reports_info

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

Interroge le service de télémétrie pour obtenir la liste de tous les rapports terminés et prêts à être récupérés. Cela est utile pour vérifier l'état des rapports si une notification de rappel a été manquée (par exemple, si report_ready_callback a été enregistré tardivement).

Types de base, rappels et gestion des erreurs

libsdv_telemetry_rust_wrapper utilise un ensemble de types personnalisés pour interagir avec le service de télémétrie, gérer les rappels asynchrones et gérer les erreurs de service.

Types de réponses et d'erreurs de l'API

Ces types sont renvoyés directement par les méthodes de la bibliothèque pour indiquer la réussite ou l'échec immédiat de l'opération demandée.

TelemetryResult

La plupart des méthodes renvoient un TelemetryResult<T>, qui est un alias pour le type Result standard, spécialisé pour les erreurs au niveau du service :

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

TelemetryError

La structure TelemetryError encapsule tous les échecs et fournit des informations détaillées sur les erreurs spécifiques au service :

TelemetryServiceStatusCodes

Énumération numérique représentant le résultat des appels d'API et des états de service internes. Ces codes sont utilisés dans TelemetryError et TelemetryServiceStatus. Exemple :

Types de rappel asynchrones

Les écouteurs enregistrés (misc_status_callback et report_ready_callback) transmettent ces types au client pour fournir des informations sur les processus en arrière-plan.

TelemetryServiceStatus

La structure TelemetryServiceStatus sert d'argument pour la fermeture misc_status_callback de init, qui est enregistrée lors de l'initialisation du service. Il fournit des mises à jour asynchrones sur l'état du service et les problèmes d'exécution (par exemple, la déconnexion d'une source de données).

StatusDetails

Cette énumération encapsule des contextes d'erreur spécifiques. Si details est présent dans TelemetryServiceStatus, il s'agit de l'une des variantes suivantes :

Chaque variante d'énumération contient des champs supplémentaires qui fournissent encore plus de contexte.

ReportInfo

La structure ReportInfo sert d'argument pour la fermeture report_ready_callback de init, qui est enregistrée lors de l'initialisation du service. Il contient les identifiants décrivant un rapport sur les métriques :

Le champ report_uuid est le seul nécessaire pour récupérer le rapport sur les métriques lui-même (voir get_metrics_report), tandis que config_uuid ne sert que d'information supplémentaire sur sa source.