Protocol capabilities

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

library fuchsia.examples;

const MAX_STRING_LENGTH uint64 = 32;

@discoverable
protocol Echo {
    EchoString(struct {
        value string:MAX_STRING_LENGTH;
    }) -> (struct {
        response string:MAX_STRING_LENGTH;
    });
    SendString(struct {
        value string:MAX_STRING_LENGTH;
    });
    -> OnString(struct {
        response string:MAX_STRING_LENGTH;
    });
};

Protocol implementations are served from provider components using the outgoing directory and consumed from another component's namespace .

Providing protocol capabilities

To provide a protocol capability, a component must declare 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 exposing them to their parent and offering them to their children.

For more details on how the framework routes component capabilities, see capability routing.

Exposing

Exposing a protocol capability gives the component's parent access to that capability:

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

The from: "self" directive means that the protocol capability is provided by this component.

Offering

Offering a protocol capability gives a child component access to that capability:

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

Consuming protocol capabilities

To consume a protocol capability, the component must request the capability and open the corresponding path in its namespace .

To request the capability, add a use declaration for it:

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

This populates the protocol in the component's namespace at the well-known path /svc/fuchsia.example.ExampleProtocol. You can also customize the 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.

Consuming optional protocol capabilities

See Connect Components: Consuming optional capabilities.

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.component.Realm",
            from: "framework",
        },
    ],
}