הפניית API של ספריית הלקוח של Rust לטלמטריה

בדף הזה מתוארים הסוגים, השיטות וטיפול בשגיאות בספריית libsdv_telemetry_rust_wrapper.

ממשק TelemetryServiceHolder

הממשק העיקרי ללקוחות הוא מבנה הנתונים TelemetryServiceHolder. הממשק הזה מספק את כל השיטות לניהול חיבור השירות, הגדרות המדדים ודוחות הנתונים.

ניהול מחזור החיים של שירות

ה-methods האלה יוצרות את החיבור לשירות הטלמטריה הבסיסי ומסיימות אותו.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

שיטה סטטית שמקבלת נקודת אחיזה בטוחה לשימוש בשרשור לשירות הטלמטריה. זו קריאה חוסמת שממתינה עד ששירות ה-binder של הטלמטריה יהיה מוכן. שירות הטלמטריה תומך רק במופע יחיד של התג TelemetryServiceHolder. הפעלת ה-method הזו יותר מפעם אחת גורמת להתנהגות לא מוגדרת או בלתי צפויה.

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

מכבה את חיבור השירות בצורה מסודרת, מנקה את המאזינים הרשומים ומנקה את המשאבים המשויכים. צריך להפעיל את ה-method הזו פעם אחת כשהאפליקציה מסיימת את הפעולה.

ניהול הגדרות של מדדים

השיטות האסינכרוניות האלה מנהלות את ההגדרה והמצב של הגדרות איסוף הנתונים.

שירות הטלמטריה שומר את ההגדרות בשני מצבים:

• לא פעיל: ההגדרה מאומתת ונשמרת בדיסק, אבל לא נעשה בה שימוש לאיסוף נתונים.
• פעילה: ההגדרה אוספת נתונים, והרכיבים שלה (טריגרים, פלטפורמות לפרסום, למשל) פעילים.

כדי לוודא שההגדרות יישמרו גם אחרי הפעלה מחדש של השירות או אתחול של המכשיר, השירות שומר אותן בדיסק של המכשיר. השירות מאחסן את כל ההגדרות בשתי ספריות מבוססות-מצב, מאמת אותן ואם צריך, מפעיל אותן בזמן האתחול.

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

רוב השיטות מחזירות TelemetryResult<T>, שהוא כינוי לסוג הרגיל Result, שמתמחה בשגיאות ברמת השירות:

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

TelemetryError

המבנה TelemetryError מכיל את כל הכשלים ומספק מידע מפורט על שגיאות שספציפיות לשירות:

TelemetryServiceStatusCodes

ספירה מספרית שמייצגת את התוצאה של קריאות ל-API ומצבים של שירות פנימי. הקודים האלה משמשים גם ב-TelemetryError וגם ב-TelemetryServiceStatus. לדוגמה:

סוגים של קריאות חוזרות אסינכרוניות

המאזינים הרשומים (misc_status_callback ו-report_ready_callback) מעבירים את הסוגים האלה ללקוח כדי לספק עדכונים על תהליכים שמתבצעים ברקע.

TelemetryServiceStatus

המבנה TelemetryServiceStatus משמש כארגומנט לסגירת misc_status_callback של init, שרשום במהלך אתחול השירות. הוא מספק עדכונים אסינכרוניים לגבי תקינות השירות ובעיות בזמן הריצה, למשל ניתוק ממקור נתונים.

פרטי הסטטוס

המספר הזה מייצג הקשרים ספציפיים של שגיאות. אם details מופיע ב-TelemetryServiceStatus, זה אחד מהערכים הבאים:

כל וריאציה של enum מכילה שדות נוספים שמספקים עוד הקשר.

ReportInfo

המבנה ReportInfo משמש כארגומנט לסגירה report_ready_callback של init, שרשום במהלך אתחול השירות. הוא מכיל את המזהים שמתארים דוח מדדים:

השדה report_uuid הוא השדה היחיד שנדרש כדי לאחזר את דוח המדדים עצמו (ראו get_metrics_report), ואילו השדה config_uuid משמש רק כמידע נוסף על המקור שלו.