Implement a FIDL client
Prerequisites
This tutorial builds on the [FIDL server][server-tut] tutorial. For the full set of FIDL tutorials, refer to the [overview][overview].
Overview
This tutorial implements a client for a FIDL protocol and runs it against the server created in the [previous tutorial][server-tut]. The client in this tutorial is synchronous. There is an [alternate tutorial][async-client] for asynchronous clients.
If you want to write the code yourself, delete the following directories:
Create the component
Create a new component project at examples/fidl/hlcpp/client_sync:
- Add a
main()function toexamples/fidl/hlcpp/client_sync/main.cc:
- Declare a target for the client in
examples/fidl/hlcpp/client_sync/BUILD.gn:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client_sync/BUILD.gn" region_tag="imports" %}
# Declare an executable for the client.
executable("bin") {
output_name = "fidl_echo_hlcpp_client_sync"
sources = [ "main.cc" ]
}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client_sync/BUILD.gn" region_tag="rest" %}
- Add a component manifest in
examples/fidl/hlcpp/client_sync/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_sync/meta/client.cml" region_tag="example_snippet" %}
- Once you have created your component, ensure that you can add it to the build configuration:
- Build the Fuchsia image:
Edit GN dependencies
- Add the following dependencies:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client_sync/BUILD.gn" region_tag="deps" %}
- Then, include them in
main.cc:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client_sync/main.cc" region_tag="includes" %}
The reason for including these dependencies is explained in the [server tutorial][server-tut-deps].
Connect to the server
This section adds code the main() function that connects to the server and makes
requests to it.
Initialize a proxy class
The code then creates a proxy class for the Echo protocol, and connects it
to the server. 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.
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client_sync/main.cc" region_tag="main" highlight="2,3,4" %}
- [
fuchsia::examples::EchoSyncPtr][proxy] is an alias forfidl::SynchronousInterfaceRequest<fuchsia::examples::Echo>generated by the bindings. This class will proxy requests for theEchoprotocol over the channel that it is bound to. - The code calls
EchoSyncPtr::NewRequest(), which will create a channel, bind the class to one end, and return the other end - The returned end is passed to
sys::ServiceDirectory::Connect(). - Analogous to the call to
context->out()->AddPublicService()on the server side,Connecthas 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][server-tut-handler] comes from: the client passes it in toConnect, 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.
Send requests to the server
The code makes two requests to the server:
- An
EchoStringrequest - A
SendStringrequest
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/hlcpp/client_sync/main.cc" region_tag="main" highlight="6,7,8" %}
For EchoString the code passes in a pointer for each response parameter (in
this case, the EchoString method only has one response parameter), which is
written with the response from the server, whereas this does not apply to
SendString since it is a [fire and forget method][one-way]. The call to
EchoString will block until it receives a message from the server. Both methods
will return a zx_status_t indicating the result of the method call.
Though the [server implementation][server-tut-impl] sends an OnString event
in response to the SendString request, the sync bindings do not provide a
way to handle this event.
Run the client
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][glossary.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:
-
Build the Fuchsia image:
-
Run the
echo_realmcomponent. This creates the client and server component instances and routes the capabilities: -
Start the
echo_clientinstance:
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):
```none {:.devsite-disable-click-to-copy} [echo_server][][I] Running echo server [echo_client][][I] Got response: hello
Terminate the realm component to stop execution and clean up the component
instances:
```posix-terminal
ffx component destroy /core/ffx-laboratory:echo_realm
glossary.realm /development/languages/fidl/tutorials/hlcpp/client.md#proxy server-tutserver-tut-component /development/languages/fidl/tutorials/hlcpp/basics/server.md#impl server-tut-deps /development/languages/fidl/tutorials/hlcpp/basics/server.md#handler async-clientproxy /development/languages/fidl/tutorials/overview.md environment