Fuchsia

Protocol capabilities

<<../../_v2_banner.md>>

A protocol capability is a capability backed by a glossary.channel that speaks a particular FIDL protocol.

Note: Protocol and service capabilities are distinct types of capabilities. A protocol capability represents a single instance of a FIDL protocol, while a service capability represents zero or more instances of a FIDL service. See the documentation on service capabilities for more details.

Providing protocol capabilities

To provide a protocol capability, a component must define the capability and route it from self. The component hosts the protocol capability in its FIDL outgoing directory.

To define the capability, add a capabilities declaration for it:

{
    capabilities: [
        {
            protocol: "fuchsia.example.ExampleProtocol",
        },
    ],
}

This defines a capability hosted by this component whose outgoing directory path is /svc/fuchsia.example.ExampleProtocol. You can also customize the path:

{
    capabilities: [
        {
            protocol: "fuchsia.example.ExampleProtocol",
            path: "/my_svc/fuchsia.example.MyExampleProtocol",
        },
    ],
}

Routing protocol capabilities

Components route protocol capabilities by exposing them to their parent and offering them to their children.

Exposing

Exposing a protocol capability gives the component's parent access to that capability. This is done through an expose declaration.

{
    expose: [
        {
            protocol: "fuchsia.example.ExampleProtocol",
            from: "self",
        },
    ],
}

The from: "self" directive means that the protocol capability is provided by this component. In this case the protocol must have a corresponding definition.

Offering

Offering a protocol capability gives a child component access to that capability. This is done through an offer declaration.

{
    offer: [
        {
            protocol: "fuchsia.example.ExampleProtocol",
            from: "self",
            to: [ "#child-a", "#child_b" ],
        },
    ],
}

Consuming protocol capabilities

When a component uses a protocol capability that has been offered to it, that protocol is made available through the component's namespace.

Consider a component with the following manifest declaration:

{
    use: [
        {
            protocol: "fuchsia.example.ExampleProtocol",
        },
    ],
}

When the component attempts to open the path /svc/fuchsia.example.ExampleProtocol, the component framework performs capability routing to find the component that provides this protocol. Then, the framework connects the newly opened channel to this provider.

You can also customize the namespace path:

{
    use: [
        {
            protocol: "fuchsia.example.ExampleProtocol",
            path: "/my_svc/fuchsia.example.MyExampleProtocol",
        },
    ],
}

For more information about the open request, see life of a protocol open.

Note: For a working example of routing a protocol capability between components, see //examples/components/routing.

Framework protocols

A framework protocol is a protocol provided by the component framework. Any component may use these capabilities by setting framework as the source without an accompanying offer from its parent. Fuchsia supports the following framework protocols:

{
    use: [
        {
            protocol: "fuchsia.sys2.Realm",
            from: "framework",
        },
    ],
}