FIDL 屬性

系統支援下列 FIDL 屬性：

• @available
• @deprecated
• @discoverable
• @doc
• @generated_name
• @no_doc
• @selector
• @transitional
• @transport
• @unknown

範圍

FIDL 元素之前的屬性，例如：

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

用於修改元素的特性，或提供文件。

語法

屬性可以包含值，且多個屬性可以堆疊，例如：

@discoverable
@transport("Channel")

說明這兩個方面：

• 其中包含 @discoverable 和 @transport 這兩個屬性。
• @transport 屬性會採用下方列舉的值。

@available

USAGE：@available(platform="字串", added=版本, deprecated=版本, removed=版本, replaced=版本, renamed="字串", note="字串")

MEANING：所有引數皆為選用，但至少要提供 added=、deprecated、removed 或 replaced 其中一個引數。

• platform：只有在屬性位於 library 宣告中時才能使用。必須是有效的資料庫名稱元素。如果省略，則預設為程式庫名稱的第一個元素。
• added、deprecated、removed、replaced：必須是 1 到 2^31-1 (含) 之間的整數，或其中一個特殊常數 NEXT 和 HEAD。
  • removed 和 replaced 互斥。
  • 必須遵循 added <= deprecated < removed 或 added <= deprecated < replaced。
• renamed：只有在已提供 removed 或 replaced 的情況下才能使用。指定元素遭移除或取代後的新名稱。
• note：只有在提供了 deprecated、removed 或 replaced 時，才需要提供。應包含簡要說明，指出建議使用的內容，適用於編譯器警告或錯誤訊息中。

詳情請參閱「FIDL 版本管理」。

@deprecated

用法：@deprecated

意義：請參閱 RFC-0058。

@discoverable

USAGE：@discoverable(name=name)

MEANING：指派用於服務探索的名稱。也就是說，@discoverable 通訊協定可在指定名稱下方提供服務，而連線至該通訊協定的用戶端可在相同名稱下方搜尋。如此一來，用戶端搜尋就能搜尋正確的名稱，而無須手動確保查詢名稱與伺服器端傳遞的名稱相符。

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

@discoverable 名稱也由 fuchsia.unknown/Queryable 使用，可為已刪除類型的通道啟用動態通訊協定解析。舉例來說，如果用戶端的 Zircon 管道類型未類型，但知道伺服器實作了 Queryable，則可使用 fuchsia.unknown/Queryable.Query 方法取得具體的通訊協定類型。

@doc

USAGE：@doc("字串")

意義：在 FIDL 中，註解可以以兩個 ("//") 或三個反斜線 ("///") 開頭，也可以包含在 @doc 屬性中。兩個斜線變化版本不會將註解傳播至產生的目標，但三個斜線和 @doc 變化版本會。

具體說明如下：

/// Foo
type WithThreeSlashes = struct {

和

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

具有相同效果，其中一個 (///) 是另一個的語法糖。註解的文字將傳送至產生的程式碼，且與目標語言的語法相容。

@generated_name

用法：@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

意義：這個屬性用於標示說明文件產生工具應略過的程式庫。舉例來說，產生的 FIDL 程式庫會使用此屬性，例如驅動程式繫結編譯器。

@selector

用法：@selector("selector")

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

可用於重新命名方法，而不會破壞 ABI 相容性。舉例來說，如要將 Science 介面中的 Investigate 方法重新命名為 Experiment，則可以編寫：

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

這個屬性也可以用來處理從一個通訊協定移至另一個通訊協定，或從一個程式庫移至另一個程式庫的做法，甚至兩者皆是。舉例來說，請考慮 fuchsia.examples.docs 程式庫中 Org 通訊協定上的 Productionize 方法，該方法在 purple.examples.docs 程式庫中 Area120 通訊協定上原本的名稱為 Discover：

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

@transitional

用法：@transitional("description")

意義：指示繫結產生可成功建構的程式碼，無論方法是否已實作皆可。RFC-0021 包含更多詳細資料。

@transport

用法：@transport("tranportList")

意義：允許您選取運算法。請提供從下列來源選取的值 (以半形逗號分隔)：

• Channel - 使用 Zircon 頻道。
• Syscall：用來指定通訊協定用於定義 Zircon Scalls (而非一般處理序間通訊 (IPC)) 的傳輸機制。

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

@unknown

用法：@unknown

MEANING：@unknown 可放在列舉成員上，以表示該成員代表特定的未知預留位置。其目的是讓您可以將手動實作彈性行為的嚴格列舉，透過額外的「unknown」成員轉換為彈性列舉：在轉換為彈性列舉之前，使用 @unknown 屬性為代表 unknown 的成員加上註解，可確保 @unknown 成員會視為 unknown 資料，而非已知成員。移除 @unknown 成員的用法後，就不再需要該成員。