FIDL 属性

支持以下 FIDL 属性：

范围

属性在 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： 所有参数都是可选的，但必须至少提供一个。

  • platform：仅当属性位于 library 声明中时允许使用。 必须是有效的库名称元素。如果省略，则默认为 库名称的第一个元素。
  • added、deprecated、removed、replaced：必须是 1 到 1 之间的整数 2^31-1（含边界值）或特殊常量 NEXT 和 HEAD 之一。
    • removed 和 replaced 是互斥的。
    • 必须遵从 added <= deprecated < removed 或 added <= deprecated < replaced。
  • renamed：仅在提供了 removed 或 replaced 时允许。指定 元素的新名称。
  • note：仅在提供了 deprecated 时允许。应包含简介 说明应改用什么内容，适合包含在 编译器错误消息。

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

@deprecated

USAGE：@deprecated

MEANING： 请参阅 RFC-0058。

@discoverable

USAGE：@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("字符串")

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-0020。 selector 可以是原始方法的名称（例如 SomeMethod）， 或完全限定名称。

它可用于重命名方法，而不会破坏 ABI 兼容性。 例如，如果要将 Investigate 方法重命名为 Experiment 在 Science 接口中，我们可以编写以下代码：

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

该属性还可用于处理从一种协议迁移到 和/或从一个库复制到另一个库例如，考虑使用 针对 fuchsia.examples.docs 库中的 Org 协议的 Productionize 它最初在 Area120 协议中命名为 Discover， purple.examples.docs 库：

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

@transitional

USAGE：@transitional("说明")

MEANING： 指示绑定生成无论如何构建都能成功构建的代码 该方法是否已实现。 RFC-0021 包含更多详细信息。

@transport

USAGE：@transport("tranportList")

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

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

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

@unknown

USAGE：@unknown

MEANING： 可以将 @unknown 放在枚举成员上，以表示该成员代表 特定的未知占位符其目的是使系统能够将严格枚举 是手动实现灵活行为“未知”成员 转换为灵活枚举：为表示未知成员的成员添加注解 在转换为弹性方案之前使用 @unknown 属性可确保 系统会将 @unknown 成员视为未知数据，而不是 已知成员。一旦移除了使用的 @unknown 成员，该成员将 。