Referência da API da biblioteca de cliente de telemetria em Rust

Esta página descreve os tipos, métodos e tratamento de erros na biblioteca libsdv_telemetry_rust_wrapper.

Interface TelemetryServiceHolder

A interface principal para clientes é a struct TelemetryServiceHolder. Essa interface fornece o conjunto completo de métodos para gerenciar a conexão de serviço, as configurações de métricas e os relatórios de dados.

Gerenciamento do ciclo de vida do serviço

Esses métodos estabelecem e encerram a conexão com o serviço de telemetria subjacente.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Um método estático que recupera um identificador thread-safe para o serviço de telemetria. Essa é uma chamada de bloqueio que aguarda até que o serviço de vinculação de telemetria esteja pronto. O serviço de telemetria oferece suporte apenas a uma única instância do TelemetryServiceHolder. Chamar esse método mais de uma vez causa um comportamento indefinido ou inesperado.

TelemetryServiceHolder implementa os traços Send e Sync, o que significa que ele pode ser compartilhado com segurança entre threads, por exemplo, encapsulando-o em uma instância de Arc. A maioria dos métodos de TelemetryServiceHolder é async e pode ser usada simultaneamente.

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 o serviço registrando callbacks assíncronos. Chame esse método uma vez depois de receber o TelemetryServiceHolder e antes de qualquer outra interação.

finish

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

Encerra normalmente a conexão de serviço, limpa os listeners registrados e limpa os recursos associados. Chame esse método uma vez quando o app for encerrado.

Gerenciamento de configuração de métricas

Esses métodos assíncronos gerenciam a definição e o estado das configurações de coleta de dados.

O serviço de telemetria mantém as configurações em dois estados:

• Inativa:a configuração é validada e armazenada em disco, mas não é usada para coleta de dados.
• Ativa:a configuração coleta dados, e os componentes dela (gatilhos, editores, por exemplo) estão ativos.

Para garantir que as configurações persistam nas reinicializações do serviço e do dispositivo, o serviço as armazena no disco do dispositivo. O serviço armazena todas as configurações em dois diretórios baseados em estado, validando e, se necessário, ativando-as na inicialização.

add_metrics_config

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

Adiciona uma nova configuração de métricas ao serviço. A configuração precisa ser fornecida como uma matriz de bytes serializada. A configuração adicionada fica inativa por padrão.

activate_metrics_config

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

Ativa uma configuração de métricas adicionada (ou desativada) anteriormente, iniciando a coleta de dados e a geração de relatórios.

deactivate_metrics_config

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

Interrompe a coleta de dados e a geração de relatórios para uma configuração de métricas ativa. A configuração permanece no serviço e pode ser reativada mais tarde.

remove_metrics_config

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

Remove uma configuração de métricas permanentemente. Se a configuração estiver ativa, o serviço a desativará primeiro.

remove_all_metrics_configs

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

Remove todas as configurações de métricas atuais, desativando as que estão ativas.

get_active_metrics_config_uuids

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

Consulta o serviço para uma lista de UUIDs de todas as configurações no estado ativo.

get_inactive_metrics_config_uuids

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

Consulta o serviço para uma lista de UUIDs de todas as configurações no estado inativo.

Processamento e recuperação de relatórios de métricas

Com eles, é possível consultar os relatórios disponíveis e recuperar os dados coletados.

get_metrics_report

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

Recupera todos os dados do relatório de métricas para um UUID de relatório específico. Você pode receber o UUID do relatório de uma notificação usando report_ready_callback ou chamando get_ready_reports_info.

get_ready_reports_info

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

Consulta o serviço de telemetria para uma lista de todos os relatórios concluídos e prontos para recuperação. Isso é útil para verificar o estado dos relatórios se uma notificação de callback foi perdida (por exemplo, se report_ready_callback foi registrado tarde).

Tipos principais, callbacks e tratamento de erros

O libsdv_telemetry_rust_wrapper usa um conjunto de tipos personalizados para interagir com o serviço de telemetria, gerenciar callbacks assíncronos e processar erros de serviço.

Tipos de erros e respostas da API

Esses tipos são retornados diretamente pelos métodos da biblioteca para indicar o sucesso ou a falha imediata da operação solicitada.

TelemetryResult

A maioria dos métodos retorna um TelemetryResult<T>, que é um alias para o tipo Result padrão, especializado em erros no nível do serviço:

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

TelemetryError

A struct TelemetryError encapsula todas as falhas e fornece informações detalhadas e específicas do serviço sobre erros:

TelemetryServiceStatusCodes

Uma enumeração numérica que representa o resultado das chamadas de API e dos estados do serviço interno. Esses códigos são usados em TelemetryError e TelemetryServiceStatus. Exemplo:

Tipos de callback assíncronos

Os listeners registrados (misc_status_callback e report_ready_callback) transmitem esses tipos ao cliente para fornecer atualizações sobre processos em segundo plano.

TelemetryServiceStatus

A struct TelemetryServiceStatus serve como um argumento para o fechamento misc_status_callback de init, que é registrado durante a inicialização do serviço. Ele fornece atualizações assíncronas sobre a integridade do serviço e problemas de tempo de execução, por exemplo, desconexão de uma fonte de dados.

StatusDetails

Esse enum encapsula contextos de erros específicos. Se details estiver presente em TelemetryServiceStatus, ele será uma das seguintes variantes:

Cada variante de enumeração contém campos adicionais que fornecem ainda mais contexto.

ReportInfo

A struct ReportInfo serve como um argumento para o fechamento report_ready_callback de init, que é registrado durante a inicialização do serviço. Ele contém os identificadores que descrevem um relatório de métricas:

O campo report_uuid é o único necessário para a recuperação do relatório de métricas (consulte get_metrics_report), enquanto config_uuid serve apenas como informação adicional sobre a origem.