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 声明中时允许使用。 必须是有效的库名称元素。如果省略,则默认为 库名称的第一个元素。
  • addeddeprecatedremovedreplaced:必须是 1 到 1 之间的整数 2^31-1(含边界值)或特殊常量 NEXTHEAD 之一。
    • removedreplaced 是互斥的。
    • 必须遵从 added <= deprecated < removedadded <= deprecated < replaced
  • renamed:仅在提供了 removedreplaced 时允许。指定 元素的新名称。
  • 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 通道,但知道服务器会实现 Queryablefuchsia.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-0020selector 可以是原始方法的名称(例如 SomeMethod), 或完全限定名称

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

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

该属性还可用于处理从一种协议迁移到 和/或从一个库复制到另一个库例如,考虑使用 针对 fuchsia.examples.docs 库中的 Org 协议的 Productionize 它最初在 Area120 协议中命名为 Discoverpurple.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 成员,该成员将 。