本文件定義在 FIDL 結構定義中具有特定意義的一般字詞。如要進一步瞭解特定 FIDL 主題,請參閱 FIDL 追蹤記錄。
類型、版面配置、限制
類型會在 FIDL 類型系統中將值分類。類型會顯示在 FIDL 文法中定義的 type-constructor
位置。舉例來說,uint32
、string:10
和 vector<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_1
到 L_n
是版面配置參數,而透過 C_n
傳遞的 C_1
則為限制條件。
成員、欄位、子類
宣告的「成員」是屬於宣告的個別元素,即宣告由零、一或多個成員組成。
例如,考慮 Mode
位元宣告:
type Mode = strict bits {
READ = 1;
WRITE = 2;
};
READ
和 WRITE
都是成員。
提及結構體或資料表的成員時,我們還可以特別將這些成員稱為「欄位」。
稱之為聯集的成員時,我們可以更明確地將這些成員稱為「變化版本」。
例如,考慮使用 Command
聯集宣告:
type Command = strict union {
1: create_resource CreateResource;
2: release_resource ReleaseResource;
};
兩個變數為 create_resource
和 release_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_ABSENT
或 FIDL_HANDLE_PRESENT
/FIDL_HANDLE_ABSENT
,將控點移至頻外控點資料表中。
解碼
解碼是指將 FIDL 傳輸格式原始位元組的值還原為譯文語言值的程序。
如為 C 繫結系列 (HLCPP、LLPP),解碼可以更明確地擷取符合 FIDL 傳輸格式版面配置、修補指標與處理的位元組,方法是將 FIDL_ALLOC_PRESENT
/FIDL_ALLOC_ABSENT
或 FIDL_HANDLE_PRESENT
/FIDL_HANDLE_ABSENT
替換為「實際」指標/控點值,進而移出頻外的資料表控點。
驗證
「驗證」是檢查對指定值是否滿足 FIDL 定義限制的程序。無論是在傳送前對值進行編碼,或在接收後對值進行解碼時,驗證都會執行。這類限制包括向量邊界、處理限制,以及字串的有效編碼為 UTF-8。
驗證失敗時,繫結會將錯誤直接傳回使用者程式碼,或透過錯誤回呼的方式顯示錯誤。
結果/錯誤類型
針對未指定錯誤類型的方法:
DoWork() -> (struct { result Data; }) error uint32
結果類型是指伺服器針對此方法接收的完整訊息,即由 Data
結果或 uint32
錯誤組成的聯集。在本例中,錯誤類型為 uint32
,而 Data
則稱為回應類型或成功類型。