פונקציות

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

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

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

עבור כל פונקציה HIDL שיש לה ערך החזרה (יש לה משפט generates ), לרשימת הפרמטרים C++ עבור אותה פונקציה יש ארגומנט נוסף: פונקציית callback שנקראת עם ערכי ההחזרה של הפונקציה HIDL. יש יוצא מן הכלל אחד : אם הסעיף generates מכיל פרמטר בודד שממפה ישירות ל-C++ פרימיטיבי, נעשה שימוש ב-callback elision (ה-callback מוסר וערך ההחזרה מוחזר מהפונקציה באמצעות הצהרת 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 כהתקשרות חוזרת סינכרונית), אז ניתן לקרוא ל- description() באובייקט Return כדי להחזיר מחרוזת המתאימה לרישום. במקרים כאלה, אין דרך לקבוע כמה קוד עשוי להיות מופעל בשרת כתוצאה מהקריאה שנכשלה. השיטה isDeadObject() מסופקת גם כן. שיטה זו מציינת ש- !isOk() נובע מכך שהאובייקט המרוחק קרס או אינו קיים עוד. isDeadObject() מרמז תמיד על !isOk() .

החזר לפי ערך

אם ההצהרה generates ממפות ל-C++ פרימיטיבי בודד, אין פרמטר התקשרות חוזר ברשימת הפרמטרים. במקום זאת, מימוש מספק את ערך ההחזר 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++. ערך ההחזרה שלו בטל - ההתקשרות חזרה עצמה לא מחזירה ערך.

לערך ההחזרה של פונקציית C++ עם פרמטר התקשרות חוזר יש סוג Return<void> . יישום השרת אחראי רק לספק את ערך ההחזרה. מכיוון שערכי ההחזרה כבר מועברים באמצעות ה-callback, פרמטר תבנית 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 לא יהיה פרמטר Callback ברשימת הפרמטרים. סוג ההחזרה שלו יהיה Return<void>.

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

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