函式

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 值，並從該值轉換回來。您可以呼叫 isOk() 方法，檢查 Return 物件是否有傳輸錯誤。這項檢查並非必要，但如果發生錯誤，且在 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 關鍵字的函式為非同步函式 (用戶端不會阻斷執行)，且沒有傳回值。oneway 函式的 C++ 簽章在參數清單中不會有回呼參數，其 C++ 回傳值會是 Return<void>。