函式

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>