本文件列出 FIDL 編譯器 fidlc 產生的所有錯誤。這個網域中的錯誤 ID 一律會以前置字串 fi- 開頭，後面加上四位數代碼，例如 fi-0123。
fi-0001：無效字元
Lexer 無法將字元轉換為指定位置的權杖。
library test.bad.fi0001;
type ßar = struct {
value uint64;
};
請使用替換或移除字元來修正無效字元。
library test.good.fi0001;
type Foo = struct {
value uint64;
};
無效字元因位置而異。請參閱 FIDL 語言規格，以判斷 FIDL 語法每個部分可使用的字元。
fi-0002：意外換行
字串常值無法分割成多行：
library test.bad.fi0002;
const BAD_STRING string:1 = "Hello
World";
請改用逸出順序 \n 來表示換行符號：
library test.good.fi0002;
const GOOD_STRING string:11 = "Hello\nWorld";
fi-0003：逸出序列無效
lexer 在逸出序列開頭出現無效字元。
library test.bad.fi0003;
const UNESCAPED_BACKSLASH string:2 = "\ ";
const BACKSLASH_TYPO string:1 = "\i";
const CODE_POINT_TYPO string:1 = "\Y1F604";
將有效的字元替換成逸出序列開頭，或移除非預期的反斜線字元。
library test.good.fi0003;
const ESCAPED_BACKSLASH string:2 = "\\ ";
const REMOVED_BACKSLASH string:1 = "i";
const SMALL_CODE_POINT string:3 = "\u{2604}";
const BIG_CODE_POINT string:4 = "\u{01F604}";
如要瞭解有效的逸出序列，請參閱 FIDL 文法規格。
fi-0004：無效的 16 進位數字
字串文字中的萬國碼 (Unicode) 逸出不得包含無效的十六進位數字：
library test.bad.fi0004;
const SMILE string = "\u{1G600}";
您必須以十六進位的十六進位值指定有效的 Unicode 碼點，範圍介於 0 至 10FFFF。每個十六進位數字都必須是 0 到 9 之間的數字、從 a 到 f 的小寫字母，或從 A 到 F 的大寫字母。在本例中，G 是 F 的錯字：
library test.good.fi0004;
const SMILE string = "\u{1F600}";
fi-0005
fi-0006：預期宣告
當 FIDL 預期有宣告並找到其他東西時，就會發生這個錯誤。這通常是拼寫錯誤所致。有效的宣告為：type、alias、const、using、protocol 和 service。
library test.bad.fi0006;
cosnt SPELLED_CONST_WRONG string:2 = ":("; // Expected a declaraction (such as const).
如要修正這個錯誤，請檢查頂層宣告中的錯字，並確保您使用的是 FIDL 支援的功能。
library test.good.fi0006;
const SPELLED_CONST_RIGHT string:2 = ":)";
fi-0007：意外權杖
剖析期間發生非預期的權杖時，就會發生這個錯誤。一般來說，這可能是錯字：
library test.bad.fi0007;
alias MyType = vector<uint8>:<,256,optional>; // Extra leading comma
解決這個問題的做法是移除非預期的權杖；在某些情況下，請提供其他缺少的語法：
library test.good.fi0007;
alias MyType = vector<uint8>:<256, optional>;
fi-0008：意外權杖
FIDL 剖析器遇到文法無效的權杖時，就會發生這個錯誤。這種情況可能有很多種，例如列舉成員缺少 =、額外權杖 (例如 library = what.is.that.equals.doing.there) 等等。
library test.bad.unexpectedtokenofkind;
type Numbers = flexible enum {
ONE; // FIDL enums don't have a default value.
};
一般來說，如要修正這個問題，請新增缺少的權杖，或是移除額外權杖。
library test.good.fi0008;
type Numbers = flexible enum {
ONE = 1;
};
如要避免這個錯誤，請一次對 *.fidl 檔案執行一次，確認其文法是否正確。
fi-0009：未預期的 ID
之所以發生這個錯誤，通常是因為 ID 使用了不正確的位置：
using test.bad.fi0009;
請改用正確的 ID：
library test.good.fi0009;
fi-0010：ID 無效
找到的 ID 不符合有效 ID 的要求。FIDL ID 可包含英數字元和底線 (尤其是 A-Z、a-z、0-9 和 _)，且每個 ID 的開頭必須是英文字母，結尾則須為英文字母或數字。
library test.bad.fi0010a;
// Foo_ is not a valid identifier because it ends with '_'.
type Foo_ = struct {
value uint64;
};
如要修正這個問題，請變更 ID，確保其只包含有效的字元，開頭須為英文字母，結尾則須為英文字母或數字。
library test.good.fi0010a;
type Foo = struct {
value uint64;
};
如果多部分 (點號) ID 傳遞至屬性，也可能會發生這個錯誤。
library test.bad.fi0010b;
@foo(bar.baz="Bar", zork="Zoom")
type Empty = struct{};
如要修正這個問題，請變更屬性中僅使用單一部分 ID。
library test.good.fi0010b;
@foo(bar="Bar", zork="Zoom")
type Empty = struct {};
fi-0011：無效的圖書館名稱元件
程式庫名稱只能包含英文字母和數字 (A-Z、a-z 和 0-9)，且開頭必須是英文字母。
library test.bad.fi0011.name_with_underscores;
如要修正這個問題，請確認所有程式庫名稱元件都符合要求。
library test.good.fi0011.namewithoutunderscores;
fi-0012：類型的版面配置類別無效
類型宣告必須指定已知的 FIDL 版面配置：
library test.bad.fi00012;
type Foo = invalid {};
有效的版面配置為 bits、enum、struct、table 和 union：
library test.good.fi0012;
type Empty = struct {};
「版面配置」是 FIDL 類型的可參數說明。參照是一系列可接收的引數，用於指定形狀。舉例來說，struct 是一種版面配置，當其定義了特定成員時就會成為具體類型，而 array 則是在某個類型依指定次數依序重複重複時，就會變成具體的版面配置。
版面配置皆內建於 FIDL 語言中，使用者無法自行指定版面配置或建立自己的一般類型範本。
fi-0013：包裝類型無效
如果傳遞至列舉或位元宣告的值不是類型 ID (例如當您改為提供字串值做為「支援類型」時)，就會發生這個錯誤：
library test.bad.fi0013;
type TypeDecl = enum : "int32" {
FOO = 1;
BAR = 2;
};
如要修正這個錯誤，請確認列舉或位元的備份類型為類型 ID。
library test.good.fi0013;
type TypeDecl = enum : int32 {
FOO = 1;
BAR = 2;
};
fi-0014：包含空白括號的屬性
如果屬性含有括號但不含引數，就會發生這個錯誤。
library test.bad.fi0014;
@discoverable()
protocol MyProtocol {};
如要修正問題，請從沒有引數的屬性中移除括號；如果原本是要引數，請提供引數。
library test.good.fi0014;
@discoverable
protocol MyProtocol {};
FIDL 不允許屬性中的空白引數清單主要做為風格選項。
fi-0015：屬性引數必須全部命名為
為求明確，當屬性有多個引數時，您必須明確命名所有屬性的引數。
如果屬性有多個引數，但並未明確提供引數名稱，就會發生這項錯誤。
library test.bad.fi0015;
@foo("abc", "def")
type MyStruct = struct {};
如要修正問題，請使用 name=value 語法提供所有引數的名稱。
library test.good.fi0015;
@foo(bar="abc", baz="def")
type MyStruct = struct {};
fi-0016：成員前遺漏序數
當聯集或資料表中的欄位缺少序數時，就會發生這項錯誤。
library test.bad.fi0016a;
type Foo = table {
x int64;
};
library test.bad.fi0016b;
type Bar = union {
foo int64;
bar vector<uint32>:10;
};
如要修正這個問題，請明確指定資料表或聯集的序數：
library test.good.fi0016;
type Foo = table {
1: x int64;
};
type Bar = union {
1: foo int64;
2: bar vector<uint32>:10;
};
與結構體不同，資料表和聯集的設計目的在於允許回溯相容的內容變更。為了實現這一點，您需使用一致的值 (序數) 來識別資料表欄位或聯集變化版本。為避免混淆並避免在變更資料表或聯集時不小心更改序數，您必須明確指定序數。
fi-0017：序數超出範圍
資料表和聯集的序數必須是有效的未帶正負號 32 位元整數。如果負序或序數大於 4,294,967,295，就會發生這個錯誤。
library test.bad.fi0017a;
type Foo = table {
-1: foo string;
};
library test.bad.fi0017b;
type Bar = union {
-1: foo string;
};
如要修正這個問題，請確認所有序數都在允許的範圍內。
library test.good.fi0017;
type Foo = table {
1: foo string;
};
type Bar = union {
1: foo string;
};
fi-0018：序數必須從 1 開始
table 和 union 成員序數值不得為 0：
library test.bad.fi0018;
type Foo = strict union {
0: foo uint32;
1: bar uint64;
};
相反地，編號應從 1 開始：
library test.good.fi0018;
type Foo = strict union {
1: foo uint32;
2: bar uint64;
};
fi-0019：嚴格位元、列舉或聯集不得留空
嚴格位元、列舉或聯集不得包含零個成員：
library test.bad.fi0019;
type Numbers = strict enum {};
而至少要有一位成員：
library test.good.fi0019a;
type Numbers = flexible enum {};
此外，您也可以將宣告項目標示為 flexible，而不是 strict：
library test.good.fi0019b;
type Numbers = strict enum {
ONE = 1;
};
空白位元、列舉或聯集沒有任何資訊，因此通常不應在 API 中使用。不過，彈性資料類型是專為演變而設計，因此定義一個彈性位元或列舉，且一開始會留空，預期之後就會新增成員。定義新的資料類型時，請務必審慎考慮要使用 strict 還是 flexible。
fi-0020：通訊協定成員無效
如果通訊協定中的項目無法識別為有效的通訊協定成員 (例如通訊協定中的項目並非通訊協定組合、單向方法、雙向方法或事件)，就會發生這個錯誤。
library test.bad.fi0020;
protocol Example {
NotAMethodOrCompose;
};
如要修正這個錯誤，請移除無效項目，或將其轉換為所需通訊協定項目類型的正確語法。
library test.good.fi0020;
protocol Example {
AMethod();
};
fi-0021
fi-0022：無法將屬性附加至 ID
如果某個屬性是 ID 類型，卻放置在宣告的類型中，就會發生這個錯誤。例如，將屬性放在欄位名稱後方，但在結構宣告中的欄位類型之前，會將屬性與欄位類型建立關聯，而非欄位本身。如果欄位類型是依名稱參照的現有類型，則無法套用其他屬性。
library test.bad.fi0022;
type Foo = struct {
// uint32 is an existing type, extra attributes cannot be added to it just
// for this field.
data @foo uint32;
};
如果意圖是將屬性套用至欄位，則應在欄位名稱前面移動該屬性。
屬性可套用至宣告的類型。這表示如果結構欄位的類型或其他類似宣告是匿名類型，而非 ID 類型，就可以對該類型套用屬性。
library test.good.fi0022;
type Foo = struct {
// The foo attribute is associated with the data1 field, not the uint32
// type.
@foo
data1 uint32;
// The type of data2 is a newly declared anonymous structure, so that new
// type can have an attribute applied to it.
data2 @foo struct {};
};
fi-0023：備援屬性放置位置
套用至已命名類型的宣告的屬性會套用至產生的類型，與直接套用至該類型版面配置的屬性相同。
這個錯誤會發生在類型宣告和宣告的版面配置中。
library test.bad.fi0023;
@foo
type Foo = @bar struct {};
如要修正這個錯誤，請將所有屬性移至類型宣告，或將所有屬性移至版面配置。
library test.good.fi0023;
@foo
@bar
type Foo = struct {};
type Bar = @foo @bar struct {};
FIDL 包含這項錯誤，以避免因為單一類型的宣告和版面配置中包含屬性而產生混淆。
fi-0024：方法參數清單的文件註解
方法參數清單不得包含文件註解：
library test.bad.fi0024;
protocol Example {
Method(/// This is a one-way method.
struct {
b bool;
});
};
針對 time，請在方法本身中加入文件註解：
library test.good.fi0024;
protocol Example {
/// This is a one-way method.
Method(struct {
b bool;
});
};
解決這個錯誤之後，這個錯誤就不會再發生。遷移的訴訟保留錯誤，目的是說明使用 FIDL 類型 (而非參數清單) 的方法酬載。
fi-0025：匯入群組必須位於檔案頂端
除了檔案頂端的 library 宣告以外，在檔案的 using 匯入之前，沒有任何其他宣告存在：
library test.bad.fi0025;
alias i16 = int16;
using dependent;
type UsesDependent = struct {
field dependent.Something;
};
如要解決這個錯誤，請將所有 using 匯入項目直接放入 library 宣告之後的區塊中：
library test.good.fi0025;
using dependent;
alias i16 = int16;
type UsesDependent = struct {
field dependent.Something;
};
這項規則主要反映了 FIDL 團隊的美學決策，當依附元件獲得妥善分組且容易找到時，比較容易閱讀。
fi-0026：在文件註解區塊中加註
註解不應置於文件註解區塊內：
library test.bad.fi0026;
/// start
// middle
/// end
type Empty = struct {};
改將註解置於文件註解區塊之前或之後：
library test.good.fi0026;
// some comments above,
// maybe about the doc comment
/// A
/// multiline
/// comment!
// another comment, maybe about the struct
type Empty = struct {};
一般來說，緊接在文件註解區塊之前的註解是文件註解本身加註的最佳位置。
fi-0027：文件註解區塊中有空白行
文件註解區塊中不應有空白行：
library test.bad.fi0027;
/// start
/// end
type Empty = struct {};
而是應該只在文件註解區塊之前或之後放置空白行：
library test.good.fi0027a;
/// A doc comment
type Empty = struct {};
您也可以考慮完全省略空白行：
library test.good.fi0027b;
/// A doc comment
type Empty = struct {};
fi-0028：文件註解後面必須宣告宣告
文件註解不得遭到自由浮動，例如一般註解：
library test.bad.fi0028;
type Empty = struct {};
/// bad
在任何情況下，文件註解都必須在 FIDL 宣告前面：
library test.good.fi0028a;
/// A doc comment
type Empty = struct {};
在編譯期間，FIDL 會「降低」文件對 @doc 屬性的註解。事實上，任何時候都能以這種方式直接撰寫註解，方法如下：
library test.good.fi0028b;
@doc("An attribute doc comment")
type Empty = struct {};
就技術層面而言，獨立文件註解是不可編譯的，但語意上也容易混淆：何謂「文件」是什麼意思？與一般註解不同，系統會將文件註解處理成結構化說明文件，因此必須清楚瞭解這些註解所附加的 FIDL 結構。
fi-0029：資源定義必須至少有一項屬性
禁止沒有指定屬性的資源定義：
library test.bad.resourcedefinitionnoproperties;
resource_definition SomeResource : uint32 {
properties {};
};
請指定至少一個資源：
library test.good.fi0029;
resource_definition SomeResource : uint32 {
properties {
subtype strict enum : uint32 {
NONE = 0;
};
};
};
這是與 FIDL 內部實作相關的錯誤，因此應該只會向使用 FIDL 核心程式庫的開發人員顯示。使用者應該永遠不會看到這個錯誤。
所參照的 resource_definition 宣告是 FIDL 的內部方式，用於定義處理等資源，且日後可能會隨著處理一般化作業的一部分改變。
fi-0030：無效的修飾符
每個 FIDL 修飾符都有一組可用的宣告，禁止在禁止的宣告中使用修飾符：
library test.bad.fi0030;
type MyStruct = strict struct {
i int32;
};
最佳做法是移除違規的修飾符：
library test.good.fi0030;
type MyStruct = struct {
i int32;
};
fi-0031：只有位元和列舉可以有子類型
並非所有 FIDL 版面配置都附有子類型：
library test.bad.fi0031;
type Foo = flexible union : uint32 {};
只有 bits 和 enum 版面配置才會在基礎類型上定義。
library test.good.fi0031;
type Foo = flexible enum : uint32 {};
bits 和 enum 版面配置很特別，因為其只是 FIDL 基元受限的有限子類型。因此，開發人員應指定做為這個子類型的基礎類型。相反地，struct、table 和 union 版面配置可以任意大型，且可能包含許多成員，因此全域版面配置的子類型並不合理。
fi-0032：不允許重複的修飾符
請勿在單一宣告中指定相同的修飾符：
library test.bad.fi0032;
type MyUnion = strict resource strict union {
1: foo bool;
};
移除重複的修飾符：
library test.good.fi0032;
type MyUnion = resource strict union {
1: foo bool;
};
fi-0033：衝突的修飾符
某些修飾符彼此互斥，無法同時修改相同的宣告：
library test.bad.conflictingmodifiers;
type StrictFlexibleFoo = strict flexible union {
1: b bool;
};
type FlexibleStrictBar = flexible strict union {
1: b bool;
};
一次只能將一個 strict 或 flexible 修飾符用於一項宣告：
library test.good.fi0033;
type FlexibleFoo = flexible union {
1: i int32;
};
type StrictBar = strict union {
1: i int32;
};
目前，只有 strict 和 flexible 修飾符無法以這種方式互斥。resource 修飾符沒有相互修飾詞，因此沒有套用此類限制。
fi-0034：名稱衝突
兩個宣告名稱不得相同：
library test.bad.fi0034;
const COLOR string = "red";
const COLOR string = "blue";
而是為每個宣告提供不重複的名稱：
library test.good.fi0034b;
const COLOR string = "red";
const OTHER_COLOR string = "blue";
您也可以移除不小心加入的聲明：
library test.good.fi0034a;
const COLOR string = "red";
如要進一步瞭解如何選擇名稱，請參閱 FIDL 樣式指南。
fi-0035：正規名稱衝突
兩個宣告無法使用相同的標準名稱：
library test.bad.fi0035;
const COLOR string = "red";
protocol Color {};
雖然 COLOR 和 Color 看起來不同，但都是以「標準」名稱 color 表示。您可將原始名稱轉換為 snake_case，以取得正規名稱。
如要修正錯誤，請為每個宣告提供在標準化後不重複的名稱：
library test.good.fi0035;
const COLOR string = "red";
protocol ColorMixer {};
遵循 FIDL 樣式指南的命名規範可盡量降低發生此錯誤的機率。使用相同的大小寫樣式宣告之間絕不會發生標準名稱衝突，而且因為其他需求而不同樣式的宣告之間很少發生標準名稱衝突 (例如通訊協定名稱通常應該是結尾為 -er 的名詞片語)。
FIDL 會強制執行這項規則，因為繫結產生器會將名稱轉換為目標語言的慣用命名樣式。藉由確保專屬標準名稱，我們保證繫結可在不產生名稱衝突的情況下執行此操作。詳情請參閱「RFC-0040：ID 不重複性」。
fi-0036：名稱重疊
具有相同名稱的宣告不得有重疊的供應情形：
@available(added=1)
library test.bad.fi0036;
type Color = strict enum {
RED = 1;
};
@available(added=2)
type Color = flexible enum {
RED = 1;
};
請改用 @available 屬性，確保任何特定版本都只有一個宣告：
@available(added=1)
library test.good.fi0036;
@available(replaced=2)
type Color = strict enum {
RED = 1;
};
@available(added=2)
type Color = flexible enum {
RED = 1;
};
或者，您也可以重新命名或移除其中一個宣告，如 fi-0034 所示。
如要進一步瞭解版本管理，請參閱 FIDL 版本管理。
fi-0037：正規名稱重疊
具有相同標準名稱的宣告不得有重疊的功能：
@available(added=1)
library test.bad.fi0037;
const COLOR string = "red";
@available(added=2)
protocol Color {};
雖然 COLOR 和 Color 看起來不同，但都是以「標準」名稱 color 表示。您可將原始名稱轉換為 snake_case，以取得正規名稱。
如要修正錯誤，請為每個宣告提供在標準化後不重複的名稱。
@available(added=1)
library test.good.fi0037;
const COLOR string = "red";
@available(added=2)
protocol ColorMixer {};
或者，變更 fi-0036 所示的聲明供應情形，或移除宣告。
如要進一步瞭解為何 FIDL 要求宣告使用不重複的標準名稱，請參閱 fi-0035。
fi-0038：名稱與匯入衝突
宣告名稱與使用 using 匯入的程式庫的名稱不能相同：
library dependency;
const VALUE uint32 = 1;
library test.bad.fi0038b;
using dependency;
type dependency = struct {};
// Without this, we'd get fi-0178 instead.
const USE_VALUE uint32 = dependency.VALUE;
請改用 using ... as 語法，以其他名稱匯入程式庫：
library test.good.fi0038b;
using dependency as dep;
type dependency = struct {};
const USE_VALUE uint32 = dep.VALUE;
您也可以重新命名宣告來避免衝突：
library test.good.fi0038c;
using dependency;
type OtherName = struct {};
const USE_VALUE uint32 = dependency.VALUE;
如要避免這個問題，您可以在程式庫名稱中使用多個元件。例如，Fussia SDK 中的 FIDL 程式庫以 fuchsia. 開頭，因此具有至少兩個元件，而且不得與宣告名稱衝突。
這項錯誤是為了防止模稜兩可。舉例來說，如果 dependency 是含有名為 VALUE 的成員的列舉，則 dependency.VALUE 參照該列舉成員，還是在匯入的程式庫中宣告的常數，會導致混淆。
fi-0039：正規名稱與匯入衝突
宣告的標準名稱不得與包含 using 的程式庫匯入項目相同：
library dependency;
const VALUE uint32 = 1;
library test.bad.fi0039b;
using dependency;
type Dependency = struct {};
// Without this, we'd get fi-0178 instead.
const USE_VALUE uint32 = dependency.VALUE;
雖然 dependency 和 Dependency 看起來不同，但兩者都是「標準」名稱 dependency 表示。您可將原始名稱轉換為 snake_case，以取得正規名稱。
如要修正錯誤，請使用 using ... as 語法匯入不同名稱下的程式庫：
library test.good.fi0039b;
using dependency as dep;
type Dependency = struct {};
const USE_VALUE uint32 = dep.VALUE;
您也可以重新命名宣告來避免衝突：
library test.good.fi0039c;
using dependency;
type OtherName = struct {};
const USE_VALUE uint32 = dependency.VALUE;
請參閱 fi-0038，瞭解發生這個錯誤的原因和如何避免。
如要進一步瞭解為何 FIDL 要求宣告使用不重複的標準名稱，請參閱 fi-0035。
fi-0040：檔案與圖書館名稱不一致
程式庫可由多個檔案組成，但每個檔案都必須具有相同名稱：
library test.bad.fi0040a;
library test.bad.fi0040b;
確認程式庫使用的所有檔案都使用相同的名稱：
library test.good.fi0040;
library test.good.fi0040;
建議的多檔案程式庫慣例是建立空白的 overview.fidl 檔案，做為程式庫的主要「進入點」。overview.fidl 檔案還可用來放置程式庫範圍的 @available 平台規格。
fi-0041：多個名稱相同的程式庫
傳遞至 fidlc 的每個程式庫都必須擁有不重複的名稱：
library test.bad.fi0041;
library test.bad.fi0041;
確保所有程式庫的名稱都不重複：
library test.good.fi0041a;
library test.good.fi0041b;
這項錯誤通常是因為將引數提供給 fidlc 的方式不正確。每個編譯所需的程式庫 (也就是要編譯的程式庫和其所有轉換依附元件) 的組成檔案必須以空格分隔的單一檔案清單提供，透過 --files 引數傳遞的檔案，每個程式庫各有一個這類標記。常見的錯誤是嘗試為單一 --files 清單中的所有程式庫傳遞檔案。
fi-0042：複製程式庫匯入
無法多次匯入依附元件：
library test.bad.fi0042a;
type Bar = struct {};
library test.bad.fi0042b;
using test.bad.fi0042a;
using test.bad.fi0042a; // duplicated
type Foo = struct {
bar test.bad.fi0042a.Bar;
};
確保每個依附元件都僅匯入一次：
library test.good.fi0042a;
type Bar = struct {};
library test.good.fi0042b;
using test.good.fi0042a;
type Foo = struct {
bar test.good.fi0042a.Bar;
};
值得注意的是，FIDL 不支援匯入同一程式庫的不同版本。系統會透過 --available 標記解析整個 fidlc 編譯的 @available 版本，也就是說，要編譯的程式庫及其所有依附元件，都必須共用相同版本才能執行任何編譯作業。
fi-0043：衝突的程式庫匯入
禁止匯入的程式庫與其他匯入程式庫的非別名名稱發生衝突，因此禁止使用該程式庫：
library test.bad.fi0043a;
type Bar = struct {};
// This library has a one component name to demonstrate the error.
library fi0043b;
type Baz = struct {};
library test.bad.fi0043c;
using test.bad.fi0043a as fi0043b; // conflict
using fi0043b;
type Foo = struct {
a fi0043b.Bar;
b fi0043b.Baz;
};
請選擇其他別名以解決名稱衝突：
library test.good.fi0043a;
type Bar = struct {};
library fi0043b;
type Baz = struct {};
library test.good.fi0043c;
using test.good.fi0043a as dep;
using fi0043b;
type Foo = struct {
a dep.Bar;
b fi0043b.Baz;
};
fi-0044：衝突程式庫匯入別名
禁止匯入匯入的程式庫的別名，以免與指派給其他匯入程式庫的別名相衝突：
library test.bad.fi0044a;
type Bar = struct {};
library test.bad.fi0044b;
type Baz = struct {};
library test.bad.fi0044c;
using test.bad.fi0044a as dep;
using test.bad.fi0044b as dep; // conflict
type Foo = struct {
a dep.Bar;
b dep.Baz;
};
選擇非衝突的別名以解決名稱衝突：
library test.good.fi0044a;
type Bar = struct {};
library test.good.fi0044b;
type Baz = struct {};
library test.good.fi0044c;
using test.good.fi0044a as dep1;
using test.good.fi0044b as dep2;
type Foo = struct {
a dep1.Bar;
b dep2.Baz;
};
fi-0045：使用宣告時不允許的屬性
屬性無法附加至 using 宣告：
library test.bad.fi0045a;
type Bar = struct {};
library test.bad.fi0045b;
/// not allowed
@also_not_allowed
using test.bad.fi0045a;
type Foo = struct {
bar test.bad.fi0045a.Bar;
};
移除屬性即可解決錯誤：
library test.good.fi0045a;
type Bar = struct {};
library test.good.fi0045b;
using test.good.fi0045a;
type Foo = struct {
bar test.good.fi0045a.Bar;
};
這項限制適用於 /// ... 文件註解，以及 @doc("...") 屬性的語法糖。
fi-0046：不明的程式庫
在大多數情況下，這個問題的起因是依附元件拼寫錯誤，或是建構系統未提供該依附元件。如果故意未使用相關依附元件，請務必移除相關的指令列程式碼：
library test.bad.fi0046;
using dependent; // unknown using.
type Foo = struct {
dep dependent.Bar;
};
請務必使用建構系統，將所有匯入作業新增為程式庫的依附元件。
library test.good.fi0046;
type Foo = struct {
dep int64;
};
fi-0047：通訊協定多次組成
通訊協定只能組合另一個通訊協定一次：
library test.bad.fi0047;
protocol Parent {
Method();
};
protocol Child {
compose Parent;
compose Parent;
};
移除多餘的 compose 子句：
library test.good.fi0047;
protocol Parent {
Method();
};
protocol Child {
compose Parent;
};
fi-0048：選擇性資料表成員
資料表成員類型不得為 optional：
library test.bad.fi0048;
type Foo = table {
// Strings can be optional in general, but not in table member position.
1: t string:optional;
};
從所有成員中移除 optional 限制：
library test.good.fi0048;
type Foo = table {
1: t string;
};
資料表成員一律是選用項目，因此針對成員的基礎類型指定此資訊是多餘的。
資料表成員一律為選用，因為在線上，每個資料表成員都會以向量中的一個項目表示。這個向量一律代表資料表中所有已知的欄位，因此每個省略的資料表成員都會以空值信封表示，與省略的選用類型完全一樣。
fi-0049：選擇性聯集成員
聯集成員不得為選擇性成員：
library test.bad.fi0049;
type Foo = strict union {
// Strings can be optional in general, but not in unions.
1: bar string:optional;
};
移除 optional 限制：
library test.good.fi0049;
type Foo = strict union {
1: bar string;
};
FIDL 不允許將聯集成員設為選用，因為這樣可能會以多種方式表示相同的值。例如，如有三個可選成員的聯集，則會有 6 個狀態 (每位成員 2 個)。請改為使用類型為 struct {} 的第四個成員建立模型，或是使用 Foo:optional 選擇整體聯集。
fi-0050：已淘汰的結構體預設語法
先前，struct 成員可以使用 FIDL 來設定預設值：
library test.bad.fi0050;
type MyStruct = struct {
field int64 = 20;
};
自 RFC-0160：移除對 FIDL 結構體預設值的支援，系統不允許這個行為：
library test.good.fi0050;
type MyStruct = struct {
field int64;
};
您已無法再使用 struct 成員的預設值。使用者應改為在應用程式邏輯中設定這類預設值。
在編譯器內建的許可清單下，只有少數舊版使用者可以繼續使用這個語法，但無法將新的例外狀況加入這份清單中。關閉這些使用者後，這項功能就會從 FIDL 中永久移除。
fi-0051：未知的相依程式庫
如果使用的符號來自不明資料庫，就會發生這個錯誤。
library test.bad.fi0051;
type Company = table {
1: employees vector<unknown.dependent.library.Person>;
2: name string;
};
如要修正這個問題，請使用宣告匯入缺少的相依程式庫。
library known.dependent.library;
type Person = table {
1: age uint8;
2: name string;
};
library test.good.fi0051;
using known.dependent.library;
type Company = table {
1: employees vector<known.dependent.library.Person>;
2: name string;
};
這項錯誤通常會在 fidlc 指令列叫用格式錯誤時發生。如果您確信不明程式庫存在且應該可解決，請務必透過傳遞至 --files 旗標的以空格分隔的清單，正確傳遞依附程式庫的檔案。
fi-0052：找不到名稱
使用 FIDL 編譯器找不到的名稱時，就會發生這個錯誤。
library test.bad.fi0052;
protocol Parser {
Tokenize() -> (struct {
tokens vector<string>;
}) error ParsingError; // ParsingError doesn't exist.
};
如要修正這個問題，請移除找不到的名稱：
library test.good.fi0052a;
protocol Parser {
Tokenize() -> (struct {
tokens vector<string>;
});
};
或是定義找不到的名稱：
library test.good.fi0052b;
type ParsingError = flexible enum {
UNEXPECTED_EOF = 0;
};
protocol Parser {
Tokenize() -> (struct {
tokens vector<string>;
}) error ParsingError;
};
fi-0053：無法參照成員
如果您參照的成員不是 bits 或 enum 項目，就會發生這個錯誤。
library test.bad.fi0053a;
type Person = struct {
name string;
birthday struct {
year uint16;
month uint8;
day uint8;
};
};
const JOHNS_NAME Person.name = "John Johnson"; // Cannot refer to member of struct 'Person'.
library test.bad.fi0053b;
type Person = struct {
name string;
birthday struct {
year uint16;
month uint8;
day uint8;
};
};
type Cat = struct {
name string;
age Person.birthday; // Cannot refer to member of struct 'Person'.
};
如要修正這項錯誤，請變更為已命名的類型：
library test.good.fi0053a;
type Person = struct {
name string;
birthday struct {
year uint16;
month uint8;
day uint8;
};
};
const JOHNS_NAME string = "John Johnson";
或擷取成員類型：
library test.good.fi0053b;
type Date = struct {
year uint16;
month uint8;
day uint8;
};
type Person = struct {
name string;
birthday Date;
};
type Cat = struct {
name string;
age Date;
};
fi-0054：位元/列舉成員無效
如果參照 enum 或 bits 成員但未先定義，就會發生這個錯誤。
library test.bad.fi0054;
type Enum = enum {
foo_bar = 1;
};
const EXAMPLE Enum = Enum.FOO_BAR;
為了避免發生這個錯誤，請確認您先前已宣告參照成員值的值。這些值有大小寫之分。
library test.good.fi0054;
type Enum = enum {
foo_bar = 1;
};
const EXAMPLE Enum = Enum.foo_bar;
fi-0055：無效的參照無效
如果使用對 type 或 const 的參照包含不相容的 @available 屬性，就會發生這個錯誤。這種情況通常會在使用較新版本的 types 或 consts 時發生。
@available(added=1)
library test.bad.fi0055;
@available(added=1, deprecated=2, note="use Color instead")
alias RGB = array<uint8, 3>;
@available(added=2)
type Color = struct {
r uint8;
g uint8;
b uint8;
a uint8;
};
@available(added=3)
type Config = table {
// RGB is deprecated in version 2.
1: color RGB;
};
如要修正這個錯誤，請使用未淘汰的 type 或 const：
@available(added=1)
library test.good.fi0055;
@available(added=1, deprecated=2, note="use Color instead")
alias RGB = array<uint8, 3>;
@available(added=2)
type Color = struct {
r uint8;
g uint8;
b uint8;
a uint8;
};
@available(added=3)
type Config = table {
// Using a non-deprecated type.
1: color Color;
};
fi-0056：其他平台的參照無效
如果從其他平台使用不相容 @available 屬性的 type 或 const 參照，就會發生這個錯誤。這種情況通常會在後續版本中使用已淘汰的 types 或 consts 時發生。
@available(platform="foo", added=1)
library test.bad.fi0056a;
@available(added=1, deprecated=2, note="use Color instead")
alias RGB = array<uint8, 3>;
@available(added=2)
type Color = struct {
r uint8;
g uint8;
b uint8;
a uint8;
};
@available(platform="bar", added=2)
library test.bad.fi0056b;
using test.bad.fi0056a;
@available(added=3)
type Config = table {
// RGB is deprecated in version 2.
1: color test.bad.fi0056a.RGB;
};
如要修正這個錯誤，請使用未淘汰的 type 或 const：
@available(platform="foo", added=1)
library test.good.fi0056a;
@available(added=1, deprecated=2, note="use Color instead")
alias RGB = array<uint8, 3>;
@available(added=2)
type Color = struct {
r uint8;
g uint8;
b uint8;
a uint8;
};
@available(platform="bar", added=2)
library test.good.fi0056b;
using test.good.fi0056a;
@available(added=2)
type Config = table {
// Change to use a non-deprecated type.
1: color test.good.fi0056a.Color;
};
fi-0057：包含月經週期
有許多情況可能會造成這個問題，但所有情況基本上都指向一個 FIDL 宣告，且這種宣告方式無法解決。依照自身定義直接參照類型或通訊協定時，會出現這項錯誤：
library test.bad.fi0057c;
type MySelf = struct {
me MySelf;
};
當類型或通訊協定「間接」透過至少一個間接程度參照自身時，可能會發生較複雜的失敗情況：
library test.bad.fi0057a;
type Yin = struct {
yang Yang;
};
type Yang = struct {
yin Yin;
};
library test.bad.fi0057b;
protocol Yin {
compose Yang;
};
protocol Yang {
compose Yin;
};
只要在納入週期的某處新增信封 (又稱選用性)，即可解決這項錯誤，因為這樣在編碼/解碼時可能會「毀損」循環：
library test.good.fi0057;
type MySelf = struct {
me box<MySelf>;
};
library test.bad.fi0057d;
type MySelf = table {
1: me MySelf;
};
系統不允許信封造成信封的遞迴類型，因為這種形式無法進行編碼。在上述第一個範例中，編碼 MySelf 需要先對 MySelf 的執行個體進行編碼，後者則需要對 MySelf 的例項進行編碼。解決這個問題的方法是透過選擇性性，在這個鏈結中新增「中斷點」，其中之一可以選擇為另一個 MySelf 的巢狀執行個體進行編碼，或對空值信封進行編碼，但這類執行個體沒有其他資料。
fi-0058：編譯器產生的酬載名稱的參照
匿名方法酬載會由 FIDL 編譯器自動產生名稱，因此產生的後端程式碼使用者可視需要參照其代表的類型。不過，在 *.fidl 檔案中參照這些類型是禁止的：
library test.bad.fi0058;
protocol MyProtocol {
strict MyInfallible(struct {
in uint8;
}) -> (struct {
out int8;
});
strict MyFallible(struct {
in uint8;
}) -> (struct {
out int8;
}) error flexible enum {};
strict -> MyEvent(struct {
out int8;
});
};
type MyAnonymousReferences = struct {
a MyProtocolMyInfallibleRequest;
b MyProtocolMyInfallibleResponse;
c MyProtocolMyFallibleRequest;
d MyProtocol_MyFallible_Result;
e MyProtocol_MyFallible_Response;
f MyProtocol_MyFallible_Error;
g MyProtocolMyEventRequest;
};
如果您想直接參照酬載類型，請改為將酬載類型擷取到專屬的已命名類型宣告中：
library test.good.fi0058;
type MyRequest = struct {
in uint8;
};
type MyResponse = struct {
out int8;
};
type MyError = flexible enum {};
protocol MyProtocol {
strict MyInfallible(MyRequest) -> (MyResponse);
strict MyFallible(MyRequest) -> (MyResponse) error MyError;
strict -> MyEvent(MyResponse);
};
type MyAnonymousReferences = struct {
a MyRequest;
b MyResponse;
c MyRequest;
// There is no way to explicitly name the error result union.
// d MyProtocol_MyFallible_Result;
e MyResponse;
f MyError;
g MyResponse;
};
所有 FIDL 方法和事件都會為匿名要求酬載保留 [PROTOCOL_NAME][METHOD_NAME]Request 名稱。嚴格、無法避免的雙向方法會額外保留 [PROTOCOL_NAME][METHOD_NAME]Response。彈性或可保留的雙向方法：
[PROTOCOL_NAME]_[METHOD_NAME]_Result[PROTOCOL_NAME]_[METHOD_NAME]_Response[PROTOCOL_NAME]_[METHOD_NAME]_Error
基於歷史因素，這些名稱使用底線與其他名稱不同。
fi-0059：常數類型無效
並非所有類型可用於 const 宣告：
library test.bad.fi0059;
const MY_CONST string:optional = "foo";
在可能的情況下，轉換為允許的類型：
library test.good.fi0059;
const MY_CONST string = "foo";
const 宣告的左側只能使用 FIDL 基元 (bool、int8、int16、int32、int64、uint8、uint16、uint32、uint64、float32、float64) 和非選用的 string 類型。
fi-0060：無法解析常數值
常數值必須能夠解析為已知值：
library test.bad.fi0060;
const MY_CONST bool = optional;
請確定使用的常數是有效值：
library test.good.fi0060;
const MY_CONST bool = true;
這項錯誤通常會伴隨著其他錯誤，進而針對無法解析預期常數提供更多資訊。
fi-0061：或是非原始值的運算子
二進位或運算子只能用於原始物件：
library test.bad.fi0061;
const HI string = "hi";
const THERE string = "there";
const OR_OP string = HI | THERE;
請嘗試將運作中的資料顯示為 bits 列舉：
library test.good.fi0061;
type MyBits = flexible bits {
HI = 0x1;
THERE = 0x10;
};
const OR_OP MyBits = MyBits.HI | MyBits.THERE;
fi-0062： 不允許使用新類型
來自 RFC-0052：類型別名和新類型的新類型尚未完全實作，因此尚無法使用：
library test.bad.fi0062;
type Matrix = array<float64, 9>;
同時，您可以使用單一元素定義結構體，藉此達到類似的目的：
library test.good.fi0062a;
type Matrix = struct {
elements array<float64, 9>;
};
或者，您可以定義別名，但請注意，與新類型不同，這樣做沒有類型安全性 (也就是說，可以與基礎類型交替使用)：
library test.good.fi0062b;
alias Matrix = array<float64, 9>;
fi-0063：預期值，但是類型為類型
const 宣告的右側必須解析為常數值，而非類型：
library test.bad.fi0063;
type MyType = struct {};
const MY_CONST uint32 = MyType;
確認右側為值：
library test.good.fi0063;
const MY_VALUE uint32 = 8;
const MY_CONST uint32 = MY_VALUE;
fi-0064：位元或列舉值類型不正確
使用 bits 或 enum 變數做為 const 宣告中的值時，bits/enum 值的類型必須與 Const 宣告的左側相同：
library test.bad.fi0064;
type MyEnum = enum : int32 {
VALUE = 1;
};
type OtherEnum = enum : int32 {
VALUE = 5;
};
const MY_CONST MyEnum = OtherEnum.VALUE;
其中一種解決方法是變更 const 宣告的類型，使其符合儲存的值：
library test.good.fi0064;
type MyEnum = enum : int32 {
VALUE = 1;
};
type OtherEnum = enum : int32 {
VALUE = 5;
};
const MY_CONST OtherEnum = OtherEnum.VALUE;
或者，您也可以選取其他值，以符合 const 宣告的類型：
library test.good.fi0064;
type MyEnum = enum : int32 {
VALUE = 1;
};
type OtherEnum = enum : int32 {
VALUE = 5;
};
const MY_CONST MyEnum = MyEnum.VALUE;
fi-0065：無法將值轉換為預期類型
常數值必須是適合其使用位置的類型。
這個錯誤最常見的原因是 const 宣告的值與指定的類型不符：
library test.bad.fi0065a;
const MY_CONST bool = "foo";
如果將正確定義的 const 值用於基礎類型無效的位置，則仍會發生問題：
library test.bad.fi0065b;
const ONE uint8 = 0x0001;
const TWO_FIFTY_SIX uint16 = 0x0100;
const TWO_FIFTY_SEVEN uint8 = ONE | TWO_FIFTY_SIX;
此外，FIDL 的「官方」會檢查結構定義的引數。這些引數本身就是常數值，因此可能會發生相同類型的不相符情況：
library test.bad.fi0065c;
protocol MyProtocol {
@selector(3840912312901827381273)
MyMethod();
};
在這些情況下，這項解決方案都只會在接受 const 值的位置使用預期類型的值。上述情況分別會變成：
library test.good.fi0065a;
const MY_CONST string = "foo";
library test.good.fi0065b;
const ONE uint8 = 0x0001;
const TWO_FIFTY_SIX uint16 = 0x0100;
const TWO_FIFTY_SEVEN uint16 = ONE | TWO_FIFTY_SIX;
library test.good.fi0065c;
protocol MyProtocol {
@selector("MyOldMethod")
MyMethod();
};
fi-0066：常數溢位類型
常數值不得超出範圍本身的基礎類型：
library test.bad.fi0066;
const NUM uint64 = -42;
您可以透過變更值以符合類型範圍來修正這個問題：
library test.good.fi0066a;
const NUM uint64 = 42;
或者，您也可以變更為類型來因應目前溢位的值：
library test.good.fi0066b;
const NUM int64 = -42;
這個錯誤只涉及 FIDL 的數值類型，且這些類型都有溢位能力。範圍取自 C++ std::numeric_limits
介面，如下所示：
| 類型 | 最小值 | 最大值 |
|---|---|---|
int8 |
-128 | 127 |
int16 |
32768 | 32767 |
int32 |
2147483648 | 2147483647 |
int64 |
9223372036854775808 | 9223372036854775807 |
uint8 |
0 | 255 |
uint16 |
0 | 65536 |
uint32 |
0 | 4294967295 |
uint64 |
0 | 18446744073709551615 |
float32 |
-3.40282e+38 | 3.40282e+38 |
float64 |
-1.79769e+308 | 1.79769e+308 |
fi-0067：小比方必須為二的次方
bits 宣告中所有成員的值不得為非二次方的任意數字：
library test.bad.fi0067;
type NonPowerOfTwo = bits : uint64 {
THREE = 3;
};
成員值應一律為二的次方：
library test.good.fi0067a;
type Fruit = bits : uint64 {
ORANGE = 1;
APPLE = 2;
BANANA = 4;
};
為避免因這項限製而增加，最簡單的方法就是只使用位元遮罩 (而非十進位數字) 做為位元成員值：
library test.good.fi0067b;
type Life = bits {
A = 0b000010;
B = 0b001000;
C = 0b100000;
};
bits 結構代表位元陣列。這是表示一系列布林值標記的結果，最能節省記憶體的方法。由於 bits 宣告的每個成員都會對應到基礎記憶體的特定位元，因此用於該對應的值必須能在無正負號整數中明確識別要指派的特定位元。
fi-0068：彈性列舉有保留的未知值
當您定義一個列舉成員，且其值與保留的未知值衝突時，就會發生這個錯誤。
彈性的列舉可能會保留 FIDL 結構定義不明的值。此外，彈性列舉一律會保留某些值，系統會將這個值視為未知。根據預設，該值是列舉的基礎整數類型所代表的最大數值 (例如，如果是 uint8，則為 255)。
library test.bad.fi0068;
type Foo = flexible enum : uint8 {
ZERO = 0;
ONE = 1;
MAX = 255;
};
如要修正錯誤，您可以移除成員或變更該成員的值：
library test.good.fi0068a;
type Foo = flexible enum : uint8 {
ZERO = 0;
ONE = 1;
};
library test.good.fi0068b;
type Foo = flexible enum : uint8 {
ZERO = 0;
ONE = 1;
MAX = 254;
};
最後，如果您在將 strict 列舉轉換為 flexible 列舉時遇到這個錯誤，就可以使用 @unknown 屬性，將特定成員的數值指定為不明值。查看「@unknown」。
fi-0069：位元必須使用未簽署的積分子類型
禁止使用帶正負號的數值做為 bits 宣告的基礎類型：
library test.bad.fi0069;
type Fruit = bits : int64 {
ORANGE = 1;
APPLE = 2;
BANANA = 4;
};
請改用以下任一種方法：uint8、uint16、uint32 或 uint64：
library test.good.fi0069;
type Fruit = bits : uint64 {
ORANGE = 1;
APPLE = 2;
BANANA = 4;
};
有別於允許帶正負號整數 (請參閱 fi-0070) 的 enum 宣告，bits 宣告僅允許使用後者。這是因為每個 bits 成員都必須代表 位元陣列中的特定基礎位元 (這就是 fi-0067 存在的原因)。幾乎是一個無正負號整數。無正負號整數的二進位表示法會直接對應至單一位元 (2 為其索引的次方)，而帶正負號整數中的負數幾乎都是因為兩個互補表示法的機制所致。
fi-0070：列舉必須使用 integral 子類型
禁止使用非整合數字 float32 或 float64 做為 enum 宣告的基礎類型：
library test.bad.fi0070;
type MyEnum = enum : float64 {
ONE_POINT_FIVE = 1.5;
};
請改用以下任一種方法：int8、int16、int32、int64、uint8、uint16、uint32 或 uint64：
library test.good.fi0070;
type MyEnum = enum : uint64 {
ONE = 1;
};
fi-0071：嚴格列舉成員禁止使用未知屬性
strict enum 不得包含使用 @unknown 屬性註解的成員：
library test.bad.fi0071;
type MyEnum = strict enum : int8 {
@unknown
UNKNOWN = 0;
FOO = 1;
MAX = 127;
};
如要繼續使用 @unknown 屬性，請變更為 flexible enum：
library test.good.fi0071a;
type MyEnum = flexible enum : int8 {
@unknown
UNKNOWN = 0;
FOO = 1;
MAX = 127;
};
否則，只要移除該屬性，即可保持 strict enum：
library test.good.fi0071;
type MyEnum = strict enum : int8 {
UNKNOWN = 0;
FOO = 1;
MAX = 127;
};
@unknown 屬性的用途是在包含使用者定義未知值的 strict enum 轉換間流暢執行轉換，就像這樣，就會成為含有 FIDL 已知且由 FIDL 處理且未知的值的 flexible enum。在上述範例中，這會用來從第二個正確的用法轉換到第一項正確用法。
fi-0072：只有列舉成員能夠攜帶未知屬性
在使用 @unknown 屬性時，不得同時接受多位 enum 成員：
library test.bad.fi0072;
type MyEnum = flexible enum : uint8 {
@unknown
UNKNOWN = 0;
@unknown
OTHER = 1;
};
僅選擇做為網域專屬「未知」值的成員並加上註解：
library test.good.fi0071a;
type MyEnum = flexible enum : int8 {
@unknown
UNKNOWN = 0;
OTHER = 1;
};
@unknown 屬性的用途是在包含使用者定義不明值的 strict enum 轉換間流暢執行轉換，例如以下為具有 FIDL 已知且由 FIDL 處理且未知的值的 flexible enum：
library test.good.fi0072;
type MyEnum = strict enum : int8 {
UNKNOWN = 0;
OTHER = 1;
};
library test.good.fi0071a;
type MyEnum = flexible enum : int8 {
@unknown
UNKNOWN = 0;
OTHER = 1;
};
fi-0073：撰寫非通訊協定
只有通訊協定可用於 compose 陳述式：
library test.bad.fi0073;
type MyStruct = struct {};
protocol MyProtocol {
compose MyStruct;
};
確認您的名稱指向通訊協定：
library test.good.fi0073;
protocol MyOtherProtocol {};
protocol MyProtocol {
compose MyOtherProtocol;
};
fi-0074：方法酬載使用無效的版面配置
只有 struct、table 或 union 版面配置才能描述方法酬載：
library test.bad.fi0074;
protocol MyProtocol {
MyMethod(enum {
FOO = 1;
});
};
請改用下列其中一種版面配置：
library test.good.fi0074;
protocol MyProtocol {
MyMethod(struct {
foo bool;
});
};
fi-0075：方法酬載使用無效的原始版本
基本項目無法做為方法酬載：
library test.bad.fi0075;
protocol MyProtocol {
MyMethod(uint32);
};
請改用 struct、table 或 union 版面配置的類型：
library test.good.fi0075;
protocol MyProtocol {
MyMethod(struct {
wrapped_in_struct uint32;
});
};
如果所需酬載實際上只是原始值，並不必擔心日後的演變，將值納入 struct 版面配置中會導致酬載本身與所需值相同。
fi-0076
fi-0077：互動酬載不得為空白結構
方法或事件中的酬載不得為空白結構：
library test.bad.fi0077a;
protocol Test {
MyMethod(struct {}) -> (struct {});
};
library test.bad.fi0077b;
protocol Test {
-> MyEvent(struct {});
};
如要表示特定要求/回應未保留任何資訊，請刪除空白結構，將 () 留在該位置：
library test.good.fi0077a;
protocol Test {
MyMethod() -> ();
};
library test.good.fi0077b;
protocol Test {
-> MyEvent();
};
空白結構體無法擴充，且需在線路上佔 1 位元組。由於 FIDL 支援沒有酬載的互動，因此以這種方式使用空白結構會精準且效率較低。因此不允許使用。
fi-0078
fi-0079
fi-0080：產生的零值序數
這種錯誤應該永遠不要發生。恭喜你順利完成工作，因為你可能已經破壞了 SHA-256！
如果不行，當 fidlc 編譯器產生 0 的序數值時，就會發生這個錯誤。這種情況應該永遠不會發生，因此如果確實如此，您可能在 FIDL 編譯器中發現了錯誤。如果出現這種情況，請向我們的 Issue Tracker 回報問題。
fi-0081：重複方法序數
這個錯誤通常會發生於使用 @selector 屬性使兩個方法名稱產生相同的序數時。
library test.bad.fi0081;
protocol Parser {
ParseLine();
// Multiple methods with the same ordinal...
@selector("ParseLine")
ParseOneLine();
};
如要修正這個問題，請更新方法名稱或選取器，導致無法發生衝突。
library test.good.fi0081;
protocol Parser {
ParseLine();
@selector("Parse1Line")
ParseOneLine();
};
如果發生 SHA-256 衝突，但這種情況基本上為零，也可能會發生這個錯誤。如果您是正向的選取器本身沒有錯誤，且您仍然遇到這個錯誤，則您可能在 FIDL 編譯器中發現了錯誤。如果出現這種情況，請向我們的 Issue Tracker 回報問題。
fi-0082：無效的選取器值
如果 @selector 的值無效，就會發生這個錯誤。最常見的原因是錯字。選取器必須是獨立方法名稱，或是完整的方法名稱。
library test.bad.fi0082;
protocol Parser {
@selector("test.old.fi0082.Parser.Parse")
Parse();
};
如要修正這個問題，請將選取器更新為有效的獨立方法或完整方法名稱：
library test.good.fi0082;
protocol Parser {
@selector("test.old.fi0082/Parser.Parse")
Parse();
};
fi-0083：fuchsia.io 必須使用明確的序數
用來將 fuchsia.io 序數自動重新命名為 fuchsia.io1 的 FIDL 編譯器。這項神奇指令旨在讓方法的 io2 版本處於「一般」狀態，讓您輕鬆遷移至 fuchsia.io2。不過，這個系統最後變得太神奇了，因此現在必須手動為 fuchsia.io 提供序數。
library fuchsia.io;
protocol SomeProtocol {
SomeMethod();
};
如要修正這個問題，請使用 fuchsia.io1 做為程式庫名稱手動提供選取器，允許將 fuchsia.io 名稱用於 io2。
library fuchsia.io;
protocol SomeProtocol {
@selector("fuchsia.io1/SomeProtocol.SomeMethod")
SomeMethod();
};
fi-0084：不允許使用方法酬載結構的預設成員
用作付款方式的結構體不得指定預設成員：
library test.bad.fi0084;
type MyStruct = struct {
@allow_deprecated_struct_defaults
a bool = false;
};
protocol MyProtocol {
MyMethod(MyStruct) -> (MyStruct);
};
從相關的 struct 宣告中移除預設成員：
library test.good.fi0084;
type MyStruct = struct {
a bool;
};
protocol MyProtocol {
MyMethod(MyStruct) -> (MyStruct);
};
fi-0085
fi-0086
fi-0087
fi-0088：服務成員不能為選擇性
將服務成員標示為 optional 時會發生這個錯誤。不得將服務成員標示為 optional，因為服務成員一律為選用。
library test.bad.fi0088;
protocol Sorter {
Sort(struct {
input vector<int32>;
}) -> (struct {
output vector<int32>;
});
};
service SortService {
quicksort client_end:<Sorter, optional>;
mergesort client_end:<Sorter, optional>;
};
如要修正這個問題，請移除選用子句：
library test.good.fi0088;
protocol Sorter {
Sort(struct {
input vector<int32>;
}) -> (struct {
output vector<int32>;
});
};
service SortService {
quicksort client_end:Sorter;
mergesort client_end:Sorter;
};
fi-0089
fi-0090
fi-0091：無效的結構體成員類型
當您嘗試為不支援的類型設定預設結構值時，就會發生這個錯誤。只有數字和布林值類型才能設定預設結構值。
library test.bad.fi0091;
type Person = struct {
@allow_deprecated_struct_defaults
name string:optional = "";
};
如要修正這個問題，請移除預設值：
library test.good.fi0091;
type Person = struct {
@allow_deprecated_struct_defaults
name string:optional;
};
fi-0092：表格序數過大
FIDL 資料表序數不得大於 64：
library test.bad.fi0092;
type Table64thField = table {
1: x int64;
};
type Example = table {
1: v1 int64;
2: v2 int64;
3: v3 int64;
4: v4 int64;
5: v5 int64;
6: v6 int64;
7: v7 int64;
8: v8 int64;
9: v9 int64;
10: v10 int64;
11: v11 int64;
12: v12 int64;
13: v13 int64;
14: v14 int64;
15: v15 int64;
16: v16 int64;
17: v17 int64;
18: v18 int64;
19: v19 int64;
20: v20 int64;
21: v21 int64;
22: v22 int64;
23: v23 int64;
24: v24 int64;
25: v25 int64;
26: v26 int64;
27: v27 int64;
28: v28 int64;
29: v29 int64;
30: v30 int64;
31: v31 int64;
32: v32 int64;
33: v33 int64;
34: v34 int64;
35: v35 int64;
36: v36 int64;
37: v37 int64;
38: v38 int64;
39: v39 int64;
40: v40 int64;
41: v41 int64;
42: v42 int64;
43: v43 int64;
44: v44 int64;
45: v45 int64;
46: v46 int64;
47: v47 int64;
48: v48 int64;
49: v49 int64;
50: v50 int64;
51: v51 int64;
52: v52 int64;
53: v53 int64;
54: v54 int64;
55: v55 int64;
56: v56 int64;
57: v57 int64;
58: v58 int64;
59: v59 int64;
60: v60 int64;
61: v61 int64;
62: v62 int64;
63: v63 int64;
// The 64th field of a table must be another table, otherwise it will cause
// fi-0093: Max Ordinal In Table Must Be Table.
64: v64 Table64thField;
65: v65 int64;
};
為了容許超過 64 條序數的成長，FIDL 需要資料表的最後一個欄位做為另一個資料表。任何超過 64 的資料表欄位都必須放在巢狀資料表中。
library test.good.fi0092;
type Table64thField = table {
1: x int64;
// Any fields beyond 64 of table Example must be move to the nested table in
// ordinal 64 of Example.
2: v65 int64;
};
type Example = table {
1: v1 int64;
2: v2 int64;
3: v3 int64;
4: v4 int64;
5: v5 int64;
6: v6 int64;
7: v7 int64;
8: v8 int64;
9: v9 int64;
10: v10 int64;
11: v11 int64;
12: v12 int64;
13: v13 int64;
14: v14 int64;
15: v15 int64;
16: v16 int64;
17: v17 int64;
18: v18 int64;
19: v19 int64;
20: v20 int64;
21: v21 int64;
22: v22 int64;
23: v23 int64;
24: v24 int64;
25: v25 int64;
26: v26 int64;
27: v27 int64;
28: v28 int64;
29: v29 int64;
30: v30 int64;
31: v31 int64;
32: v32 int64;
33: v33 int64;
34: v34 int64;
35: v35 int64;
36: v36 int64;
37: v37 int64;
38: v38 int64;
39: v39 int64;
40: v40 int64;
41: v41 int64;
42: v42 int64;
43: v43 int64;
44: v44 int64;
45: v45 int64;
46: v46 int64;
47: v47 int64;
48: v48 int64;
49: v49 int64;
50: v50 int64;
51: v51 int64;
52: v52 int64;
53: v53 int64;
54: v54 int64;
55: v55 int64;
56: v56 int64;
57: v57 int64;
58: v58 int64;
59: v59 int64;
60: v60 int64;
61: v61 int64;
62: v62 int64;
63: v63 int64;
64: v64 Table64thField;
};
為方便選用欄位，資料表中的每個欄位都會產生 FIDL 信封的負擔。如此一來，資料表的每個欄位都會顯示或缺少，也能透過新增或移除欄位來更新資料表，但代價是比結構體大得多。
一般來說，只要避免資料表中具有小型且精細的欄位，就能避免發生這項錯誤並降低負擔。您可以將預期必須同時新增或移除的元素歸為一組，並把這些元素當做資料表的欄位使用。這樣可以減少負擔，避免因程序異常而耗盡異常。
這在 RFC-0132：FIDL 資料表大小限制中變成錯誤，這是為了避免使用者意外對超大型資料表造成負擔。在結構定義中，這項額外費用並不顯而易見，特別是在只有幾個欄位 (序數較大) 的情況下，或是有多個欄位但一次只使用幾個欄位時。
fi-0093：資料表中的序數最大值必須為表格
FIDL 資料表中第 64 名成員的類型本身必須為資料表：
library test.bad.fi0093;
type Example = table {
1: v1 int64;
2: v2 int64;
3: v3 int64;
4: v4 int64;
5: v5 int64;
6: v6 int64;
7: v7 int64;
8: v8 int64;
9: v9 int64;
10: v10 int64;
11: v11 int64;
12: v12 int64;
13: v13 int64;
14: v14 int64;
15: v15 int64;
16: v16 int64;
17: v17 int64;
18: v18 int64;
19: v19 int64;
20: v20 int64;
21: v21 int64;
22: v22 int64;
23: v23 int64;
24: v24 int64;
25: v25 int64;
26: v26 int64;
27: v27 int64;
28: v28 int64;
29: v29 int64;
30: v30 int64;
31: v31 int64;
32: v32 int64;
33: v33 int64;
34: v34 int64;
35: v35 int64;
36: v36 int64;
37: v37 int64;
38: v38 int64;
39: v39 int64;
40: v40 int64;
41: v41 int64;
42: v42 int64;
43: v43 int64;
44: v44 int64;
45: v45 int64;
46: v46 int64;
47: v47 int64;
48: v48 int64;
49: v49 int64;
50: v50 int64;
51: v51 int64;
52: v52 int64;
53: v53 int64;
54: v54 int64;
55: v55 int64;
56: v56 int64;
57: v57 int64;
58: v58 int64;
59: v59 int64;
60: v60 int64;
61: v61 int64;
62: v62 int64;
63: v63 int64;
64: v64 int64;
};
如果使用者需要加入第 64 名成員，應建立獨立的資料表，將成員類型設為 64 歲以上，然後改為將該成員加入資料表：
library test.good.fi0093;
type Table64thField = table {
1: x int64;
};
type Example = table {
1: v1 int64;
2: v2 int64;
3: v3 int64;
4: v4 int64;
5: v5 int64;
6: v6 int64;
7: v7 int64;
8: v8 int64;
9: v9 int64;
10: v10 int64;
11: v11 int64;
12: v12 int64;
13: v13 int64;
14: v14 int64;
15: v15 int64;
16: v16 int64;
17: v17 int64;
18: v18 int64;
19: v19 int64;
20: v20 int64;
21: v21 int64;
22: v22 int64;
23: v23 int64;
24: v24 int64;
25: v25 int64;
26: v26 int64;
27: v27 int64;
28: v28 int64;
29: v29 int64;
30: v30 int64;
31: v31 int64;
32: v32 int64;
33: v33 int64;
34: v34 int64;
35: v35 int64;
36: v36 int64;
37: v37 int64;
38: v38 int64;
39: v39 int64;
40: v40 int64;
41: v41 int64;
42: v42 int64;
43: v43 int64;
44: v44 int64;
45: v45 int64;
46: v46 int64;
47: v47 int64;
48: v48 int64;
49: v49 int64;
50: v50 int64;
51: v51 int64;
52: v52 int64;
53: v53 int64;
54: v54 int64;
55: v55 int64;
56: v56 int64;
57: v57 int64;
58: v58 int64;
59: v59 int64;
60: v60 int64;
61: v61 int64;
62: v62 int64;
63: v63 int64;
64: v64 Table64thField;
};
這項要求背後的理由和動機已完全詳載於 RFC-0132：FIDL 資料表大小限制中。簡而言之，FIDL 資料表對允許的欄位數量設有相對限制，否則以編碼形式同時僅使用幾個欄位的資料表，會有大量的死空間 (每個省略的成員均有 16 位元組)。
為提供解決方法，為希望資料表中超過 64 個欄位的使用者提供解決方法，FIDL 會強制將最後一個序數保留給包含額外欄位的「接續資料表」。在這個位置中使用任何其他類型，會導致資料表往後轉譯。
fi-0094：複製資料表成員序數
table 宣告中用於成員的序數不得重複：
library test.bad.fi0094;
type MyTable = table {
1: my_field string;
1: my_other_field uint32;
};
視需要遞增序數，確保宣告對所有成員具有不重複的序數：
library test.good.fi0094a;
type MyTable = table {
1: my_field string;
2: my_other_field uint32;
};
或者，您也可以移除名稱重複的成員：
library test.good.fi0094b;
type MyTable = table {
1: my_field string;
};
序數是用於識別電線的欄位。如果兩個成員共用一個一般，則沒有可靠的方式可以判斷解碼 FIDL 訊息時參照的欄位。
fi-0095
fi-0096
fi-0097：重複聯集成員序
union 宣告中用於成員的序數不得重複：
library test.bad.fi0097;
type MyUnion = strict union {
1: my_variant string;
1: my_other_variant int32;
};
視需要遞增序數，確保宣告對所有成員具有不重複的序數：
library test.good.fi0097a;
type MyUnion = strict union {
1: my_variant string;
2: my_other_variant int32;
};
或者，您也可以移除名稱重複的成員：
library test.good.fi0097b;
type MyUnion = strict union {
1: my_variant string;
};
序數是用來識別線上的變體。如果兩個成員共用一個一般，就無法在解碼 FIDL 訊息時識別參照哪個變體。
fi-0098
fi-0099
fi-0100
fi-0101：無法解析的大小限制
套用至 vector 或 string 類型定義的大小限制必須是 uint32 類型的有效值：
library test.bad.fi0101a;
alias MyBoundedOptionalVector = vector<uint32>:<"255", optional>;
library test.bad.fi0101b;
alias MyBoundedOptionalVector = vector<uint32>:<uint8, optional>;
請確認下列事項：
library test.good.fi0101;
alias MyBoundedOptionalVector = vector<uint32>:<255, optional>;
fi-0102：無法解析的成員值
bits 和 enum 宣告的成員必須是指定子類型的可解析值：
library test.bad.fi0102;
type Fruit = bits : uint64 {
ORANGE = 1;
APPLE = 2;
BANANA = -4;
};
確認所有值都與宣告的基礎類型相符：
library test.good.fi0102;
type Fruit = bits : uint64 {
ORANGE = 1;
APPLE = 2;
BANANA = 4;
};
fi-0103：無法解析的結構預設值
struct 宣告成員的預設值必須與各自的成員宣告類型相符：
library test.bad.fi0103;
type MyEnum = enum : int32 {
A = 1;
};
type MyStruct = struct {
@allow_deprecated_struct_defaults
field MyEnum = 1;
};
確認值與宣告的類型相符：
library test.good.fi0103;
type MyEnum = enum : int32 {
A = 1;
};
type MyStruct = struct {
@allow_deprecated_struct_defaults
field MyEnum = MyEnum.A;
};
fi-0104：無法解析的屬性引數
根據該引數的屬性結構定義預期，官方FIDL 屬性的值不得無效：
library test.bad.fi0104;
type MyStruct = struct {
my_field @generated_name(true) struct {};
};
請確認要做為屬性引數的值類型正確無誤：
library test.good.fi0104;
type MyStruct = struct {
my_field @generated_name("my_inner_type") struct {};
};
fi-0105
fi-0106
fi-0107：成員值重複
bits 和 enum 宣告都不得含有具有相同值的成員：
library test.bad.fi0107;
type Fruit = flexible enum {
ORANGE = 1;
APPLE = 1;
};
將成員值變更為全部不重複的：
library test.good.fi0107a;
type Fruit = flexible enum {
ORANGE = 1;
APPLE = 2;
};
或者，您也可以移除其中一個重複的成員：
library test.good.fi0107b;
type Fruit = flexible enum {
ORANGE = 1;
};
fi-0108
fi-0109
fi-0110：包含類型的資源必須標示為資源
如要宣告包含控制代碼的類型，無論是直接或透過轉換納入其他控制代碼類型進行轉換，都必須將該類型指定為 resource：
library test.bad.fi0110;
using zx;
type Foo = struct {
handle zx.Handle;
};
有兩種可能的解決方案。第一種是使用資源修飾符為令人反感的宣告加上註解：
library test.good.fi0110a;
using zx;
type Foo = resource struct {
handle zx.Handle;
};
或者，您也可以選擇完全移除 resource 包含類型，因此程式宣告本身必須使用修飾符：
library test.good.fi0110b;
type Foo = struct {
value uint32;
};
想瞭解新增 resource 修飾符之後的原因和動機，以及這項錯誤強制執行的使用模式「產生感染性」性質，請參閱 RFC-0057：Default no handle 中。
fi-0111：內嵌大小超過限制
不允許內嵌大小為 64 KiB 以上的 FIDL 類型：
library test.bad.fi0111;
type MyStruct = struct {
numbers array<uint8, 65536>;
};
而是確認型別的內嵌大小小於 64 KiB。在此情況下，我們可以調整陣列邊界：
library test.good.fi0111;
type MyStruct = struct {
numbers array<uint8, 65535>;
};
系統基於效能考量而設有這項限制。這表示編碼器和解碼器會假設大小和位移符合未簽署的 16 位元整數。
除非您使用大型陣列或深度巢狀結構，否則不太可能實際執行此操作。大部分的 FIDL 結構 (例如字串、向量、資料表和聯集) 使用多行儲存空間，這不會計入各自的內嵌大小。
fi-0112：服務成員不是client_end
服務成員只能是用戶端結束，不得為任何其他類型：
library test.bad.fi0112;
protocol Calculator {};
service Service {
calculator server_end:Calculator;
};
如要修正錯誤，請確認成員對於某些通訊協定 P 的格式為 client_end:P：
library test.good.fi0112;
protocol Calculator {};
service Service {
calculator client_end:Calculator;
};
服務是一組通訊協定執行個體，而非一般用途的資料結構，因此允許任意類型的情況下並不合理。
fi-0113：服務中的運輸不一致
FIDL 服務不得含有使用不同傳輸的通訊協定：
library test.bad.fi0113;
protocol ChannelProtocol {};
@transport("Driver")
protocol DriverProtocol {};
service SomeService {
a client_end:ChannelProtocol;
b client_end:DriverProtocol;
};
請針對每種傳輸方式，使用不同的服務：
library test.good.fi0113;
protocol ChannelProtocol {};
@transport("Driver")
protocol DriverProtocol {};
service ChannelService {
protocol client_end:ChannelProtocol;
};
service DriverService {
protocol client_end:DriverProtocol;
};
請注意，服務是 FIDL 中未完成的功能。這些 API 最初是在 RFC-0041：支援統合服務和裝置中設計。如要瞭解截至 2022 年 10 月的狀態，請參閱 https://fxbug.dev/42160684。
fi-0114：Composed 通訊協定過於開放
通訊協定無法組合其他比自身開啟的通訊協定：
library test.bad.fi0114;
open protocol Composed {};
ajar protocol Composing {
compose Composed;
};
如要修正此問題，請提高撰寫通訊協定的開放性 (例如從 closed 變更為 ajar 或從 ajar 變更為 open)：
library test.good.fi0114a;
open protocol Composed {};
open protocol Composing {
compose Composed;
};
您也可以減少組合通訊協定的開放性，例如將其從 open 變更為 ajar，或者從 ajar 變更為 closed：
library test.good.fi0114b;
ajar protocol Composed {};
ajar protocol Composing {
compose Composed;
};
之所以會有這項規則，是因為通訊協定的開放性會限制其允許包含的方法種類。例如，ajar 通訊協定不能包含彈性的雙向方法，但開放式通訊協定可以，因此使用 ajar 通訊協定組合開放式通訊協定並不安全。
如要進一步瞭解通訊協定修飾符，請參閱 RFC-0138：處理不明互動。
fi-0115： 彈性的雙向方法需要開放通訊協定
封閉式通訊協定和 ajar 通訊協定不得包含彈性的雙向方法：
library test.bad.fi0115;
ajar protocol Protocol {
flexible Method() -> ();
};
請改為標記雙向方法 strict，而不是 flexible：
library test.good.fi0115a;
ajar protocol Protocol {
strict Method() -> ();
};
您也可以標示通訊協定 open，而不是 closed 或 ajar：
library test.good.fi0115b;
open protocol Protocol {
flexible Method() -> ();
};
之所以發生這個錯誤，是因為 closed (或 ajar) 修飾符的目的是確保方法不含任何彈性 (雙向) 方法。首次建立通訊協定時，請根據所需的易變屬性仔細思考應設為關閉、ajar 或開放式。
如要進一步瞭解通訊協定修飾符，請參閱 RFC-0138：處理不明互動。
fi-0116： 彈性的單向方法需要 ajar 或開放式通訊協定
封閉通訊協定不得含有彈性的單向方法：
library test.bad.fi0116;
closed protocol Protocol {
flexible Method();
};
請改為標記單向方法 strict，而不是 flexible：
library test.good.fi0116;
closed protocol Protocol {
strict Method();
};
此外，您也可以將通訊協定 ajar 或 open 標示為通訊協定，而不是 closed：
library test.good.fi0116;
ajar protocol Protocol {
flexible Method();
};
之所以發生這個錯誤，是因為 closed 修飾符的目的是確保方法不含任何彈性方法。首次建立通訊協定時，請根據所需的易變性屬性仔細思考該通訊協定是關閉、ajar 或開放式。
如要進一步瞭解通訊協定修飾符，請參閱 RFC-0138：處理不明互動。
fi-0117：不相容的傳輸控制代碼
通訊協定只能參照與傳輸協定相容的帳號代碼。例如，Zircon 管道傳輸的通訊協定不得參照 Fuuchsia 驅動程式架構控制代碼：
library test.bad.fi0117;
using fdf;
protocol Protocol {
Method(resource struct {
h fdf.handle;
});
};
請改用與通訊協定傳輸作業相容的控點：
library test.good.fi0117a;
using zx;
protocol Protocol {
Method(resource struct {
h zx.Handle;
});
};
或者，您也可以變更通訊協定的傳輸方式來比對控點：
library test.good.fi0117b;
using fdf;
@transport("Driver")
protocol Protocol {
Method(resource struct {
h fdf.handle;
});
};
fi-0118：使用不相容的交通運輸終點
通訊協定只能參照透過同一傳輸通訊協定傳輸通訊協定的端點 (client_end 和 server_end)。舉例來說，使用 Syscall 傳輸的通訊協定不能透過驅動程式傳輸來參照通訊協定的用戶端端：
library test.bad.fi0118;
@transport("Driver")
protocol DriverProtocol {};
@transport("Syscall")
protocol P {
M(resource struct {
s client_end:DriverProtocol;
});
};
如要修正錯誤，請移除運輸最終成員：
library test.good.fi0118;
@transport("Driver")
protocol DriverProtocol {};
@transport("Syscall")
protocol Protocol {
M();
};
fi-0119：事件中的錯誤語法已淘汰
允許使用錯誤語法的事件，但現已淘汰：
library example;
protocol MyProtocol {
-> OnMyEvent() error int32;
};
請改為指定不含錯誤的事件：
library test.good.fi0119a;
protocol MyProtocol {
-> OnMyEvent();
};
或者，也可改用聯集模型來建立錯誤模型：
library test.good.fi0119b;
protocol MyProtocol {
-> OnMyEvent(flexible union {
1: success struct {};
2: error uint32;
});
};
在淘汰事件前使用錯誤語法與事件，是相當不尋常的做法。事件是由伺服器啟動，且伺服器向用戶端傳送來路不明的失敗。建議您針對這些罕見用途使用聯集，而不要在所有繫結中支援語言功能。
fi-0120：屬性刊登位置無效
部分官方屬性只能在特定位置使用。舉例來說，@selector 屬性只能用於方法：
library test.bad.fi0120a;
@selector("Nonsense")
type MyUnion = union {
1: hello uint8;
};
如要修正錯誤，請移除這項屬性：
library test.good.fi0120a;
type MyUnion = union {
1: hello uint8;
};
如果您打算以系統支援的方式使用屬性，但是將屬性放在錯誤的位置，則可能也會遇到這個錯誤。舉例來說，@generated_name 屬性無法直接屬於成員：
library test.bad.fi0120a;
@selector("Nonsense")
type MyUnion = union {
1: hello uint8;
};
而應該安插在成員的匿名版面配置之前：
library test.good.fi0120a;
type MyUnion = union {
1: hello uint8;
};
fi-0121：已淘汰的屬性
部分官方屬性已淘汰，不應再使用：
library test.bad.fi0121;
@example_deprecated_attribute
type MyStruct = struct {};
修正方式取決於屬性淘汰的原因。舉例來說，錯誤訊息可能會顯示使用其他屬性。在這種情況下，我們可以只移除屬性：
library test.good.fi0121;
type MyStruct = struct {};
fi-0122：重複的屬性名稱
元素不得有多個名稱相同的屬性：
library test.bad.fi0122;
@custom_attribute("first")
@custom_attribute("second")
type Foo = struct {};
因此只要指定每個屬性一次即可：
library test.good.fi0122;
@custom_attribute("first")
type Foo = struct {};
fi-0123：重複的標準屬性名稱
單一元素不得有多個屬性相同的標準名稱：
library test.bad.fi0123;
@custom_attribute("first")
@CustomAttribute("second")
type Foo = struct {};
雖然 custom_attribute 和 CustomAttribute 看起來不同，但都是以「標準」名稱 custom_attribute 表示。您可將原始名稱轉換為 snake_case，以取得正規名稱。
如要修正錯誤，請為每個屬性提供在標準化後不重複的名稱。
library test.good.fi0123;
@custom_attribute("first")
@AnotherCustomAttribute("first")
type Foo = struct {};
如要進一步瞭解為何 FIDL 要求宣告使用不重複的標準名稱，請參閱 fi-0035。
fi-0124：自訂屬性引數必須為字串或布林值
使用者定義 FIDL 屬性上的引數僅限於字串或布林值類型：
library test.bad.fi0124;
@my_custom_attr(foo=1, bar=2.3)
type MyStruct = struct {};
library test.good.fi0124;
@my_custom_attr(foo=true, bar="baz")
type MyStruct = struct {};
與官方屬性不同，編譯器不知道使用者定義屬性的結構定義。因此，編譯器無法推斷任何指定數字引數的類型，例如 2、int8、uint64 或 float32？沒有方法讓編譯器知道。
為解決這個問題，可行的解決方法是在 JSON IR 中實作一流的 numeric 類型，以處理這類模稜兩可的情況。不過，由於自訂屬性引數是目前唯一已知的用途，因此尚未優先考慮這項功能。
fi-0125：屬性引數不可命名為
使用接受單一引數的官方屬性時，您無法為該引數命名：
library test.bad.fi0125;
@discoverable(value="example.Bar")
protocol Foo {};
相反地，您應該傳送引數但不要為其指定名稱：
library test.good.fi0125;
@discoverable("example.Bar")
protocol Foo {};
FIDL 會強制執行這種作法，讓屬性更簡潔一致。實際上，引數名稱會推論為 value (這會顯示在 JSON IR 中)，因為這是該屬性使用的唯一引數。
fi-0126：屬性引數必須命名為
如果您使用的官方屬性需要多個引數，則無法傳送未命名的引數：
@available(1)
library test.bad.fi0126;
請改為指定引數名稱：
@available(added=1)
library test.good.fi0126;
之所以發生這個錯誤，是因為如果屬性接受多個引數，就無法得知您要設定的引數。
fi-0127：缺少必要屬性引數
如果使用具有必要引數的官方屬性，則無法省略：
library test.bad.fi0127;
@has_required_arg
type Foo = struct {};
請改為提供必要的引數：
library test.good.fi0127;
@has_required_arg(required="something")
type Foo = struct {};
fi-0128：缺少單一屬性引數
當使用需要單一引數的官方屬性時，您無法省略該屬性：
library test.bad.fi0128;
@transport
protocol Protocol {};
而是改為提供引數：
library test.good.fi0128;
@transport("Driver")
protocol Protocol {};
fi-0129：未知的屬性引數
使用官方屬性時，您無法提供不在其結構定義中的引數：
@available(added=1, discontinued=2)
library test.bad.fi0129;
假如您要傳遞其他引數但名稱有誤，請變更該引數以使用正確的名稱：
@available(added=1, deprecated=2)
library test.good.fi0129a;
或者，您也可以移除引數：
@available(added=1)
library test.good.fi0129b;
發生這個錯誤，是因為官方屬性是根據結構定義進行驗證。如果 FIDL 允許任意引數，則不會有任何作用，並且可能會藉由遮蓋錯字而發生錯誤。
fi-0130：重複的屬性引數
一個屬性不能有兩個名稱相同的引數：
library test.bad.fi0130;
@custom_attribute(custom_arg=true, custom_arg=true)
type Foo = struct {};
只需要提供一個具備該名稱的引數：
library test.good.fi0130;
@custom_attribute(custom_arg=true)
type Foo = struct {};
fi-0131：重複的標準屬性引數
一個屬性不得有兩個具有相同正規名稱的引數：
library test.bad.fi0131;
@custom_attribute(custom_arg=true, CustomArg=true)
type Foo = struct {};
雖然 custom_arg 和 CustomArg 看起來不同，但兩者都是「標準」名稱 custom_arg 表示。您可將原始名稱轉換為 snake_case，以取得正規名稱。
如要修正錯誤，請為每個引數提供在標準化後不重複的名稱：
library test.good.fi0131a;
@custom_attribute(custom_arg=true, AnotherCustomArg=true)
type Foo = struct {};
或者，您也可以移除其中一個引數：
library test.good.fi0131b;
@custom_attribute(custom_arg=true)
type Foo = struct {};
如要進一步瞭解為何 FIDL 要求宣告使用不重複的標準名稱，請參閱 fi-0035。
fi-0132：非預期的屬性引數
使用不含引數的官方屬性時，您無法提供引數：
library test.bad.fi0132;
type Foo = flexible enum : uint8 {
@unknown("hello")
BAR = 1;
};
請改為移除以下引數：
library test.good.fi0132;
type Foo = flexible enum : uint8 {
@unknown
BAR = 1;
};
fi-0133：屬性引數必須為常值
某些官方屬性不允許參照常數的引數：
library test.bad.fi0133;
const NAME string = "MyTable";
type Foo = struct {
bar @generated_name(NAME) table {};
};
請改為傳送常值做為引數：
library test.good.fi0133;
type Foo = struct {
bar @generated_name("MyTable") table {};
};
這些屬性需要文字引數，因為其值會影響編譯。支援非常值引數可能很難實作，或者在某些情況下，由於這會造成衝突。
fi-0134
fi-0135：無效的可探索名稱
如果您為 @discoverable 屬性使用錯誤的名稱，就會發生這項錯誤。@discoverable 屬性應為程式庫名稱，後面接著 . 和通訊協定名稱。
library test.bad.fi0135;
@discoverable("test.bad.fi0135/Parser")
protocol Parser {
Tokenize() -> (struct {
tokens vector<string>;
});
};
如要修正這個錯誤，請使用有效的可探索名稱：
library test.good.fi0135;
@discoverable("test.good.fi0135.Parser")
protocol Parser {
Tokenize() -> (struct {
tokens vector<string>;
});
};
fi-0136
fi-0137
fi-0138
fi-0139
fi-0140
fi-0141：無效的錯誤類型
方法回應酬載的 error 類型必須是 int32、uint32 或 enum：
library test.bad.fi0141;
protocol MyProtocol {
MyMethod() -> () error float32;
};
如要修正這個錯誤，請將 error 類型變更為其中一個有效選項：
library test.good.fi0141;
protocol MyProtocol {
MyMethod() -> () error int32;
};
詳情請參閱「RFC-0060：錯誤處理」。
fi-0142：無效的通訊協定傳輸類型
protocol 宣告中的 @transport(...) 屬性不得指定無效的傳輸方式：
library test.bad.fi0142;
@transport("Invalid")
protocol MyProtocol {
MyMethod();
};
請改用系統支援的其中一種傳輸方式：
library test.good.fi0142;
@transport("Syscall")
protocol MyProtocol {
MyMethod();
};
涵蓋的交通方式仍在最終定案中。詳情請參閱 FIDL 屬性。
fi-0143
fi-0144
fi-0145：屬性錯字
如果屬性名稱的拼字與 FIDL 的其中一個官方屬性太相似，將會導致編譯器警告：
library test.bad.fi0145;
@duc("should be doc")
protocol Example {
Method();
};
在上述範例中，@duc 屬性與官方 FIDL 屬性 @doc 的拼字相似。在這種情況下，屬性命名是刻意設定，而非官方 FIDL 屬性的錯別字，因此應修改為充分唯一：
library test.good.fi0145;
@duck("quack")
protocol Example {
Method();
};
除了拼字檢查以外，這項警告的目的，是避免使用與官方 FIDL 屬性太類似的名稱。
錯字偵測演算法會從每個官方 FIDL 屬性計算屬性名稱的「編輯距離」。如果名稱過於相似 (定義為編輯距離過小)，就會觸發錯字偵測器。
fi-0146：產生的名稱無效
當您使用 @generated_name 屬性的名稱無效時，就會發生這個錯誤。產生的名稱必須遵守與所有 FIDL ID 相同的規則。
library test.bad.fi0146;
type Device = table {
1: kind flexible enum {
DESKTOP = 1;
PHONE = 2;
};
};
type Input = table {
1: kind @generated_name("_kind") flexible enum {
KEYBOARD = 1;
MOUSE = 2;
};
};
如要解決這個問題，請將 @generated_name 值變更為有效的 ID。
library test.good.fi0146;
type Device = table {
1: kind flexible enum {
DESKTOP = 1;
PHONE = 2;
};
};
type Input = table {
1: kind @generated_name("input_kind") flexible enum {
KEYBOARD = 1;
MOUSE = 2;
};
};
fi-0147：@available 缺少引數
如果使用 @available 屬性且未提供必要的引數，就會發生這個錯誤。@available 需要至少一個 added、deprecated 或 removed 其中之一。
@available(added=1)
library test.bad.fi0147;
@available
type Foo = struct {};
如要修正這個問題，請新增下列其中一個必要引數：
@available(added=1)
library test.good.fi0147;
@available(added=2)
type Foo = struct {};
詳情請參閱「FIDL 版本管理」。
fi-0148：不含淘汰的備註
當您在不含 deprecated 引數的 @available 屬性中使用 note 引數時，就會發生這個錯誤。note 僅支援淘汰。
@available(added=1, note="My note")
library test.bad.fi0148;
如要修正這個錯誤，請移除附註：
@available(added=1)
library test.good.fi0148a;
或新增必要的 deprecated 通知：
@available(added=1, deprecated=2, note="Removed in 2; use X instead.")
library test.good.fi0148b;
詳情請參閱「FIDL 版本管理」。
fi-0149：平台不在程式庫中
如果嘗試在程式庫宣告上方以外的位置使用 @available 屬性的 platform 引數，就會發生這個錯誤。platform 引數僅在 library 層級有效。
@available(added=1)
library test.bad.fi0149;
@available(platform="foo")
type Person = struct {
name string;
};
如要修正這個問題，請將 platform 引數移至程式庫 @available 屬性：
@available(added=1, platform="foo")
library test.good.fi0149a;
type Person = struct {
name string;
};
或完全移除 platform 引數：
@available(added=1)
library test.good.fi0149b;
type Person = struct {
name string;
};
fi-0150：缺少程式庫可用性
如果您將 @available 屬性新增至程式庫，但未提供 added 引數，就會發生這個錯誤。library
@available 屬性需要 added 引數。
@available(removed=2)
library test.bad.fi0150a;
@available(platform="foo")
library test.bad.fi0150b;
如要修正這個問題，請將 added 引數新增至程式庫的 @available 屬性：
@available(added=1, removed=2)
library test.good.fi0150a;
@available(added=1, platform="foo")
library test.good.fi0150b;
fi-0151：缺少程式庫可用性
在非 library 宣告中加入 @available 屬性時，如果 library 宣告中沒有 @available 屬性，就會發生這個錯誤。
library test.bad.fi0151;
@available(added=1)
type Person = struct {
name string;
};
如要修正這個錯誤，請在 library 宣告中加入 @available 屬性：
@available(added=1)
library test.good.fi0151a;
@available(added=1)
type Person = struct {
name string;
};
或者從非 library 宣告中移除 @available 屬性：
library test.good.fi0151b;
type Person = struct {
name string;
};
fi-0152：平台無效
當您在 @available 屬性的 platform 引數中使用無效字元時，就會發生這個錯誤。platform 引數必須是有效的 FIDL 程式庫 ID。
@available(added=1, platform="Spaces are not allowed")
library test.bad.fi0152;
如要修正這個錯誤，請移除不允許的字元：
@available(added=1, platform="foo")
library test.good.fi0152;
fi-0153：版本無效
在 @available 屬性的 added 或 removed 引數中使用無效版本時，就會發生這個錯誤。added 和 removed 引數必須是介於 1 至 2^63-1 之間的正整數，或特殊常數 HEAD。
@available(added=0)
library test.bad.fi0153;
如要解決這個問題，請將版本變更為有效值：
@available(added=1)
library test.good.fi0153;
fi-0154：供應情形順序無效
對 @available 屬性使用錯誤的 added、deprecated 和 remove 引數組合時，就會發生這個錯誤。必須遵守下列限制：
added必須小於或等於deprecateddeprecated必須小於removedadded必須小於removed
@available(added=2, removed=2)
library test.bad.fi0154a;
@available(added=2, deprecated=3, removed=3)
library test.bad.fi0154b;
如要修正這個問題，請將 added、deprecated 和 removed 引數更新為所需的順序：
@available(added=1, removed=2)
library test.good.fi0154a;
@available(added=2, deprecated=2, removed=3)
library test.good.fi0154b;
fi-0155：可用性與父項相衝突
如果將 @availability 屬性新增至非 library 的宣告，該宣告與 library 的宣告相衝突，就會發生這個錯誤。
@available(added=2, deprecated=3, removed=4)
library test.bad.fi0155a;
@available(added=1)
type Person = struct {
name string;
};
@available(added=2, deprecated=3, removed=4)
library test.bad.fi0155b;
@available(added=4)
type Person = struct {
name string;
};
如要修正這個錯誤，請將 @availability 屬性更新為必要限制：
@available(added=2, deprecated=3, removed=4)
library test.good.fi0155;
@available(added=2)
type Person = struct {
name string;
};
fi-0156：不可選用
當您嘗試將類型標示為「非必要」無法選用時，就會發生這個錯誤。
library test.bad.fi0156;
type Person = struct {
name string;
age int16:optional;
};
如要修正這項錯誤，請移除選用限制：
library test.good.fi0156;
type Person = struct {
name string;
age int16;
};
只有可以不變更線形形狀的 FIDL 類型允許使用 optional 限制。詳情請參閱「選用」指南或下方可展開的內容。
FIDL 方案：選用
您可以將某些 FIDL 類型設為選用，而不因加入 :optional 限製而變更其所含訊息的線形形狀。此外，table 版面配置一律為選用，但 struct 版面配置一律不會。如要選用 struct，該版面配置必須納入 box<T> 中，藉此變更包含訊息的線形形狀。
| 基礎類型 | 選用版本 | 電線配置是否改變？ |
|---|---|---|
struct {...} |
box<struct {...}> |
是 |
table {...} |
table {...} |
否 |
union {...} |
union {...}:optional |
否 |
vector<T> |
vector<T>:optional |
否 |
string |
string:optional |
否 |
zx.Handle |
zx.Handle:optional |
否 |
client_end:P |
client_end:<P, optional> |
否 |
server_end:P |
server_end:<P, optional> |
否 |
所有其他類型 (bits、enum、array<T, N> 和原始類型) 均無法設為選用。
在這個變數中，我們允許鍵/值存放區將其他鍵/值存放區視為成員。簡單來說，我們把它變成一個樹狀結構。具體做法是將 value 的原始定義替換成使用兩成員 union 的變數：一個變化版本會儲存與先前相同 vector<byte> 類型的分葉節點，另一個變數則會以其他巢狀儲存庫的形式儲存分支節點。
推理
在這裡，我們來看看幾個「選用性」用法，藉此宣告可能存在或不存在的類型。FIDL 中有三種選用變種：
- 類型一律儲存在線外的類型，因此具有透過 null 信封描述「缺失」的內建方法。啟用這些類型的選用功能不會影響訊息的傳輸形狀，只會變更該特定類型有效值。透過新增
:optional限制，union、vector<T>、client_end、server_end和zx.Handle類型都可以設為選用。將valueunion設為選用項目，我們就能以缺少value的形式，引入標準「空值」項目。這表示空白的bytes以及缺少/空白的store屬性是無效的值。 - 與上述類型不同，
struct版面配置並無額外空間，可儲存空值標頭。因此，郵件必須納入信封中，藉此變更所納入訊息的傳輸模式形狀。為確保此線路修改效果清晰易讀，Itemstruct類型必須納入box<T>類型範本中。 - 最後，
table版面配置一律為選用項目。缺少的table只是沒有任何成員設定的項目。
樹狀結構是一種自然的自參照資料結構，樹狀結構中的任何節點可能包含包含純資料的分葉 (在本例中為字串)，或含有更多節點的子樹狀結構。這需要使用遞迴：Item 的定義現在間接依附於本身！在 FIDL 中代表遞迴類型可能有點困難，尤其是因為目前支援有部分限制。只要自我參照建立的週期中至少有一個選用類型，我們就能支援這類類型。舉例來說，這裡我們將 items struct 成員定義為 box<Item>，進而破壞包含週期。
這些變更也會大量使用「匿名類型」，或宣告內嵌於其唯一使用點，而非自行命名的頂層 type 宣告類型。根據預設，在產生的語言繫結中，匿名類型名稱取自本機背景資訊。舉例來說，新推出的 flexible union 會使用其本身成員的名稱 Value，新引入的 struct 會變成 Store，以此類推。由於此經驗法則有時可能會造成衝突，因此 FIDL 允許作者手動覆寫匿名類型的「產生的名稱」，提供一個跳躍點。方法是透過 @generated_name 屬性變更後端產生的名稱。我們可以在這裡使用一個，其中預計的 Store 類型已重新命名為 NestedStore，以避免與 protocol 宣告使用相同名稱的名稱衝突。
實作
FIDL、CML 和領域介面的定義修改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supporttrees;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value strict union {
// Keep the original `bytes` as one of the options in the new union. All leaf nodes in the
// tree must be `bytes`, or absent unions (representing empty). Empty byte arrays are
// disallowed.
1: bytes vector<byte>:64000;
// Allows a store within a store, thereby turning our flat key-value store into a tree
// thereof. Note the use of `@generated_name` to prevent a type-name collision with the
// `Store` protocol below, and the use of `box<T>` to ensure that there is a break in the
// chain of recursion, thereby allowing `Item` to include itself in its own definition.
//
// This is a table so that added fields, like for example a `hash`, can be easily added in
// the future.
2: store @generated_name("nested_store") table {
1: items vector<box<Item>>;
};
}:optional;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
};
CML
用戶端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A newline separated list nested entries. The first line should be the key
// for the nested store, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
write_nested: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A list of keys, all of which will be populated as null entries.
write_null: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
伺服器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "self",
},
],
}
運作範圍
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
接著，用戶端和伺服器實作能以任何支援的語言編寫：
Rust
用戶端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_supporttrees::{Item, NestedStore, StoreMarker, Value},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
let res = store
.write_item(&Item {
key: key.clone(),
value: Some(Box::new(Value::Bytes(value.into_bytes()))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Add nested entries to the key-value store as well. The entries are strings, where the first
// line is the key of the entry, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
for spec in config.write_nested.into_iter() {
let mut items = vec![];
let mut nested_store = NestedStore::default();
let mut lines = spec.split("\n");
let key = lines.next().unwrap();
// For each entry, make a new entry in the `NestedStore` being built.
for entry in lines {
let path = format!("/pkg/data/{}.txt", entry);
let contents = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
items.push(Some(Box::new(Item {
key: entry.to_string(),
value: Some(Box::new(Value::Bytes(contents.into()))),
})));
}
nested_store.items = Some(items);
// Send the `NestedStore`, represented as a vector of values.
let res = store
.write_item(&Item {
key: key.to_string(),
value: Some(Box::new(Value::Store(nested_store))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Each entry in this list is a null value in the store.
for key in config.write_null.into_iter() {
match store.write_item(&Item { key: key.to_string(), value: None }).await? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
伺服器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_supporttrees::{
Item, StoreRequest, StoreRequestStream, Value, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
std::str::from_utf8,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
// A representation of a key-value store that can contain an arbitrarily deep nesting of other
// key-value stores.
#[allow(dead_code)] // TODO(https://fxbug.dev/318827209)
enum StoreNode {
Leaf(Option<Vec<u8>>),
Branch(Box<HashMap<String, StoreNode>>),
}
/// Recursive item writer, which takes a `StoreNode` that may not necessarily be the root node, and
/// writes an entry to it.
fn write_item(
store: &mut HashMap<String, StoreNode>,
attempt: Item,
path: &str,
) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
let key = format!("{}{}", &path, entry.key());
match attempt.value {
// Null entries are allowed.
None => {
println!("Wrote value: NONE at key: {}", key);
entry.insert(StoreNode::Leaf(None));
}
Some(value) => match *value {
// If this is a nested store, recursively make a new store to insert at this
// position.
Value::Store(entry_list) => {
// Validate the value - absent stores, items lists with no children, or any
// of the elements within that list being empty boxes, are all not allowed.
if entry_list.items.is_some() {
let items = entry_list.items.unwrap();
if !items.is_empty() && items.iter().all(|i| i.is_some()) {
let nested_path = format!("{}/", key);
let mut nested_store = HashMap::<String, StoreNode>::new();
for item in items.into_iter() {
write_item(&mut nested_store, *item.unwrap(), &nested_path)?;
}
println!("Created branch at key: {}", key);
entry.insert(StoreNode::Branch(Box::new(nested_store)));
return Ok(());
}
}
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
// This is a simple leaf node on this branch.
Value::Bytes(value) => {
// Validate the value.
if value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
println!("Wrote key: {}, value: {:?}", key, from_utf8(&value).unwrap());
entry.insert(StoreNode::Leaf(Some(value)));
}
},
}
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, StoreNode>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt, ""))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++ (自然)
用戶端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
伺服器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++ (有線)
用戶端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
伺服器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
用戶端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
伺服器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
fi-0157：用戶端/伺服器端限制必須為通訊協定
套用至 client_end 或 server_end 的第一個限制必須指向 protocol 定義：
library test.bad.fi0157;
type MyStruct = struct {};
alias ServerEnd = server_end:MyStruct;
將限制變更為指向通訊協定：
library test.good.fi0157;
protocol MyProtocol {};
alias ServerEnd = server_end:MyProtocol;
fi-0158：無法繫結兩次
alias 宣告無法在其別名的類型上變更已設定的限制值：
library test.bad.fi0158;
alias ByteVec256 = vector<uint8>:256;
alias ByteVec512 = ByteVec256:512;
不受限的定義應接收自己的 alias 宣告，而每個進一步受限的別名應依序繼承該宣告：
library test.good.fi0158;
alias AliasOfVectorOfString = vector<string>;
alias AliasOfVectorOfStringSmall = AliasOfVectorOfString:8;
alias AliasOfVectorOfStringLarge = AliasOfVectorOfString:16;
這可避免造成混淆，編譯器實作時也比較複雜。
fi-0159：結構體無法選用
結構體不得具有 optional 限制：
library test.bad.fi0159;
type Date = struct {
year uint16;
month uint8;
day uint8;
};
type Person = struct {
name string;
birthday Date:optional;
};
將 T:optional 變更為 box<T> 以修正問題：
library test.good.fi0159;
type Date = struct {
year uint16;
month uint8;
day uint8;
};
type Person = struct {
name string;
birthday box<Date>;
};
只有可以不變更線形形狀的 FIDL 類型允許使用 optional 限制。詳情請參閱選用指南。
fi-0160：不能將類型標示為可選兩次
當某個類型設為選用兩次時，就會發生這個錯誤。一般而言，如果類型在其使用和宣告網站上標示為選用類型，就會發生這種情形。
library test.bad.fi0160;
alias MyAlias = vector<string>:optional;
type MyStruct = struct {
my_member MyAlias:optional;
};
如要修正這項錯誤，只需將類型設為「非必要」即可。
例如，您可以從使用網站移除 :optional。
library test.good.fi0160a;
alias MyAlias = vector<string>:optional;
type MyStruct = struct {
my_member MyAlias;
};
您也可以在別名宣告中移除 :optional。
library test.good.fi0160b;
alias MyAlias = vector<string>;
type MyStruct = struct {
my_member MyAlias:optional;
};
fi-0161：大小不得為零
如果嘗試將陣列大小限制設為 0，就會發生這個錯誤。陣列大小不得為零。
library test.bad.fi0161;
type Person = struct {
name string;
nicknames array<string, 0>;
};
如要修正這項錯誤，請將大小限制變更為正整數。
library test.good.fi0161;
type Person = struct {
name string;
nicknames array<string, 5>;
};
fi-0162：版面配置參數數量錯誤
某些 FIDL 版面配置 (例如 vector 和 array) 會採用參數。這項錯誤表示醒目顯示類型的參數數量有誤：
library test.bad.fi0162a;
type Foo = struct {
bar array<8>;
};
若非參數類型類型不小心附加參數，也可能會發生這個情況：
library test.bad.fi0162b;
type Foo = struct {
bar uint8<8>;
};
修正方式一律會為有問題的版面配置指定正確的參數數量：
library test.good.fi0162;
type Foo = struct {
bar array<uint8, 8>;
};
FIDL 中唯一的參數化類型是 array<T, N>、box<T> 和 vector<T>。先前在舊版的 FIDL 語法中參數化的 client_end 和 server_end 類型，但現在已非如此，但這是發生此錯誤時的常見執行來源。這兩種類型現在會將其通訊協定規格改為 (必要) 限制。
一律列在角括號 <...> 中的參數與限制類似，後者會顯示在類型結尾的 :... 字元後方。舉例來說，在第一次汙染時，你可能覺得 array<T, N> 將大小指定為參數，而 vector<T>:N 卻將其大小指定為限制。差別在於參數一律會影響該類型的線路配置形狀，而限制只會變更該類型編碼/解碼時間可接受的值的組合，不會影響傳輸版面配置。
如要深入瞭解這兩個概念之間的區別，請參閱 RFC-0050：FIDL 語法 Revamp。
fi-0163：多項限制定義
當您嘗試使用多個半形冒號 (:) 定義多個限制定義時，就會發生這個錯誤。多項限制定義必須使用角度括號語法 type:<constraint1, constraint2, etc>。
library test.bad.fi0163;
type Person = struct {
name string;
favorite_color string:30:optional;
};
如要修正這項錯誤，請使用角括號語法來設定限制條件：
library test.good.fi0163;
type Person = struct {
name string;
favorite_color string:<30, optional>;
};
fi-0164：太多限制
當您嘗試為類型新增超出支援的限制時，就會發生這個錯誤。舉例來說，string 最多支援兩個限制。
library test.bad.fi0164;
type Person = struct {
name string:<0, optional, 20>;
};
如要修正這個問題，請移除額外限制條件：
library test.good.fi0164;
type Person = struct {
name string:<20, optional>;
};
fi-0165：預期類型
使用常數或通訊協定 ID 時，系統會在 FIDL 預期類型時使用這項錯誤。
library test.bad.fi0165;
type Person = struct {
name string;
nicknames vector<5>;
};
如要修正這個問題，請更新程式碼，改用有效的類型：
library test.good.fi0165;
type Person = struct {
name string;
nicknames vector<string>:5;
};
通訊協定不會視為 FIDL 類型，也無法用於預期類型的地方。
fi-0166：非預期的限制
當您嘗試使用不符合預期的情況時，就會發生這個錯誤。這通常是因為名稱為 const 的位置錯誤。
library test.bad.fi0166;
const MIN_SIZE uint8 = 1;
const MAX_SIZE uint8 = 5;
type Person = struct {
name string;
nicknames vector<string>:<MIN_SIZE, MAX_SIZE>;
};
如要修正這個錯誤，請移除限制：
library test.good.fi0166;
const MAX_SIZE uint8 = 5;
type Person = struct {
name string;
nicknames vector<string>:<MAX_SIZE>;
};
fi-0167：無法限制兩次
如果 client_end 或 server_end 已透過 alias 宣告定義傳輸邊界，則禁止重新指派傳輸繫結：
library test.bad.fi0167;
protocol MyOtherProtocol {};
alias ClientEnd = client_end:MyProtocol;
alias ServerEnd = server_end:MyProtocol;
protocol MyProtocol {
MyMethod(resource struct {
my_client ClientEnd:MyOtherProtocol;
}) -> (resource struct {
my_server ServerEnd:MyOtherProtocol;
});
};
請改為完全避免將 client_end 和 server_end 類型的別名：
library test.good.fi0167;
protocol MyProtocol {
MyMethod(resource struct {
my_client client_end:MyProtocol;
}) -> (resource struct {
my_server server_end:MyProtocol;
});
};
這可避免造成混淆，編譯器實作時也比較複雜。
fi-0168：用戶端/伺服器端必須具備通訊協定限制
套用至 client_end 或 server_end 的第一個限制必須指向 protocol 定義：
library test.bad.fi0168;
protocol MyProtocol {
MyMethod(resource struct {
server server_end;
});
};
新增限制，指向所需通訊協定：
library test.good.fi0168;
protocol MyProtocol {
MyMethod(resource struct {
server server_end:MyProtocol;
});
};
fi-0169：盒裝類型不能為選擇性
「box<T>」形式類型無法套用 optional 限制：
library test.bad.fi0169;
type Color = struct {
red byte;
green byte;
blue byte;
};
type MyStruct = struct {
maybe_color box<Color>:optional;
};
Boxed 類型在定義上是選用項目，因此加入不必要的限制是不必要的，而且多餘：
library test.good.fi0169;
type Color = struct {
red byte;
green byte;
blue byte;
};
type MyStruct = struct {
maybe_color box<Color>;
};
fi-0170
fi-0171：Boxed 類型應改用選用限制
您只能為使用 struct 版面配置的類型加上方框；union、vector、string、client_end、server_end 和 zx.Handle 必須改用 optional 限制：
library test.bad.fi0171;
using zx;
type MyStruct = resource struct {
my_resource_member box<zx.Handle>;
};
將 box<T> 轉換為 T:optional 即可解決這個問題：
library test.good.fi0171;
using zx;
type MyStruct = resource struct {
my_resource_member zx.Handle:optional;
};
只有可以不變更線形形狀的 FIDL 類型允許使用 optional 限制。詳情請參閱「選用」指南或下方可展開的內容。
FIDL 方案：選用
您可以將某些 FIDL 類型設為選用，而不因加入 :optional 限製而變更其所含訊息的線形形狀。此外，table 版面配置一律為選用，但 struct 版面配置一律不會。如要選用 struct，該版面配置必須納入 box<T> 中，藉此變更包含訊息的線形形狀。
| 基礎類型 | 選用版本 | 電線配置是否改變？ |
|---|---|---|
struct {...} |
box<struct {...}> |
是 |
table {...} |
table {...} |
否 |
union {...} |
union {...}:optional |
否 |
vector<T> |
vector<T>:optional |
否 |
string |
string:optional |
否 |
zx.Handle |
zx.Handle:optional |
否 |
client_end:P |
client_end:<P, optional> |
否 |
server_end:P |
server_end:<P, optional> |
否 |
所有其他類型 (bits、enum、array<T, N> 和原始類型) 均無法設為選用。
在這個變數中，我們允許鍵/值存放區將其他鍵/值存放區視為成員。簡單來說，我們把它變成一個樹狀結構。具體做法是將 value 的原始定義替換成使用兩成員 union 的變數：一個變化版本會儲存與先前相同 vector<byte> 類型的分葉節點，另一個變數則會以其他巢狀儲存庫的形式儲存分支節點。
推理
在這裡，我們來看看幾個「選用性」用法，藉此宣告可能存在或不存在的類型。FIDL 中有三種選用變種：
- 類型一律儲存在線外的類型，因此具有透過 null 信封描述「缺失」的內建方法。啟用這些類型的選用功能不會影響訊息的傳輸形狀，只會變更該特定類型有效值。透過新增
:optional限制，union、vector<T>、client_end、server_end和zx.Handle類型都可以設為選用。將valueunion設為選用項目，我們就能以缺少value的形式，引入標準「空值」項目。這表示空白的bytes以及缺少/空白的store屬性是無效的值。 - 與上述類型不同，
struct版面配置並無額外空間，可儲存空值標頭。因此，郵件必須納入信封中，藉此變更所納入訊息的傳輸模式形狀。為確保此線路修改效果清晰易讀，Itemstruct類型必須納入box<T>類型範本中。 - 最後，
table版面配置一律為選用項目。缺少的table只是沒有任何成員設定的項目。
樹狀結構是一種自然的自參照資料結構，樹狀結構中的任何節點可能包含包含純資料的分葉 (在本例中為字串)，或含有更多節點的子樹狀結構。這需要使用遞迴：Item 的定義現在間接依附於本身！在 FIDL 中代表遞迴類型可能有點困難，尤其是因為目前支援有部分限制。只要自我參照建立的週期中至少有一個選用類型，我們就能支援這類類型。舉例來說，這裡我們將 items struct 成員定義為 box<Item>，進而破壞包含週期。
這些變更也會大量使用「匿名類型」，或宣告內嵌於其唯一使用點，而非自行命名的頂層 type 宣告類型。根據預設，在產生的語言繫結中，匿名類型名稱取自本機背景資訊。舉例來說，新推出的 flexible union 會使用其本身成員的名稱 Value，新引入的 struct 會變成 Store，以此類推。由於此經驗法則有時可能會造成衝突，因此 FIDL 允許作者手動覆寫匿名類型的「產生的名稱」，提供一個跳躍點。方法是透過 @generated_name 屬性變更後端產生的名稱。我們可以在這裡使用一個，其中預計的 Store 類型已重新命名為 NestedStore，以避免與 protocol 宣告使用相同名稱的名稱衝突。
實作
FIDL、CML 和領域介面的定義修改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supporttrees;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value strict union {
// Keep the original `bytes` as one of the options in the new union. All leaf nodes in the
// tree must be `bytes`, or absent unions (representing empty). Empty byte arrays are
// disallowed.
1: bytes vector<byte>:64000;
// Allows a store within a store, thereby turning our flat key-value store into a tree
// thereof. Note the use of `@generated_name` to prevent a type-name collision with the
// `Store` protocol below, and the use of `box<T>` to ensure that there is a break in the
// chain of recursion, thereby allowing `Item` to include itself in its own definition.
//
// This is a table so that added fields, like for example a `hash`, can be easily added in
// the future.
2: store @generated_name("nested_store") table {
1: items vector<box<Item>>;
};
}:optional;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
};
CML
用戶端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A newline separated list nested entries. The first line should be the key
// for the nested store, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
write_nested: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A list of keys, all of which will be populated as null entries.
write_null: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
伺服器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "self",
},
],
}
運作範圍
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
接著，用戶端和伺服器實作能以任何支援的語言編寫：
Rust
用戶端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_supporttrees::{Item, NestedStore, StoreMarker, Value},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
let res = store
.write_item(&Item {
key: key.clone(),
value: Some(Box::new(Value::Bytes(value.into_bytes()))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Add nested entries to the key-value store as well. The entries are strings, where the first
// line is the key of the entry, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
for spec in config.write_nested.into_iter() {
let mut items = vec![];
let mut nested_store = NestedStore::default();
let mut lines = spec.split("\n");
let key = lines.next().unwrap();
// For each entry, make a new entry in the `NestedStore` being built.
for entry in lines {
let path = format!("/pkg/data/{}.txt", entry);
let contents = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
items.push(Some(Box::new(Item {
key: entry.to_string(),
value: Some(Box::new(Value::Bytes(contents.into()))),
})));
}
nested_store.items = Some(items);
// Send the `NestedStore`, represented as a vector of values.
let res = store
.write_item(&Item {
key: key.to_string(),
value: Some(Box::new(Value::Store(nested_store))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Each entry in this list is a null value in the store.
for key in config.write_null.into_iter() {
match store.write_item(&Item { key: key.to_string(), value: None }).await? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
伺服器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_supporttrees::{
Item, StoreRequest, StoreRequestStream, Value, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
std::str::from_utf8,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
// A representation of a key-value store that can contain an arbitrarily deep nesting of other
// key-value stores.
#[allow(dead_code)] // TODO(https://fxbug.dev/318827209)
enum StoreNode {
Leaf(Option<Vec<u8>>),
Branch(Box<HashMap<String, StoreNode>>),
}
/// Recursive item writer, which takes a `StoreNode` that may not necessarily be the root node, and
/// writes an entry to it.
fn write_item(
store: &mut HashMap<String, StoreNode>,
attempt: Item,
path: &str,
) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
let key = format!("{}{}", &path, entry.key());
match attempt.value {
// Null entries are allowed.
None => {
println!("Wrote value: NONE at key: {}", key);
entry.insert(StoreNode::Leaf(None));
}
Some(value) => match *value {
// If this is a nested store, recursively make a new store to insert at this
// position.
Value::Store(entry_list) => {
// Validate the value - absent stores, items lists with no children, or any
// of the elements within that list being empty boxes, are all not allowed.
if entry_list.items.is_some() {
let items = entry_list.items.unwrap();
if !items.is_empty() && items.iter().all(|i| i.is_some()) {
let nested_path = format!("{}/", key);
let mut nested_store = HashMap::<String, StoreNode>::new();
for item in items.into_iter() {
write_item(&mut nested_store, *item.unwrap(), &nested_path)?;
}
println!("Created branch at key: {}", key);
entry.insert(StoreNode::Branch(Box::new(nested_store)));
return Ok(());
}
}
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
// This is a simple leaf node on this branch.
Value::Bytes(value) => {
// Validate the value.
if value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
println!("Wrote key: {}, value: {:?}", key, from_utf8(&value).unwrap());
entry.insert(StoreNode::Leaf(Some(value)));
}
},
}
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, StoreNode>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt, ""))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++ (自然)
用戶端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
伺服器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++ (有線)
用戶端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
伺服器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
用戶端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
伺服器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
fi-0172：資源定義必須使用 uint32 子類型
resource_definition 宣告的子類型必須為 uint32：
library test.bad.fi0172;
type MySubtype = strict enum : uint32 {
NONE = 0;
};
resource_definition MyResource : uint8 {
properties {
subtype MySubtype;
};
};
如要修正這個錯誤，請將子類型變更為 uint32：
library test.good.fi0172;
type MySubtype = strict enum : uint32 {
NONE = 0;
};
resource_definition MyResource : uint32 {
properties {
subtype MySubtype;
};
};
這是與 FIDL 內部實作相關的錯誤，因此應該只會向使用 FIDL 核心程式庫的開發人員顯示。使用者應該永遠不會看到這個錯誤。
所參照的 resource_definition 宣告是 FIDL 的內部方式，用於定義處理等資源，且日後可能會隨著處理一般化作業的一部分改變。
fi-0173：資源定義必須指定子類型
resource_definition 宣告無法省略 subtype 成員：
library test.bad.fi0173;
resource_definition MyResource : uint32 {
properties {
rights uint32;
};
};
將這個成員指向有效的 enum : uint32 宣告：
library test.good.fi0173;
resource_definition MyResource : uint32 {
properties {
subtype flexible enum : uint32 {};
rights uint32;
};
};
這是與 FIDL 內部實作相關的錯誤，因此應該只會向使用 FIDL 核心程式庫的開發人員顯示。使用者應該永遠不會看到這個錯誤。
所參照的 resource_definition 宣告是 FIDL 的內部方式，用於定義處理等資源，且日後可能會隨著處理一般化作業的一部分改變。
fi-0174
fi-0175：資源定義子類型屬性必須參照列舉
resource_definition 宣告無法使用非 enum 做為 subtype 成員：
library test.bad.fi0175;
resource_definition MyResource : uint32 {
properties {
subtype struct {};
};
};
將這個成員指向有效的 enum : uint32 宣告：
library test.good.fi0175;
resource_definition MyResource : uint32 {
properties {
subtype flexible enum : uint32 {};
};
};
這是與 FIDL 內部實作相關的錯誤，因此應該只會向使用 FIDL 核心程式庫的開發人員顯示。使用者應該永遠不會看到這個錯誤。
所參照的 resource_definition 宣告是 FIDL 的內部方式，用於定義處理等資源，且日後可能會隨著處理一般化作業的一部分改變。
fi-0176
fi-0177：資源定義權限屬性必須參照位元
resource_definition 宣告無法使用非 bits 做為 rights 成員：
library test.bad.fi0177;
type MySubtype = enum : uint32 {
NONE = 0;
VMO = 3;
};
resource_definition MyResource : uint32 {
properties {
subtype MySubtype;
rights string;
};
};
將這個成員指向有效的 bits : uint32 宣告：
library test.good.fi0177;
type MySubtype = enum : uint32 {
NONE = 0;
VMO = 3;
};
resource_definition MyResource : uint32 {
properties {
subtype MySubtype;
rights uint32;
};
};
這是與 FIDL 內部實作相關的錯誤，因此應該只會向使用 FIDL 核心程式庫的開發人員顯示。使用者應該永遠不會看到這個錯誤。
所參照的 resource_definition 宣告是 FIDL 的內部方式，用於定義處理等資源，且日後可能會隨著處理一般化作業的一部分改變。
fi-0178：未使用的匯入
未參照透過 using 宣告匯入的依附元件會發生錯誤：
library test.bad.fi0178;
using dependent;
type Foo = struct {
does_not int64;
use_dependent int32;
};
藉由實際參照匯入或移除未使用的依附元件，確保程式庫匯入作業中的所有這類匯入項目：
library test.good.fi0178;
using dependent;
type Foo = struct {
dep dependent.Bar;
};
fi-0179：Newtypes 無法受限
來自 RFC-0052：類型別名和新類型的新類型沒有限制。舉例來說，全新 string 類型不得與 :optional 設限：
library test.bad.fi0179;
type Name = string;
type Info = struct {
name Name:optional;
};
在這種情況下，我們可以將 name 欄位設為選用欄位，做法是將欄位放在資料表而非結構中：
library test.good.fi0179;
type Name = string;
type Info = table {
1: name Name;
};
這項限制簡化了新類型的設計。至於受限的新型類型，API 和 ABI 大致上應該是什麼樣子 (例如，限制是否應套用至新類型本身，還是要導向基礎類型？)。
fi-0180：Zircon C 類型為實驗性質
我們正在針對 Zither 專案開發內建類型 usize、uintptr、uchar 和 experimental_pointer。這些屬性無法用於一般 FIDL 程式庫：
library test.bad.fi0180;
type Data = struct {
size usize64;
};
請改用其他類型，例如 uint64 而不是 usize：
library test.good.fi0180;
type Data = struct {
size uint64;
};
fi-0181：程式庫屬性引數參照常數
程式庫宣告的屬性引數不得參照常數：
@custom_attribute(VALUE)
library test.bad.fi0181a;
const VALUE string = "hello";
請改為提供常值引數：
@custom_attribute("hello")
library test.good.fi0181a;
這項限制之所以存在，是因為在少數情況下，支援這個做法會讓編譯器增加無謂的複雜性。
fi-0182：舊版僅適用於已移除的元素
從未移除的元素 (直接或透過繼承) 不得為 @available 屬性提供 legacy 引數：
@available(added=1)
library test.bad.fi0182;
protocol Foo {
@available(added=2, legacy=true)
Bar() -> ();
};
而是應該移除 legacy 引數：
@available(added=1)
library test.good.fi0182a;
protocol Foo {
@available(added=2)
Bar() -> ();
};
您也可以保留 legacy 引數，但新增 removed 引數：
@available(added=1)
library test.good.fi0182b;
protocol Foo {
@available(added=2, removed=3, legacy=true)
Bar() -> ();
};
legacy 引數會指出元素移除後是否應加回 LEGACY 版本，因此在從未移除的元素中使用這個元素並不合理。詳情請參閱 legacy 的說明文件。
fi-0183：舊版與父項衝突
如果子項元素的父項在沒有舊版支援的情況下遭到移除，則無法將子元素標示為 legacy=true：
@available(added=1)
library test.bad.fi0183;
@available(removed=3)
protocol Foo {
@available(added=2, legacy=true)
Bar() -> ();
};
而是應該移除 legacy=true 引數：
@available(added=1)
library test.good.fi0183a;
@available(removed=3)
protocol Foo {
@available(added=2)
Bar() -> ();
};
或者，您也可以將 legacy=true 加入父項。子項會繼承該子項，因此您不必在該處重新指定。請注意，這也會影響父項擁有的任何其他子項。
@available(added=1)
library test.good.fi0183b;
@available(removed=3, legacy=true)
protocol Foo {
@available(added=2)
Bar() -> ();
};
legacy=true 引數表示元素移除後應於 LEGACY 版本加回，而且子項元素不能與父項元素獨立存在。詳情請參閱 legacy 的說明文件。
fi-0184：非預期的控製字元
字串常值不得包含原始控製字元 (從 0x00 到 0x1f 的 ASCII 字元)：
library test.bad.fi0184;
const TAB string = " "; // literal tab character
請改用逸出序列。在本範例中，\t 是正確的：
library test.good.fi0184a;
const TAB string = "\t";
您也可以使用 Unicode 逸出序列。此做法適用於任何 Unicode 碼點：
library test.good.fi0184b;
const TAB string = "\u{9}";
字串常值不允許原始控製字元，因為這些字元都是空白字元或不可列印，因此如果直接嵌入 FIDL 來源檔案，就會造成混淆而難以察覺。
fi-0185：Unicode 逸出序列缺少大括號
字串常值中的萬國碼 (Unicode) 逸出序列必須在括號中指定碼點：
library test.bad.fi0185;
const SMILE string = "\u";
如要修正錯誤，請在大括號中指定碼點：
library test.good.fi0185;
const SMILE string = "\u{1F600}";
fi-0186：萬國碼 (Unicode) 逸出序列未結束
字串常值中的萬國碼 (Unicode) 逸出序列必須終止：
library test.bad.fi0186;
const SMILE string = "\u{1F600";
如要終止逸出序列，請加入右大括號 }：
library test.good.fi0186;
const SMILE string = "\u{1F600}";
fi-0187：空白 Unicode 逸出序列
字串常值的萬國碼 (Unicode) 逸出序列必須包含至少一個十六進位數字：
library test.bad.fi0187;
const SMILE string = "\u{}";
如要修正錯誤，請加入十六進位數字來指定萬國碼 (Unicode) 碼點：
library test.good.fi0187;
const SMILE string = "\u{1F600}";
fi-0188：Unicode 逸出序列中的位數過多
字串常值的萬國碼 (Unicode) 逸出序列不得含有超過 6 個十六進位數字：
library test.bad.fi0188;
const SMILE string = "\u{001F600}";
如要修正錯誤，請指定最多 6 個十六進位數字。在本例中，移除的前 0 個值可能如下：
library test.good.fi0188;
const SMILE string = "\u{1F600}";
之所以會有這項限制，是因為所有有效的 Unicode 碼點皆符合 6 個十六進位數字，所以沒有理由允許超過此數字以上的數字。
fi-0189：Unicode 碼點過大
字串常值中的 Unicode 逸出序列不得指定大於 0x10ffff 上限的 Unicode 碼點：
library test.bad.fi0189;
const TOO_LARGE string = "\u{110000}";
請改為確認碼點是否有效：
library test.good.fi0189;
const MAX_CODEPOINT string = "\u{10ffff}";
fi-0190
fi-0191：方法必須指定嚴格程度
這個錯誤表示 FIDL 方法沒有 strict 或 flexible 修飾符。
library test.bad.fi0191;
open protocol Example {
OneWay();
};
如要修正這個問題，請在方法中加入 strict 或 flexible。如果這是現有的方法，您必須使用 strict。如要瞭解如何將其變更為 flexible，請參閱相容性指南。如果這是新方法，請參閱 API 評分量表，瞭解如何選擇該方法。
library test.good.fi0191;
open protocol Example {
flexible OneWay();
};
FIDL 目前正在進行遷移，以支援處理未知互動 (如 RFC-0138 所定義)。這項新功能可讓修飾符 strict 和 flexible 套用至 FIDL 方法和事件。以往，所有方法的運作方式都與 strict 相同，但在遷移作業結束時，預設值會是 flexible。為避免混淆並避免因將方法預設修飾符從 strict 變更為 flexible 而造成的問題，在這段過渡期間需要使用方法修飾符。遷移作業完成後，這個項目將從錯誤變更為 Linter 建議。
如要進一步瞭解不明互動，請參閱 FIDL 語言參考資料。
fi-0192：通訊協定必須指定開放性
這個錯誤表示 FIDL 通訊協定沒有 open、ajar 或 closed 修飾符。
library test.bad.fi0192;
protocol ImplicitOpenness {};
如要修正這個問題，請在通訊協定中加入 open、ajar 或 closed。如果這是現有的通訊協定，您必須使用 closed，而且應參閱相容性指南，瞭解如何將通訊協定變更為 open 或 ajar。如果這是新方法，請參閱 API 評分量表，瞭解如何選擇該級別。
library test.good.fi0192;
open protocol ImplicitOpenness {};
FIDL 目前正在進行遷移，以支援處理未知互動 (如 RFC-0138 所定義)。這項新功能會新增三個適用於 FIDL 通訊協定的新修飾符 open、ajar 和 closed。以往所有通訊協定的行為就像是 closed，但在遷移作業結束時，預設值會是 open。為避免將通訊協定預設修飾符從 closed 變更為 open 而造成的混淆和可能問題，在此過渡期內需要使用通訊協定修飾符。遷移作業完成後，這個項目將從錯誤變更為 Linter 建議。
如要進一步瞭解不明互動，請參閱 FIDL 語言參考資料。
fi-0193：無法建立方塊類型
除了結構體外，不能加上方塊。舉例來說，您無法針對基本類型加上包裝盒：
library test.bad.fi0193;
type MyStruct = struct {
my_member box<bool>;
};
如要方塊基元，請改用單一成員 struct：
library test.good.fi0193;
type MyStruct = struct {
my_member box<struct {
my_bool bool;
}>;
};
請注意，您可以透過使用 optional 限制，將某些類型設為選用。詳情請參閱「選用」指南或下方可展開的內容。
FIDL 方案：選用
您可以將某些 FIDL 類型設為選用，而不因加入 :optional 限製而變更其所含訊息的線形形狀。此外，table 版面配置一律為選用，但 struct 版面配置一律不會。如要選用 struct，該版面配置必須納入 box<T> 中，藉此變更包含訊息的線形形狀。
| 基礎類型 | 選用版本 | 電線配置是否改變？ |
|---|---|---|
struct {...} |
box<struct {...}> |
是 |
table {...} |
table {...} |
否 |
union {...} |
union {...}:optional |
否 |
vector<T> |
vector<T>:optional |
否 |
string |
string:optional |
否 |
zx.Handle |
zx.Handle:optional |
否 |
client_end:P |
client_end:<P, optional> |
否 |
server_end:P |
server_end:<P, optional> |
否 |
所有其他類型 (bits、enum、array<T, N> 和原始類型) 均無法設為選用。
在這個變數中，我們允許鍵/值存放區將其他鍵/值存放區視為成員。簡單來說，我們把它變成一個樹狀結構。具體做法是將 value 的原始定義替換成使用兩成員 union 的變數：一個變化版本會儲存與先前相同 vector<byte> 類型的分葉節點，另一個變數則會以其他巢狀儲存庫的形式儲存分支節點。
推理
在這裡，我們來看看幾個「選用性」用法，藉此宣告可能存在或不存在的類型。FIDL 中有三種選用變種：
- 類型一律儲存在線外的類型，因此具有透過 null 信封描述「缺失」的內建方法。啟用這些類型的選用功能不會影響訊息的傳輸形狀，只會變更該特定類型有效值。透過新增
:optional限制，union、vector<T>、client_end、server_end和zx.Handle類型都可以設為選用。將valueunion設為選用項目，我們就能以缺少value的形式，引入標準「空值」項目。這表示空白的bytes以及缺少/空白的store屬性是無效的值。 - 與上述類型不同，
struct版面配置並無額外空間，可儲存空值標頭。因此，郵件必須納入信封中，藉此變更所納入訊息的傳輸模式形狀。為確保此線路修改效果清晰易讀，Itemstruct類型必須納入box<T>類型範本中。 - 最後，
table版面配置一律為選用項目。缺少的table只是沒有任何成員設定的項目。
樹狀結構是一種自然的自參照資料結構，樹狀結構中的任何節點可能包含包含純資料的分葉 (在本例中為字串)，或含有更多節點的子樹狀結構。這需要使用遞迴：Item 的定義現在間接依附於本身！在 FIDL 中代表遞迴類型可能有點困難，尤其是因為目前支援有部分限制。只要自我參照建立的週期中至少有一個選用類型，我們就能支援這類類型。舉例來說，這裡我們將 items struct 成員定義為 box<Item>，進而破壞包含週期。
這些變更也會大量使用「匿名類型」，或宣告內嵌於其唯一使用點，而非自行命名的頂層 type 宣告類型。根據預設，在產生的語言繫結中，匿名類型名稱取自本機背景資訊。舉例來說，新推出的 flexible union 會使用其本身成員的名稱 Value，新引入的 struct 會變成 Store，以此類推。由於此經驗法則有時可能會造成衝突，因此 FIDL 允許作者手動覆寫匿名類型的「產生的名稱」，提供一個跳躍點。方法是透過 @generated_name 屬性變更後端產生的名稱。我們可以在這裡使用一個，其中預計的 Store 類型已重新命名為 NestedStore，以避免與 protocol 宣告使用相同名稱的名稱衝突。
實作
FIDL、CML 和領域介面的定義修改如下：
FIDL
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.supporttrees;
/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
key string:128;
value strict union {
// Keep the original `bytes` as one of the options in the new union. All leaf nodes in the
// tree must be `bytes`, or absent unions (representing empty). Empty byte arrays are
// disallowed.
1: bytes vector<byte>:64000;
// Allows a store within a store, thereby turning our flat key-value store into a tree
// thereof. Note the use of `@generated_name` to prevent a type-name collision with the
// `Store` protocol below, and the use of `box<T>` to ensure that there is a break in the
// chain of recursion, thereby allowing `Item` to include itself in its own definition.
//
// This is a table so that added fields, like for example a `hash`, can be easily added in
// the future.
2: store @generated_name("nested_store") table {
1: items vector<box<Item>>;
};
}:optional;
};
/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
UNKNOWN = 0;
INVALID_KEY = 1;
INVALID_VALUE = 2;
ALREADY_EXISTS = 3;
};
/// A very basic key-value store.
@discoverable
open protocol Store {
/// Writes an item to the store.
flexible WriteItem(struct {
attempt Item;
}) -> () error WriteError;
};
CML
用戶端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/client_bin",
},
use: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
config: {
write_items: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A newline separated list nested entries. The first line should be the key
// for the nested store, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
write_nested: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
// A list of keys, all of which will be populated as null entries.
write_null: {
type: "vector",
max_count: 16,
element: {
type: "string",
max_size: 64,
},
},
},
}
伺服器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
include: [ "syslog/client.shard.cml" ],
program: {
runner: "elf",
binary: "bin/server_bin",
},
capabilities: [
{ protocol: "examples.keyvaluestore.supporttrees.Store" },
],
expose: [
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "self",
},
],
}
運作範圍
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
{
children: [
{
name: "client",
url: "#meta/client.cm",
},
{
name: "server",
url: "#meta/server.cm",
},
],
offer: [
// Route the protocol under test from the server to the client.
{
protocol: "examples.keyvaluestore.supporttrees.Store",
from: "#server",
to: "#client",
},
// Route diagnostics support to all children.
{
protocol: [
"fuchsia.inspect.InspectSink",
"fuchsia.logger.LogSink",
],
from: "parent",
to: [
"#client",
"#server",
],
},
],
}
接著，用戶端和伺服器實作能以任何支援的語言編寫：
Rust
用戶端
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
config::Config,
fidl_examples_keyvaluestore_supporttrees::{Item, NestedStore, StoreMarker, Value},
fuchsia_component::client::connect_to_protocol,
std::{thread, time},
};
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Load the structured config values passed to this component at startup.
let config = Config::take_from_startup_handle();
// Use the Component Framework runtime to connect to the newly spun up server component. We wrap
// our retained client end in a proxy object that lets us asynchronously send `Store` requests
// across the channel.
let store = connect_to_protocol::<StoreMarker>()?;
println!("Outgoing connection enabled");
// This client's structured config has one parameter, a vector of strings. Each string is the
// path to a resource file whose filename is a key and whose contents are a value. We iterate
// over them and try to write each key-value pair to the remote store.
for key in config.write_items.into_iter() {
let path = format!("/pkg/data/{}.txt", key);
let value = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
let res = store
.write_item(&Item {
key: key.clone(),
value: Some(Box::new(Value::Bytes(value.into_bytes()))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Add nested entries to the key-value store as well. The entries are strings, where the first
// line is the key of the entry, and each subsequent entry should be a pointer to a text file
// containing the string value. The name of that text file (without the `.txt` suffix) will
// serve as the entries key.
for spec in config.write_nested.into_iter() {
let mut items = vec![];
let mut nested_store = NestedStore::default();
let mut lines = spec.split("\n");
let key = lines.next().unwrap();
// For each entry, make a new entry in the `NestedStore` being built.
for entry in lines {
let path = format!("/pkg/data/{}.txt", entry);
let contents = std::fs::read_to_string(path.clone())
.with_context(|| format!("Failed to load {path}"))?;
items.push(Some(Box::new(Item {
key: entry.to_string(),
value: Some(Box::new(Value::Bytes(contents.into()))),
})));
}
nested_store.items = Some(items);
// Send the `NestedStore`, represented as a vector of values.
let res = store
.write_item(&Item {
key: key.to_string(),
value: Some(Box::new(Value::Store(nested_store))),
})
.await;
match res? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// Each entry in this list is a null value in the store.
for key in config.write_null.into_iter() {
match store.write_item(&Item { key: key.to_string(), value: None }).await? {
Ok(_) => println!("WriteItem Success at key: {}", key),
Err(err) => println!("WriteItem Error: {}", err.into_primitive()),
}
}
// TODO(https://fxbug.dev/42156498): We need to sleep here to make sure all logs get drained. Once the
// referenced bug has been resolved, we can remove the sleep.
thread::sleep(time::Duration::from_secs(2));
Ok(())
}
伺服器
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use {
anyhow::{Context as _, Error},
fidl_examples_keyvaluestore_supporttrees::{
Item, StoreRequest, StoreRequestStream, Value, WriteError,
},
fuchsia_component::server::ServiceFs,
futures::prelude::*,
lazy_static::lazy_static,
regex::Regex,
std::cell::RefCell,
std::collections::hash_map::Entry,
std::collections::HashMap,
std::str::from_utf8,
};
lazy_static! {
static ref KEY_VALIDATION_REGEX: Regex =
Regex::new(r"^[A-Za-z]\w+[A-Za-z0-9]$").expect("Key validation regex failed to compile");
}
// A representation of a key-value store that can contain an arbitrarily deep nesting of other
// key-value stores.
#[allow(dead_code)] // TODO(https://fxbug.dev/318827209)
enum StoreNode {
Leaf(Option<Vec<u8>>),
Branch(Box<HashMap<String, StoreNode>>),
}
/// Recursive item writer, which takes a `StoreNode` that may not necessarily be the root node, and
/// writes an entry to it.
fn write_item(
store: &mut HashMap<String, StoreNode>,
attempt: Item,
path: &str,
) -> Result<(), WriteError> {
// Validate the key.
if !KEY_VALIDATION_REGEX.is_match(attempt.key.as_str()) {
println!("Write error: INVALID_KEY, For key: {}", attempt.key);
return Err(WriteError::InvalidKey);
}
// Write to the store, validating that the key did not already exist.
match store.entry(attempt.key) {
Entry::Occupied(entry) => {
println!("Write error: ALREADY_EXISTS, For key: {}", entry.key());
Err(WriteError::AlreadyExists)
}
Entry::Vacant(entry) => {
let key = format!("{}{}", &path, entry.key());
match attempt.value {
// Null entries are allowed.
None => {
println!("Wrote value: NONE at key: {}", key);
entry.insert(StoreNode::Leaf(None));
}
Some(value) => match *value {
// If this is a nested store, recursively make a new store to insert at this
// position.
Value::Store(entry_list) => {
// Validate the value - absent stores, items lists with no children, or any
// of the elements within that list being empty boxes, are all not allowed.
if entry_list.items.is_some() {
let items = entry_list.items.unwrap();
if !items.is_empty() && items.iter().all(|i| i.is_some()) {
let nested_path = format!("{}/", key);
let mut nested_store = HashMap::<String, StoreNode>::new();
for item in items.into_iter() {
write_item(&mut nested_store, *item.unwrap(), &nested_path)?;
}
println!("Created branch at key: {}", key);
entry.insert(StoreNode::Branch(Box::new(nested_store)));
return Ok(());
}
}
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
// This is a simple leaf node on this branch.
Value::Bytes(value) => {
// Validate the value.
if value.is_empty() {
println!("Write error: INVALID_VALUE, For key: {}", key);
return Err(WriteError::InvalidValue);
}
println!("Wrote key: {}, value: {:?}", key, from_utf8(&value).unwrap());
entry.insert(StoreNode::Leaf(Some(value)));
}
},
}
Ok(())
}
}
}
/// Creates a new instance of the server. Each server has its own bespoke, per-connection instance
/// of the key-value store.
async fn run_server(stream: StoreRequestStream) -> Result<(), Error> {
// Create a new in-memory key-value store. The store will live for the lifetime of the
// connection between the server and this particular client.
let store = RefCell::new(HashMap::<String, StoreNode>::new());
// Serve all requests on the protocol sequentially - a new request is not handled until its
// predecessor has been processed.
stream
.map(|result| result.context("failed request"))
.try_for_each(|request| async {
// Match based on the method being invoked.
match request {
StoreRequest::WriteItem { attempt, responder } => {
println!("WriteItem request received");
// The `responder` parameter is a special struct that manages the outgoing reply
// to this method call. Calling `send` on the responder exactly once will send
// the reply.
responder
.send(write_item(&mut store.borrow_mut(), attempt, ""))
.context("error sending reply")?;
println!("WriteItem response sent");
}
StoreRequest::_UnknownMethod { ordinal, .. } => {
println!("Received an unknown method with ordinal {ordinal}");
}
}
Ok(())
})
.await
}
// A helper enum that allows us to treat a `Store` service instance as a value.
enum IncomingService {
Store(StoreRequestStream),
}
#[fuchsia::main]
async fn main() -> Result<(), Error> {
println!("Started");
// Add a discoverable instance of our `Store` protocol - this will allow the client to see the
// server and connect to it.
let mut fs = ServiceFs::new_local();
fs.dir("svc").add_fidl_service(IncomingService::Store);
fs.take_and_serve_directory_handle()?;
println!("Listening for incoming connections");
// The maximum number of concurrent clients that may be served by this process.
const MAX_CONCURRENT: usize = 10;
// Serve each connection simultaneously, up to the `MAX_CONCURRENT` limit.
fs.for_each_concurrent(MAX_CONCURRENT, |IncomingService::Store(stream)| {
run_server(stream).unwrap_or_else(|e| println!("{:?}", e))
})
.await;
Ok(())
}
C++ (自然)
用戶端
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
伺服器
// TODO(https://fxbug.dev/42060656): C++ (Natural) implementation.
C++ (有線)
用戶端
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
伺服器
// TODO(https://fxbug.dev/42060656): C++ (Wire) implementation.
HLCPP
用戶端
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
伺服器
// TODO(https://fxbug.dev/42060656): HLCPP implementation.
fi-0194
fi-0195
fi-0196
fi-0201：未選取平台版本
如果您在編譯版本化的 FIDL 程式庫時未選擇版本，就會發生這個錯誤：
// fidlc --files test.fidl --out test.json
@available(platform="foo", added=1)
library test.bad.fi0201;
如要修正問題，請選擇具有 --available 指令列旗標的版本：
// fidlc --files test.fidl --out test.json --available foo:1
@available(platform="foo", added=1)
library test.good.fi0201;
版本必須是大於或等於 1 的數字，或其中一個特殊版本 HEAD 和 LEGACY。詳情請參閱 FIDL 版本管理的說明文件。
fi-0202
fi-0203：移除了並取代為互斥
@available 屬性支援引數 removed 和 replaced，但兩者無法搭配使用：
@available(added=1)
library test.bad.fi0203;
protocol Foo {
@available(removed=2, replaced=2)
Foo();
};
如要修正錯誤，請刪除其中一個引數。如果想在不取代元素的情況下移除元素，請保留 removed 並刪除 replaced：
@available(added=1)
library test.good.fi0203a;
open protocol Foo {
@available(removed=2)
strict Foo();
};
或者，如果您要使用新定義「替換」元素，請保留 replaced 並刪除 removed：
@available(added=1)
library test.good.fi0203b;
open protocol Foo {
@available(replaced=2)
strict Foo();
@available(added=2)
flexible Foo();
};
同時使用 removed 和 replaced 沒有意義，因為兩者俱有相反意義。元素標示為 removed 時，fidlc 會驗證「不是」相同版本新增的替換元素。當元素標示為 replaced 時，fidlc 會驗證該元素是否「IS」IS是在同一版本新增的替換元素。
如要進一步瞭解版本管理，請參閱 FIDL 版本管理。
fi-0204：無法替換程式庫
@available 屬性的 replaced 引數無法用於程式庫宣告：
@available(added=1, replaced=2)
library test.bad.fi0204;
請改用 removed 引數：
@available(added=1, removed=2)
library test.good.fi0204;
replaced 引數表示元素已由新的定義取代。這不適用於整個程式庫，因為我們假設每個程式庫都只有一組檔案來定義這個程式庫。
如要進一步瞭解版本管理，請參閱 FIDL 版本管理。
fi-0205：已移除的元素不得包含替換字元
如果元素標示為 @available(removed=N)，表示該元素無法在 N 版本中使用。這應該只是一個標示為 @available(added=N) 的新定義：
@available(added=1)
library test.bad.fi0204;
open protocol Foo {
@available(removed=2)
strict Bar();
@available(added=2)
flexible Bar();
};
如果是刻意取代的，請使用 replaced 引數而不是 removed 引數，以明確表示替換項目：
@available(added=1)
library test.good.fi0204a;
open protocol Foo {
@available(replaced=2)
strict Bar();
@available(added=2)
flexible Bar();
};
如果您無意間替換元素，請移除或重新命名其他元素：
@available(added=1)
library test.good.fi0204b;
open protocol Foo {
@available(removed=2)
strict Bar();
@available(added=2)
flexible NewBar();
};
removed 和 replaced 引數對產生的繫結的影響相同，但代表 API 生命週期中的不同時間點。removed 引數代表 API 的結束，replaced 引數則代表轉換至新定義的轉換。
如要進一步瞭解版本管理，請參閱 FIDL 版本管理。
fi-0206：已取代的元素沒有替代元素
如果元素標示為 @available(replaced=N)，表示該元素會替換成標示為 @available(added=N) 的新定義。如果 FIDL 編譯器找不到下列定義，就會回報錯誤：
@available(added=1)
library test.bad.fi0205;
open protocol Foo {
@available(replaced=2)
strict Bar();
};
如果您無意取代元素，請使用 removed 引數而非 replaced 引數：
@available(added=1)
library test.good.fi0205a;
open protocol Foo {
@available(removed=2)
strict Bar();
};
如要取代元素，請新增替換定義：
@available(added=1)
library test.good.fi0205b;
open protocol Foo {
@available(replaced=2)
strict Bar();
@available(added=2)
flexible Bar();
};
removed 和 replaced 引數對產生的繫結的影響相同，但代表 API 生命週期中的不同時間點。removed 引數代表 API 的結束，replaced 引數則代表轉換至新定義的轉換。
如要進一步瞭解版本管理，請參閱 FIDL 版本管理。
fi-0207：類型整數溢位
FIDL 類型不得過大，導致大小溢位 uint32：
library test.bad.fi0207;
type Foo = struct {
bytes array<uint64, 536870912>;
};
如要修正錯誤，請使用較小的陣列大小：
library test.good.fi0207;
type Foo = struct {
bytes array<uint64, 100>;
};
實際上，FIDL 類型應遠小於 232 個位元組，因為它們通常是透過 Zircon 管道傳送，而這類管道的限制為「每則訊息 64 KiB」。
fi-0208：保留平台
某些平台名稱是由 FIDL 保留。例如，「未版本」平台是保留來代表未使用版本管理的程式庫：
@available(platform="unversioned", added=1)
library test.bad.fi0208;
請改用其他平台名稱：
@available(platform="foo", added=1)
library test.good.fi0208;
如要進一步瞭解版本管理，請參閱 FIDL 版本管理。