Google is committed to advancing racial equity for Black communities. See how.

Implement a 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 will be asynchronous. There is an alternate tutorial for synchronous clients.

If you'd like to follow along and write the code yourself, feel free to delete the example code:

rm -r examples/fidl/hlcpp/client/*

Create a stub component

Referring back to the previous tutorial as necessary, start by setting up a hello world component in examples/fidl/hlcpp/client. You can name the component echo-client, and give the package a name of echo-hlcpp-client. You should ensure that the following works:

fx set core.x64 --with //examples/fidl/hlcpp/client
fx build
fx serve
fx shell run fuchsia-pkg://fuchsia.com/echo-hlcpp-client#meta/echo-client.cmx

Edit GN dependencies

Next, add the following dependencies:

  deps = [
    "//examples/fidl/fuchsia.examples",
    "//sdk/lib/sys/cpp",
    "//zircon/system/ulib/async-loop:async-loop-cpp",
    "//zircon/system/ulib/async-loop:async-loop-default",
  ]

and include them in main.cc:

#include <fuchsia/examples/cpp/fidl.h>
#include <lib/async-loop/cpp/loop.h>
#include <lib/async-loop/default.h>
#include <lib/sys/cpp/component_context.h>

The reason for including these dependencies is explained in the server tutorial.

Edit component manifest

Finally, include the Echo protocol in the client component's sandbox by editing the component manifest in client.cmx.

{
    "program": {
        "binary": "bin/fidl_echo_hlcpp_client"
    },
    "sandbox": {
        "services": [
            "fuchsia.examples.Echo"
        ]
    }
}

Connect to the server

The steps in this section explain how to add code to the main() function in the main.cc file that connects the client to the server and makes requests to that server.

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);

  fuchsia::examples::EchoPtr echo_proxy;
  auto context = sys::ComponentContext::Create();
  context->svc()->Connect(echo_proxy.NewRequest());

  echo_proxy.set_error_handler([&loop](zx_status_t status) {
    printf("Error reading incoming message: %d\n", status);
    loop.Quit();
  });

  int num_responses = 0;
  echo_proxy->SendString("hi");
  echo_proxy->EchoString("hello", [&](std::string response) {
    printf("Got response %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  });
  echo_proxy.events().OnString = [&](std::string response) {
    printf("Got event %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  };

  loop.Run();
  return num_responses == 2 ? 0 : 1;
}

Initialize a proxy class

In the context of FIDL, "proxy" is used to designate 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.

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

  fuchsia::examples::EchoPtr echo_proxy;
  auto context = sys::ComponentContext::Create();
  context->svc()->Connect(echo_proxy.NewRequest());

  echo_proxy.set_error_handler([&loop](zx_status_t status) {
    printf("Error reading incoming message: %d\n", status);
    loop.Quit();
  });

  int num_responses = 0;
  echo_proxy->SendString("hi");
  echo_proxy->EchoString("hello", [&](std::string response) {
    printf("Got response %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  });
  echo_proxy.events().OnString = [&](std::string response) {
    printf("Got event %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  };

  loop.Run();
  return num_responses == 2 ? 0 : 1;
}
  • fuchsia::examples::EchoPtr is an alias for fidl::InterfaceRequest<fuchsia::examples::Echo> generated by the bindings.
  • Analogous to the 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.
  • The code calls EchoPtr::NewRequest(), which creates a channel, binds the class to one end of the channel, and returns the other end of the channel.
  • The returned end of the channel is passed to sys::ServiceDirectory::Connect().
    • Analogous to the call to 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.

Set an error handler

Finally, the code sets an error handler for the proxy:

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

  fuchsia::examples::EchoPtr echo_proxy;
  auto context = sys::ComponentContext::Create();
  context->svc()->Connect(echo_proxy.NewRequest());

  echo_proxy.set_error_handler([&loop](zx_status_t status) {
    printf("Error reading incoming message: %d\n", status);
    loop.Quit();
  });

  int num_responses = 0;
  echo_proxy->SendString("hi");
  echo_proxy->EchoString("hello", [&](std::string response) {
    printf("Got response %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  });
  echo_proxy.events().OnString = [&](std::string response) {
    printf("Got event %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  };

  loop.Run();
  return num_responses == 2 ? 0 : 1;
}

Send requests to the server

The code makes two requests to the server: one SendString request, and one EchoString request:

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

  fuchsia::examples::EchoPtr echo_proxy;
  auto context = sys::ComponentContext::Create();
  context->svc()->Connect(echo_proxy.NewRequest());

  echo_proxy.set_error_handler([&loop](zx_status_t status) {
    printf("Error reading incoming message: %d\n", status);
    loop.Quit();
  });

  int num_responses = 0;
  echo_proxy->SendString("hi");
  echo_proxy->EchoString("hello", [&](std::string response) {
    printf("Got response %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  });
  echo_proxy.events().OnString = [&](std::string response) {
    printf("Got event %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  };

  loop.Run();
  return num_responses == 2 ? 0 : 1;
}

Notice that 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.

Set an event handler

The code then sets a handler for any incoming OnString events:

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

  fuchsia::examples::EchoPtr echo_proxy;
  auto context = sys::ComponentContext::Create();
  context->svc()->Connect(echo_proxy.NewRequest());

  echo_proxy.set_error_handler([&loop](zx_status_t status) {
    printf("Error reading incoming message: %d\n", status);
    loop.Quit();
  });

  int num_responses = 0;
  echo_proxy->SendString("hi");
  echo_proxy->EchoString("hello", [&](std::string response) {
    printf("Got response %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  });
  echo_proxy.events().OnString = [&](std::string response) {
    printf("Got event %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  };

  loop.Run();
  return num_responses == 2 ? 0 : 1;
}

Terminate the event loop

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:

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

  fuchsia::examples::EchoPtr echo_proxy;
  auto context = sys::ComponentContext::Create();
  context->svc()->Connect(echo_proxy.NewRequest());

  echo_proxy.set_error_handler([&loop](zx_status_t status) {
    printf("Error reading incoming message: %d\n", status);
    loop.Quit();
  });

  int num_responses = 0;
  echo_proxy->SendString("hi");
  echo_proxy->EchoString("hello", [&](std::string response) {
    printf("Got response %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  });
  echo_proxy.events().OnString = [&](std::string response) {
    printf("Got event %s\n", response.c_str());
    if (++num_responses == 2) {
      loop.Quit();
    }
  };

  loop.Run();
  return num_responses == 2 ? 0 : 1;
}

Check that this builds using fx build.

Run the client

If you try running the client directly, you'll notice that the error handler gets called because the client does not automatically get the Echo protocol provided in its sandbox (in /svc). In order to get this to work, a launcher tool is provided that will launch the server, create a new Environment for the client that provides the server's protocol, then launch the client in it.

  1. Configure your GN build as follows:

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

  2. Run the following command to 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-hlcpp-client#meta/echo-client.cmx fuchsia-pkg://fuchsia.com/echo-hlcpp-server#meta/echo-server.cmx fuchsia.examples.Echo

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

[117659.968] 754089:754091> Running echo server
[117659.978] 754194:754196> Got event hi
[117659.978] 754194:754196> Got response hello