Referencia de la API de la biblioteca cliente de telemetría de Rust

En esta página, se describen los tipos, los métodos y el manejo de errores en la biblioteca de libsdv_telemetry_rust_wrapper.

Interfaz TelemetryServiceHolder

La interfaz principal para los clientes es la estructura TelemetryServiceHolder. Esta interfaz proporciona el conjunto completo de métodos para administrar la conexión de servicio, las configuraciones de métricas y los informes de datos.

Administración del ciclo de vida del servicio

Estos métodos establecen y finalizan la conexión con el servicio de telemetría subyacente.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Es un método estático que recupera un identificador seguro para subprocesos del servicio de Telemetry. Esta es una llamada de bloqueo que espera hasta que el servicio de vinculación de telemetría esté listo. El servicio de Telemetría solo admite una instancia de TelemetryServiceHolder. Si se llama a este método más de una vez, se produce un comportamiento indefinido o inesperado.

TelemetryServiceHolder implementa los rasgos Send y Sync, lo que significa que se puede compartir de forma segura entre subprocesos, por ejemplo, envolviéndolo en una instancia de Arc. La mayoría de los métodos de TelemetryServiceHolder son async y se pueden usar de forma simultánea.

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

Inicializa el servicio registrando devoluciones de llamada asíncronas. Llama a este método una vez después de obtener TelemetryServiceHolder y antes de cualquier otra interacción.

finish

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

Cierra correctamente la conexión de servicio, borra los objetos de escucha registrados y limpia los recursos asociados. Llama a este método una vez cuando finalice la app.

Administración de la configuración de métricas

Estos métodos asíncronos administran la definición y el estado de las configuraciones de recopilación de datos.

El servicio de Telemetría mantiene las configuraciones en dos estados:

• Inactiva: La configuración se valida y se almacena en el disco, pero no se usa para la recopilación de datos.
• Activa: La configuración recopila datos y sus componentes (activadores, publicadores, por ejemplo) están activos.

Para garantizar que las configuraciones persistan en los reinicios del servicio y del dispositivo, el servicio las almacena en el disco del dispositivo. El servicio almacena todas las configuraciones en dos directorios basados en el estado, los valida y, si es necesario, los activa durante el inicio.

add_metrics_config

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

Agrega una nueva configuración de métricas al servicio. La configuración se debe proporcionar como un array de bytes serializado. La configuración agregada está inactiva de forma predeterminada.

activate_metrics_config

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

Activa una configuración de métricas agregada (o desactivada) anteriormente, e inicia su recopilación de datos y generación de informes.

deactivate_metrics_config

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

Detiene la recopilación y la generación de informes de datos para una configuración de métricas activa. La configuración permanece en el servicio y se puede reactivar más adelante.

remove_metrics_config

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

Quita una configuración de métricas de forma permanente. Si la configuración está activa, el servicio la desactiva primero.

remove_all_metrics_configs

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

Quita todos los parámetros de configuración de métricas existentes y desactiva los que estén activos.

get_active_metrics_config_uuids

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

Consulta el servicio para obtener una lista de UUID de todas las configuraciones en el estado activo.

get_inactive_metrics_config_uuids

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

Consulta el servicio para obtener una lista de UUID de todas las configuraciones en estado inactivo.

Control y recuperación de informes de métricas

Estos métodos te permiten consultar los informes disponibles y recuperar los datos recopilados de los informes.

get_metrics_report

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

Recupera los datos completos del informe de métricas para un UUID de informe específico. Puedes obtener el UUID del informe desde una notificación con report_ready_callback o llamando a get_ready_reports_info.

get_ready_reports_info

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

Consulta el servicio de Telemetría para obtener una lista de todos los informes que se completaron y están listos para recuperarse. Esto es útil para verificar el estado de los informes si se omitió una notificación de devolución de llamada (por ejemplo, si report_ready_callback se registró tarde).

Tipos principales, devoluciones de llamada y control de errores

El libsdv_telemetry_rust_wrapper usa un conjunto de tipos personalizados para interactuar con el servicio de Telemetría, administrar devoluciones de llamada asíncronas y controlar errores del servicio.

Tipos de errores y respuestas de la API

Los métodos de la biblioteca devuelven estos tipos directamente para indicar el éxito o el error inmediato de la operación solicitada.

TelemetryResult

La mayoría de los métodos devuelven un TelemetryResult<T>, que es un alias para el tipo Result estándar, especializado para errores a nivel del servicio:

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

TelemetryError

La estructura TelemetryError encapsula todas las fallas y proporciona información detallada sobre los errores específicos del servicio:

TelemetryServiceStatusCodes

Es una enumeración numérica que representa el resultado de las llamadas a la API y los estados internos del servicio. Estos códigos se usan en TelemetryError y TelemetryServiceStatus. Por ejemplo:

Tipos de devolución de llamada asíncrona

Los objetos de escucha registrados (misc_status_callback y report_ready_callback) pasan estos tipos al cliente para proporcionar actualizaciones sobre los procesos en segundo plano.

TelemetryServiceStatus

La estructura TelemetryServiceStatus funciona como un argumento para el cierre misc_status_callback de init, que se registra durante la inicialización del servicio. Proporciona actualizaciones asíncronas sobre el estado del servicio y los problemas de tiempo de ejecución, por ejemplo, la desconexión de una fuente de datos.

StatusDetails

Este enum contiene contextos de error específicos. Si details está presente en TelemetryServiceStatus, es una de las siguientes variantes:

Cada variante de enumeración contiene campos adicionales que proporcionan aún más contexto.

ReportInfo

La estructura ReportInfo sirve como argumento para el cierre report_ready_callback de init, que se registra durante la inicialización del servicio. Contiene los identificadores que describen un informe de métricas:

El campo report_uuid es el único necesario para recuperar el informe de métricas (consulta get_metrics_report), mientras que config_uuid solo sirve como información adicional sobre su fuente.