Справочник по API библиотеки клиента телеметрии Rust

На этой странице описаны типы, методы и обработка ошибок в библиотеке libsdv_telemetry_rust_wrapper .

интерфейс TelemetryServiceHolder

Основным интерфейсом для клиентов является структура TelemetryServiceHolder . Этот интерфейс предоставляет полный набор методов для управления подключением к сервису, конфигурацией метрик и отчетами о данных.

Управление жизненным циклом сервиса

Эти методы устанавливают и разрывают соединение с базовой службой телеметрии.

получать

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Статический метод, получающий потокобезопасный дескриптор службы телеметрии. Это блокирующий вызов, который ожидает готовности службы привязки телеметрии. Служба телеметрии поддерживает только один экземпляр TelemetryServiceHolder . Вызов этого метода более одного раза приводит к неопределенному или неожиданному поведению.

TelemetryServiceHolder реализует трейты Send и Sync , что означает, что его можно безопасно использовать в разных потоках, например, обернув его в экземпляр Arc . Большинство методов TelemetryServiceHolder являются async и могут использоваться параллельно.

инициализация

pub async fn init(
    &self,
    misc_status_callback: impl Fn(TelemetryServiceStatus) + Send + Sync + 'static,
    report_ready_callback: impl Fn(ReportInfo) + Send + Sync + 'static,
) -> TelemetryResult<()>

Инициализирует сервис путем регистрации асинхронных обратных вызовов. Вызовите этот метод один раз после получения объекта TelemetryServiceHolder и перед любыми другими взаимодействиями.

заканчивать

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

Этот метод корректно завершает соединение со службой, удаляет зарегистрированные обработчики событий и очищает связанные ресурсы. Вызовите этот метод один раз при завершении работы приложения.

Управление конфигурацией метрик

Эти асинхронные методы управляют определением и состоянием конфигураций сбора данных.

Служба телеметрии поддерживает конфигурации в двух состояниях:

• Неактивно: Конфигурация проверена и сохранена на диске, но не используется для сбора данных.
• Активно: Конфигурация собирает данные, и ее компоненты (например, триггеры, издатели) активны.

Для обеспечения сохранения конфигураций после перезапуска службы и перезагрузки устройства, служба хранит их на диске устройства. Служба хранит все конфигурации в двух каталогах, основанных на состоянии, проверяя и, при необходимости, активируя их при загрузке.

add_metrics_config

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

Добавляет новую конфигурацию метрик к сервису. Конфигурация должна быть предоставлена ​​в виде сериализованного массива байтов. Добавленная конфигурация по умолчанию неактивна.

activate_metrics_config

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

Активирует ранее добавленную (или деактивированную) конфигурацию метрик, запуская сбор данных и формирование отчетов.

deactivate_metrics_config

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

Останавливает сбор и формирование отчетов по активной конфигурации метрик. Конфигурация остается в сервисе и может быть повторно активирована позже.

remove_metrics_config

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

Удаляет конфигурацию метрик навсегда. Если конфигурация активна, служба сначала деактивирует её.

remove_all_metrics_configs

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

Удаляет все существующие конфигурации метрик, деактивируя все активные.

get_active_metrics_config_uuids

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

Выполняет запрос к сервису для получения списка UUID для всех конфигураций в активном состоянии.

get_inactive_metrics_config_uuids

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

Выполняет запрос к сервису для получения списка UUID для всех конфигураций, находящихся в неактивном состоянии.

Обработка и извлечение отчетов по метрикам

Эти методы позволяют запрашивать доступные отчеты и извлекать собранные данные из отчетов.

get_metrics_report

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

Получает полные данные отчета по метрикам для конкретного UUID отчета. Вы можете получить UUID отчета из уведомления, используя функцию report_ready_callback или вызвав get_ready_reports_info .

get_ready_reports_info

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

Выполняет запрос к службе телеметрии для получения списка всех отчетов, которые завершены и готовы к получению. Это полезно для проверки состояния отчетов, если уведомление об обратном вызове было пропущено (например, если report_ready_callback был зарегистрирован с опозданием).

Основные типы данных, обратные вызовы и обработка ошибок.

Библиотека libsdv_telemetry_rust_wrapper использует набор пользовательских типов для взаимодействия со службой телеметрии, управления асинхронными обратными вызовами и обработки ошибок службы.

Типы ответов и ошибок API

Эти типы возвращаются непосредственно методами библиотеки, указывая на немедленный успех или неудачу запрошенной операции.

Результат телеметрии

Большинство методов возвращают объект TelemetryResult<T> , который является псевдонимом для стандартного типа Result , специализированного для ошибок уровня сервиса:

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

Ошибка телеметрии

Структура TelemetryError инкапсулирует все ошибки и предоставляет подробную информацию об ошибках, специфичную для данной службы:

Коды состояния службы телеметрии

Числовое значение, представляющее результат вызовов API и внутренние состояния сервиса. Эти коды используются как в TelemetryError , так и TelemetryServiceStatus . Например:

Асинхронные типы обратных вызовов

Зарегистрированные обработчики событий ( misc_status_callback и report_ready_callback ) передают эти типы клиенту для предоставления обновлений о фоновых процессах.

TelemetryServiceStatus

Структура TelemetryServiceStatus служит аргументом для замыкания misc_status_callback функции init , которое регистрируется во время инициализации сервиса. Она предоставляет асинхронные обновления о состоянии сервиса и проблемах во время выполнения, например, об отключении от источника данных.

StatusDetails

Этот перечислимый тип содержит информацию о конкретных контекстах ошибок. Если details присутствует в TelemetryServiceStatus , оно принимает один из следующих вариантов:

Каждый вариант перечисления содержит дополнительные поля, предоставляющие еще больше контекста.

ReportInfo

Структура ReportInfo служит аргументом для замыкания report_ready_callback функции init , которое регистрируется во время инициализации сервиса. Она содержит идентификаторы, описывающие отчет по метрикам:

Поле report_uuid является единственным необходимым для дальнейшего получения самого отчета по метрикам (см. get_metrics_report ), в то время как config_uuid служит лишь дополнительной информацией о его источнике.