FIDL 字典

本文件定義在 FIDL 結構定義中具有特定意義的一般字詞。如要進一步瞭解特定 FIDL 主題,請參閱 FIDL 追蹤記錄

類型、版面配置、限制

類型會在 FIDL 類型系統中將值分類。類型會顯示在 FIDL 文法中定義的 type-constructor 位置。舉例來說,uint32string:10vector<bool> 都是類型。

「版面配置」是類型的可參數說明。這裡並未參照單一類型,但用於說明將版面配置執行個體化 (使用零或多個版面配置參數) 取得的一系列類型。舉例來說,vector 是一種版面配置,可接受一個版面配置參數,而類型 (例如 vector<bool>) 本身就是類型。再舉一個例子,array 版面配置使用了兩個版面配置參數,並產生 array<bool, 3> 等類型。

版面配置和類型之間的差異可能有些細微差異。舉例來說,上述 uint32 類型的陳述式並不完全正確。相反地,此版面配置會採用零參數,與透過執行個體化取得的類型不同。FIDL 語法不會擷取上述區別,因此在類型位置 (例如 alias uint = uint32;) 中使用 uint32 時,實際上會參照版面配置 uint32,並以零版面配置參數隱含方式執行個體化。

限制會限制類型只允許符合述詞的值。舉例來說,類型 string:10 的限制 length <= 10 縮寫為 10,也就是字串長度不得超過 10 個位元組。

版面配置和版面配置參數會影響位元組以 FIDL 傳輸格式的配置方式,而限制條件會影響用來限制內容的驗證 (詳情請參閱 RFC-050)。以語法來說,版面配置參數只能套用至版面配置,且限制只能套用至類型。例如:

alias Bools = vector<bool>;       // ok: layout parameter applied to layout
alias MaxTenBools = Bools:10;     // ok: constraint applied to type
alias MaxTenBytes = Bools<byte>;  // INVALID: layout parameter applied to type
alias MaxTen = vector:10;         // INVALID: constraint applied to layout

類型例項的一般形式是

L<L_1, L_2, ..., L_n>:<C_1, C_2, ..., C_n>

其中 L 是版面配置,L_1L_n 是版面配置參數,而透過 C_n 傳遞的 C_1 則為限制條件。

成員、欄位、子類

宣告的「成員」是屬於宣告的個別元素,即宣告由零、一或多個成員組成。

例如,考慮 Mode 位元宣告:

type Mode = strict bits {
    READ = 1;
    WRITE = 2;
};

READWRITE 都是成員。

提及結構體或資料表的成員時,我們還可以特別將這些成員稱為「欄位」

稱之為聯集的成員時,我們可以更明確地將這些成員稱為「變化版本」

例如,考慮使用 Command 聯集宣告:

type Command = strict union {
    1: create_resource CreateResource;
    2: release_resource ReleaseResource;
};

兩個變數為 create_resourcerelease_resource

此外,聯集執行個體的「選取的變化版本」是聯集目前持有的值。

標記和序數

「標記」是譯文語言變體鑑別器,即用於表示聯集所選變化版本的指定語言特定結構。舉例來說,請考慮使用以下 Command 聯集的 TypeScript 表示法:

enum CommandTag {
    Create,
    Release,
}

interface Command {
    tag: CommandTag,
    data: CreateResource | ReleaseResource,
}

Command 的標記為 Command.tag,類型為 CommandTag。每個 Command 變化版本的實際值和類型取決於實作方式。

請注意,部分語言不需要標記。例如,某些語言會使用模式比對來比對聯集變化版本的分支版本,而不會使用明確的標記值。

「ordinal」是線路鑑別器,即 FIDL 線型格式指出聯集變變化版本的值。您必須在 FIDL 定義中明確指定序數 (在這個範例中為 1 代表 create_resource,2 代表 release_resource)。

編碼

編碼是指將譯文語言的值序列化為 FIDL 傳輸格式的程序。

如為 C 繫結系列 (HLCPP、LLPP),編碼可讓編碼更具體地代表擷取與 FIDL 傳輸格式版面配置、修補指標及控點的位元組,方法是將控點替換為 FIDL_ALLOC_PRESENT/FIDL_ALLOC_ABSENTFIDL_HANDLE_PRESENT/FIDL_HANDLE_ABSENT,將控點移至頻外控點資料表中。

解碼

解碼是指將 FIDL 傳輸格式原始位元組的值還原為譯文語言值的程序。

如為 C 繫結系列 (HLCPP、LLPP),解碼可以更明確地擷取符合 FIDL 傳輸格式版面配置、修補指標與處理的位元組,方法是將 FIDL_ALLOC_PRESENT/FIDL_ALLOC_ABSENTFIDL_HANDLE_PRESENT/FIDL_HANDLE_ABSENT 替換為「實際」指標/控點值,進而移出頻外的資料表控點。

驗證

「驗證」是檢查對指定值是否滿足 FIDL 定義限制的程序。無論是在傳送前對值進行編碼,或在接收後對值進行解碼時,驗證都會執行。這類限制包括向量邊界、處理限制,以及字串的有效編碼為 UTF-8。

驗證失敗時,繫結會將錯誤直接傳回使用者程式碼,或透過錯誤回呼的方式顯示錯誤。

結果/錯誤類型

針對未指定錯誤類型的方法:

DoWork() -> (struct { result Data; }) error uint32

結果類型是指伺服器針對此方法接收的完整訊息,即由 Data 結果或 uint32 錯誤組成的聯集。在本例中,錯誤類型為 uint32,而 Data 則稱為回應類型或成功類型。