| keywords: docType:Guide,category:FuchsiaFidl | |
| keywords_public: FIDL, C++, server, tutorial, Fuchsia, protocol, implementation, outgoing directory, component, natural types, wire types | |
| description: This tutorial explains how to implement, publish, and run a C++ FIDL server on Fuchsia using both natural and wire domain objects. | |
| <!-- These keywords are for search widget on fuchsia.dev. Do not remove. --> | |
| # Implement a C++ FIDL server | |
| ## Prerequisites | |
| This tutorial builds on the [domain objects][domain-objects] tutorial. For the | |
| full set of FIDL tutorials, refer to the [overview][overview]. | |
| ## Overview | |
| <!-- TODO(https://fxbug.dev/42136750) <<../../common/server/overview.md>> --> | |
| This tutorial shows you how to implement a server for a FIDL protocol | |
| (`fuchsia.examples/Echo`) and run it on Fuchsia. This protocol has one method | |
| of each kind: a one-way method, a two-way method, and an event: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/echo.test.fidl" region_tag="echo" %} | |
| ``` | |
| For more on FIDL methods and messaging models, refer to the | |
| [FIDL concepts][concepts] page. | |
| This document covers how to complete the following tasks: | |
| * [Implement the FIDL protocol](#protocol). | |
| * [Publish the protocol implementation](#serve). | |
| * [Run the server](#run). | |
| ## Structure of the server example | |
| The example code accompanying this tutorial is located in your Fuchsia checkout | |
| at [`//examples/fidl/cpp/server`][cpp-server-src]. It consists of a server | |
| component and its containing package. For more information about building | |
| components, see [Build components][build-components]. | |
| To get the server component up and running, there are three targets that are | |
| defined in `//examples/fidl/cpp/server/BUILD.bazel`: | |
| 1. The raw executable file for the server. This produces a binary with the | |
| specified output name that can run on Fuchsia: | |
| ```bazel | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/BUILD.bazel" region_tag="bin" %} | |
| ``` | |
| 1. A component that is set up to run the server executable. | |
| Components are the units of software execution on Fuchsia. A component is | |
| described by its manifest file. In this case `meta/server.cml` | |
| configures `echo-server` as an executable component which runs | |
| `fidl_echo_cpp_server` in `:bin`. | |
| ```bazel | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/BUILD.bazel" region_tag="component" %} | |
| ``` | |
| The server component manifest is located at | |
| `//examples/fidl/cpp/server/meta/server.cml`. The binary name in the | |
| manifest must match the output name of the `executable` defined in | |
| `BUILD.bazel`. | |
| ```json5 | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/meta/server.cml" region_tag="example_snippet" %} | |
| ``` | |
| 1. The component is then put into a package, which is the unit of software | |
| distribution on Fuchsia. In this case, the package just contains a | |
| single component. | |
| ```bazel | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/BUILD.bazel" region_tag="package" %} | |
| ``` | |
| ### Building the server {#build} | |
| You may build the server package via the following: | |
| 1. Add the server to your build configuration. This only needs to be done once: | |
| ```posix-terminal | |
| fx set core.x64 --with //examples/fidl/cpp/server | |
| ``` | |
| 1. Build the server package: | |
| ```posix-terminal | |
| fx build //examples/fidl/cpp/server | |
| ``` | |
| Note: This build configuration assumes your device target is the emulator. | |
| To run the example on a physical device, select the appropriate | |
| [product configuration][products] for your hardware. | |
| ## Implement the FIDL protocol {#protocol} | |
| `EchoImpl` implements the server request handler for the `fuchsia.examples/Echo` | |
| protocol. To do so, `EchoImpl` inherits from the generated pure virtual server | |
| interface `fidl::Server<fuchsia_examples::Echo>`, and overrides its pure virtual | |
| methods corresponding to every one way and two way call: | |
| ```cpp | |
| class EchoImpl : public fidl::Server<fuchsia_examples::Echo> { | |
| public: | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/main.cc" region_tag="impl" %} | |
| // ... other methods from examples/fidl/cpp/server/main.cc omitted, to be covered later. | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/main.cc" region_tag="binding_ref" %} | |
| }; | |
| ``` | |
| Note: in this tutorial the `EchoString` handler replies synchronously. For | |
| asynchronous replies, see | |
| [responding to requests asynchronously][responding-asynchronously]. | |
| ### Bind the implementation to a server endpoint | |
| Implementing the request handlers is only half the story. The server needs to be | |
| able to monitor new messages that arrives on a | |
| [server endpoint][server-endpoint]. To do this, `EchoImpl` defines two more | |
| methods: a `BindSelfManagedServer` static factory function that creates a | |
| new `EchoImpl` instance to handle requests on a new server endpoint | |
| `fidl::ServerEnd<fuchsia_examples::Echo>`, and an `OnUnbound` method that | |
| is called when the connection is torn down: | |
| ```cpp | |
| /* Inside `class EchoImpl {`... */ | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/main.cc" region_tag="bind_server" %} | |
| ``` | |
| ## Publish the protocol implementation {#server} | |
| A component that implements a FIDL protocol can expose that FIDL | |
| protocol to other components. This is done by publishing the protocol | |
| implementation to the component's | |
| [outgoing directory][glossary.outgoing-directory]. This complete process is | |
| described in further detail in the [Life of a protocol open][protocol-open]. | |
| We can use `component::OutgoingDirectory` from the C++ component runtime library | |
| to perform the heavy lifting. | |
| To depend on the component runtime library: | |
| ```bazel | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/BUILD.bazel" region_tag="bin" highlight="12" %} | |
| ``` | |
| Import the library at the top of `examples/fidl/cpp/server/main.cc`: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/main.cc" region_tag="includes" highlight="3" %} | |
| ``` | |
| Serve the component's outgoing directory: | |
| ```cpp | |
| int main(int argc, const char** argv) { | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/main.cc" region_tag="serve-out-dir" %} | |
| // ... | |
| ``` | |
| ### Serve the protocol {#server-handler} | |
| The server then registers the Echo protocol using `outgoing.AddProtocol`. | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/main.cc" region_tag="main" highlight="27,28,29,30,31,32,33,34,35,36" %} | |
| ``` | |
| The call to `AddProtocol` installs a handler at the name of the FIDL protocol | |
| (`fidl::DiscoverableProtocolName<fuchsia_examples::Echo>`, which is the string | |
| `"fuchsia.examples.Echo"`). When a client component connects to | |
| `fuchsia.examples.Echo`, `outgoing` will call the lambda function that we | |
| created with a server endpoint corresponding to the client endpoint from the | |
| client, and this lambda function will call the `EchoImpl::BindSelfManagedServer` | |
| detailed above to bind the server endpoint to a new instance of `EchoImpl`. | |
| Our main method will keep listening for incoming requests on the | |
| [async loop][async-loop]. | |
| ## Test the server {#run} | |
| After [building the server](#build), you may run the example on a running | |
| instance of Fuchsia emulator via | |
| ```posix-terminal | |
| ffx component run /core/ffx-laboratory:echo-server fuchsia-pkg://fuchsia.com/echo-cpp-server#meta/echo_server.cm | |
| ``` | |
| Note: Components are resolved using their [component URL][glossary.component-url], | |
| which is determined with the [`fuchsia-pkg://`][glossary.fuchsia-pkg-url] scheme. | |
| You should see output similar to the following in the device logs (`ffx log`): | |
| ```none {:.devsite-disable-click-to-copy} | |
| [ffx-laboratory:echo_server][][I] Running C++ echo server with natural types | |
| ``` | |
| The server is now running and waiting for incoming requests. | |
| The next step will be to write a client that sends `Echo` protocol requests. | |
| For now, you can simply terminate the server component: | |
| ```posix-terminal | |
| ffx component destroy /core/ffx-laboratory:echo_server | |
| ``` | |
| Note: Component instances are referenced by their | |
| [component moniker][glossary.moniker], which is determined by their location in | |
| the [component instance tree][glossary.component-instance-tree] | |
| ## Serve requests using wire domain objects {#using-wire} | |
| The above tutorial implements a server with | |
| [natural domain objects][natural-types]: the server receives requests | |
| represented in natural domain objects, and sends replies encoded from natural | |
| domain objects. When optimizing for performance and heap allocation, one may | |
| implement a server that speaks [wire domain objects][wire-types], i.e. a wire | |
| server. Here is the `EchoImpl` rewritten to use wire domain objects: | |
| ```cpp | |
| class EchoImpl final : public fidl::WireServer<fuchsia_examples::Echo> { | |
| public: | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/wire/main.cc" region_tag="handlers" %} | |
| // ... |BindSelfManagedServer| etc omitted. Those stay the same. | |
| }; | |
| ``` | |
| The relevant classes and functions used in a wire server have similar shapes to | |
| those used in a natural server. When a different class or function is called | |
| for, the wire counterpart is usually prefixed with `Wire`. There are also | |
| small differences in pointers vs references and argument structure: | |
| * The server interface implemented by a natural server is | |
| `fidl::Server<fuchsia_examples::Echo>`. The server interface implemented by a | |
| wire server is `fidl::WireServer<fuchsia_examples::Echo>`. | |
| * The handler function in a natural server takes a reference to the request | |
| message. The `Reply` method takes a single argument that is the response | |
| payload domain object: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/main.cc" region_tag="impl-echo-string" adjust_indentation="auto" %} | |
| ``` | |
| Whereas the handler function in a wire server takes a view (akin to a pointer) | |
| of the request message. When the response payload is a struct, the `Reply` | |
| method flattens the list of struct fields in the response payload into | |
| separate arguments (here, a single `fidl::StringView` argument): | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/wire/main.cc" region_tag="impl-echo-string" adjust_indentation="auto" %} | |
| ``` | |
| * The function to send events with natural types is `fidl::SendEvent`. The | |
| function to send events with wire types is `fidl::WireSendEvent`. Struct | |
| fields are also flattened into separate arguments when sending an event. | |
| The same `fidl::BindServer` function may be used to bind either a natural server | |
| or a wire server. | |
| The full example code for a wire server is located in your Fuchsia checkout | |
| at [`//examples/fidl/cpp/server/wire`][cpp-wire-server-src]. | |
| <!-- xrefs --> | |
| [glossary.component-instance-tree]: /docs/glossary/README.md#component-instance-tree | |
| [glossary.component-url]: /docs/glossary/README.md#component-url | |
| [glossary.fuchsia-pkg-url]: /docs/glossary/README.md#fuchsia-pkg-url | |
| [glossary.moniker]: /docs/glossary/README.md#moniker | |
| [glossary.outgoing-directory]: /docs/glossary/README.md#outgoing-directory | |
| [cpp-server-src]: /examples/fidl/cpp/server | |
| [cpp-wire-server-src]: /examples/fidl/cpp/server/wire | |
| [domain-objects]: /docs/development/languages/fidl/tutorials/cpp/basics/domain-objects.md | |
| [build-components]: /docs/development/components/build.md | |
| [products]: /docs/development/build/software_assembly/build_configuration.md | |
| [protocol-open]: /docs/concepts/components/v2/capabilities/life_of_a_protocol_open.md#binding_to_a_component_and_sending_a_protocol_channel | |
| [compiling-fidl]: /docs/development/languages/fidl/tutorials/fidl.md | |
| [async-loop]: /sdk/lib/async-loop/include/lib/async-loop/cpp/loop.h | |
| [overview]: /docs/development/languages/fidl/tutorials/overview.md | |
| [concepts]: /docs/concepts/fidl/overview.md | |
| [responding-asynchronously]: /docs/development/languages/fidl/tutorials/cpp/topics/async-completer.md | |
| [server-endpoint]: /docs/reference/fidl/language/language.md#protocols-use | |
| [natural-types]: /docs/development/languages/fidl/tutorials/cpp/basics/domain-objects.md#using-natural | |
| [wire-types]: /docs/development/languages/fidl/tutorials/cpp/basics/domain-objects.md#using-wire |