FIDL 属性

支持以下 FIDL 属性：

范围

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

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

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

语法

属性可以包括值，多个属性可以堆叠在一起，例如：

@discoverable
@transport("Channel")

说明了以下两个方面：

  • 有两个属性：@discoverable 和 @transport，并且
  • @transport 属性采用下方列表中的值。

@available

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

含义：所有参数都是可选的，但必须提供 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

用法：@discoverable(name=name)

MEANING：分配用于服务发现的名称。也就是说，@discoverable 协议可在指定名称下提供，连接到该协议的客户端可在相同名称下搜索该协议。这样，客户端就可以搜索正确的名称，而无需手动确保查找名称与服务器端传递的名称一致。

如果省略 name，则系统会根据库和协议名称（例如 some.library.SomeProtocol）生成一个名称。如果提供了 name，则它必须遵循相同的格式。请注意，这不是完全限定名称，后者会使用斜线（例如 some.library/SomeProtocol）。

fuchsia.unknown/Queryable 也会使用 @discoverable 名称为已清除的通道类型启用动态协议解析。例如，如果客户端具有未类型的 Zircon 通道，但知道服务器实现 Queryable，则可以使用 fuchsia.unknown/Queryable.Query 方法获取具体的协议类型。

@doc

USAGE：@doc("字符串")

含义：在 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

用法：@no_doc

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

@selector

用法：@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("说明")

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

@transport

USAGE：@transport("tranportList")

MEANING：可让您选择传输。请提供以逗号分隔的值列表，可供选择的值包括：

  • Channel - 使用 Zircon 通道。
  • Syscall - 用于指定该协议用于定义 Zircon 系统调用，而不是典型的 IPC 的传输。

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

@unknown

用法：@unknown

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