支持以下 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
使用:@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
成员后,就不再需要该成员。