HIDL 接口中的函數映射到自動生成的IFoo
C++ 類聲明中的方法。每個函數的名稱在 C++ 中保持不變;以下部分介紹瞭如何將 HIDL 參數和返回值轉換為 C++。
功能參數
.hal
文件中列出的參數映射到 C++ 數據類型。不映射到原始 C++ 類型的參數由 const 引用傳遞。
對於每個具有返回值(具有generates
語句)的 HIDL 函數,該函數的 C++ 參數列表都有一個附加參數:使用 HIDL 函數的返回值調用的回調函數。有一個例外:如果generates
子句包含一個直接映射到 C++ 原語的參數,則使用回調省略(回調被刪除並通過正常的return
語句從函數返回返回值)。
函數返回值
以下函數具有返回值。
傳輸錯誤和返回類型
generates
語句可以產生三種類型的函數簽名:
- 只有一個返回值是 C++ 原語,
generates
的返回值由Return<T>
對像中的函數的值返回。 - 對於更複雜的情況,
generates
的返回值通過函數調用本身提供的回調參數返回,函數返回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
作為同步回調傳遞)指示傳輸錯誤或調用失敗,則可以在 Return 對像上調用description()
以返回適合記錄的字符串。在這種情況下,無法確定由於調用失敗而在服務器上執行了多少代碼。還提供了方法isDeadObject()
。該方法表明!isOk()
是因為遠程對像已經崩潰或不再存在。 isDeadObject()
總是暗示!isOk()
。
按值返回
如果generates
語句映射到單個 C++ 原語,則參數列表中沒有回調參數。相反,實現在Return<T>
對像中提供返回值T
,該對象可以從原始類型T
隱式生成。例如:
Return<uint32_t> someMethod() { uint32_t return_data = ...; // Compute return_data return return_data; };
還提供了Return<*>::withDefault
方法。此方法在返回值為!isOk()
的情況下提供一個值。此方法還會自動將返回對象標記為正常,因此不會終止客戶端進程。
使用回調參數返回
回調可以將 HIDL 函數的返回值傳遞回調用方。回調的原型是一個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(); };
沒有返回值的函數
沒有generates
語句的函數的 C++ 簽名在參數列表中不會有回調參數。它的返回類型將是Return<void>.
單向函數
用oneway
關鍵字標記的函數是異步函數(客戶端不會阻塞它們的執行)並且沒有返回值。 oneway
函數的 C++ 簽名在參數列表中不會有回調參數,並且其 C++ 返回值將為Return<void>
。