如需進一步瞭解 FIDL 的整體用途、目標與需求， 請參閱概念總覽。

核心概念

訊息

FIDL 訊息是指一組資料。

訊息為連續結構，其中包含單一 內嵌主要物件，後面加上零或多個 離線次要物件。

物件以週遊順序儲存，並且受到邊框間距影響。

主要和次要物件

第一個物件稱為主要物件。 這是固定大小的結構，其類型和大小是從 相關資訊讀取郵件時，需要知道 要讀取的型別，即格式不是自述。背景介紹 進行讀取時應該不會造成混淆舉例來說 例如讀取屬於處理序間通訊 (IPC) 的郵件 (請參閱交易郵件標頭) 內容則完全由 標頭包含的資料所指定 特別是此序數讓接收者瞭解 預期的類型)。如果是讀取靜態資料，則不會 但系統會假設編碼器和解碼器都假設 知道要編碼或解碼的類型 (例如 這些資訊會編譯成 和解碼器構成

主要物件可能會參照次要物件 (例如 字串、向量、聯集等) (如果其他可變大小) 或選用資料

次要物件會以「非線形」順序儲存。

主要和次要物件都以 8 位元組對齊，而且都儲存 之間不會有間隙 (對齊時需符合)。

主要物件及其次要物件合稱為 訊息。

交易訊息

交易 FIDL 郵件 (交易郵件) 用於 在應用程式之間傳送資料

請參閱「交易郵件」一節的說明 交易郵件包含標頭訊息 (選擇性) 回應。

遍歷順序

訊息的週遊順序取決於遞迴深度 當中走路時取得的所有物件 參考。

假設結構如下：

type Cart = struct {
    items vector<Item>;
};

type Item = struct {
    product Product;
    quantity uint32;
};

type Product = struct {
    sku string;
    name string;
    description string:optional;
    price uint32;
};

Cart 訊息的深度優先遍歷順序定義如下 虛擬程式碼：

visit Cart:
    for each Item in Cart.items vector data:
        visit Item.product:
            visit Product.sku
            visit Product.name
            visit Product.description
            visit Product.price
        visit Item.quantity

雙格式：編碼與已解碼

相同的訊息內容可以使用以下兩種格式之一來呈現： 編碼和解碼。 這些項目的大小和整體版面配置相同，但兩者的 指標 (記憶體位址) 或控點 (功能) 的表示法。

FIDL 在設計上可讓訊息編碼及解碼 留在記憶體中

訊息編碼是標準網址， 指定訊息。

經過編碼的訊息

編碼訊息已準備好轉移至其他程序： 不含指標 (記憶體位址) 或控點 (功能)。

在編碼期間...

• 訊息內子物件的指標會替換為標記 指出引用者是否存在、
• 訊息中的所有控點都會擷取至相關聯的控制代碼 向量，並替換為標記來指出其參照來源 目前是否存在

接著，產生的編碼訊息和處理常式就能傳送至 另一個處理序，也就是使用 zx_channel_write() 或類似的處理序間通訊 (IPC) 以注意力機制為基礎 這類 IPC 還有其他限制。詳情請見 交易郵件。

已解碼的訊息

解碼的訊息已準備好在程序位址中使用 空格：可能包含指標 (記憶體位址) 或控點 (功能)。

解碼期間：

• 所有指向訊息內子物件的指標都會透過 編碼的存在與否標記。
• 訊息中的所有帳號代碼都會從 處理常式。

產生的已解碼訊息隨時可以從記憶體中使用。

內嵌物件

物件也可能包含內嵌物件，這些物件會在 包含物件的主體，例如內嵌結構體和 結構體

範例

在以下範例中，Region 結構包含 Rect 結構，而每個 Rect 都包含兩個 Point。 每個 Point 都包含一個 x 和 y 值。

type Region = struct {
    rects vector<Rect>;
};

type Rect = struct {
    top_left Point;
    bottom_right Point;
};

type Point = struct {
    x uint32;
    y uint32;
};

以遍歷順序檢視物件意味著我們從 Region 結構：這是主要物件。

rects 成員是 vector，因此其內容會儲存在離線中。 這表示 vector 內容緊接在 Region 物件之後。

每個 Rect 結構體都包含兩個 Point，分別儲存在內嵌中 (因為有固定數量)，而 Point 的 原始資料類型 (x 和 y) 也會「內嵌」儲存。 原因相同；有固定的成員類型數量

我們會使用內嵌儲存空間 物件都會固定，而「離線」則視為變數 (包括 盒子結構體)。

類型詳細資料

在本節中，我們將說明所有 FIDL 物件的編碼。

基本

• 以小端格式儲存的值。
• 具備自然對齊。
  • 每個 m 位元組基元都儲存在 m 位元組邊界上。
• 非選用。

支援下列原始類型：

號碼類型後面會用位元的大小。

布林值類型 bool 會以單一位元組的形式儲存，但只有 值 0 或 1。

所有浮點值代表有效的 IEEE 754 位元模式。

列舉和位元

位元欄位和列舉會儲存為基礎原始物件 類型 (例如uint32)。

帳號代碼

帳號代碼是 32 位元整數，但須以特殊方式處理。 編碼用於轉移時，系統會將控制代碼的線路表示法替換成 而處理常式將儲存在 和一個獨立的控點向量解碼時，處理存在指標是 替換成零 (如果沒有的話) 或有效的帳號代碼 (如有)。

控點 value 本身「不會」從應用程式轉移到 另一個例子。

為此，控點就像指標。會參考情境 每個應用程式都有專屬的 ID 帳號代碼會從一個應用程式的內容移至另一個應用程式的情境。

如果值為 0，可用來表示缺少選用帳號代碼¹。

請參閱帳號代碼生命週期，瞭解轉移帳號代碼的詳細範例 FIDL。

匯總物件

匯總物件可做為其他物件的容器使用。 視類型而定，他們可能會以內嵌或離線方式儲存資料。

陣列

• 固定同質元素的長度序列。
• 其元素的自然對齊方式。
  • 陣列的對齊方式與其元素的對齊方式相同。
  • 每個後續的元素都會對齊元素的對齊邊界。
• 陣列的步距與元素大小 ( 包含滿足元素對齊限制所需的邊框間距)。
• 絕不可選。
• 布林值陣列沒有特殊案例。每個布林值元素 像系統一樣

陣列會標示：

• array<T, N>：其中 T 可以是任何 FIDL 類型 (包括陣列) 和「N」是陣列中的元素數量。 注意：陣列的大小不得超過 2³²-1。 詳情請參閱 RFC-0059。

向量

• 同質元素的可變長度序列。
• 可以是選用項目；但不含向量和空向量
• 可指定大小上限，例如vector<T>:40 最多 40 個元素向量
• 儲存為 16 位元組記錄，包含：
  • size：64 位元無正負號元素數量 注意：向量大小不得超過 2³²-1。 詳情請參閱 RFC-0059。
  • data：64 位元存在狀態指標或指標指向外部元素資料
• 將資料移轉編碼時，data 代表 內容呈現方式：
  • 0：缺少向量
  • UINTPTR_MAX：具有向量，資料是下一個外線物件
• 解碼供耗用時，data 是 內容指標：
  • 0：缺少向量
  • <valid pointer>：具有向量，資料位於指定的記憶體位址
• 布林值向量並沒有特殊案例。每個布林值元素 像系統一樣

向量的表示方式如下：

• vector<T>：元素類型為「T」的必要向量 (驗證錯誤) 會在缺少 data 時觸發)
• vector<T>:optional：可選用的元素向量為「T」
• vector<T>:N、vector<T>:<N, optional>：長度上限為 N 個元素的向量

T 可以是任何 FIDL 類型。

字串

字串會以 uint8 個位元組的向量形式實作，但設有限制 位元組必須是有效的 UTF-8。

建築作品

結構包含一系列型別的欄位。

在內部，結構設有填充，確保所有成員對齊 所有成員都必須符合相同的要求 在外部，結構在 8 位元組邊界對齊，因此可能有 以滿足這項需求

以下是幾個例子。

包含 int32 和 int8 欄位的結構體具有 4 個位元組的對齊方式 (因為 int32)，並且大小為 8 個位元組 (int8 之後的填充 3 個位元組)：

包含 bool 和 string 欄位的結構體具有 8 個位元組的對齊方式 (因為 string) 與 24 個位元組的大小 (在 bool)：

一個結構體包含 bool 和兩個 uint8 欄位，其對齊方式為 1 位元組 以及 3 個位元組 (沒有填充字元！)：

結構可以是：

• 空白 — 不含任何欄位。此結構大小為 1 個位元組 且等同於包含 uint8 的值為 0。
• 必要 — 系統會將結構的內容儲存為內嵌項目。
• 選用 — 結構的內容會儲存在非線上， 並透過間接參照存取。

結構的儲存空間儲存方式取決於它是否在參考點上裝箱。

• 非盒狀結構：
  • 儲存於內嵌內容的類型中， 有效匯總結構
  • 內嵌式結構時，結構版面配置不會改變；其欄位則不是 以填補其容器中的缺口
• 盒裝結構：
  • 內容是離線儲存，並透過間接存取 參照。
  • 編碼用於移轉時，已儲存的參照會指出 結構：
  • 0：缺少參考資料
  • UINTPTR_MAX：已參照，正在結構內容 是下一個虛線物件
  • 解碼供使用時，已儲存的參照是一個指標：
  • 0：缺少參考資料
  • <valid pointer>：已參照，結構內容位於 指定的回憶集錦位址

結構體會以宣告的名稱 (例如 Circle) 表示，且可以裝箱：

• Point：必要 Point
• box<Color>：盒裝，一律選用 Color

以下範例會說明：

• 結構版面配置 (排序、封裝和對齊)
• 必要結構 (Point)
• 盒裝 (Color)

type Circle = struct {
    filled bool;
    center CirclePoint; // CirclePoint will be stored in-line
    radius float32;
    color box<Color>; // Color will be stored out-of-line
    dashed bool;
};

type CirclePoint = struct {
    x float32;
    y float32;
};

type Color = struct {
    r float32;
    g float32;
    b float32;
};

Color 內容會填充至 8 位元組次要物件對齊邊界。 詳細檢視版面配置：

1. 第一位成員 (filled bool) 佔用了 1 個位元組，但需要三個位元組 邊框間距的原因是下一個成員具有 4 位元組對齊 才能正常運作
2. center CirclePoint 成員是必要結構的範例。因此 其內容 (x 和 y 32 位元浮點值) 都加入內嵌元素，而整個物件 會耗用 8 個位元組
3. radius 是 32 位元的項目，必須對齊 4 位元組。自下一個 可用位置已位於 4 位元組對齊邊界上，無填充 必填。
4. color box<Color> 成員是盒裝結構的範例。由於 color 資料不一定會顯示，這是最有效率的處理方式 是要將結構指標當做內嵌資料。如此一來 如果 color 成員確實存在，則指標會指向其資料 (如果是編碼格式，則表示「存在」)，而 資料本身是離線儲存 (Circle 的資料之後) 結構)。如果 color 成員不存在，則指標為 NULL (或者，如果編碼格式，則會儲存 0，藉此表示「不存在」。
5. dashed bool 不需要任何特殊對齊，因此接下來就會採用。 現在，我們已抵達物件的結尾處，所有物件都必須 對齊 8 位元組。也就是說，我們需要額外的 7 位元組填充。
6. color 的外線資料遵循 Circle 資料結構，以及 包含三個 32 位元 float 值 (r、g 和 b)；他們需要 位元組對齊，因此可以彼此跟隨，無需填充。但就像 若是 Circle 物件，我們要求物件本身 對齊 8 位元組，因此需要 4 個位元組的邊框間距。

整體而言，這個結構需要 48 個位元組。

然而，將 dashed bool 移至 filled bool 之後， 有大幅節省空間²：

1. 兩個 bool 值「已封裝」組成鍵/值 不僅浪費空間，
2. 邊框間距減少為 2 個位元組，這適用於 新增 16 位元值，或更多 bool 或 8 位元整數。
3. 請注意，Color 方塊之後不需要邊框間距。全部 與 8 位元組邊界的對齊設定完全對齊

結構現在包含 40 個位元組。

信封

信封是資料的容器，供資料表和聯集在內部使用。是 沒有公開的 FIDL 語言。採用固定的 8 位元組格式。

只要是 0 的信封標頭，就稱為「零信封」。這項服務 代表缺少信封。如果沒有，則顯示信封 旗標的位元 0 指出資料是以內嵌方式儲存，還是離線儲存：

• 如果設定了位元 0，則會使用內嵌表示法。

• 如果未設定位元 0，則會使用非線形表示法。

只有當酬載大小小於 4 位元組時，才能設定 Bit 0。位元 0 可以是 除非信封為零或 酬載是 >4 個位元組。

如果有 num_bytes 和 num_handles，我們就能略過不明的信封內容。

num_bytes 一律會是 8 的倍數，因為非線物件 對齊 8 位元組。

表格

• 由元素數量和指標組成的記錄類型。
• 指標指向一個信封陣列，每個信封陣列包含一個元素。
• 每個元素都與一個序數相關聯。
• 序數是依序排列，缺口會產生空白的信封成本，因此不建議使用。

資料表會以宣告的名稱 (例如Value)，而且不一定是選用項目：

• Value：必要 Value

以下範例顯示如何根據欄位配置表格。

type Value = table {
    1: command int16;
    2: data Circle;
    3: offset float64;
};

聯合工會

• 包含序數和信封的記錄類型。
• 序數表示成員選取，以 uint64 表示。
• 每個元素都會與使用者指定的序數建立關聯。
• 序數依序排列。與桌子不同的是，泛型之間的落差不會產生線路 格式空間費用。
• 缺少的選用聯集會以 0 序數和零信封表示。
• 不允許空白的聯集。

聯集會以宣告的名稱 (例如 Value) 表示，並視需要表示：

• Value：必要 Value
• Value:optional：選用 Value

以下範例顯示如何根據欄位配置聯集。

type UnionValue = strict union {
    1: command int16;
    2: data Circle;
    3: offset float64;
};

交易訊息

交易郵件中一律設有「標頭」，後面會緊接 選擇性的內文。

標頭和內文皆為 FIDL 訊息 (如上文所定義)；也就是 資料集合。

標頭的格式如下：

• zx_txid_t txid，交易 ID (32 位元)
  • 具有高位元設定的 txid 會保留供以下使用： zx_channel_call()
  • 具有高位元設定的 txid 會保留供使用者空間使用
  • txid 的值將保留給非此訊息的 0 則需要另一端回應 注意：如要進一步瞭解 txid 分配作業，請參閱 zx_channel_call().
• uint8[3] flags，「不得」由繫結檢查。您可以運用這些旗標 啟用線路格式的柔轉換效果。請參閱標頭旗標 ，瞭解目前標記定義。
• uint8 magic number：判斷兩種線路格式是否相容。
• uint64 ordinal
  • 零序數無效。
  • 位元組合最顯著的序數為保留 控制訊息和未來擴展
  • 缺少最顯著位元集的序數表示方法呼叫 和回應

交易郵件有三種類型：

• 方法要求時
• 方法回應
• 事件要求。

在接下來的幾個範例中，我們會使用下列介面：

type DivisionError = strict enum : uint32 {
    DIVIDE_BY_ZERO = 1;
};

protocol Calculator {
    Add(struct {
        a int32;
        b int32;
    }) -> (struct {
        sum int32;
    });
    Divide(struct {
        dividend int32;
        divisor int32;
    }) -> (struct {
        quotient int32;
        remainder int32;
    }) error DivisionError;
    Clear();
    -> OnError(struct {
        status_code uint32;
    });
};

Add() 和 Divide() 方法會說明這兩種方法要求 (從用戶端傳送至伺服器)，以及方法回應 (從伺服器傳回至用戶端)。

Clear() 方法是不會 因此可能有主體

不正確的例子是「空白」意味著 標頭後方有一個內文。以 Clear() 為例， 如果結果沒有 body，則只有一個 header。

方法要求訊息

介面的用戶端會將方法要求訊息傳送至伺服器 即可叫用方法

方法回應訊息

伺服器傳送方法回應訊息給用戶端，表示完成 方法，並提供 (可能為空白) 的結果。

只有已定義為提供結果 (可能為空白) 的雙向方法要求 都會產生方法回應。 單向方法要求不得產生方法回應。

方法回應訊息會提供與先前方法要求相關聯的結果。 訊息的內文包含方法結果，就像將這些結果包裝在 struct。

我們看到 912 / 43 的答案是 21，其餘 9 則。 請留意 txid 的值 1，這會識別交易。 2 的 ordinal 值代表方法。在這個範例中， Divide() 方法。

在下方，我們可以看到 123 + 456 為 579。 此處的 txid 值現在是 2，這只是下一筆交易 指派給交易的號碼。 ordinal 為 1，表示 Add()。請注意，結果需要 4 位元組的邊框間距，讓 body 物件的大小 是 8 位元組的倍數

最後，Clear() 方法和 Add() 不同， Divide() 有兩種重要方式： * 沒有 body (也就是說，不含任何 header) * 不會要求介面回應 (txid 為零)。

活動要求

事件範例就是 Calculator 中的 OnError() 事件。

伺服器向用戶端傳送來路不明的事件要求 表示發生非同步事件 通訊協定宣告

在 Calculator 範例中，我們可以想像，嘗試除以零 會導致在傳送 OnError() 事件時，系統傳送「除以 0」狀態碼 才會關閉連線這可讓用戶端區分 等待連線因錯誤而關閉 (例如計算程序異常終止)。

請注意，txid 是零 (表示這不屬於交易的一部分)， 且 ordinal 為 4 (表示 OnError() 方法)。

body 包含事件引數，就像包裝在 struct，就像方法結果訊息一樣。 請注意，主體會經過填充，維持 8 位元組對齊。

Epitaph (控制訊息序數 0xFFFFFFFFFFFFFFFF)

八位元是序數為 0xFFFFFFFFFFFFFFFFFF 的事件 (txid 0)。伺服器 可能會在關閉連線前傳送最終訊息， 會說明連線關閉的原因。沒有其他訊息了 才能傳送出去。Epitaph 字串並非傳送來源 用戶端之間的連線

八爪族的電匯方式相當於這個 FIDL： fidl struct { error zx.Status; }; 日後可能會在 FIDL 中正式定義。

詳細資料

大小和對齊方式

sizeof(T) 表示 T 類型物件的大小 (以位元組為單位)。

alignof(T) 表示對齊係數 (以位元組為單位) 來儲存類型為 T 的物件。

FIDL 原始類型會儲存在訊息中的偏移位置 以位元組為單位因此，如果是原始物件 T，alignof(T) == sizeof(T)。這就是所謂的「自然對齊」。這個元件具有 符合現代 CPU 一般對齊要求的絕佳屬性 架構

struct 和陣列等 FIDL 複雜型別會儲存在 是所有其所有內容最大對齊係數的倍數 只要使用來自這些領域的 小型資料集訓練即可因此，對複雜類型 T 而言，T 中所有欄位 F 皆是 alignof(T) == max(alignof(F:T))。和 可滿足一般 C 結構封裝需求的屬性 (例如 對產生的程式碼中套用封裝屬性強制執行)。複雜程度的大小 type 是正確對齊成員元素所需的位元組總數 以及邊框間距與類型對齊係數之間的邊框間距

FIDL 主要和次要物件會對齊 無論其內容為何FIDL 訊息的主要物件 始於位移 0次要物件，也就是 訊息中的指標，一律從位移開始到 8 的倍數。 (因此訊息點中的所有指標在偏移位置為 8 的倍數)。

FIDL 內嵌物件 (內嵌在主要或次要中的複雜類型) 物件) 會根據其類型對齊。不會強制採用 8 個位元組 對齊。

類型

注意：

• N 代表元素數量 (無論明確表示是否提供，如 array<T, N> (具有 N 類型的 N 元素的陣列) 或隱含的陣列 (由 7 個元素的 table 會包含 N=7)。
• 外行大小一律會填補至 8 個位元組。我們會指明內容 但不含邊框間距。
• 下列 vector 項目中的「sizeof(T)」是
  in_line_sizeof(T) + out_of_line_sizeof(T)。
• 以下 table 項目中的 M 是目前欄位的序數上限。
• 在下方的 struct 項目中，邊框間距是指為 讓 struct 對齊最寬的元素。例如： struct{uint32;uint8} 的邊框間距為 3 個位元組，與 邊框間距，對齊 8 位元組界線。

上述 handle 項目是指帳號代碼的所有變種版本，特別是 handle、handle:optional、handle:H、handle:<H, optional>、 client_end:Protocol、client_end:<Protocol, optional>、 server_end:Protocol和server_end:<Protocol, optional>。

同樣地，上述 vector 項目是指向量的所有變種版本 特別是 vector<T>、vector<T>:optional、vector<T>:N。 vector<T>:<N, optional>、string、string:optional、string:N和 string:<N, optional>。

邊框間距

訊息的創作者必須在所有對齊的邊框間距空隙中加上零。

訊息的取用者必須驗證邊框間距是否包含零 (並產生 傳回錯誤)。

最高遞迴深度

您可以利用 FIDL 向量、選擇性結構、表格和聯集來建構 遞迴訊息。如果沒有勾選，系統處理過多深度訊息時 會導致資源耗盡，或是未偵測到的無限迴圈。

基於安全考量，所有 FIDL 郵件的最大遞迴深度設有限制： 32 個間接等級。FIDL 編碼器、解碼器或驗證工具「必須」 系統會持續追蹤當前週期深度，藉此強制執行這項限制 訊息驗證

遞迴深度的正式定義：

• FIDL 訊息的內嵌物件已定義為遞迴深度 0。
• 每個間接行經經由指標或信封時週遊 將週期性深度設為 1。

在任何情況下，只要遞迴深度超過 32，作業就必須 並引發錯誤

例如：

type InlineObject = struct {
    content_a string;
    vector vector<OutOfLineStructAtLevel1>;
    table TableInlineAtLevel0;
};

type OutOfLineStructAtLevel1 = struct {
    content_b string;
};

type TableInlineAtLevel0 = table {
    1: content_c string;
};

對 InlineObject 的例項編碼時，系統會有各自的遞迴深度：

• content_a 的位元組屬於 1 的週期深度，即 content_a 字串標頭內嵌在 InlineObject 結構中，而位元組位於 可透過指標間接存取的離線物件。
• content_b 的位元組呈現 2 的遞迴深度，即 vector 將標頭內嵌到 InlineObject 結構中， OutOfLineStructAtLevel1 結構體因此呈遞迴深度 1， content_b 字串標頭內嵌於 OutOfLineStructAtLevel1 內，而 位元組是屬於離線物件，可透過指標間接存取 從深度 1 跳到深度 2
• content_c 的位元組呈現 3 的遞迴深度，即 table 標頭內嵌在 InlineObject 結構中，資料表信封位於 深度 1，指向深度為 2 的 content_c 字串標頭， 位元組是屬於離線物件，可透過指標間接存取 進入深度 3 的架構

驗證

訊息驗證的目的是提早找出線路格式錯誤。 就可能會引發安全性或穩定性問題

當系統將來自同業的訊息解碼時，必須進行訊息驗證 以防止錯誤資料在服務進入點之外傳播。

當系統將訊息編碼為 時，建議使用訊息驗證 傳送到對等節點，協助本地化違反的完整性限制。

為了盡可能減輕執行階段負擔，驗證通常應在執行驗證時 單一傳遞訊息編碼或解碼程序，因此只會處理 需要周遊由於訊息是依據深度週遊順序編碼， 穿越時空的記憶區域良好，因此效率很高。

如果是簡單的訊息，驗證可能較為繁瑣，且數量最多不超過 進行幾項大小檢查雖然我們鼓勵程式設計師採用 FIDL 繫結 程式庫驗證訊息，也可進行驗證 手動調整。

符合規定的 FIDL 繫結必須檢查以下所有完整性限制：

• 訊息的總大小 (包括其所有非行子物件) 等於包含該緩衝區的緩衝區總大小。所有語言 子物件。
• 訊息參照的帳號代碼總數等於 也就是帳號代碼資料表的總大小所有帳號代碼皆會計入。
• 不會超過複雜物件的最大遞迴深度。
• 所有列舉值都落在定義的範圍內。
• 所有聯集標記值都會落在定義的範圍內。
• 僅限編碼：
  • 遍歷執行期間發生的所有子物件指標可準確參照 移至要顯示子物件的下一個緩衝區位置。阿斯 會指向緩衝區外的位置。
• 僅解碼：
  • 所參照子物件的所有存在和未顯示的標記，都會保留 值僅限 0 或 UINTPTR_MAX。
  • 所參照標記中所有存在和未顯示的標記都會保留值 僅限 0 或 UINT32_MAX。

標頭旗標

Flags[0]

Flags[1]

Flags[2]