比较新的 C++ 和高级 C++ 语言绑定

快速参考

下面介绍了如何识别 C++ 代码中的特定类型/函数/标识符是新的 C++ 绑定还是高级 C++ 绑定的一部分。

以 examples.keyvaluestore.baseline 库为例：

library examples.keyvaluestore.baseline;

type Item = struct {
    key string:128;
    value vector<byte>:64000;
};

type WriteError = flexible enum {
    UNKNOWN = 0;
    INVALID_KEY = 1;
    INVALID_VALUE = 2;
    ALREADY_EXISTS = 3;
};

@discoverable
open protocol Store {
    /// Writes an item to the store.
    flexible WriteItem(struct {
        attempt Item;
    }) -> () error WriteError;
};

下面介绍了各种 FIDL 元素在 C++ 绑定中的映射方式。请注意，表中的“C++”是指新的 C++ 绑定，同样适用于自然域对象和传输域对象。“自然”是指新 C++ 绑定中的自然网域对象。“Wire”是指新 C++ 绑定中的线路域对象。

以下是设置客户端的最常用方法：

  // Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
  // |zx::result| and it must be checked for errors.
  zx::result client_end = component::Connect<examples_canvas_baseline::Instance>();
  if (!client_end.is_ok()) {
    FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
                   << client_end.status_string();
    return -1;
  }

  // Create an instance of the event handler.
  EventHandler event_handler(loop);

  // Create an asynchronous client using the newly-established connection.
  fidl::Client client(std::move(*client_end), dispatcher, &event_handler);
  FX_LOGS(INFO) << "Outgoing connection enabled";

  // Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
  // |zx::result| and it must be checked for errors.
  zx::result client_end = component::Connect<examples_canvas_baseline::Instance>();
  if (!client_end.is_ok()) {
    FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
                   << client_end.status_string();
    return -1;
  }

  // Create an instance of the event handler.
  EventHandler event_handler(loop);

  // Create an asynchronous client using the newly-established connection.
  fidl::WireClient client(std::move(*client_end), dispatcher, &event_handler);
  FX_LOGS(INFO) << "Outgoing connection enabled";

  // Connect to the protocol inside the component's namespace, then create an asynchronous client
  // using the newly-established connection.
  examples::canvas::baseline::InstancePtr instance_proxy;
  auto context = sys::ComponentContext::Create();
  context->svc()->Connect(instance_proxy.NewRequest(dispatcher));
  FX_LOGS(INFO) << "Outgoing connection enabled";

  instance_proxy.set_error_handler([&loop](zx_status_t status) {
    FX_LOGS(ERROR) << "Shutdown unexpectedly";
    loop.Quit();
  });

如需查看完整的代码列表和说明，请参阅 canvas 示例。

以下是实现服务器的最常用方法：

// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::Server<examples_canvas_baseline::Instance> {
  void AddLine(AddLineRequest& request, AddLineCompleter::Sync& completer) override {
    // ...
  }
};

// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::WireServer<examples_canvas_baseline::Instance> {
  void AddLine(AddLineRequestView request, AddLineCompleter::Sync& completer) override {
    // ...
  }
};

// An implementation of the |Instance| protocol.
class InstanceImpl final : public examples::canvas::baseline::Instance {
  void AddLine(Line line) override {
    // ...
  }
};

如需查看完整的代码列表和说明，请参阅 canvas 示例。

新的 C++ 绑定

新的 C++ 绑定通过提供两个生成的网域对象系列以及采用这些类型的相应客户端和服务器 API 来支持低级和高级用例。

自然类型

• 经过优化，可满足高级服务编程的需求。
• 使用惯用的 C++ 类型（如 std::vector、std::optional 和 std::string）表示数据结构。
• 使用智能指针管理堆分配的对象。
• 请使用 zx::handle 管理标识名所有权。
• 可以在其传输线（例如 fidl::StringView）和自然类型表示形式（例如 std::string）之间转换数据。

电线类型

• 经过优化，可以满足低级别系统编程的需求，同时提供比 C 绑定略多的安全性和功能。
• 表示内存布局与传输格式一致的数据结构，即满足 C++ 标准布局的要求。这样便打开了就地编码和解码的大门。
• 生成的结构是底层缓冲区的视图；它们没有内存。
• 支持就地访问 FIDL 消息。
• 对内存分配进行精细控制。
• 使用自有句柄类型，例如 zx::handle。请注意，由于生成的结构是底层缓冲区的视图，因此父结构只有在也拥有底层缓冲区的情况下才会拥有子句柄。例如，FIDL 结构体拥有以内嵌方式存储的所有句柄，但包含句柄的结构体的 FIDL 矢量将表示为矢量视图，该视图不会拥有外行句柄。

客户端和服务器 API

• 与 C 绑定相比，代码生成器生成的代码更多。其中包括构造函数、析构函数、复制/移动函数、网域对象系列之间的转换、协议客户端实现，以及纯虚拟服务器接口。
• 用户通过以下方式实现服务器：对提供的服务器接口进行子类化并替换每项操作的纯虚拟方法。
• 客户端支持同步和异步调用以及同步和异步事件处理。
• 需要 C++17 或更高版本。

如需开始使用，请参阅新 C++ 教程。

高级 C++ 绑定

• 经过优化，可满足高级服务编程的需求。
• 使用惯用的 C++ 类型（如 std::vector、std::optional 和 std::string）表示数据结构。
• 使用智能指针管理堆分配的对象。
• 使用 zx::handle (libzx) 管理标识名所有权。
• 可以将数据从就地 FIDL 缓冲区转换为惯用的堆分配对象。
• 可将数据从惯用的堆分配对象（例如 std::string）转换为就地缓冲区（例如作为 fidl::StringView）。
• 与 C 绑定相比，代码生成器生成的代码更多。这包括构造函数、析构函数、协议代理、协议存根、复制/移动函数以及进出就地缓冲区的转换。
• 客户端通过子类化提供的存根并实现每项操作的虚拟方法来执行协议调度。
• 异步客户端和同步客户端均受支持。但是，异步客户端不是线程安全的。
• 需要 C++14 或更高版本。

请参阅 HLCPP 教程开始使用。

摘要