FIDL 編譯器錯誤目錄

本文列出 FIDL 編譯器 fidlc 所產生的所有錯誤。這個網域中的錯誤 ID 一律會以前置字串 fi- 顯示,後面接著四位數代碼,例如 fi-0123

fi-0001:無效字元

字元分析器無法將字元轉換為指定位置的符記。

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:逸出序列無效

分析器在轉義序列開頭遇到無效字元。

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:無效的十六進位數字

字串常值中的 Unicode 逸出不得包含無效的十六進位數字:

library test.bad.fi0004;

const SMILE string = "\u{1G600}";

您必須以十六進制指定有效的 萬國碼碼點,範圍為 0 到 10FFFF。每個 16 進位數字必須為 0 到 9 的數字、小寫字母 af,或大寫字母 AF。在本例中,GF 的錯字:

library test.good.fi0004;

const SMILE string = "\u{1F600}";

fi-0005

fi-0006:預期的宣告

當 FIDL 預期宣告,但找到其他內容時,就會發生這個錯誤。這通常是因為輸入錯誤所致。有效的宣告為:typealiasconstusingprotocolservice

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-Za-z0-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-Za-z0-9),且開頭必須為英文字母。

library test.bad.fi0011.name_with_underscores;

如要修正這個問題,請確認所有程式庫名稱元件都符合規定。

library test.good.fi0011.namewithoutunderscores;

fi-0012:無效的類型版面配置類別

型別宣告必須指定 FIDL 所知的版面配置:

library test.bad.fi00012;

type Foo = invalid {};

有效的版面配置為 bitsenumstructtableunion

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 開始

tableunion 成員序列值不得為 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。不過,彈性資料類型是為了演進而設計,因此定義彈性位元或列舉時,應先將其設為空白,以便日後新增成員。定義新資料類型時,請務必仔細考慮是否要使用 strictflexible

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;

type Foo = @foo struct {};

您必須將屬性放在 type 關鍵字前面:

library test.good.fi0023;

@foo
type Foo = struct {};

我們會強制執行這項規定,因為允許在兩個位置使用屬性會造成混淆。

fi-0024:方法參數清單的文件註解

方法參數清單無法附帶文件註解:

library test.bad.fi0024;

protocol Example {
    Method(/// This is a one-way method.
            struct {
        b bool;
    });
};

目前,請在方法本身上放置文件註解:

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 {};

只有 bitsenum 版面配置會在基礎類型上定義。

library test.good.fi0031;

type Foo = flexible enum : uint32 {};

bitsenum 版面配置有點特別,因為它們只是內建 FIDL 基本元素的受限子型別。因此,建議您指定可充當此子類型的基礎類型。相反地,structtableunion 版面配置可以任意擴大,且可包含許多成員,因此全域版面配置型別就沒有意義。

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;
};

一次只能在單一宣告中使用 strictflexible 其中一個修飾符:

library test.good.fi0033;

type FlexibleFoo = flexible union {
    1: i int32;
};

type StrictBar = strict union {
    1: i int32;
};

目前,只有 strictflexible 修飾符會以這種方式互斥。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 {};

雖然 COLORColor 的外觀不同,但兩者都以標準名稱 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 {};

雖然 COLORColor 的外觀不同,但兩者都以標準名稱 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;

您可以在程式庫名稱中使用多個元件,避免發生這個問題。舉例來說,Fuchsia SDK 中的 FIDL 程式庫開頭為 fuchsia.,因此至少有兩個元件,且不會與宣告名稱衝突。

這個錯誤是為了避免產生歧義。舉例來說,如果 dependency 是具有名為 VALUE 成員的列舉,dependency.VALUE 是指該列舉成員還是在匯入的程式庫中宣告的 const,就會變得模糊不清。

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;

雖然 dependencyDependency 看起來不同,但兩者都以標準名稱 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:未知的程式庫

在大多數情況下,這個問題是因為依附元件拼寫錯誤,或是未由建構系統提供。如果您刻意不使用相關依附元件,請務必移除相關的 using 行:

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

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 不允許組合成員為選用,因為這可能會導致以多種方式表示相同的值。舉例來說,如果聯集有 3 個選用成員,則會有 6 個狀態 (每個成員 2 個)。相反地,您應使用類型為 struct {} 的第四個成員來模擬此類型,或是將整體聯集設為 Foo:optional 的選用項目。

fi-0050:禁止使用已淘汰的結構體預設語法

先前,FIDL 允許在 struct 成員上設定預設值:

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;
};

如要修正這個問題,請使用 using 宣告匯入缺少的依附程式庫。

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:無法參照成員

如果您參照的不是 bitsenum 項目,就會發生這個錯誤。

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:位元/列舉成員無效

如果未先定義 enumbits 成員,就會發生這項錯誤。

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:對已淘汰項目的參照無效

如果您使用與 typeconst 相符的 @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;
};

如要修正這項錯誤,請使用未淘汰的 typeconst

@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:參照已淘汰的其他平台無效

當您使用參照其他平台的 typeconst,但該平台的 @available 屬性不相容時,就會發生這個錯誤。這通常發生在使用已淘汰的 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;
};

如要修正這項錯誤,請使用未淘汰的 typeconst

@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 的例項,以此類推。解決這個問題的方法是透過選項在這個鏈結中加入「中斷點」,這樣一來,您可以選擇編碼另一個 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";

只有 FIDL 原始值 (boolint8int16int32int64uint8uint16uint32uint64float32float64) 和非選用 string 類型可用於 const 宣告的左側。

fi-0060:無法解析常數值

常數值必須能解析為已知值:

library test.bad.fi0060;

const MY_CONST bool = optional;

請確認使用的常數為有效值:

library test.good.fi0060;

const MY_CONST bool = true;

這類錯誤通常會伴隨其他錯誤,這些錯誤會提供無法解析的預期常數性質的更多資訊。

fi-0061:在非基本值上使用 Or 運算子

二元或運算子只能用於原始值:

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:類型別名和新類型中的 Newtype 尚未完全實作,因此無法使用:

library test.bad.fi0062;

type Matrix = array<float64, 9>;

與此同時,您可以定義具有單一元素的結構體,以達到類似的效果:

library test.good.fi0062a;

type Matrix = struct {
    elements array<float64, 9>;
};

或者,您也可以定義別名,但請注意,與 newtype 不同,這不會提供任何類型安全性 (也就是說,它可以與其基礎類型互換使用):

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:位元或列舉值類型不正確

使用 bitsenum 變體做為 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:位元成員必須是 2 的冪

bits 宣告中所有成員的值不得是任何非 2 次方數的數字:

library test.bad.fi0067;

type NonPowerOfTwo = bits : uint64 {
    THREE = 3;
};

相反地,成員值應一律為 2 的冪:

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 結構定義未知的值。此外,彈性列舉一律會保留一些值,這些值會視為未知。根據預設,這個值是該列舉的基礎整數型別 (例如 uint8255) 所能表示的最大數值。

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;
};

請改用下列任一值:uint8uint16uint32uint64

library test.good.fi0069;

type Fruit = bits : uint64 {
    ORANGE = 1;
    APPLE = 2;
    BANANA = 4;
};

enum 宣告可同時接受帶符號和未帶符號的整數 (請參閱 fi-0070),但 bits 宣告只接受未帶符號的整數。這是因為每個 bits 成員都必須代表位元陣列中的特定基礎位元 (這就是 fi-0067 存在的原因)。這項資訊以單一無符號整數的形式呈現最為清晰。無符號整數的二進位表示法會直接對應至單一位元 (2 的索引次方),而有符號整數中的負數幾乎總是會選取多個位元,這是因為兩補數表示法的機制。

fi-0070:列舉必須使用整數子類型

禁止使用非整數的 float32float64 做為 enum 宣告的基礎類型:

library test.bad.fi0070;

type MyEnum = enum : float64 {
    ONE_POINT_FIVE = 1.5;
};

請改用下列任一值:int8int16int32int64uint8uint16uint32uint64

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 所知及處理的不明值 flexible enum。在上述範例中,這會用於從第二個正確用法轉換至第一個用法。

fi-0072:只有列舉成員可以攜帶未知屬性

禁止使用 @unknown 屬性修飾多個 enum 成員:

library test.bad.fi0072;

type MyEnum = flexible enum : uint8 {
    @unknown
    UNKNOWN = 0;
    @unknown
    OTHER = 1;
};

請只選擇並註解用於特定網域的「unknown」值的元素:

library test.good.fi0071a;

type MyEnum = flexible enum : int8 {
    @unknown
    UNKNOWN = 0;
    OTHER = 1;
};

@unknown 屬性的目的,是讓使用者從含有使用者定義不明值的 strict enum 順利轉換至含有不明值的 flexible enum,並由 FIDL 處理:

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:用於方法酬載的版面配置無效

只有 structtableunion 版面配置可用於描述方法酬載:

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);
};

請改用 structtableunion 版面配置類型:

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 必須使用明確的序數

FIDL 編譯器會自動將 fuchsia.io 序數重新命名為 fuchsia.io1。這項魔法旨在讓 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:無法解析的大小限制

套用至 vectorstring 類型定義的大小限制,必須是 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:無法解析的會員值

bitsenum 宣告的元素必須是可解析的值,且屬於指定的子類型:

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:重複的會員值

bitsenum 宣告都不能有值相同的成員:

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:預設無句柄

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;
};

如要修正錯誤,請確認成員具有某些通訊協定 Pclient_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 中尚未完成的功能。這些類別最初是在 RFC-0041:支援統一服務和裝置中設計。如要瞭解 2022 年 10 月的狀態,請參閱 https://fxbug.dev/42160684

fi-0114:組合通訊協定過於開放

一個通訊協定無法組合比自己更開放的其他通訊協定:

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;
};

這個規則的存在原因是,通訊協定的開放程度會限制其可包含哪些方法。舉例來說,半開放式通訊協定無法包含彈性雙向方法,但開放式通訊協定可以,因此半開放式通訊協定無法組合開放式通訊協定。

如要進一步瞭解通訊協定修飾符,請參閱 RFC-0138:處理不明互動

fi-0115:需要開放式通訊協定的彈性雙向方法

封閉和半開放式通訊協定不得包含彈性的雙向方法:

library test.bad.fi0115;

ajar protocol Protocol {
    flexible Method() -> ();
};

請改為標記雙向方法 strict,而非 flexible

library test.good.fi0115a;

ajar protocol Protocol {
    strict Method() -> ();
};

或者,請標記通訊協定 open 而非 closedajar

library test.good.fi0115b;

open protocol Protocol {
    flexible Method() -> ();
};

這個錯誤的發生原因是,closed (或 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();
};

或者,請標記通訊協定 ajaropen,而非 closed

library test.good.fi0116;

ajar protocol Protocol {
    flexible Method();
};

這個錯誤的發生原因是 closed 修飾符的用途是確保方法不含任何彈性方法。首次建立通訊協定時,請根據所需的演進性屬性,仔細考慮是否應將其設為關閉、半開或開放。

如要進一步瞭解通訊協定修飾符,請參閱 RFC-0138:處理不明互動

fi-0117:在相容性不佳的傳輸中使用句柄

通訊協定只能參照與其傳輸相容的句柄。舉例來說,透過 Zircon 管道傳輸的通訊協定無法參照 Fuchsia Driver Framework 句柄:

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_endserver_end)。舉例來說,使用 Syscall 傳輸的通訊協定無法參照使用 Driver 傳輸的通訊協定用戶端端點:

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

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_attributeCustomAttribute 看起來不同,但兩者都以標準名稱 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 {};

官方屬性不同,編譯器不知道使用者定義屬性的結構定義。因此,編譯器無法推斷任何指定數值引數的類型 - 2int8uint64 還是 float32?編譯器無法得知。

解決這個問題的可能方法,是在 JSON IR 中實作第一類 numeric 類型,以便處理這類不確定的情況。不過,由於目前只有自訂屬性引數是這項功能的已知用途,因此我們並未將這項功能列為優先。

fi-0125:屬性引數不得命名

使用官方屬性時,如果該屬性只接受單一引數,您就無法為該引數命名:

library test.bad.fi0125;

@transport(value="Driver")
protocol Foo {};

請改為傳遞引數,但不要為其指定名稱:

library test.good.fi0125;

@discoverable(name="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_argCustomArg 看起來不同,但兩者都以標準名稱 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(name="test.bad.fi0135/Parser")
protocol Parser {
    Tokenize() -> (struct {
        tokens vector<string>;
    });
};

如要修正這項錯誤,請使用有效的探索名稱:

library test.good.fi0135;

@discoverable(name="test.good.fi0135.Parser")
protocol Parser {
    Tokenize() -> (struct {
        tokens vector<string>;
    });
};

fi-0136

fi-0137

fi-0138

fi-0139

fi-0140

fi-0141:錯誤類型無效

方法回應酬載的 error 類型必須是 int32uint32enum

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 識別碼的規則。

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 至少需要 addeddeprecatedremoved 其中一個。

@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:未標示已淘汰的附註

如果您在 @available 屬性中使用 note 引數,但未使用 deprecated 引數,就會發生這類錯誤。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:新增圖書館可用性缺少

如果您在未提供 added 引數的情況下,將 @available 屬性新增至程式庫,就會發生這個錯誤。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 程式庫識別碼

@available(added=1, platform="Spaces are not allowed")
library test.bad.fi0152;

如要修正這項錯誤,請移除不允許使用的字元:

@available(added=1, platform="foo")
library test.good.fi0152;

fi-0153:無效的版本

如果您在 @available 屬性上使用 addedremoved 引數的無效版本,就會發生這個錯誤。addedremoved 引數必須是介於 1 和 2^63-1 之間的正整數,或是特殊常數 HEAD

@available(added=0)
library test.bad.fi0153;

如要修正這個問題,請將版本變更為有效值:

@available(added=1)
library test.good.fi0153;

fi-0154:供應情形順序無效

如果您為 @available 屬性使用 addeddeprecatedremove 引數的錯誤組合,就會發生這個錯誤。必須遵守下列限制:

  • added 必須小於或等於 deprecated
  • deprecated 必須小於 removed
  • added 必須小於 removed
@available(added=2, removed=2)
library test.bad.fi0154a;
@available(added=2, deprecated=3, removed=3)
library test.bad.fi0154b;

如要修正這個問題,請將 addeddeprecatedremoved 引數更新為必要的排序:

@available(added=1, removed=2)
library test.good.fi0154a;
@available(added=2, deprecated=2, removed=3)
library test.good.fi0154b;

fi-0155:可用性與父項衝突

當您在非 library 宣告中新增 @availability 屬性,且與 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 食譜:選用性

您可以透過新增 :optional 限制,讓特定 FIDL 類型變成選用,且不會變更所含訊息的線路形狀。此外,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>

所有其他類型 (bitsenumarray<T, N> 和原始類型) 皆無法設為選用。

在這個變化版本中,我們允許鍵/值存放區將其他鍵/值存放區做為成員。簡而言之,我們會將其轉換為樹狀結構。我們會將 value 的原始定義替換為使用兩個成員 union 的定義:一個變化版本會使用與先前相同的 vector<byte> 類型儲存葉結點,另一個則會以其他巢狀儲存的形式儲存分支節點。

推理

這裡我們會看到幾種 optionality 的用法,我們可以宣告可能存在或不存在的型別。FIDL 中的選用性有三種:

  • 具有此類型的類型一律會在網路上離線儲存,因此具有內建方式,可透過空值封套描述「缺席」。為這些類型啟用選用性不會影響所包含訊息的線路形狀,只會變更哪些值適用於該特定類型。您可以透過新增 :optional 限制,將 unionvector<T>client_endserver_endzx.Handle 類型設為選用。將 value union 設為選用項目後,我們就能以缺少 value 的形式,引入標準的「空值」項目。這表示空白的 bytes 和缺少/空白的 store 屬性是無效的值。
  • 與上述類型不同,struct 版面配置沒有可儲存空值標頭的額外空間。因此,您必須將其包裝在信封中,以便變更所附帶訊息的線上傳輸形狀。為確保這個線路修改效果易於解讀,Item struct 類型必須包裝在 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 s