Tài liệu tham khảo API thư viện ứng dụng đo từ xa Rust

Trang này mô tả các loại, phương thức và cách xử lý lỗi trong thư viện libsdv_telemetry_rust_wrapper.

Giao diện TelemetryServiceHolder

Giao diện chính cho các ứng dụng là cấu trúc TelemetryServiceHolder. Giao diện này cung cấp đầy đủ các phương thức để quản lý kết nối dịch vụ, cấu hình chỉ số và báo cáo dữ liệu.

Quản lý vòng đời dịch vụ

Các phương thức này thiết lập và chấm dứt kết nối với dịch vụ Telemetry cơ bản.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Một phương thức tĩnh truy xuất một thao tác an toàn theo luồng đến dịch vụ Telemetry. Đây là một lệnh gọi chặn, chờ cho đến khi dịch vụ liên kết đo từ xa sẵn sàng. Dịch vụ Đo từ xa chỉ hỗ trợ một phiên bản duy nhất của TelemetryServiceHolder. Việc gọi phương thức này nhiều lần sẽ gây ra hành vi không xác định hoặc không mong muốn.

TelemetryServiceHolder triển khai các đặc điểm Send và Sync, nghĩa là bạn có thể chia sẻ một cách an toàn trên các luồng, chẳng hạn như bằng cách gói trong một thực thể của Arc. Hầu hết các phương thức của TelemetryServiceHolder đều là async và có thể được dùng đồng thời.

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

Khởi động dịch vụ bằng cách đăng ký các lệnh gọi lại không đồng bộ. Gọi phương thức này một lần sau khi nhận được TelemetryServiceHolder và trước khi có bất kỳ hoạt động tương tác nào khác.

hoàn tất

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

Tắt kết nối dịch vụ một cách thích hợp, xoá các trình nghe đã đăng ký và dọn dẹp các tài nguyên được liên kết. Gọi phương thức này một lần khi ứng dụng kết thúc.

Quản lý cấu hình chỉ số

Các phương thức không đồng bộ này quản lý định nghĩa và trạng thái của các cấu hình thu thập dữ liệu.

Dịch vụ đo từ xa duy trì cấu hình ở hai trạng thái:

• Không hoạt động: Cấu hình được xác thực và lưu trữ trên ổ đĩa nhưng không được dùng để thu thập dữ liệu.
• Đang hoạt động: Cấu hình này thu thập dữ liệu và các thành phần của cấu hình (ví dụ: trình kích hoạt, nhà xuất bản) đang hoạt động.

Để đảm bảo các cấu hình vẫn được giữ nguyên trong các lần khởi động lại dịch vụ và khởi động lại thiết bị, dịch vụ sẽ lưu trữ các cấu hình đó trên ổ đĩa của thiết bị. Dịch vụ này lưu trữ tất cả các cấu hình trong 2 thư mục dựa trên trạng thái, xác thực và kích hoạt các cấu hình đó khi khởi động (nếu cần).

add_metrics_config

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

Thêm một cấu hình chỉ số mới vào dịch vụ. Bạn phải cung cấp cấu hình dưới dạng một mảng byte được chuyển đổi tuần tự. Theo mặc định, cấu hình được thêm sẽ không hoạt động.

activate_metrics_config

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

Kích hoạt một cấu hình chỉ số đã được thêm (hoặc huỷ kích hoạt) trước đó, bắt đầu thu thập dữ liệu và báo cáo.

deactivate_metrics_config

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

Ngừng thu thập dữ liệu và báo cáo cho một cấu hình chỉ số đang hoạt động. Cấu hình vẫn nằm trong dịch vụ và có thể được kích hoạt lại sau.

remove_metrics_config

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

Xoá vĩnh viễn một cấu hình chỉ số. Nếu cấu hình đang hoạt động, dịch vụ sẽ huỷ kích hoạt cấu hình đó trước.

remove_all_metrics_configs

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

Xoá tất cả cấu hình chỉ số hiện có, huỷ kích hoạt mọi cấu hình đang hoạt động.

get_active_metrics_config_uuids

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

Truy vấn dịch vụ để lấy danh sách UUID cho tất cả các cấu hình ở trạng thái đang hoạt động.

get_inactive_metrics_config_uuids

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

Truy vấn dịch vụ để lấy danh sách UUID cho tất cả cấu hình ở trạng thái không hoạt động.

Xử lý và truy xuất báo cáo chỉ số

Các phương thức này cho phép bạn truy vấn các báo cáo hiện có và truy xuất dữ liệu báo cáo đã thu thập.

get_metrics_report

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

Truy xuất dữ liệu báo cáo đầy đủ về chỉ số cho một UUID báo cáo cụ thể. Bạn có thể nhận UUID báo cáo từ một thông báo bằng cách sử dụng report_ready_callback hoặc bằng cách gọi get_ready_reports_info.

get_ready_reports_info

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

Truy vấn dịch vụ Đo từ xa để lấy danh sách tất cả các báo cáo đã hoàn tất và sẵn sàng truy xuất. Điều này hữu ích khi kiểm tra trạng thái của báo cáo nếu bạn bỏ lỡ thông báo gọi lại (ví dụ: nếu report_ready_callback được đăng ký muộn).

Các loại nhân, lệnh gọi lại và xử lý lỗi

libsdv_telemetry_rust_wrapper sử dụng một nhóm các kiểu tuỳ chỉnh để tương tác với dịch vụ Đo từ xa, quản lý các lệnh gọi lại không đồng bộ và xử lý lỗi dịch vụ.

Các loại lỗi và phản hồi API

Các loại này được các phương thức của thư viện trả về trực tiếp để cho biết thao tác được yêu cầu có thành công hay không.

TelemetryResult

Hầu hết các phương thức đều trả về một TelemetryResult<T>, đây là một bí danh cho loại Result tiêu chuẩn, chuyên biệt cho các lỗi ở cấp dịch vụ:

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

TelemetryError

Cấu trúc TelemetryError bao bọc tất cả các lỗi và cung cấp thông tin chi tiết về lỗi dành riêng cho dịch vụ:

TelemetryServiceStatusCodes

Một chế độ liệt kê bằng số thể hiện kết quả của các lệnh gọi API và trạng thái dịch vụ nội bộ. Các mã này được dùng trong cả TelemetryError và TelemetryServiceStatus. Ví dụ:

Các loại lệnh gọi lại không đồng bộ

Các trình nghe đã đăng ký (misc_status_callback và report_ready_callback) sẽ truyền các loại này đến ứng dụng để cung cấp thông tin cập nhật về các quy trình ở chế độ nền.

TelemetryServiceStatus

Cấu trúc TelemetryServiceStatus đóng vai trò là đối số cho phương thức đóng misc_status_callback của init, được đăng ký trong quá trình khởi chạy dịch vụ. Nó cung cấp thông tin cập nhật không đồng bộ về tình trạng của dịch vụ và các vấn đề về thời gian chạy, chẳng hạn như ngắt kết nối với một nguồn dữ liệu.

StatusDetails

Liệt kê này bao bọc các ngữ cảnh lỗi cụ thể. Nếu details xuất hiện trong TelemetryServiceStatus, thì đó là một trong các biến thể sau:

Mỗi biến thể enum chứa các trường bổ sung cung cấp thêm nhiều bối cảnh.

ReportInfo

Cấu trúc ReportInfo đóng vai trò là đối số cho đóng report_ready_callback của init. Cấu trúc này được đăng ký trong quá trình khởi tạo dịch vụ. Nội dung này chứa các giá trị nhận dạng mô tả một báo cáo chỉ số:

Trường report_uuid là trường duy nhất cần thiết để truy xuất thêm báo cáo chỉ số (xem get_metrics_report), trong khi config_uuid chỉ đóng vai trò là thông tin bổ sung về nguồn của báo cáo.