مرجع API کتابخانه کلاینت Rust برای سنجش از راه دور

این صفحه انواع، روش‌ها و نحوه‌ی مدیریت خطا در کتابخانه‌ی libsdv_telemetry_rust_wrapper را شرح می‌دهد.

رابط TelemetryServiceHolder

رابط اصلی برای کلاینت‌ها، ساختار TelemetryServiceHolder است. این رابط، مجموعه کاملی از متدها را برای مدیریت اتصال سرویس، پیکربندی معیارها و گزارش‌های داده ارائه می‌دهد.

مدیریت چرخه حیات خدمات

این روش‌ها اتصال با سرویس Telemetry مربوطه را برقرار و قطع می‌کنند.

دریافت

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

یک متد استاتیک که یک هندل thread-safe را برای سرویس Telemetry بازیابی می‌کند. این یک فراخوانی مسدودکننده است که تا آماده شدن سرویس telemetry binder منتظر می‌ماند. سرویس Telemetry فقط از یک نمونه 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<()>

Gracefully اتصال سرویس را قطع می‌کند، listenerهای ثبت‌شده را پاک می‌کند و منابع مرتبط را پاکسازی می‌کند. این متد را یک بار هنگام خاتمه برنامه فراخوانی کنید.

مدیریت پیکربندی معیارها

این متدهای ناهمزمان، تعریف و وضعیت پیکربندی‌های جمع‌آوری داده‌ها را مدیریت می‌کنند.

سرویس تله‌متری پیکربندی‌ها را در دو حالت حفظ می‌کند:

• غیرفعال: پیکربندی اعتبارسنجی و روی دیسک ذخیره می‌شود اما برای جمع‌آوری داده‌ها استفاده نمی‌شود.
• فعال: پیکربندی داده‌ها را جمع‌آوری می‌کند و اجزای آن (مثلاً تریگرها، ناشران) فعال هستند.

برای اطمینان از اینکه پیکربندی‌ها در طول راه‌اندازی مجدد سرویس و راه‌اندازی مجدد دستگاه باقی می‌مانند، این سرویس آنها را روی دیسک دستگاه ذخیره می‌کند. این سرویس تمام پیکربندی‌ها را در دو دایرکتوری مبتنی بر وضعیت ذخیره می‌کند و آنها را در هنگام بوت اعتبارسنجی و در صورت لزوم فعال می‌کند.

پیکربندی_معیارهای_افزودنی

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

یک پیکربندی جدید برای معیارها به سرویس اضافه می‌کند. این پیکربندی باید به صورت یک آرایه بایتی سریالی شده ارائه شود. پیکربندی اضافه شده به طور پیش‌فرض غیرفعال است.

پیکربندی_متریک_فعال‌سازی

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

پیکربندی معیارهای قبلاً اضافه شده (یا غیرفعال شده) را فعال می‌کند و جمع‌آوری داده‌ها و گزارش‌دهی آن را آغاز می‌کند.

غیرفعال کردن_متریک_پیکربندی

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

جمع‌آوری داده‌ها و گزارش‌دهی برای پیکربندی معیارهای فعال را متوقف می‌کند. پیکربندی در سرویس باقی می‌ماند و می‌تواند بعداً دوباره فعال شود.

حذف_متریک_پیکربندی

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

پیکربندی معیارها را برای همیشه حذف می‌کند. اگر پیکربندی فعال باشد، سرویس ابتدا آن را غیرفعال می‌کند.

حذف همه پیکربندی‌های متریک

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ها را برای تمام پیکربندی‌های غیرفعال درخواست می‌کند.

مدیریت و بازیابی گزارش معیارها

این متدها به شما امکان می‌دهند گزارش‌های موجود را جستجو کرده و داده‌های گزارش جمع‌آوری‌شده را بازیابی کنید.

دریافت_معیارها_گزارش

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

داده‌های کامل گزارش معیارها را برای یک UUID گزارش خاص بازیابی می‌کند. می‌توانید UUID گزارش را از طریق اعلان با استفاده از report_ready_callback یا با فراخوانی get_ready_reports_info دریافت کنید.

دریافت_آماده_گزارش_اطلاعات

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

از سرویس Telemetry لیستی از تمام گزارش‌های تکمیل‌شده و آماده برای بازیابی را درخواست می‌کند. این برای بررسی وضعیت گزارش‌ها در صورت از دست رفتن اعلان فراخوانی مجدد (مثلاً اگر report_ready_callback با تأخیر ثبت شده باشد) مفید است.

انواع اصلی، فراخوانی‌های برگشتی و مدیریت خطا

libsdv_telemetry_rust_wrapper از مجموعه‌ای از انواع سفارشی برای تعامل با سرویس Telemetry، مدیریت فراخوانی‌های ناهمزمان و مدیریت خطاهای سرویس استفاده می‌کند.

پاسخ API و انواع خطا

این نوع‌ها مستقیماً توسط متدهای کتابخانه‌ای برگردانده می‌شوند تا موفقیت یا شکست فوری عملیات درخواستی را نشان دهند.

نتیجه تله‌متری

اکثر متدها یک TelemetryResult<T> برمی‌گردانند که یک نام مستعار برای نوع استاندارد Result است و برای خطاهای سطح سرویس تخصصی شده است:

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

خطای تله‌متری

ساختار TelemetryError تمام خطاها را کپسوله‌سازی می‌کند و اطلاعات خطای دقیق و مختص سرویس را ارائه می‌دهد:

کدهای وضعیت سرویس تله‌متری

یک شمارش عددی که نتیجه فراخوانی‌های API و وضعیت‌های سرویس داخلی را نشان می‌دهد. این کدها هم در TelemetryError و هم TelemetryServiceStatus استفاده می‌شوند. برای مثال:

انواع فراخوانی‌های ناهمزمان

شنوندگان ثبت‌شده ( misc_status_callback و report_ready_callback ) این نوع‌ها را به کلاینت ارسال می‌کنند تا به‌روزرسانی‌هایی در مورد فرآیندهای پس‌زمینه ارائه دهند.

وضعیت سرویس تله‌متری

ساختار TelemetryServiceStatus به عنوان آرگومانی برای تابع بسته‌ی misc_status_callback از init عمل می‌کند که در طول مقداردهی اولیه‌ی سرویس ثبت می‌شود. این ساختار به‌روزرسانی‌های ناهمزمان در مورد سلامت سرویس و مشکلات زمان اجرا، به عنوان مثال، قطع ارتباط از منبع داده، ارائه می‌دهد.

جزئیات وضعیت

این enum زمینه‌های خطای خاص را در بر می‌گیرد. اگر details در TelemetryServiceStatus وجود داشته باشد، یکی از انواع زیر است:

هر نوع enum شامل فیلدهای اضافی است که زمینه بیشتری را فراهم می‌کند.

گزارش اطلاعات

ساختار ReportInfo به عنوان آرگومانی برای بسته شدن report_ready_callback از init عمل می‌کند که در طول مقداردهی اولیه سرویس ثبت می‌شود. این ساختار شامل شناسه‌هایی است که یک گزارش معیارها را توصیف می‌کنند:

فیلد report_uuid تنها فیلد ضروری برای بازیابی بیشتر خود گزارش معیارها است (به get_metrics_report مراجعه کنید)، در حالی که config_uuid فقط به عنوان اطلاعات اضافی در مورد منبع آن عمل می‌کند.