docs/concepts/components/v2/capabilities/protocol.md

# Protocol capabilities

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

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

```fidl
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;
    });
};
```

Note: For more details on FIDL protocol syntax, see the
[FIDL language reference][fidl-reference].

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

## Providing protocol capabilities {#provide}

To provide a protocol capability, a component must declare the capability and
[route](#route) it from `self`. The component hosts the protocol capability in
its [outgoing directory][glossary.outgoing-directory].

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

```json5
{
    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:

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

## Routing protocol capabilities {#route}

Components route protocol capabilities by [exposing](#expose) them to their
parent and [offering](#offer) them to their children.

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

### Exposing {#expose}

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

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

The `from: "self"` directive means that the protocol capability is
[provided](#provide) by this component.

### Offering {#offer}

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

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

## Consuming protocol capabilities {#consume}

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

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

```json5
{
    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:

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

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

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

## Framework protocols {#framework}

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:

-   [`fuchsia.component.Realm`][fidl-realm]: Allows a component to manage and bind to
    its children. Scoped to the component's realm.
-   [`fuchsia.component.Binder`][fidl-binder]: Allows a component to start
    another component.

```json5
{
    use: [
        {
            protocol: "fuchsia.component.Realm",
            from: "framework",
        },
    ],
}
```

[glossary.namespace]: /docs/glossary/README.md#namespace
[glossary.outgoing-directory]: /docs/glossary/README.md#outgoing-directory
[glossary.channel]: /docs/glossary/README.md#channel
[glossary.protocol]: /docs/glossary/README.md#protocol
[glossary.protocol-capability]: /docs/glossary/README.md#protocol-capability
[capability-routing]: /docs/concepts/components/v2/component_manifests.md#capability-routing
[fidl-reference]: /docs/reference/fidl/language/language.md
[fidl-binder]: /sdk/fidl/fuchsia.component/binder.fidl
[fidl-realm]: /sdk/fidl/fuchsia.component/realm.fidl
[life-of-a-protocol-open]: /docs/concepts/components/v2/capabilities/life_of_a_protocol_open.md
[routing-example]: /examples/components/routing