FIDL 属性

支持以下 FIDL 属性：

范围

属性在 FIDL 元素之前，例如：

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

它用于修改元素的特性或提供文档。

语法

属性可以包含值，并且可以堆叠多个属性，例如：

@discoverable
@transport("Channel")

说明以下两个方面：

  • 有两个属性：@discoverable 和 @transport。
  • @transport 属性从下面枚举的列表中获取一个值。

@available

使用：@available(platform="字符串", added=版本, deprecated=版本, removed=版本, removed=版本, note="字符串", legacy=旧版)

MEANING：所有参数都是可选的，但必须至少提供一个参数。

  • platform：仅当属性位于 library 声明中时允许。必须是有效的库名称元素。如果省略，则默认为库名称的第一个元素。
  • added、deprecated、removed、replaced：必须是 1 到 2^63-1 之间的整数，或特殊常量 HEAD。不得为 LEGACY。
    • removed 和 replaced 是互斥的。
    • 必须遵循 added <= deprecated < removed 或 added <= deprecated < replaced。
  • note：仅当提供了 deprecated 时才允许。应包含简要说明，说明应改用什么内容，适合包含在编译器错误消息中。
  • legacy：仅在提供或继承了 removed 的情况下允许。默认情况下为 false。如果为 true，则该元素包含在 LEGACY 版本中。

如需了解详情，请参阅 FIDL 版本控制。

@deprecated

使用量：@deprecated

含义：请参阅 RFC-0058。

@discoverable

使用：@discoverable(名称)

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

使用量：@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

使用量：@no_doc

MEANING：此属性用于标记文档生成工具应跳过的库。例如，生成的 FIDL 库（如驱动程序绑定编译器）会使用此属性。

@selector

USAGE：@selector("selector")

MEANING：可让您更改方法序数的哈希基础，请参阅 RFC-0020。选择器可以是原始方法的名称（例如 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("说明")

MEANING：指示绑定生成将成功构建的代码，无论相应方法是否已实现。RFC-0021 包含更多详细信息。

@transport

使用情况：@transport("tranportList")

MEANING：允许您选择传输。请提供以英文逗号分隔的值列表，从以下选项中选择：

  • Channel - 使用 Zircon 通道。
  • Syscall - 用于指定用于定义 Zircon 系统调用（而非典型 IPC）的传输。

如果未指定，则默认值为 Channel。 如果您指定了一个或多个值，则系统只会使用这些值（例如，指定 @transport("Foo") 会停用 Channel，而仅使用 Foo）。

@unknown

使用量：@unknown

MEANING：可将 @unknown 放置在枚举成员上，以表明此成员表示特定的未知占位符。其目的是让您能够将手动实现灵活行为（具有额外“未知”成员）的严格枚举转换为灵活枚举：在转换为柔性环境之前，使用 @unknown 属性为表示未知的成员添加注解，可确保 @unknown 成员被视为未知数据，而不是已知成员。移除使用的 @unknown 成员后，就不再需要该成员。