FIDL 屬性

支援的 FIDL 屬性如下:

範圍

FIDL 元素前面的屬性,例如:

@doc(" MyType summary\n")
type MyType = struct {

用於修改元素特性或提供說明文件。

語法

屬性可能包含值,多個屬性可能會堆疊,例如:

@discoverable
@transport("Channel")

同時說明以下兩個層面:

  • 有兩個屬性:@discoverable@transport,以及
  • @transport 屬性會從下方列舉的清單取得值。

@available

USAGE@available(platform="string", added=版本, deprecated=版本, removed=版本, removed=版本, note="字串", legacy=舊版)

MEANING:所有引數都是選用引數,但必須提供至少一個引數。

  • platform:只有在屬性出現在 library 宣告中時才能使用。必須是有效的程式庫名稱元素。如果省略,則會預設為程式庫名稱的第一個元素。
  • addeddeprecatedremovedreplaced:必須是介於 1 到 2^63-1 之間的整數,或是特殊常數 HEAD。不得為 LEGACY
    • removedreplaced 互斥,無法共同存在。
    • 必須遵循 added <= deprecated < removedadded <= deprecated < replaced
  • note:只有在提供 deprecated 的情況下才允許。提供簡短的說明,指示您改用哪些功能,適合包含在編譯器錯誤訊息中。
  • legacy:只有在提供或沿用 removed 的情況下才允許。預設值為 False。如為 true,該元素會包含 LEGACY 版本。

詳情請參閱 FIDL 版本管理

@deprecated

USAGE@deprecated

MEANING:請參閱 RFC-0058

@discoverable

USAGE@discoverable(name)

MEANING:指派用於服務探索的名稱。也就是說,@discoverable 通訊協定可以使用指定的名稱提供,而連線至該通訊協定的用戶端則可使用相同名稱搜尋該通訊協定。如此便可在用戶端搜尋正確的名稱,而不需手動確保查詢名稱與伺服器端傳遞的名稱相符。

如果省略 name,系統會根據程式庫和通訊協定名稱 (例如 some.library.SomeProtocol) 產生名稱。如果提供「name」,則必須採用相同格式。請注意,這「不是」完整名稱,而是使用斜線 (例如 some.library/SomeProtocol)。

@doc

USAGE@doc("string")

MEANING:在 FIDL 中,註解的開頭可以有兩個 (「//」) 或三個斜線 (「///」),也可以在 @doc 屬性中納入這些項目。雙斜線變化版本不會將註解傳播至產生的目標,而三斜線和 @doc 變體則會同時套用。

如下所示:

/// Foo
type WithThreeSlashes = struct {

@doc("Foo")
type WithAttribute = struct {

達到相同效果,其中一個 (「///」) 是彼此的語法糖。註解文字會發送到產生的程式碼,運作方式與譯文語言的語法相容。

@generated_name

USAGE@generated_name("Foo")

MEANING:這個屬性用來覆寫 fidlc 為所有內嵌版面配置保留的名稱。當您偏好使用其他名稱時,這項功能就很實用 (例如避免與其他類型名稱衝突)。

舉例來說,以下程式碼會導致名稱衝突,因為這兩個內嵌版面配置都會保留相同的 Options 名稱:

table StartupConfig {
  1: options table {
    ...
  };
  ...
};

table TeardownConfig {
  2: options table {
    ...
  };
};

要區分兩者之間的一種方法,是手動指定不同的產生名稱:

table StartupConfig {
  1: options
  @generated_name("StartupOptions") table {
    ...
  };
  ...
};

table TeardownConfig {
  1: options
  @generated_name("TeardownOptions") table {
    ...
  };
  ...
};

@no_doc

USAGE@no_doc

MEANING:這個屬性是用來標示文件產生工具應略過的程式庫。舉例來說,這個屬性由產生的 FIDL 程式庫 (例如驅動程式繫結編譯器) 使用。

@selector

USAGE@selector("選取器")

MEANING:可讓您變更方法序數的雜湊基礎,請參閱 RFC-0020selector 可以是原始方法的名稱 (例如 SomeMethod) 或完整名稱

可用於在不影響 ABI 相容性的情況下重新命名方法。舉例來說,如果想在 Science 介面中將 Investigate 方法重新命名為 Experiment,我們可以編寫:

protocol Science {
    @selector("Investigate")
    Experiment();
};

這項屬性也可用來處理從某個通訊協定移至另一個通訊協定,或移至另一個程式庫的方法,或兩者並用。舉例來說,假設在 purple.examples.docs 程式庫的 fuchsia.examples.docs 程式庫中,Org 通訊協定上的 Org 通訊協定原本在 Area120 通訊協定上命名為 DiscoverProductionize

protocol Org {
    @selector("purple.examples.docs/Area120.Discover")
    Productionize();
};

@transitional

USAGE@transitional("description")

MEANING:指示繫結產生可成功建構的程式碼,無論是否實作方法都一樣。RFC-0021 包含更多詳細資料。

@transport

USAGE@transport("tranportList")

MEANING:可讓您選取傳輸。請提供以逗號分隔的值清單,選項如下:

  • Channel — 使用 Zircon 頻道
  • Syscall:用來指定通訊協定用於定義 Zircon syscall (而非一般 IPC) 的傳輸機制。

如未指定,則預設值為 Channel。如果指定值或值,則系統只會使用這些值 (例如指定 @transport("Foo") 會停用 Channel,且只使用 Foo)。

@unknown

USAGE@unknown

MEANING:您可以將 @unknown 置於列舉成員中,表示此成員代表特定的未知預留位置。其用意是將以「未知」成員手動實作的嚴格行為,轉換為手動實作的嚴格列舉,轉換為彈性列舉:在轉換為彈性前,使用 @unknown 屬性將代表未知的成員加上註解,確保 @unknown 成員會視為不明資料,而不是當做已知成員。移除 @unknown 成員的使用後,就不再需要該成員。