Service capabilities

A service capability is a capability that enables discovery of one or more individually named FIDL service instances. Service capabilities are backed by a Channel that speaks the Directory protocol, where each entry in the directory exposes a named service instance.

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

service EchoService {
    regular_echo client_end:Echo;
    reversed_echo client_end:Echo;
};

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

Service instances

Multiple named instances of a service can be hosted by a single component. These are present in the namespace of the consuming component as subdirectories of the service. The component framework generates an arbitrary, unique identifier for each service instance name.

For example, if the framework generates 57dfe118a2a8 as the instance name of the fuchsia.examples.EchoService service, a consuming component could connect to the protocols in that instance using the following namespace paths:

• /svc/fuchsia.examples.EchoService/57dfe118a2a8/regular_echo
• /svc/fuchsia.examples.EchoService/57dfe118a2a8/reversed_echo

Providing service capabilities

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

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

{
    capabilities: [
        {
            service: "fuchsia.example.ExampleService",
        },
    ],
}

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

{
    capabilities: [
        {
            service: "fuchsia.example.ExampleService",
            path: "/my_svc/fuchsia.example.MyExampleService",
        },
    ],
}

Routing service capabilities

Components route service 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 service capability gives the component's parent access to that capability:

{
    expose: [
        {
            service: "fuchsia.example.ExampleService",
            from: "self",
        },
    ],
}

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

Dynamic collections

A service capability can be exposed from a dynamic collection:

{
    collections: [
        {
            name: "coll",
            durability: "transient",
        },
    ],
    expose: [
        {
            service: "fuchsia.example.ExampleService",
            from: "#coll",
        },
    ],
}

Offering

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

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

Consuming service capabilities

To consume a service 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: [
        {
            service: "fuchsia.example.ExampleService",
        },
    ],
}

This populates the service in the component's namespace at the well-known path /svc/fuchsia.example.ExampleService. You can also customize the path:

{
    use: [
        {
            service: "fuchsia.example.ExampleService",
            path: "/my_svc/fuchsia.example.MyExampleService",
        },
    ],
}

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