פונקציות

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

פונקציות בממשק HIDL ממפות לשיטות בהצהרה של הכיתה IFoo ב-C++ שנוצרה באופן אוטומטי. השם של כל פונקציה נשאר זהה ב-C++‎. בקטעים הבאים מוסבר איך מתבצעת התרגום של ארגומנטים וערכי החזרה של HIDL ל-C++‎.

פרמטרים של פונקציות

הארגומנטים שמפורטים בקובץ .hal ממפים לסוגים של נתוני C++‎. ארגומנטים שלא ממופים לסוג פרימיטיבי של C++ מועברים באמצעות הפניה קבועה.

לכל פונקציית HIDL שיש לה ערך מוחזר (יש לה generates הצהרה), לרשימת הפרמטרים של C++ של אותה פונקציה יש ארגומנט נוסף: פונקציית קריאה חוזרת (callback) שנקראת עם ערכי ההחזרה של פונקציית ה-HIDL. יש חרגה אחת: אם התנאי generates מכיל פרמטר יחיד שממופה ישירות ל-primitive של C++, נעשה שימוש ב-elision של קריאה חוזרת (הקריאה החוזרת מוסרת והערך המוחזר מוחזר מהפונקציה באמצעות משפט return רגיל).

ערכים שמוחזרים על ידי פונקציות

לפונקציות הבאות יש ערכי החזרה.

שגיאות העברה וסוג ההחזרה

ההצהרה generates יכולה להוביל לשלושה סוגים של חתימות פונקציה:

• אם יש רק ערך אחד להחזרה שהוא פרימיטיבי של C++, ערך ההחזרה generates מוחזר על ידי ערך מהפונקציה באובייקט Return<T>.
• במקרים מורכבים יותר, ערכי ההחזרה של generates מוחזרים דרך פרמטר הקריאה החוזרת(callback) שסופק בקריאה לפונקציה עצמה, והפונקציה מחזירה את הערך Return<void>.
• אם אין טענת generates, הפונקציה מחזירה את הערך Return<void>.

לפעמים קריאות RPC עלולות להיתקל בשגיאות תעבורה, למשל כשהשרת נכבה, כשמשאבי התעבורה לא מספיקים כדי להשלים את הקריאה או כשהפרמטרים שהועברו לא מאפשרים להשלים את הקריאה (למשל, חסרה פונקציית קריאה חוזרת נדרשת). אובייקטים מסוג Return שומרים אינדיקציות של שגיאות בהעברה וגם ערך T (למעט Return<void>).

מכיוון שלפונקציות בצד הלקוח ובצד השרת יש את אותה חתימה, הפונקציה בצד השרת חייבת להחזיר את הטיפוס Return גם אם ההטמעה שלה לא מסמנת שגיאות בהעברה. אובייקטים מסוג Return<T> נוצרים באמצעות Return(myTValue) (או אפשר ליצור אותם באופן משתמע מ-mTValue, למשל במשפטי return), ואובייקטים מסוג Return<void> נוצרים באמצעות Void().

קיימת המרה משתמעת של אובייקטים מסוג Return<T> אל הערך שלהם ב-T וממנו. אפשר לבדוק אם יש באובייקט Return שגיאות בהעברה על ידי קריאה לשיטה isOk() שלו. הבדיקה הזו לא חובה, אבל אם מתרחשת שגיאה ולא בודקים אותה עד שהאובייקט Return נהרס, או אם מנסים להמיר ערך T, תהליך הלקוח יופסק ותירשם שגיאה ביומן. אם isOk() מציין שגיאת תעבורה או כשל קריאה בגלל שגיאה לוגית בקוד של המפתח (למשל, העברה של nullptr כקריאה חוזרת (callback) סינכרונית), אפשר להפעיל את description() באובייקט Return כדי להחזיר מחרוזת שמתאימה לרישום ביומן. במקרים כאלה, אי אפשר לקבוע כמה קוד בוצע בשרת כתוצאה מהקריאה שנכשלה. השיטה isDeadObject() זמינה גם כן. השיטה הזו מציינת שהערך של !isOk() הוא 0 כי האובייקט המרוחק קרס או שהוא לא קיים יותר. isDeadObject() תמיד משמעותו !isOk().

החזרה לפי ערך

אם משפט generates ממופה לפרימיטיב יחיד של C++, לא מופיע פרמטר של קריאה חוזרת (callback) ברשימת הפרמטרים. במקום זאת, ההטמעה מספקת את ערך ההחזרה T באובייקט Return<T>, שאפשר ליצור אותו באופן משתמע מהטיפוס הפרימיטיבי T. לדוגמה:

Return<uint32_t> someMethod() {
    uint32_t return_data = ...; // Compute return_data
    return return_data;
};

השיטה Return<*>::withDefault זמינה גם כן. השיטה הזו מספקת ערך במקרים שבהם ערך ההחזרה הוא !isOk(). השיטה הזו גם מסמנת באופן אוטומטי את אובייקט ההחזרה כתקין, כדי שתהליך הלקוח לא יופסק.

חזרה באמצעות פרמטר קריאה חוזרת

פונקציית קריאה חוזרת יכולה להעביר את הערך המוחזר של פונקציית ה-HIDL בחזרה למבצע הקריאה. אב הטיפוס של פונקציית ה-callback הוא אובייקט std::function עם פרמטרים (שנלקחים מהצהרה generates) שממופים לסוגים של C++‎. ערך ההחזרה שלה הוא void – פונקציית ההתקשרות חזרה עצמה לא מחזירה ערך.

הערך המוחזר של פונקציית C++ עם פרמטר של קריאה חוזרת הוא מסוג Return<void>. הטמעת השרת אחראית רק על מתן ערך ההחזרה. מאחר שערכים שמוחזרים כבר מועברים באמצעות פונקציית ההתקשרות חזרה, פרמטר התבנית T הוא void:

Return<void> someMethod(someMethod_cb _cb);

מההטמעה שלהם ב-C++, הטמעות השרת צריכות להחזיר את הערך Void(), שהיא פונקציה סטטית מוטמעת שמחזירה אובייקט Return<void>. דוגמה להטמעה טיפוסית של שיטת שרת עם פרמטר של קריאה חוזרת:

Return<void> someMethod(someMethod_cb _cb) {
    // Do some processing, then call callback with return data
    hidl_vec<uint32_t> vec = ...
    _cb(vec);
    return Void();
};

פונקציות ללא ערכים חזרה

בחתימה של פונקציה ב-C++ ללא הצהרת generates לא יהיה פרמטר של קריאה חוזרת ברשימה של הפרמטרים. סוג ההחזרה שלו יהיה Return<void>.

פונקציות חד-כיווניות

פונקציות שמסומנות במילת המפתח oneway הן פונקציות אסינכררוניות (הלקוחות לא ייחסמו בזמן ההפעלה שלהן) ואין להן ערכי חזרה. בחתימה של פונקציית oneway ב-C++ לא יהיה פרמטר של קריאה חוזרת (callback) ברשימת הפרמטרים, וערך ההחזרה שלה ב-C++ יהיה Return<void>.