Implement an LLCPP FIDL client

Prerequisites

This tutorial builds on the FIDL server tutorial. For the full set of FIDL tutorials, refer to the overview.

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/llcpp/client/*

Create a stub component

1. Set up a hello world component in examples/fidl/llcpp/client. You can name the component echo-client, and give the package a name of echo-llcpp-client.

2. Once you have created your component, ensure that the following works:

   fx set core.x64 --with //examples/fidl/llcpp/client
   

3. Build the Fuchsia image:

   fx build
   

4. In a separate terminal, run:

   fx serve
   

5. In a separate terminal, run:

   fx shell run fuchsia-pkg://fuchsia.com/echo-llcpp-client#meta/echo-client.cmx
   

Edit GN dependencies

1. Add the following dependencies:

     deps = [
       "//examples/fidl/fuchsia.examples:fuchsia.examples_llcpp",
       "//sdk/lib/fdio",
       "//zircon/public/lib/fidl",
       "//zircon/system/ulib/async-loop:async-loop-cpp",
       "//zircon/system/ulib/async-loop:async-loop-default",
       "//zircon/system/ulib/service:service-llcpp",
     ]
   
   

2. Then, include them in main.cc:

   #include <fuchsia/examples/llcpp/fidl.h>
   #include <lib/async-loop/cpp/loop.h>
   #include <lib/async-loop/default.h>
   #include <lib/fidl/llcpp/client.h>
   #include <lib/service/llcpp/service.h>
   #include <zircon/assert.h>
   
   #include <iostream>
   

These dependencies are explained in the server tutorial.

Edit component manifest

1. Include the Echo protocol in the client component's sandbox by editing the component manifest in client.cmx.

   {
       "include": [
           "syslog/client.shard.cmx"
       ],
       "program": {
           "binary": "bin/fidl_echo_llcpp_client"
       },
       "sandbox": {
           "services": [
               "fuchsia.examples.Echo"
           ]
       }
   }
   
   

Connect to the server

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.

Initialize the event loop

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.

int main(int argc, const char** argv) {
  async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
  async_dispatcher_t* dispatcher = loop.dispatcher();

  // |service::OpenServiceRoot| returns a channel connected to the /svc directory.
  // The remote end of the channel implements the |fuchsia.io/Directory| protocol
  // and contains the capabilities provided to this component.
  auto svc = service::OpenServiceRoot();
  ZX_ASSERT(svc.is_ok());

  // Connect to the |fuchsia.examples/Echo| protocol, here we demonstrate
  // using |service::ConnectAt| relative to some service directory.
  // One may also directly call |Connect| to use the default service directory.
  auto client_end = service::ConnectAt<fuchsia_examples::Echo>(*svc);
  ZX_ASSERT(client_end.status_value() == ZX_OK);

  // Define the event handler for the client. The OnString event handler prints the event.
  class EventHandler : public fidl::WireAsyncEventHandler<fuchsia_examples::Echo> {
   public:
    explicit EventHandler(async::Loop& loop) : loop_(loop) {}

    void OnString(fidl::WireResponse<fuchsia_examples::Echo::OnString>* event) override {
      std::string response(event->response.data(), event->response.size());
      std::cout << "Got event: " << response << std::endl;
      loop_.Quit();
    }

   private:
    async::Loop& loop_;
  };
  EventHandler handler(loop);

  // Create a client to the Echo protocol.
  fidl::WireClient client(std::move(*client_end), dispatcher, &handler);

  // Make an EchoString call, passing it a lambda to handle the response asynchronously.
  auto result_async = client->EchoString(
      "hello", [&](fidl::WireResponse<fuchsia_examples::Echo::EchoString>* response) {
        std::string reply(response->response.data(), response->response.size());
        std::cout << "Got response: " << reply << std::endl;
        loop.Quit();
      });
  ZX_ASSERT(result_async.ok());
  loop.Run();
  loop.ResetQuit();

  // Make a synchronous EchoString call, which blocks until it receives the response,
  // then returns a ResultOf object for the response.
  auto result_sync = client->EchoString_Sync("hello");
  ZX_ASSERT(result_sync.ok());
  std::string reply_string(result_sync->response.data(), result_sync->response.size());
  std::cout << "Got synchronous response: " << reply_string << std::endl;

  // Make a SendString request. The resulting OnString event will be handled by
  // the event handler defined above.
  auto result_oneway = client->SendString("hi");
  // Check for any synchronous errors.
  ZX_ASSERT(result_oneway.ok());
  loop.Run();

  return 0;
}

The dispatcher is used to run two pieces of async code. It is first used to run the EchoString method, and quits when the response is received. It is then run after calling the SendString in order to listen for events, and quits when an OnString event is received. The call to ResetQuit() in between these two instances allows the client to reuse the loop.

Connect to the server

The client then connects to the service directory /svc, and uses it to connect to the server.

int main(int argc, const char** argv) {
  async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
  async_dispatcher_t* dispatcher = loop.dispatcher();

  // |service::OpenServiceRoot| returns a channel connected to the /svc directory.
  // The remote end of the channel implements the |fuchsia.io/Directory| protocol
  // and contains the capabilities provided to this component.
  auto svc = service::OpenServiceRoot();
  ZX_ASSERT(svc.is_ok());

  // Connect to the |fuchsia.examples/Echo| protocol, here we demonstrate
  // using |service::ConnectAt| relative to some service directory.
  // One may also directly call |Connect| to use the default service directory.
  auto client_end = service::ConnectAt<fuchsia_examples::Echo>(*svc);
  ZX_ASSERT(client_end.status_value() == ZX_OK);

  // Define the event handler for the client. The OnString event handler prints the event.
  class EventHandler : public fidl::WireAsyncEventHandler<fuchsia_examples::Echo> {
   public:
    explicit EventHandler(async::Loop& loop) : loop_(loop) {}

    void OnString(fidl::WireResponse<fuchsia_examples::Echo::OnString>* event) override {
      std::string response(event->response.data(), event->response.size());
      std::cout << "Got event: " << response << std::endl;
      loop_.Quit();
    }

   private:
    async::Loop& loop_;
  };
  EventHandler handler(loop);

  // Create a client to the Echo protocol.
  fidl::WireClient client(std::move(*client_end), dispatcher, &handler);

  // Make an EchoString call, passing it a lambda to handle the response asynchronously.
  auto result_async = client->EchoString(
      "hello", [&](fidl::WireResponse<fuchsia_examples::Echo::EchoString>* response) {
        std::string reply(response->response.data(), response->response.size());
        std::cout << "Got response: " << reply << std::endl;
        loop.Quit();
      });
  ZX_ASSERT(result_async.ok());
  loop.Run();
  loop.ResetQuit();

  // Make a synchronous EchoString call, which blocks until it receives the response,
  // then returns a ResultOf object for the response.
  auto result_sync = client->EchoString_Sync("hello");
  ZX_ASSERT(result_sync.ok());
  std::string reply_string(result_sync->response.data(), result_sync->response.size());
  std::cout << "Got synchronous response: " << reply_string << std::endl;

  // Make a SendString request. The resulting OnString event will be handled by
  // the event handler defined above.
  auto result_oneway = client->SendString("hi");
  // Check for any synchronous errors.
  ZX_ASSERT(result_oneway.ok());
  loop.Run();

  return 0;
}

The service::OpenServiceRoot function initializes a channel, then passes the server end to fdio_service_connect to connect to the /svc directory, returning the client end wrapped in a zx::status result type. We should check for the is_ok() value on the result to determine if any synchronous error occurred.

Connecting to a protocol relative to the service directory is done by calling fdio_service_connect_at, passing it the service directory, the name of the service to connect to, as well as the channel that should get passed to the server. The service::ConnectAt function wraps the low level fdio call, providing the user with a typed client channel endpoint to the requested protocol.

In parallel, the component manager will route the requested service name and channel to the server component, where the connect function implemented in the server tutorial is called with these arguments, binding the channel to the server implementation.

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. A workaround will be when running the example at the end of the tutorial.

Initialize the client

In order to make Echo requests to the server, initialize a client using the client end of the channel from the previous step, the loop dispatcher, as well as an event handler delegate:

int main(int argc, const char** argv) {
  async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
  async_dispatcher_t* dispatcher = loop.dispatcher();

  // |service::OpenServiceRoot| returns a channel connected to the /svc directory.
  // The remote end of the channel implements the |fuchsia.io/Directory| protocol
  // and contains the capabilities provided to this component.
  auto svc = service::OpenServiceRoot();
  ZX_ASSERT(svc.is_ok());

  // Connect to the |fuchsia.examples/Echo| protocol, here we demonstrate
  // using |service::ConnectAt| relative to some service directory.
  // One may also directly call |Connect| to use the default service directory.
  auto client_end = service::ConnectAt<fuchsia_examples::Echo>(*svc);
  ZX_ASSERT(client_end.status_value() == ZX_OK);

  // Define the event handler for the client. The OnString event handler prints the event.
  class EventHandler : public fidl::WireAsyncEventHandler<fuchsia_examples::Echo> {
   public:
    explicit EventHandler(async::Loop& loop) : loop_(loop) {}

    void OnString(fidl::WireResponse<fuchsia_examples::Echo::OnString>* event) override {
      std::string response(event->response.data(), event->response.size());
      std::cout << "Got event: " << response << std::endl;
      loop_.Quit();
    }

   private:
    async::Loop& loop_;
  };
  EventHandler handler(loop);

  // Create a client to the Echo protocol.
  fidl::WireClient client(std::move(*client_end), dispatcher, &handler);

  // Make an EchoString call, passing it a lambda to handle the response asynchronously.
  auto result_async = client->EchoString(
      "hello", [&](fidl::WireResponse<fuchsia_examples::Echo::EchoString>* response) {
        std::string reply(response->response.data(), response->response.size());
        std::cout << "Got response: " << reply << std::endl;
        loop.Quit();
      });
  ZX_ASSERT(result_async.ok());
  loop.Run();
  loop.ResetQuit();

  // Make a synchronous EchoString call, which blocks until it receives the response,
  // then returns a ResultOf object for the response.
  auto result_sync = client->EchoString_Sync("hello");
  ZX_ASSERT(result_sync.ok());
  std::string reply_string(result_sync->response.data(), result_sync->response.size());
  std::cout << "Got synchronous response: " << reply_string << std::endl;

  // Make a SendString request. The resulting OnString event will be handled by
  // the event handler defined above.
  auto result_oneway = client->SendString("hi");
  // Check for any synchronous errors.
  ZX_ASSERT(result_oneway.ok());
  loop.Run();

  return 0;
}

The event handler delegate should be an object that implements the Echo::AsyncEventHandler virtual interface, which has methods corresponding to the events offered by the protocol (see LLCPP event handlers). In this case, a local class is defined with a single method corresponding to the handler for the OnString event. The handler prints the string and quits the event loop.

Send requests to the server

The code makes three requests to the server:

• An asynchronous EchoString request.
• A synchronous EchoString request.
• A SendString request (async vs sync is not relevant for this case because it is a fire and forget method).

int main(int argc, const char** argv) {
  async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
  async_dispatcher_t* dispatcher = loop.dispatcher();

  // |service::OpenServiceRoot| returns a channel connected to the /svc directory.
  // The remote end of the channel implements the |fuchsia.io/Directory| protocol
  // and contains the capabilities provided to this component.
  auto svc = service::OpenServiceRoot();
  ZX_ASSERT(svc.is_ok());

  // Connect to the |fuchsia.examples/Echo| protocol, here we demonstrate
  // using |service::ConnectAt| relative to some service directory.
  // One may also directly call |Connect| to use the default service directory.
  auto client_end = service::ConnectAt<fuchsia_examples::Echo>(*svc);
  ZX_ASSERT(client_end.status_value() == ZX_OK);

  // Define the event handler for the client. The OnString event handler prints the event.
  class EventHandler : public fidl::WireAsyncEventHandler<fuchsia_examples::Echo> {
   public:
    explicit EventHandler(async::Loop& loop) : loop_(loop) {}

    void OnString(fidl::WireResponse<fuchsia_examples::Echo::OnString>* event) override {
      std::string response(event->response.data(), event->response.size());
      std::cout << "Got event: " << response << std::endl;
      loop_.Quit();
    }

   private:
    async::Loop& loop_;
  };
  EventHandler handler(loop);

  // Create a client to the Echo protocol.
  fidl::WireClient client(std::move(*client_end), dispatcher, &handler);

  // Make an EchoString call, passing it a lambda to handle the response asynchronously.
  auto result_async = client->EchoString(
      "hello", [&](fidl::WireResponse<fuchsia_examples::Echo::EchoString>* response) {
        std::string reply(response->response.data(), response->response.size());
        std::cout << "Got response: " << reply << std::endl;
        loop.Quit();
      });
  ZX_ASSERT(result_async.ok());
  loop.Run();
  loop.ResetQuit();

  // Make a synchronous EchoString call, which blocks until it receives the response,
  // then returns a ResultOf object for the response.
  auto result_sync = client->EchoString_Sync("hello");
  ZX_ASSERT(result_sync.ok());
  std::string reply_string(result_sync->response.data(), result_sync->response.size());
  std::cout << "Got synchronous response: " << reply_string << std::endl;

  // Make a SendString request. The resulting OnString event will be handled by
  // the event handler defined above.
  auto result_oneway = client->SendString("hi");
  // Check for any synchronous errors.
  ZX_ASSERT(result_oneway.ok());
  loop.Run();

  return 0;
}

The client object works by overriding the dereference operator to return a protocol specific client implementation, allowing calls such as client->EchoString().

The asynchronous method call requires the request parameters followed by a response handler callback, which is called when the response is received.

The client object also allows synchronous calls, which will block until the response is received and return the response object. These are suffixed with _Sync (e.g. client->EchoString_Sync()).

In the synchronous case, a result object is returned, since the method call can fail. In the asynchronous or fire-and-forget case, a lightweight status object is returned, which communicates any synchronous errors. The response callback takes the response message pointer as argument directly, since the handler is only called in the case of a successful method call.

Run the client

If you run the client directly, it will not connect to the server correctly because the client does not automatically get the Echo protocol provided in its sandbox (in /svc). To get this to work, a launcher tool is provided that launches the server, creates a new Environment for the client that provides the server's protocol, then launches the client in it.

1. Configure your GN build as follows:

   fx set core.x64 --with //examples/fidl/llcpp/server --with //examples/fidl/llcpp/client --with //examples/fidl/test:echo-launcher
   

2. Build the Fuchsia image:

   fx build
   

3. Run the launcher by passing it the client URL, the server URL, and the protocol that the server provides to the client:

   fx shell run fuchsia-pkg://fuchsia.com/echo-launcher#meta/launcher.cmx fuchsia-pkg://fuchsia.com/echo-llcpp-client#meta/echo-client.cmx fuchsia-pkg://fuchsia.com/echo-llcpp-server#meta/echo-server.cmx fuchsia.examples.Echo
   

You should see the print output in the QEMU console (or using fx log).

[166633.167] 757796:757798> Running echo server
[166633.489] 757796:757798> echo_server_llcpp: Incoming connection for fuchsia.examples.Echo
[166633.528] 758101:758103> Got synchronous response: hello
[166633.531] 758101:758103> Got response: hello
[166633.531] 758101:758103> Got event: hi"