This document defines general terms that have a specific meaning in a FIDL context. To learn more about specific FIDL topics, refer to the FIDL traihead
A member of a declaration is an individual element belonging to a declaration, i.e. a declaration is comprised of zero, one, or many members.
For instance, consider the Mode
bits declaration:
{%includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples.docs/misc.test.fidl" region_tag="mode" %}
Both READ
and WRITE
are members.
When referring to members of structs or tables, we can more specifically refer to these members as fields.
When referring to members of a union, we can more specifically refer to these members as variants.
For example, consider the Command
union declaration:
{%includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples.docs/misc.test.fidl" region_tag="command" %}
The two variants are create_resource
and release_resource
.
Furthermore, the selected variant of an instance of a union is the current value held by the union at that moment.
The tag is the target language variant discriminator, i.e. the specific construct in a target language that is used to indicate the selected variant of a union. For example, consider the following TypeScript representation of the Command
union:
enum CommandTag { Create, Release, } interface Command = { tag: CommandTag, data: CreateResource | ReleaseResource, }
The tag of Command
is Command.tag
and has type CommandTag
. The actual values and type representing each variant of Command
are up to the implementation.
Note that some languages will not require a tag. For example, some languages use pattern matching to branch on the variant of a union instead of having an explicit tag value.
The ordinal is the on the wire variant discriminator, i.e. the value used to indicate the variant of a union in the FIDL wire format. The ordinals are explicitly specified in the FIDL definition (in this example, 1 for create_resource
and 2 for release_resource
).
Encoding refers to the process of serializing values from a target language into the FIDL wire format.
For the C family of bindings (HLCPP, LLCPP), encode can have a more specific meaning of taking bytes matching the layout of the FIDL wire format and patching pointers and handles by replacing them with FIDL_ALLOC_PRESENT
/FIDL_ALLOC_ABSENT
or FIDL_HANDLE_PRESENT
/FIDL_HANDLE_ABSENT
in-place, moving handles into an out-of-band handle table.
Decoding refers to the process of deserializing values from raw bytes in the FIDL wire format into a value in a target language.
For the C family of bindings (HLCPP, LLCPP), decode can have a more specific meaning of taking bytes matching the layout of the FIDL wire format and patching pointers and handles by replacing FIDL_ALLOC_PRESENT
/FIDL_ALLOC_ABSENT
or FIDL_HANDLE_PRESENT
/FIDL_HANDLE_ABSENT
with the “real” pointer/handle values in-place, moving handles out of an out-of-band handle table.
Validation is the process of checking if constraints from the FIDL definition are satisfied for a given value. Validation occurs both when encoding a value before being sent, or when decoding a value after receiving it. Example constraints are vector bounds, handle constraints, and the valid encoding of a string as UTF-8.
For methods with error types specified:
DoWork() -> (Data result) error uint32
The result type refers to the entire message that would be received by a server for this method, i.e. the union that consists of either a result of Data
or an error of uint32
. The error type in this case is uint32
, whereas Data
can be referred to as either the response type or the success type.