Google is committed to advancing racial equity for Black communities. See how.

FIDL attributes

The following FIDL attributes are supported:

Scope

An attribute precedes a FIDL element, for example:

[MaxBytes = "64"]
struct MyType {

It's used to either modify the characteristics of the element, or provide documentation.

Syntax

Attributes may include multiple values, and multiple attributes may be specified in the same element, for example:

[Discoverable, Transport = "Channel"]

Illustrates both aspects: * there are two attributes, Discoverable and Transport, and * the Transport attribute takes a value from the list enumerated below.

[Deprecated]

USAGE: [Deprecated]

MEANING: See RFC-0058.

[Discoverable]

USAGE: [Discoverable]

MEANING: Automatically generates a path name for the annotated protocol. That is to say, a [Discoverable] protocol can be served under the generated name, and clients that connect to that protocol can search for it under the same generated name. This makes it possible to have a client search for the correct name without manually ensuring that the lookup name matches the one passed on the server side.

[Doc]

USAGE: [Doc = "string"]

MEANING: In FIDL, comments can start with two ("//") or three slashes ("///"), or they can be embodied within a [Doc] attribute. The two-slash variant does not propagate the comments to the generated target, whereas both the three-slash and [Doc] variants do.

That is:

/// Foo
struct WithThreeSlashes {

and

[Doc = "Foo"]
struct WithAttribute {

have the same effect — one ("///") is syntactic sugar for the other. The text of the comment is emitted into the generated code, in a manner compatible with the syntax of the target language.

[Internal]

USAGE: [Internal]

MEANING: This marks internal libraries, such as library zx. It should be used only by Fuchsia developers.

[ForDeprecatedCBindings]

USAGE: [ForDeprecatedCBindings]

MEANING: This attribute is used to ensure that a protocol is compatible with the deprecated C bindings. There should be no new uses of this attribute.

[ForDeprecatedCBindings]
protocol SimpleProtocol {
    DynamicCountOfFixedArguments(vector<uint8>:1024 inputs);
};

[MaxBytes]

USAGE: [MaxBytes = "number"]

MEANING: This attribute is used to limit the number of bytes that can be transferred in a message. The compiler will issue an error if the number of bytes exceeds this limit.

[MaxHandles]

USAGE: [MaxHandles = "number"]

MEANING: This attribute is used to limit the number of handles that can be transferred in a message. The compiler will issue an error if the number of handles exceeds this limit.

[NoDoc]

USAGE: [NoDoc]

MEANING: This attribute is used to mark libraries that should be skipped by documentation generation tools. As an example, this attribute is used by generated FIDL libraries, such as by the driver bind compiler.

[Selector]

USAGE: [Selector = "selector"]

MEANING: Allows you to change the hashing basis for the method ordinal, see RFC-0020. The selector can be either the original method's name (e.g. SomeMethod), or the fully qualified name (e.g. some.library/SomeProtocol.SomeMethod).

It can be used to rename a method without breaking ABI compatibility. For example, if we wish to rename the Investigate method to Experiment in the Science interface, we can write:

protocol Science {
    [Selector = "Investigate"] Experiment();
};

The attribute can also be used to handle a method moving from one protocol to another, or to one library to another, or both. For example, consider the method Productionize on the Org protocol in the fuchsia.examples.docs library which was originally named Discover on the Area120 protocol, in the purple.examples.docs library:

protocol Org {
    [Selector = "purple.examples.docs/Area120.Discover"] Productionize();
};

[Transitional]

USAGE: [Transitional = "description"]

MEANING: Instructs bindings to generate code that will successfully build, regardless of whether the method is implemented or not. RFC-0021 contains more details.

[Transport]

USAGE: [Transport = "tranportList"]

MEANING: Allows you to select a transport. Provide a comma-separated list of values, selected from:

  • Channel — use a Zircon channel.
  • Syscall — transport used to specify that the protocol is used to define Zircon syscalls, rather than typical IPC.

The default is Channel if none specified. If you do specify a value or values, then only those values are used (e.g., specifying [Transport="Foo"] disables Channel and uses only Foo).

[Unknown]

USAGE: [Unknown]

MEANING: [Unknown] can be placed on an enum member to indicate that this member represents a specific unknown placeholder. Its purpose is to make it possible to transition a strict enum that was manually implementing flexible behavior with an extra "unknown" member to transition into a flexible enum: annotating the member representing unknown with the [Unknown] attribute before transitioning to flexible ensures that the [Unknown] member is treated as unknown data, instead of as a known member. Once usages of the [Unknown] member are removed, the member is no longer necessary.