class OutgoingDirectory

Defined at line 66 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

The directory containing handles to capabilities this component provides.

Entries served from this outgoing directory should correspond to the

component manifest's `capabilities` declarations.

The outgoing directory contains one special subdirectory, named `svc`. This

directory contains the FIDL Services and Protocols offered by this component

to other components. For example the FIDL Protocol `fuchsia.foo.Bar` will be

hosted under the path `/svc/fuchsia.foo.Bar`.

# Thread safety

This class is thread-unsafe. Instances must be managed and used from a

[synchronized async dispatcher][synchronized-dispatcher]. See

https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/thread-safe-async#synchronized-dispatcher

# Server lifetimes

This class supports a simpler usage style where it owns the server

implementations published to the directory, and an advanced usage style

where it borrows the server and where the user manages the server lifetimes.

When the outgoing directory owns the server implementation (e.g. see

|AddProtocol|), removing the published capability or destroying the outgoing

directory will destroy the server object and teardown all connections to it.

When the outgoing directory borrows the server implementation (usually via

callbacks e.g. see |AddUnmanagedProtocol|), removing the published

capability or destroying the outgoing directory synchronously stops all

future attempts to connect to the server. Thereafter, the user may teardown

existing connections and destroy the server.

# Maintainer's Note

This class' API is semantically identical to the one found in

`//sdk/lib/sys/cpp`. This exists in order to offer equivalent facilities to

the new C++ bindings. The other class is designed for the older, HLCPP

(High-Level C++) FIDL bindings. It is expected that once all clients of HLCPP

are migrated to the new C++ bindings, that library will be removed.

Public Members

static const const char[] kDefaultServiceInstance

static const const char[] kServiceDirectory

Public Methods

void OutgoingDirectory (async_dispatcher_t * dispatcher)

Creates an OutgoingDirectory which will serve requests when

|Serve| or |ServeFromStartupInfo()| is called.

|dispatcher| must not be nullptr. If it is, this method will panic.

Defined at line 31 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

void OutgoingDirectory (OutgoingDirectory && )

OutgoingDirectory can be moved. Once moved, invoking a method on an

instance will yield undefined behavior.

Defined at line 62 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

OutgoingDirectory & operator= (OutgoingDirectory && )

Defined at line 64 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

void ~OutgoingDirectory ()

Destroying the directory will stop any future attempts to connect to the

services and protocols published within.

Defined at line 66 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

void OutgoingDirectory ()

Defined at line 80 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

zx::result<> Serve (fidl::ServerEnd<fuchsia_io::Directory> directory_server_end)

Starts serving the outgoing directory on the given channel.

This should be invoked after the outgoing directory has been populated,

i.e. after |AddProtocol|. While |OutgoingDirectory| does not require

calling |AddProtocol| before |Serve|, if you call them in the other order

there is a chance that requests that arrive in between will be dropped.

This object will implement the |fuchsia.io.Directory| interface using this

channel. Note that this method returns immediately and that the |dispatcher|

provided to the constructor will be responsible for processing messages

sent to the server endpoint.

# Errors

ZX_ERR_BAD_HANDLE: |directory_server_end| is not a valid handle.

ZX_ERR_ACCESS_DENIED: |directory_server_end| has insufficient rights.

Defined at line 83 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

void OutgoingDirectory (const OutgoingDirectory & )

OutgoingDirectory cannot be copied.

Defined at line 88 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

OutgoingDirectory & operator= (const OutgoingDirectory & )

Defined at line 89 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

zx::result<> ServeFromStartupInfo ()

Starts serving the outgoing directory on the channel provided to this

process at startup as |PA_DIRECTORY_REQUEST|.

This object will implement the |fuchsia.io.Directory| interface using this

channel.

# Errors

ZX_ERR_BAD_HANDLE: the process did not receive a |PA_DIRECTORY_REQUEST|

startup handle or it was already taken.

ZX_ERR_ACCESS_DENIED: The |PA_DIRECTORY_REQUEST| handle has insufficient

rights.

Defined at line 93 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

zx::result<> AddUnmanagedProtocol (AnyHandler handler, std::string_view name)

Same as above but is untyped. This method is generally discouraged but

is made available if a generic handler needs to be provided.

Defined at line 99 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

zx::result<> AddUnmanagedProtocolAt (AnyHandler handler, std::string_view path, std::string_view name)

Same as |AddProtocol| but is untyped and allows the usage of setting the

parent directory in which the protocol will be installed.

Defined at line 103 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

template <typename Protocol, typename ServerImpl, typename = std::enable_if_t<fidl::IsProtocolV<Protocol>>>

zx::result<> AddProtocol (std::unique_ptr<ServerImpl> impl, std::string_view name)

Adds a FIDL Protocol server instance.

|impl| will be used to handle requests for this protocol.

|name| is used to determine where to host the protocol. This protocol will

be hosted under the path /svc/{name}, where `name` is the discoverable name

of the protocol, by default. A pointer to |impl| is returned on the success

case of this function call. This pointer will be valid until either this

|OutgoingDirectory| is destroyed or |RemoveProtocol| is invoked with the

provided |name|.

Note, if and when |RemoveProtocol| is called for the provided |name|, this

object will asynchronously close down the associated server end channel and

stop receiving requests. This method provides no facilities for waiting

until teardown is complete. If such control is desired, then the

|TypedHandler| overload of this method listed below ought to be used.

# Errors

ZX_ERR_ALREADY_EXISTS: An entry already exists for this protocol.

ZX_ERR_INVALID_ARGS: |impl| is nullptr or |name| is an empty string.

# Examples

See sample use cases in test case(s) located at

//sdk/lib/component/tests/outgoing_directory_test.cc

Defined at line 157 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

zx::result<> AddService (ServiceInstanceHandler handler, std::string_view service, std::string_view instance)

Same as above but is untyped.

Defined at line 161 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

zx::result<> AddServiceAt (ServiceInstanceHandler handler, std::string_view path, std::string_view service, std::string_view instance)

Same as above but is untyped.

Defined at line 166 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

zx::result<> AddDirectory (fidl::ClientEnd<fuchsia_io::Directory> remote_dir, std::string_view directory_name)

Serve a subdirectory at the root of this outgoing directory.

The directory will be installed under the path |directory_name|. When

a request is received under this path, then it will be forwarded to

|remote_dir|.

# Errors

ZX_ERR_ALREADY_EXISTS: An entry with the provided name already exists.

ZX_ERR_BAD_HANDLE: |remote_dir| is an invalid handle.

ZX_ERR_INVALID_ARGS: |directory_name| is an empty string.

Defined at line 139 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

zx::result<> AddDirectoryAt (fidl::ClientEnd<fuchsia_io::Directory> remote_dir, std::string_view path, std::string_view directory_name)

Same as |AddDirectory| but allows setting the parent directory

in which the directory will be installed.

Defined at line 144 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

template <typename Protocol, typename = std::enable_if_t<fidl::IsProtocolV<Protocol>>>

zx::result<> AddUnmanagedProtocol (TypedHandler<Protocol> handler, std::string_view name)

Same as |AddProtocol| except that a typed handler is used. The

|handler| is a callback that handles connection requests for this

particular protocol.

# Note

Active connections are never torn down when/if |RemoveProtocol| is invoked

with the same |name|. Users of this method should manage teardown of

all active connections.

Defined at line 172 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

template <typename Protocol, typename ServerImpl, typename = std::enable_if_t<fidl::IsProtocolV<Protocol>>>

zx::result<> AddProtocolAt (std::string_view path, std::unique_ptr<ServerImpl> impl, std::string_view name)

Same as |AddProtocol| but allows setting the parent directory in

which the protocol will be installed.

Defined at line 188 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

zx::result<> RemoveProtocol (std::string_view name)

Same as above but untyped.

Defined at line 191 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

zx::result<> RemoveProtocolAt (std::string_view directory, std::string_view name)

Same as above but untyped.

Defined at line 195 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

template <typename Protocol, typename = std::enable_if_t<fidl::IsProtocolV<Protocol>>>

zx::result<> AddUnmanagedProtocolAt (std::string_view path, TypedHandler<Protocol> handler, std::string_view name)

Same as |AddProtocol| but uses a typed handler and allows the usage of

setting the parent directory in which the protocol will be installed.

Defined at line 214 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

zx::result<> RemoveService (std::string_view service, std::string_view instance)

Same as above but untyped.

Defined at line 230 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

zx::result<> RemoveServiceAt (std::string_view path, std::string_view service, std::string_view instance)

Defined at line 234 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

template <typename Service, typename = std::enable_if_t<fidl::IsServiceV<Service>>>

zx::result<> AddService (ServiceInstanceHandler handler, std::string_view instance)

Adds an instance of a FIDL Service.

A |handler| is added to provide an |instance| of a service.

The template type |Service| must be the generated type representing a FIDL Service.

The generated class |Service::Handler| helps the caller populate a

|ServiceInstanceHandler|.

# Errors

ZX_ERR_ALREADY_EXISTS: The instance already exists.

ZX_ERR_INVALID_ARGS: |instance| is an empty string or |handler| is empty.

# Example

See sample use cases in test case(s) located at

//sdk/lib/sys/component/cpp/outgoing_directory_test.cc

Defined at line 251 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

zx::result<> RemoveDirectory (std::string_view directory_name)

Removes the subdirectory on the provided |directory_name|.

# Errors

ZX_ERR_NOT_FOUND: No entry was found with provided name.

Defined at line 259 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

template <typename Service, typename = std::enable_if_t<fidl::IsServiceV<Service>>>

zx::result<> AddServiceAt (ServiceInstanceHandler handler, std::string_view path, std::string_view instance)

Defined at line 263 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

zx::result<> RemoveDirectoryAt (std::string_view path, std::string_view directory_name)

Same as |RemoveDirectory| but allows specifying the parent directory

that the directory will be removed from. The parent directory, |path|,

will not be removed.

Defined at line 263 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.cc

template <typename Protocol, typename = std::enable_if_t<fidl::IsProtocolV<Protocol>>>

zx::result<> RemoveProtocol (std::string_view name)

Removes a FIDL Protocol entry with the path `/svc/{name}`.

Removing the protocol will stop any future attempts to connect to this

protocol.

# Errors

ZX_ERR_NOT_FOUND: The protocol entry was not found.

# Example

```

outgoing.RemoveProtocol

<lib

_example::MyProtocol>();

```

Defined at line 311 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

template <typename Protocol, typename = std::enable_if_t<fidl::IsProtocolV<Protocol>>>

zx::result<> RemoveProtocolAt (std::string_view path, std::string_view name)

Removes a FIDL Protocol entry located in the provided |directory|.

Unlike |RemoveProtocol| which looks for the protocol to remove in the

path `/svc/{name}`, this method uses the directory name provided, e.g.

`/{path}/{name}`.

# Errors

ZX_ERR_NOT_FOUND: The protocol entry was not found.

# Example

```

outgoing.RemoveProtocolAt

<lib

_example::MyProtocol>("diagnostics");

```

Defined at line 333 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

template <typename Service, typename = std::enable_if_t<fidl::IsServiceV<Service>>>

zx::result<> RemoveService (std::string_view instance)

Removes an instance of a FIDL Service.

Removing the service will stop any future attempts to connect to members

within service. Connections to intermediate directories will be closed.

# Errors

ZX_ERR_NOT_FOUND: The instance was not found.

# Example

```

outgoing.RemoveService

<lib

_example::MyService>("my-instance");

```

Defined at line 356 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h

template <typename Service, typename = std::enable_if_t<fidl::IsServiceV<Service>>>

zx::result<> RemoveServiceAt (std::string_view path, std::string_view instance)

Defined at line 365 of file ../../sdk/lib/component/outgoing/cpp/outgoing_directory.h