FIDL Attributes

The following FIDL attributes are supported:

Scope

An attribute preceeds a FIDL element, for example:

[Layout = "Simple"]
protocol MyProtocol {...

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:

[Layout = "Simple", Transport = "Channel"]

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

[Deprecated]

USAGE: [Deprecated]

MEANING: See FTP-013.

[Discoverable]

USAGE: [Discoverable]

MEANING: Causes the service's name to be made available for lookup. A service with a [Discoverable] attribute can be found at run-time. That is to say, you can "request" this service, and zircon will locate it and provide access to it.

[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 MyFooStruct { ...

and

[Doc = "Foo"]
struct MyFooStruct { ...

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.

[FragileBase]

USAGE: [FragileBase]

MEANING: Denotes that the interface can be composed, otherwise it cannot. See also Protocol Composition.

[Internal]

USAGE: [Internal]

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

[Layout]

USAGE: [Layout = "layout"]

MEANING: This attribute currently has one valid value, Simple, and is meaningful only on protocols.

It's used to indicate that all arguments and returns must contain objects that are of a fixed size. The arguments and returns themselves, however, can be dynamically sized strings or vectors of primitives.

To clarify with an example, the following is valid:

[Layout = "Simple"]
protocol MyProtocol {
    DynamicCountOfFixedArguments(vector<uint8>:1024 inputs);
};

Here, the argument is a dynamically sized vector of unsigned 8-bit integers called inputs, with a maximum bound of 1024 elements.

The benefit of [Layout = "Simple"] is that the data can be directly mapped without having to be copied and assembled.

[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.

[Selector]

USAGE: [Selector = "selector"]

MEANING: Allows you to change the hashing basis for the method ordinal, see FTP-020.

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:

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

It can also be used for xunion variants to keep ABI compatibility in the same way.

[Transitional]

USAGE: [Transitional = "description"]

MEANING: Instructs bindings to generate code that will successfully build, regardless of whether the method is implemented or not. FTP-021 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).