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>
。