<<../../_v2_banner.md>>
A [protocol capability][glossary.protocol capability] allows 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 protocols, while a service represents zero or more instances of a FIDL service. See the documentation on service capabilities for more details.
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", }, ], }
Components route protocol capabilities by either [exposing] or [offering] them.
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 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" ], }, ], }
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
.
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", }, ], }