This tutorial builds on the FIDL server tutorial. For the full set of FIDL tutorials, refer to the overview.
This tutorial implements a client for a FIDL protocol and runs it against the server created in the previous tutorial. The client in this tutorial is asynchronous. There is an alternate tutorial for synchronous clients.
If you want to write the code yourself, delete the following directories:
rm -r examples/fidl/hlcpp/client/*
Create a new component project at examples/fidl/hlcpp/client
:
Add a main()
function to examples/fidl/hlcpp/client/main.cc
:
int main(int argc, const char** argv) { printf("Hello, world!\n"); return 0; }
Declare a target for the client in examples/fidl/hlcpp/client/BUILD.gn
:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/BUILD.gn" region_tag="imports" %} # Declare an executable for the client. executable("bin") { output_name = "fidl_echo_hlcpp_client" sources = [ "main.cc" ] } {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/BUILD.gn" region_tag="rest" %}
Add a component manifest in examples/fidl/hlcpp/client/meta/client.cml
:
Note: The binary name in the manifest must match the output name of the executable
defined in the previous step.
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/meta/client.cml" region_tag="example_snippet" %}
Once you have created your component, ensure that you can add it to the build configuration:
fx set core.qemu-x64 --with //examples/fidl/hlcpp/client:echo-client
Build the Fuchsia image:
fx build
Add the following dependencies:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/BUILD.gn" region_tag="deps" %}
Then, include them in main.cc
:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/main.cc" region_tag="includes" %}
The reason for including these dependencies is explained in the server tutorial.
The steps in this section explain how to add code to the main()
function that connects the client to the server and makes requests to it.
As in the server, the code first sets up an async loop so that the client can listen for incoming responses from the server without blocking.
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/main.cc" region_tag="main" highlight="2,28" %}
In the context of FIDL, proxy designates the code generated by the FIDL bindings that enables users to make remote procedure calls to the server. In HLCPP, the proxy takes the form of a class with methods corresponding to each FIDL protocol method.
The code then creates a proxy class for the Echo
protocol, and connects it to the server.
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/main.cc" region_tag="main" highlight="4,5,6" %}
fuchsia::examples::EchoPtr
is an alias for fidl::InterfaceRequest<fuchsia::examples::Echo>
generated by the bindings.fidl::Binding<fuchsia::examples::Echo>
used in the server, fidl::InterfaceRequest<fuchsia::examples::Echo>
is parameterized by a FIDL protocol and a channel it will proxy requests over the channel, and listen for incoming responses and events.EchoPtr::NewRequest()
, which creates a channel, binds the class to one end of the channel, and returns the other end of the channel.sys::ServiceDirectory::Connect()
.context->out()->AddPublicService()
on the server side, Connect
has an implicit second parameter here, which is the protocol name ("fuchsia.examples.Echo"
). This is where the input to the handler defined in the previous tutorial comes from: the client passes it in to Connect
, which then passes it to the handler.An important point to note here is that this code assumes that /svc
already contains an instance of the Echo
protocol. This is not the case by default because of the sandboxing provided by the component framework.
Finally, the code sets an error handler for the proxy:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/main.cc" region_tag="main" highlight="8,9,10" %}
The code makes two requests to the server:
EchoString
requestSendString
request{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/main.cc" region_tag="main" highlight="14,15,16,17,18,19,20" %}
For EchoString
the code passes in a callback to handle the response. SendString
does not require such a callback because the method does not have any response.
The code then sets a handler for any incoming OnString
events:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/main.cc" region_tag="main" highlight="21,22,23,24,25,26" %}
The code waits to receive both a response to the EchoString
method as well as an OnString
event (which in the current implementation is sent after receiving a SendString
request) before quitting from the loop. The code returns a successful exit code only if it receives both a response and an event:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client/main.cc" region_tag="main" highlight="13,17,18,23,24,29" %}
In order for the client and server to communicate using the Echo
protocol, component framework must route the fuchsia.examples.Echo
capability from the server to the client. For this tutorial, a realm component is provided to declare the appropriate capabilities and routes.
Note: You can explore the full source for the realm component at //examples/fidl/echo-realm
Configure your build to include the provided package that includes the echo realm, server, and client:
fx set core.qemu-x64 --with //examples/fidl/hlcpp:echo-hlcpp-client
Build the Fuchsia image:
fx build
Run the echo_realm
component. This creates the client and server component instances and routes the capabilities:
ffx component run fuchsia-pkg://fuchsia.com/echo-hlcpp-client#meta/echo_realm.cm
Start the echo_client
instance:
ffx component start /core/ffx-laboratory:echo_realm/echo_client
The server component starts when the client attempts to connect to the Echo
protocol. You should see output similar to the following in the device logs (ffx log
):
[echo_server][][I] Running echo server [echo_client][][I] Got event hi [echo_client][][I] Got response hello
Terminate the realm component to stop execution and clean up the component instances:
ffx component destroy /core/ffx-laboratory:echo_realm