مرجع واجهة برمجة التطبيقات لمكتبة عميل القياس عن بُعد في Rust

توضّح هذه الصفحة الأنواع والطرق والتعامل مع الأخطاء في مكتبة libsdv_telemetry_rust_wrapper.

واجهة TelemetryServiceHolder

الواجهة الأساسية للعملاء هي بنية TelemetryServiceHolder. توفّر هذه الواجهة المجموعة الكاملة من الطرق لإدارة اتصال الخدمة وإعدادات المقاييس وتقارير البيانات.

إدارة مراحل نشاط الخدمة

تنشئ هذه الطرق الاتصال بخدمة القياس عن بُعد الأساسية وتنهيه.

الحصول على

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

طريقة ثابتة تستردّ معرّفًا آمنًا للاستخدام المتزامن لخدمة القياس عن بُعد. هذا هو استدعاء الحظر الذي ينتظر إلى أن تصبح خدمة ربط بيانات القياس عن بُعد جاهزة. تتيح خدمة القياس عن بُعد مثيلاً واحدًا فقط من TelemetryServiceHolder. سيؤدي استدعاء هذه الطريقة أكثر من مرة إلى سلوك غير محدّد أو غير متوقّع.

تنفّذ TelemetryServiceHolder سمات Send وSync، ما يعني أنّه يمكن مشاركتها بأمان في سلاسل محادثات، مثلاً من خلال تضمينها في مثيل من Arc. معظم طرق TelemetryServiceHolder هي async ويمكن استخدامها بشكل متزامن.

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

تُستخدَم لتهيئة الخدمة من خلال تسجيل عمليات ردّ غير متزامنة. يجب استدعاء هذه الطريقة مرة واحدة بعد الحصول على 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>>

يطلب من الخدمة الحصول على قائمة بمعرّفات فريدة عالمية لجميع عمليات الإعداد في الحالة النشطة.

get_inactive_metrics_config_uuids

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

يطلب من الخدمة الحصول على قائمة بالمعرّفات الفريدة العامة لجميع عمليات الإعداد في الحالة غير النشطة.

التعامل مع تقارير المقاييس واستردادها

تتيح لك هذه الطرق طلب التقارير المتاحة واسترداد بيانات التقارير التي تم جمعها.

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 مجموعة من الأنواع المخصّصة للتفاعل مع خدمة القياس عن بُعد وإدارة عمليات معاودة الاتصال غير المتزامنة والتعامل مع أخطاء الخدمة.

أنواع الردود والأخطاء في واجهة برمجة التطبيقات

يتم عرض هذه الأنواع مباشرةً من خلال طرق المكتبة للإشارة إلى النجاح أو الفشل الفوري للعملية المطلوبة.

TelemetryResult

تعرض معظم الطرق TelemetryResult<T>، وهو اسم مستعار للنوع Result العادي، وهو مخصّص للأخطاء على مستوى الخدمة:

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

TelemetryError

يغلّف البنية TelemetryError جميع حالات الفشل ويقدّم معلومات مفصّلة خاصة بالخدمة حول الأخطاء:

TelemeteryServiceStatusCodes

تعداد رقمي يمثّل نتيجة طلبات البيانات من واجهة برمجة التطبيقات وحالات الخدمة الداخلية. تُستخدَم هذه الرموز في كل من 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 إلا كمعلومات إضافية عن مصدره.