Protocol capabilities (Components v2)

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

Protocol capabilities allow components to connect to FIDL protocols provided either by other components or the component framework itself.

Note: Protocol and service capabilities are distinct types of capabilities. A protocol represents a single instance of a FIDL protocol, while a service 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 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 either:

• exposing them,
• or offering them.

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.

For a working example of routing a protocol capability from one component to another, see //examples/components/routing.

Consuming protocol capabilities provided by the framework

Some protocol capabilities are provided by the component framework, and thus can be used by components without their parents offering them.

For a list of these protocols and what they can be used for, see framework protocols.

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