新的 C++ 绑定

新的 C++ 绑定有自然变体和有线变体。自然绑定针对安全性和工效学设计进行了优化，而电线绑定针对性能进行了优化。大多数代码都应使用自然绑定。只有在性能要求需要或需要精确控制内存分配时，才需要使用有线绑定。

库

假设有如下库声明：

library fuchsia.examples;

协议类型在 fuchsia_examples 命名空间中生成。此库的网域对象是在 fuchsia_examples::wire 命名空间中生成的，而测试基架是在 fidl::testing 命名空间中生成的。

对生成的类型名称进行转换以遵循 Google C++ 样式指南。

常量

常量以 constexpr 的形式生成。例如，以下常量：

const BOARD_SIZE uint8 = 9;
const NAME string = "Tic-Tac-Toe";

在头文件中生成如下：

constexpr uint8_t kBoardSize = 9u;
extern const char[] kName;

内置类型中概述了 FIDL 基元类型和 C++ 类型之间的对应关系。字符串不是 constexpr，而是在头文件中声明为 extern const char[]，并在 .cc 文件中进行定义。

字段

本部分介绍 FIDL 工具链如何将 FIDL 类型转换为 C++ 线类型。这些类型可以在聚合类型中显示为成员，也可以显示为协议方法的参数。

内置类型

根据下表，FIDL 类型转换为 C++ 类型：

FIDL 类型 C++ 线类型
bool bool，（需要 sizeof(bool) == 1）
int8 int8_t
int16 int16_t
int32 int32_t
int64 int64_t
uint8 uint8_t
uint16 uint16_t
uint32 uint32_t
uint64 uint64_t
float32 float
float64 double
array<T, N> fidl::Array<T, N>
vector<T>:N fidl::VectorView<T>
string fidl::StringView
client_end:P fidl::ClientEnd<P>
server_end:P fidl::ServerEnd<P>
zx.Handle zx::handle
zx.Handle:S 尽可能使用相应的 zx 类型。例如，zx::vmo 或 zx::channel。

可选矢量、字符串、客户端/服务器端和句柄与其非可选矢量具有相同的 C++ 线类型。

用户定义的类型

C++ 线绑定为每个用户定义的位、枚举、结构体、表和并集定义一个类。对于严格枚举，它们会定义 enum class 而不是常规类。对于联合，它们使用相同的类来表示可选值和非可选值。对于盒装结构体，它们使用 fidl::ObjectView。如需详细了解 fidl::ObjectView，请参阅线路域对象的内存所有权。

类型定义

块数

根据 bits 定义：

type FileMode = strict bits : uint16 {
    READ = 0b001;
    WRITE = 0b010;
    EXECUTE = 0b100;
};

FIDL 工具链会生成一个 FileMode 类，该类中每个标志都有一个静态成员，以及一个包含所有位成员的掩码（在此示例中为 0b111）的 kMask 成员：

  • const static FileMode kRead
  • const static FileMode kWrite
  • const static FileMode kExecute
  • const static FileMode kMask

FileMode 提供了以下方法：

  • explicit constexpr FileMode(uint16_t)：根据底层基元值构造值，并保留任何未知位成员。
  • constexpr static cpp17::optional<FileMode> TryFrom(uint16_t value)：如果底层基元值不包含任何未知成员，则通过该基元值构造位实例，否则返回 cpp17::nullopt。
  • constexpr static FileMode TruncatingUnknown(uint16_t value)：根据底层基元值构造位的实例，从而清除所有未知成员。
  • 按位运算符：提供了 |、|=、&、&=、^、^= 和 ~ 运算符的实现，允许对 mode |= FileMode::kExecute 等位执行按位运算。
  • 比较运算符 == 和 !=。
  • 适用于 uint16_t 和 bool 的显式转换函数。

如果 FileMode 为灵活，则它还可以使用以下方法：

  • constexpr FileMode unknown_bits() const：返回一个位值，该值仅包含此位值中的未知成员。
  • constexpr bool has_unknown_bits() const：返回此值是否包含任何未知位。

用法示例：

static_assert(std::is_same<fuchsia_examples::FileMode, fuchsia_examples::wire::FileMode>::value,
              "natural bits should be equivalent to wire bits");
static_assert(fuchsia_examples::FileMode::kMask == fuchsia_examples::wire::FileMode::kMask,
              "natural bits should be equivalent to wire bits");

using fuchsia_examples::wire::FileMode;
auto flags = FileMode::kRead | FileMode::kWrite | FileMode::kExecute;
ASSERT_EQ(flags, FileMode::kMask);

枚举

根据 enum 定义：

type LocationType = strict enum {
    MUSEUM = 1;
    AIRPORT = 2;
    RESTAURANT = 3;
};

FIDL 工具链会使用指定的底层类型生成 C++ enum class，如果未指定，则生成 uint32_t：

enum class LocationType : uint32_t {
    kMuseum = 1u;
    kAirport = 2u;
    kRestaurant = 3u;
};

用法示例：

static_assert(
    std::is_same<fuchsia_examples::LocationType, fuchsia_examples::wire::LocationType>::value,
    "natural enums should be equivalent to wire enums");

ASSERT_EQ(static_cast<uint32_t>(fuchsia_examples::wire::LocationType::kMuseum), 1u);

灵活的枚举

灵活的枚举通过以下方法以 class（而非 enum class）的形式实现：

  • constexpr LocationType()：默认构造函数，用于将枚举初始化为未指定的未知值。
  • constexpr LocationType(uint32_t value)：接受枚举底层类型值的显式构造函数。
  • constexpr bool IsUnknown()：返回枚举值是否未知。
  • constexpr static LocationType Unknown()：返回保证被视为未知的枚举值。如果枚举具有带有 [Unknown] 注解的成员，则返回该成员的值。如果没有此类成员，则返回的枚举成员的底层值将未指定。
  • explicit constexpr operator int32_t() const：将枚举转换回其底层值。

生成的类包含每个枚举成员的静态成员，这保证与等效 strict 枚举中的 enum class 成员匹配：

  • const static LocationType kMuseum
  • const static LocationType kAirport
  • const static LocationType kRestaurant

结构体

根据 struct 声明：

type Color = struct {
    id uint32;
    @allow_deprecated_struct_defaults
    name string:MAX_STRING_LENGTH = "red";
};

FIDL 工具链会生成等效的 struct：

struct Color {
    uint32_t id = {};
    fidl::StringView name = {};
}

C++ 绑定不支持默认值，而是对结构体的所有字段进行零初始化。

用法示例：

// Wire structs are simple C++ structs with all their member fields declared
// public. One may invoke aggregate initialization:
fuchsia_examples::wire::Color blue = {1, "blue"};
ASSERT_EQ(blue.id, 1u);
ASSERT_EQ(blue.name.get(), "blue");

// ..or designated initialization.
fuchsia_examples::wire::Color blue_designated = {.id = 1, .name = "blue"};
ASSERT_EQ(blue_designated.id, 1u);
ASSERT_EQ(blue_designated.name.get(), "blue");

// A wire struct may be default constructed, but user-defined default values
// are not supported.
// Default-initializing a struct means all fields are zero-initialized.
fuchsia_examples::wire::Color default_color;
ASSERT_EQ(default_color.id, 0u);
ASSERT_TRUE(default_color.name.is_null());
ASSERT_TRUE(default_color.name.empty());

// There are no getters/setters. One simply reads or mutates the member field.
blue.id = 2;
ASSERT_EQ(blue.id, 2u);

// Here we demonstrate that wire structs do not own their out-of-line children.
// Copying a struct will not copy their out-of-line children. Pointers are
// simply aliased.
{
  fuchsia_examples::wire::Color blue2 = blue;
  ASSERT_EQ(blue2.name.data(), blue.name.data());
}
// Similarly, destroying a wire struct object does not destroy out-of-line
// children. Destroying |blue2| does not invalidate the string contents in |name|.
ASSERT_EQ(blue.name.get(), "blue");

联合体

根据联合定义：

type JsonValue = strict union {
    1: int_value int32;
    2: string_value string:MAX_STRING_LENGTH;
};

FIDL 将生成一个 JsonValue 类。JsonValue 包含一个表示可能的变体的公共标记枚举类：

enum class Tag : fidl_xunion_tag_t {
  kIntValue = 2,
  kStringValue = 3,
};

Tag 的每个成员都有一个与其在 union 定义中指定的序号相匹配的值。

JsonValue 提供了以下方法：

  • JsonValue()：默认构造函数。构造的联合体最初处于“不存在”状态，直到设置变体为止。应尽可能首选使用 WithFoo 构造函数。
  • ~JsonValue()：用于清除底层联合数据的构造函数。
  • JsonValue(JsonValue&&)：默认 move 构造函数。
  • JsonValue& operator=(JsonValue&&)：默认移动分配关系
  • static JsonValue WithIntValue(fidl::ObjectView<int32>) 和 static JsonValue WithStringValue(fidl::ObjectView<fidl::StringView>)：直接构建联合体的特定变体的静态构造函数。
  • bool has_invalid_tag()：如果 JsonValue 的实例尚未设置变体，则返回 true。如果在没有先设置变体的情况下调用此方法，则会导致断言错误。
  • bool is_int_value() const 和 bool is_string_value() const：每个变体都有一个关联的方法，用于检查 JsonValue 的实例是否属于该变体
  • const int32_t& int_value() const 和 const fidl::StringView& string_value() const：每个变体的只读访问器方法。如果在没有先设置变体的情况下调用这些方法，则会导致断言错误。
  • int32_t& int_value() 和 fidl::StringView& string_value()：每个变体的可变访问器方法。如果 JsonValue 未设置指定的变体，这些方法将失败
  • Tag Which() const：返回 JsonValue 的当前标记。在没有先设置变体的情况下调用此方法会导致断言错误。

用法示例：

// When the active member is larger than 4 bytes, it is stored out-of-line,
// and the union will borrow the out-of-line content. The lifetimes can be
// tricky to reason about, hence the FIDL runtime provides a |fidl::AnyArena|
// interface for arena-based allocation of members. The built-in
// implementation is |fidl::Arena|.
//
// Pass the arena as the first argument to |With...| factory functions, to
// construct the member content on the arena, and have the union reference it.
fidl::Arena arena;
fuchsia_examples::wire::JsonValue str_union =
    fuchsia_examples::wire::JsonValue::WithStringValue(arena, "1");

// |Which| obtains an enum corresponding to the active member, which may be
// used in switch cases.
ASSERT_EQ(str_union.Which(), fuchsia_examples::wire::JsonValue::Tag::kStringValue);

// Before accessing the |string_value| member, one should check if the union
// indeed currently holds this member, by querying |is_string_value|.
// Accessing the wrong member will cause a panic.
ASSERT_TRUE(str_union.is_string_value());
ASSERT_EQ("1", str_union.string_value().get());

// When the active member is smaller or equal to 4 bytes, such as an
// |int32_t| here, the entire member is inlined into the union object.
// In these cases, arena allocation is not necessary, and the union
// object wholly owns the member.
fuchsia_examples::wire::JsonValue int_union = fuchsia_examples::wire::JsonValue::WithIntValue(1);
ASSERT_TRUE(int_union.is_int_value());
ASSERT_EQ(1, int_union.int_value());

// A default constructed wire union is invalid.
// It must be initialized with a valid member before use.
// One is not allowed to send invalid unions through FIDL client/server APIs.
fuchsia_examples::wire::JsonValue default_union;
ASSERT_TRUE(default_union.has_invalid_tag());
default_union = fuchsia_examples::wire::JsonValue::WithStringValue(arena, "hello");
ASSERT_FALSE(default_union.has_invalid_tag());
ASSERT_TRUE(default_union.is_string_value());
ASSERT_EQ(default_union.string_value().get(), "hello");

// Optional unions are represented with |fidl::WireOptional|.
fidl::WireOptional<fuchsia_examples::wire::JsonValue> optional_json;
ASSERT_FALSE(optional_json.has_value());
optional_json = fuchsia_examples::wire::JsonValue::WithIntValue(42);
ASSERT_TRUE(optional_json.has_value());
// |fidl::WireOptional| has a |std::optional|-like API.
fuchsia_examples::wire::JsonValue& value = optional_json.value();
ASSERT_TRUE(value.is_int_value());

// When switching over the tag from a flexible union, one must add a `default:`
// case, to handle members not understood by the FIDL schema or to handle
// newly added members in a source compatible way.
fuchsia_examples::wire::FlexibleJsonValue flexible_value =
    fuchsia_examples::wire::FlexibleJsonValue::WithIntValue(1);
switch (flexible_value.Which()) {
  case fuchsia_examples::wire::FlexibleJsonValue::Tag::kIntValue:
    ASSERT_EQ(flexible_value.int_value(), 1);
    break;
  case fuchsia_examples::wire::FlexibleJsonValue::Tag::kStringValue:
    FAIL() << "Unexpected tag. |flexible_value| was set to int";
    break;
  default:  // Removing this branch will fail to compile.
    break;
}

灵活联合和未知变体

灵活联合在生成的 Tag 类中有一个额外的变体：

  enum class Tag : fidl_xunion_tag_t {
    ... // other fields omitted
    kUnknown = ::std::numeric_limits<::fidl_union_tag_t>::max(),
  };

当包含具有未知变体的联合体的 FIDL 消息被解码到 JsonValue 中时，JsonValue::Which() 将返回 JsonValue::Tag::kUnknown。

C++ 绑定绑定不会存储未知变体的原始字节和句柄。

不支持对具有未知变体的联合进行编码，这会导致编码失败。

表格

根据表定义：

type User = table {
    1: age uint8;
    2: name string:MAX_STRING_LENGTH;
};

FIDL 工具链使用以下方法生成 User 类：

  • User()：默认构造函数，用于初始化未设置字段的空表。
  • User::Builder(fidl::AnyArena& arena)：构建器工厂。 返回 fidl::WireTableBuilder<User>，用于从提供的 arena 中分配帧和成员。
  • User::ExternalBuilder(fidl::ObjectView<fidl::WireTableFrame<User>> frame)：外部构建器工厂。返回带有提供的帧的 fidl::WireTableExternalBuilder<User>。此构建器需要谨慎地管理内存，但可能偶尔有用。Caveat Emptor。
  • User(User&&)：默认 move 构造函数。
  • ~User()：默认析构函数。
  • User& operator=(User&&)：默认移动分配关系。
  • bool IsEmpty() const：如果未设置任何字段，则返回 true。
  • bool has_age() const 和 bool has_name() const：返回是否设置了字段。
  • const uint8_t& age() const 和 const fidl::StringView& name() const：只读字段访问器方法。如果在没有先设置该字段的情况下调用这些方法，则会导致断言错误。

为了构建表，还会生成另外三个类：fidl::WireTableBuilder<User>、fidl::WireTableExternalBuilder<User> 和 fidl::WireTableFrame<User>。

fidl::WireTableFrame<User> 是表内部存储空间的容器，与构建器分开分配，以维护底层传输格式的对象布局。仅供构建器在内部使用。

fidl::WireTableFrame<User> 具有以下方法：

  • WireTableFrame()：默认构造函数。

fidl::WireTableExternalBuilder<User> 具有以下方法：

  • fidl::WireTableExternalBuilder<User> age(uint8_t)：通过将存在时间内嵌到表框架中设置存在时间。
  • fidl::WireTableExternalBuilder<User> name(fidl::ObjectView<fidl::StringView>)：使用已分配的值设置名称。
  • User Build()：构建并返回表对象。调用 Build() 后，必须舍弃构建器。

fidl::WireTableBuilder<User> 包含 fidl::WireTableExternalBuilder<User> 的所有方法（但具有来自 setter 的正确返回类型），并添加了以下内容：

  • fidl::WireTableBuilder<User> name(std::string_view)：通过从构建器的 arena 中分配新的 fidl::StringView 并将提供的字符串复制到其中来设置名称。

用法示例：

fidl::Arena arena;
// To construct a wire table, you need to first create a corresponding
// |Builder| object, which borrows an arena. The |arena| will be used to
// allocate the table frame, a bookkeeping structure for field presence.
auto builder = fuchsia_examples::wire::User::Builder(arena);

// To set a table field, call the member function with the same name on the
// builder. The arguments will be forwarded to the field constructor, and the
// field is allocated on the initial |arena|.
builder.age(10);

// Note that only the inline portion of the field is automatically placed in
// the arena. The field itself may reference its own out-of-line content,
// such as in the case of |name| whose type is |fidl::StringView|. |name|
// will reference the "jdoe" literal, which lives in static program storage.
builder.name("jdoe");

// Call |Build| to finalize the table builder into a |User| table.
// The builder is no longer needed after this point. |user| will continue to
// reference objects allocated in the |arena|.
fuchsia_examples::wire::User user = builder.Build();
ASSERT_FALSE(user.IsEmpty());

// Before accessing a field, one should check if it is present, by querying
// |has_...|. Accessing an absent field will panic.
ASSERT_TRUE(user.has_name());
ASSERT_EQ(user.name().get(), "jdoe");

// Setters may be chained, leading to a fluent syntax.
user = fuchsia_examples::wire::User::Builder(arena).age(30).name("bob").Build();
ASSERT_FALSE(user.IsEmpty());
ASSERT_TRUE(user.has_age());
ASSERT_EQ(user.age(), 30);
ASSERT_TRUE(user.has_name());
ASSERT_EQ(user.name().get(), "bob");

// A default constructed wire table is empty.
// This is mostly useful to make requests or replies with empty tables.
fuchsia_examples::wire::User defaulted_user;
ASSERT_TRUE(defaulted_user.IsEmpty());

// In some situations it could be difficult to provide an arena when
// constructing tables. For example, here it is hard to provide constructor
// arguments to 10 tables at once. Because a default constructed wire table is
// empty, a new table instance should be built and assigned in its place.
fidl::Array<fuchsia_examples::wire::User, 10> users;
for (auto& user : users) {
  ASSERT_TRUE(user.IsEmpty());
  user = fuchsia_examples::wire::User::Builder(arena).age(30).Build();
  ASSERT_FALSE(user.IsEmpty());
  ASSERT_EQ(user.age(), 30);
}
ASSERT_EQ(users[0].age(), 30);

// Finally, tables support checking if it was received with unknown fields.
// A table created by ourselves will never have unknown fields.
ASSERT_FALSE(user.HasUnknownData());

除了使用 fidl::ObjectView 分配字段之外，您还可以使用线路网域对象的内存所有权中所述的任何分配策略。

内嵌布局

生成的 C++ 代码会将 fidlc 选择的名称用于内嵌布局。

C++ 绑定还会生成作用域名称来引用内嵌布局。例如，对于 FIDL：

type Outer = struct {
  inner struct {};
};

可以使用其全局唯一名称 Inner 以及作用域名称 Outer::Inner 来引用内部结构体。使用 @generated_name 属性替换顶级名称时，这会很有用，例如在以下情况下：

type Outer = struct {
  inner
  @generated_name("SomeCustomName") struct {};
};

内部结构体可以称为 SomeCustomName 或 Outer::Inner。

协议结果类型是这方面的另一个例子：TicTacToe_MakeMove_Result 等类型的成功变体和错误变体可分别引用为 TicTacToe_MakeMove_Result::Response 和 TicTacToe_MakeMove_Result::Err。

协议

根据 protocol：

closed protocol TicTacToe {
    strict StartGame(struct {
        start_first bool;
    });
    strict MakeMove(struct {
        row uint8;
        col uint8;
    }) -> (struct {
        success bool;
        new_state box<GameState>;
    });
    strict -> OnOpponentMove(struct {
        new_state GameState;
    });
};

FIDL 将生成一个 TicTacToe 类，该类充当客户端和服务器将用于与此服务进行交互的类型和类的入口点。本节其余部分中的各个子部分介绍了此类的成员。

类型化通道端点

C++ 绑定通过 Zircon 通道传输来发送和接收 FIDL 协议消息，这些传输包含任意的字节和句柄。该 API 不会公开原始端点（例如 zx::channel），而是公开三个模板化端点类：

  • fidl::ClientEnd<TicTacToe>：TicTacToe 协议的客户端端点；它具有一个 zx::channel。需要对通道具备专有所有权的客户端绑定会使用此类型。例如，可以通过 fidl::ClientEnd<TicTacToe> 构建 fidl::WireClient<TicTacToe>，这也称为“将频道绑定到消息调度程序”。
  • fidl::UnownedClientEnd<TicTacToe>：借用 TicTacToe 协议的某个客户端端点的无主值。不需要频道专有所有权的客户端 API 将采用此类型。UnownedClientEnd 可通过调用 borrow() 从同一协议类型的 ClientEnd 派生而来。从端点借用的端点可以在同一进程内执行 std::move 操作，但不能在进程外删除或转移，同时存在无主的借用。
  • fidl::ServerEnd<TicTacToe>：TicTacToe 协议的服务器端点；它具有一个 zx::channel。需要频道专有所有权的服务器绑定会使用此类型。例如，可以向 fidl::BindServer<TicTacToe> 以及其他参数提供 fidl::ServerEnd<TicTacToe> 以创建服务器绑定。

没有 UnownedServerEnd，因为尚不需要用它来安全实现当前的一系列功能。

您可以使用 ::fidl::CreateEndpoints<TicTacToe> 库调用创建一对客户端和服务器端点。在协议请求流水线场景中，在将服务器端点与远程服务器std::move()后，可以立即开始在客户端端点上执行操作。

如需了解详情，请参阅有关这些类型的类文档。

请求和响应类型

您可以通过一对别名 fidl::WireRequest 和 fidl::WireEvent 访问 FIDL 方法或事件的请求类型：

  • fidl::WireRequest<TicTacToe::StartGame>
  • fidl::WireRequest<TicTacToe::MakeMove>
  • fidl::WireEvent<TicTacToe::OnOpponentMove>

如果请求或事件使用的类型是已命名的类型，则别名将指向该类型。如果请求类型是匿名类型，则别名将指向为该匿名类型生成的类型名称。对于方法请求和事件，生成的请求类型为 [Method]Request。

与请求不同，对双向方法的响应会生成为新类型 fidl::WireResult：

  • fidl::WireResult<TicTacToe::MakeMove>

fidl::WireResult 类型继承自 fidl::Status，其状态会指示调用是否在 FIDL 层成功。如果该方法的响应非空或使用 FIDL 错误语法，生成的 WireResult 类型还会有一组访问器来访问返回值或应用层错误。所含结果的可用访问器如下：

  • WireResultUnwrapType<FidlMethod>* Unwrap()
  • const WireResultUnwrapType<FidlMethod>* Unwrap() const
  • WireResultUnwrapType<FidlMethod>& value()
  • const WireResultUnwrapType<FidlMethod>& value() const
  • WireResultUnwrapType<FidlMethod>* operator->()
  • const WireResultUnwrapType<FidlMethod>* operator->() const
  • WireResultUnwrapType<FidlMethod>& operator*()
  • const WireResultUnwrapType<FidlMethod>& operator*() const

WireResultUnwrapType 是另一种类型别名，具体取决于方法是否使用了错误语法。根据这个示例库，

library response.examples;

protocol Test {
  Foo() -> (struct { x int32; });
  Bar() -> () error int32;
  Baz() -> (struct { x int32; }) error int32;
};

以下是 Test 协议中每个方法的 fidl::WireResultUnwrapType：

  • fidl::WireResultUnwrapType<response_examples::Test::Foo> = response_examples::wire::TestFooResponse
  • fidl::WireResultUnwrapType<response_examples::Test::Bar> = fit::result<int32_t>
  • fidl::WireResultUnwrapType<response_examples::Test::Baz> = fit::result<int32_t, ::response_examples::wire::TestBazResponse*>

客户端

C++ 线绑定绑定提供了以客户端形式与 FIDL 协议进行交互的多种方式：

  • fidl::WireClient<TicTacToe>：此类为传出的异步和同步调用以及异步事件处理提供了线程安全的 API。它拥有通道的客户端。需要 async_dispatcher_t* 才能支持异步 API 以及事件和错误处理。它必须与单线程调度程序一起使用。此类的对象必须绑定到客户端端点，并在运行调度程序的同一线程上销毁。对于大多数用例来说，除了无法使用 async_dispatcher_t 或需要在线程之间移动客户端的情况之外，建议使用此变体。
  • fidl::WireSharedClient<TicTacToe>：与 WireClient 相比，此类对线程模型的看法较少，但需要两阶段关闭模式以防止释放后使用。此类的对象可以在任意线程上销毁。它还支持与多线程调度程序配合使用。如需了解详情，请参阅新的 C++ 绑定线程处理指南。
  • fidl::WireSyncClient<TicTacToe>：此类公开了用于去电以及事件处理的纯同步 API。它拥有通道的客户端。
  • fidl::WireCall<TicTacToe>：此类与 WireSyncClient 相同，只是它没有渠道客户端端的所有权。在实现获取原始 zx_handle_t 的 C API 时，WireCall 可能优于 WireSyncClient。

WireClient

fidl::WireClient 是线程安全的，支持同步和异步调用以及异步事件处理。

恣意创作

创建的客户端包含协议 P 的客户端 fidl::ClientEnd<P>、async_dispatcher_t* 和指向 WireAsyncEventHandler 的可选指针，后者用于定义收到 FIDL 事件或解除客户端绑定时要调用的方法。如果未替换特定事件的虚拟方法，则系统会忽略该事件。

class EventHandler : public fidl::WireAsyncEventHandler<TicTacToe> {
 public:
  EventHandler() = default;

  void OnOpponentMove(fidl::WireEvent<OnOpponentMove>* event) override {
    /* ... */
  }

  void on_fidl_error(fidl::UnbindInfo unbind_info) override { /* ... */ }
};

fidl::ClientEnd<TicTacToe> client_end = /* logic to connect to the protocol */;
EventHandler event_handler;
fidl::WireClient<TicTacToe> client;
client.Bind(std::move(client_end), dispatcher, &event_handler);

如果服务器端关闭或从服务器收到无效消息，绑定可能会被自动解除。您还可以通过销毁客户端对象主动解除绑定。

传出的 FIDL 方法

您可以通过 fidl::WireClient 实例调用传出 FIDL API。解引用 fidl::WireClient 后，您可以访问以下方法：

  • 对于 StartGame（即发即弃）：

    • fidl::Status StartGame(bool start_first)：消防和忘记方法的受管理变体。

  • 对于 MakeMove（双向）：

    • [...] MakeMove(uint8_t row, uint8_t col)：异步双向方法的受管理变体。它会返回一个内部类型，该类型必须用于注册异步接续以接收结果，例如回调。请参阅指定异步接续。除非调度程序关闭，否则将在调度程序线程上执行接续。

fidl::WireClient::buffer 提供对以下方法的访问权限：

  • fidl::Status StartGame(bool start_first)：触发和忘记方法的调用方分配的变体。
  • [...] MakeMove(uint8_t row, uint8_t col)：双向方法的异步调用方分配的变体。它返回的内部类型与代管式变体相同。

fidl::WireClient::sync 提供对以下方法的访问权限：

  • fidl::WireResult<MakeMove> MakeMove(uint8_t row, uint8_t col)：双向方法的同步托管变体。WireSyncClient 中存在相同的方法。
指定异步接续

请参阅相应的 C++ 文档注释。

系统会使用一个结果对象（代表已成功解码的响应或错误）来调用该接续。当用户需要将每个 FIDL 调用的错误传播到其发起者时，此方法非常有用。例如，服务器在处理现有 FIDL 调用时可能需要执行另一个 FIDL 调用，并且需要在发生错误时使原始调用失败。

以下是通过双向调用返回的对象的一些方法：

  • Then：接受回调，并且最多调用一次该回调，直到客户端消失。

  • ThenExactlyOnce：当传递回调时，无论调用成功还是失败，该回调都只执行一次。不过，由于回调是异步调用的，因此请留意销毁客户端时释放后使用 bug：回调捕获的对象可能无效。

  • 当需要控制分配时，ThenExactlyOnce 可能也会接受响应上下文。TicTacToe 只有一个响应上下文 fidl::WireResponseContext<TicTacToe::MakeMove>，其中含有应替换的纯虚拟方法来处理调用的结果：

virtual void OnResult(fidl::WireUnownedResult<MakeMove>& result) = 0;

使用一个结果对象调用 OnResult，该结果对象表示已成功解码的响应或错误。您负责确保响应上下文对象的存在时间比整个异步调用的持续时间更长，因为 fidl::WireClient 按地址借用上下文对象，以避免隐式分配。

集中式错误处理程序

当绑定因错误而被拆除时，系统会从调度程序线程调用 fidl::WireAsyncEventHandler<TicTacToe>::on_fidl_error 并提供详细原因。当错误是调度程序关闭时，系统将从正在调用调度程序关闭的线程调用 on_fidl_error。建议将用于日志记录或发布资源的中心逻辑放在该处理程序中。

WireSyncClient

fidl::WireSyncClient<TicTacToe> 是一个同步客户端，可提供以下方法：

  • explicit WireSyncClient(fidl::ClientEnd<TicTacToe>)：构造函数。
  • ~WireSyncClient()：默认析构函数。
  • WireSyncClient(&&)：默认 move 构造函数。
  • WireSyncClient& operator=(WireSyncClient&&)：默认移动分配关系。
  • const fidl::ClientEnd<TicTacToe>& client_end() const：返回底层客户端端点。
  • fidl::Status StartGame(bool start_first)：Fire 和 Forget 方法调用的受管理变体。请求的缓冲区分配完全在此函数中处理。
  • fidl::WireResult<TicTacToe::MakeMove> MakeMove(uint8_t row, uint8_t col)：双向方法调用的受管理变体，它将参数作为参数并返回 WireResult 对象。请求和响应的缓冲区分配完全在此函数中进行处理。绑定会根据 FIDL 传输格式和最大长度约束，在编译时计算特定于此调用的安全缓冲区大小。如果缓冲区小于 512 个字节，则会在堆栈上分配缓冲区，否则在堆上分配缓冲区。如需详细了解缓冲区管理，请参阅 WireResult。
  • fidl::Status HandleOneEvent(SyncEventHandler& event_handler)：用于仅消耗渠道中的一个事件的块。如果服务器发送了抬头，则系统会返回相应抬头中包含的状态。请参阅事件。

fidl::WireSyncClient<TicTacToe>::buffer 提供了以下方法：

  • fidl::WireUnownedResult<TicTacToe::StartGame> StartGame(bool start_first)：触发和忘记调用的调用方分配的变体，该变体会采用作为 buffer 参数和请求参数传递的请求缓冲区的后备存储空间，并返回一个 fidl::WireUnownedResult。

  • fidl::WireUnownedResult<TicTacToe::MakeMove> MakeMove(uint8_t row, uint8_t col)：双向方法的调用方分配的变体，既请求对请求进行编码的空间，也请求从传递给 buffer 方法的同一内存资源接收响应的空间。

请注意，每个方法都有自有变体和调用方分配的变体。简而言之，每个方法的自有变体处理请求和响应的内存分配，而调用方分配的变体允许用户自行提供缓冲区。拥有的变体更易于使用，但可能会导致额外的分配。

WireCall

fidl::WireCall<TicTacToe> 提供的方法与 WireSyncClient 中的方法类似，唯一的区别在于 WireCall 可以使用 fidl::UnownedClientEnd<TicTacToe>（即借用客户端端点）来构建：

  • fidl::WireResult<StartGame> StartGame(bool start_first)：StartGame 的自有变体。
  • fidl::WireResult<MakeMove> MakeMove(uint8_t row, uint8_t col)：MakeMove 的自有变体。

fidl::WireCall<TicTacToe>(client_end).buffer 提供了以下方法：

  • fidl::WireUnownedResult<StartGame> StartGame(bool start_first)：StartGame 的调用方分配的变体。
  • fidl::WireUnownedResult<MakeMove> MakeMove(uint8_t row, uint8_t col);：MakeMove 的调用方分配的变体。

Result、WireResult 和 WireUnOwnResult

WireSyncClient 和 WireCall 的每个方法的受管理变体都会返回 fidl::WireResult<Method> 类型，而调用方分配变体都会返回 fidl::WireUnownedResult<Method>。针对 fidl::WireClient 的触发和忘记方法会返回 fidl::Status。这些类型定义了同一组方法：

  • zx_status status() const 用于返回传输状态。它会返回在（如果适用）线性化、编码、对底层信道进行调用以及对结果进行解码期间遇到的第一个错误。如果状态为 ZX_OK，则表示调用成功，反之亦然。
  • 当 status() 不是 ZX_OK 时，fidl::Reason reason() const 会返回关于哪个操作失败的详细信息。例如，如果编码失败，reason() 将返回 fidl::Reason::kEncodeError。当状态为 ZX_OK 时，不应调用 reason()。
  • 当状态不是 ZX_OK 时，const char* error_message() const 会包含一条简短的错误消息。否则，返回 nullptr。
  • （仅适用于 WireResult 和 WireUnOwnResult 用于双向调用）T* Unwrap() 会返回一个指向响应结构体的指针。对于 WireResult，该指针指向结果对象拥有的内存。对于 WireUnownedResult，该指针指向调用方提供的缓冲区。仅当状态为 ZX_OK 时，才应调用 Unwrap()。

此外，用于双向调用的 WireResult 和 WireUnownedResult 将实现返回响应结构体本身的解引用运算符。这允许使用如下代码：

fidl::WireResult result = client.sync()->MakeMove(0, 0);
auto* response = result.Unwrap();
bool success = response->success;

简化为：

fidl::WireResult result = client.sync()->MakeMove(0, 0);
bool success = result->success;

WireResult<Method> 管理所有缓冲区和句柄的所有权，而 ::Unwrap() 会返回该缓冲区的视图。因此，此对象的存在时间必须比对未封装响应的任何引用更长。

分配策略和移动语义

如果能保证消息大小不超过 512 个字节，则 WireResult 会以内嵌方式存储响应缓冲区。由于结果对象通常在调用方的堆栈上实例化，因此这实际上意味着当响应较小时，系统会进行堆栈分配。如果最大响应大小超过 512 字节，则 WireResult 会改为包含堆分配的缓冲区。

因此，不支持在 WireResult 上使用 std::move()。如果缓冲区是内联的，则必须复制内容，并且指向外联对象的指针必须更新为目标对象中的位置，对于通常被认为费用低的移动操作来说，这些开销会令人惊讶。

如果需要将结果对象传递给多个函数调用，请考虑在最外层的函数中预先分配缓冲区，并使用调用方分配变种。

服务器

为 FIDL 协议实现服务器需要提供 TicTacToe 的具体实现。

生成的 fidl::WireServer<TicTacToe> 类具有纯虚方法，对应于 FIDL 协议中定义的方法调用。用户通过提供 fidl::WireServer<TicTacToe> 的具体实现来实现 TicTacToe 服务器，该实现具有以下纯虚拟方法：

  • virtual void StartGame(StartGameRequestView request, StartGameCompleter::Sync& completer)
  • virtual void MakeMove(MakeMoveRequestView request, MakeMoveCompleter::Sync& completer)

请参阅示例 C++ 服务器，了解如何绑定和设置服务器实现。

C++ 线绑定还提供函数，用于在给定实现 fidl::WireDispatch<TicTacToe> 的情况下手动调度消息：

  • void fidl::WireDispatch<TicTacToe>(fidl::WireServer<TicTacToe>* impl, fidl::IncomingMessage&& msg, ::fidl::Transaction* txn)：调度传入消息。如果没有匹配的处理程序，它会关闭消息中的所有句柄并通知 txn 出现错误。

请求

该请求会作为每个生成的 FIDL 方法处理程序的第一个参数提供。这是请求的视图（指针）。所有请求参数均可使用箭头运算符和参数名称进行访问。

例如：

  • request->start_first
  • request->row

有关请求生命周期的说明，请参阅传输域对象的内存所有权。

完成者

在生成的每个 FIDL 方法处理程序的所有 FIDL 请求参数之后，都会提供一个补全器。完整的类可以捕获完成 FIDL 事务的各种方法（例如，通过发送回复、以书写结尾的频道等），并且既有同步版本，又有异步版本（尽管 ::Sync 类默认作为参数提供）。在此示例中，这些完成者为：

  • fidl::WireServer<TicTacToe>::StartGameCompleter::Sync
  • fidl::WireServer<TicTacToe>::StartGameCompleter::Async
  • fidl::WireServer<TicTacToe>::MakeMoveCompleter::Sync
  • fidl::WireServer<TicTacToe>::MakeMoveCompleter::Async

所有 completer 类均提供以下方法：

  • void Close(zx_status_t status)：关闭频道并发送 status 作为片语。

此外，两种方式将为响应响应提供两个版本的 Reply 方法：受管变体和调用方分配变体。这些变体对应于客户端 API 中显示的变体。例如，MakeMoveCompleter::Sync 和 MakeMoveCompleter::Async 都提供以下 Reply 方法：

  • ::fidl::Status Reply(bool success, fidl::ObjectView<GameState> new_state)
  • ::fidl::Status Reply(fidl::BufferSpan _buffer, bool success, fidl::ObjectView<GameState> new_state)

由于 Reply 返回的状态与解除绑定状态相同，因此您可以放心地忽略它。

最后，可以使用 ToAsync() 方法将两种方法的同步完成器转换为异步完成器。异步完成器的生命周期可以比处理程序的作用域更长，例如将处理程序移到 lambda 捕获中，使服务器能够异步响应请求。异步完成器响应客户端的方法与同步完成器相同。如需查看用法示例，请参阅异步响应请求

并行消息处理

默认情况下，系统会按顺序处理来自单个绑定的消息，也就是说，系统会在必要时唤醒附加到调度程序的单个线程（运行循环），读取消息，执行处理程序，然后返回到调度程序。::Sync 完成器提供了一个额外的 API，即 EnableNextDispatch()，它可用于选择性地违反此限制。具体来说，调用此 API 可让等待调度程序的另一个线程处理绑定中的下一条消息，而第一个线程仍在处理程序中。请注意，对同一 Completer EnableNextDispatch() 的重复调用具有幂等性。

void DirectedScan(int16_t heading, ScanForPlanetsCompleter::Sync& completer) override {
  // Suppose directed scans can be done in parallel. It would be suboptimal to block one scan until
  // another has completed.
  completer.EnableNextDispatch();
  fidl::VectorView<Planet> discovered_planets = /* perform a directed planet scan */;
  completer.Reply(std::move(discovered_planets));
}

调用方分配的方法

上述许多 API 都提供了所生成方法的自有变体和调用方分配的变体。

调用方分配的变体会将所有内存分配责任移交给调用方。类型 fidl::BufferSpan 引用缓冲区地址和大小。绑定库将使用它来构建 FIDL 请求，因此它必须足够大。方法参数（例如 heading）会线性化到缓冲区内的适当位置。创建缓冲区的方式有多种：

// 1. On the stack
using StartGame = TicTacToe::StartGame;
fidl::SyncClientBuffer<StartGame> buffer;
auto result = client.buffer(buffer.view())->StartGame(true);

// 2. On the heap
auto buffer = std::make_unique<fidl::SyncClientBuffer<StartGame>>();
auto result = client.buffer(buffer->view())->StartGame(true);

// 3. Some other means, e.g. thread-local storage
constexpr uint32_t buffer_size = fidl::SyncClientMethodBufferSizeInChannel<StartGame>();
uint8_t* buffer = allocate_buffer_of_size(buffer_size);
fidl::BufferSpan buffer_span(/* data = */buffer, /* capacity = */request_size);
auto result = client.buffer(buffer_span)->StartGame(true);

// Check the transport status (encoding error, channel writing error, etc.)
if (result.status() != ZX_OK) {
  // Handle error...
}

// Don't forget to free the buffer at the end if approach #3 was used...

使用调用方分配变种时，result 对象会借用请求和响应缓冲区（因此其类型为 WireUnownedResult）。请确保缓冲区的存在时间比 result 对象长。请参阅 WireUnownedResult。

事件

在 C++ 绑定中，可以异步或同步处理事件，具体取决于所使用的客户端类型。

异步客户端

使用 fidl::WireClient 时，可以通过向类传递 fidl::WireAsyncEventHandler<TicTacToe>* 来异步处理事件。WireAsyncEventHandler 类具有以下成员：

  • virtual void OnOpponentMove(fidl::WireEvent<OnOpponentMove>* event) {}：OnOpponentMove 事件的处理程序（每个事件一个方法）。

  • virtual on_fidl_error(::fidl::UnbindInfo info) {}：在客户端遇到终端错误时调用的方法。

为了能够处理事件和错误，必须定义一个从 fidl::WireAsyncEventHandler<TicTacToe> 继承的类。

同步客户端

在 WireSyncClient 中，通过调用 HandleOneEvent 函数并向其传递 fidl::WireSyncEventHandler<TicTacToe> 来同步处理事件。

WireSyncEventHandler 是一个类，其中包含每个事件的纯虚拟方法。在此示例中，它包含以下成员：

  • virtual void OnOpponentMove(fidl::WireEvent<TicTacToe::OnOpponentMove>* event) = 0：OnOpponentMove 事件的句柄。

为了能够处理事件，必须定义一个从 WireSyncEventHandler 继承的类。此类必须为协议中的所有事件定义虚拟方法。然后，必须创建此类的实例。

处理一个事件的方法有两种。每个方法都使用用户定义的事件处理脚本类的实例：

  • ::fidl::Status fidl::WireSyncClient<TicTacToe>::HandleOneEvent( SyncEventHandler& event_handler)：同步客户端的绑定版本。
  • ::fidl::Status fidl::WireSyncEventHandler<TicTacToe>::HandleOneEvent( fidl::UnownedClientEnd<TicTacToe> client_end)：未绑定版本，使用 fidl::UnownedClientEnd<TicTacToe> 为特定处理程序处理一个事件。

对于每次调用 HandleOneEvent，该方法都会在通道上等待一条传入消息。然后，对消息进行解码。如果结果为 fidl::Status::Ok()，则表示已调用且仅调用了一个虚拟方法。否则，系统不会调用任何虚拟方法，并且状态会指示错误。

如果处理程序始终相同（从一次调用到 HandleOneEvent 到另一次调用），则 WireSyncEventHandler 对象应构建一次，并在每次需要调用 HandleOneEvent 时使用。

如果某个事件被标记为过渡，系统会提供默认实现，这会导致 HandleOneEvent 在接收到用户未处理的过渡事件时返回错误。

服务器

fidl::WireSendEvent 用于从服务器端发送事件。存在两种过载：

  • fidl::WireSendEvent(const fidl::ServerBindingRef<Protocol>& binding_ref)，用于通过服务器绑定引用发送事件。
  • fidl::WireSendEvent(const fidl::ServerEnd<Protocol>& endpoint) 通过端点发送事件。
使用服务器绑定对象发送事件

将服务器实现绑定到某个通道时，fidl::BindServer 会返回一个 fidl::ServerBindingRef<Protocol>，这是您可以用来与服务器绑定安全地交互的方式。

使用绑定引用调用 fidl::WireSendEvent 时，系统会返回一个接口来发送事件。

事件发送器接口包含用于发送每个事件的方法。例如，TicTacToe 的事件发送器接口提供了以下方法：

  • fidl::Status OnOpponentMove(GameState new_state)：代管式变种。

调用 .buffer(...) 会返回一个类似的接口，用于调用方分配变种，从传递到 .buffer 的内存资源中分配编码缓冲区，这类似于客户端 API 和服务器完成器。

使用 ServerEnd 对象发送事件

服务器端点本身由 fidl::ServerEnd<Protocol> 表示。

使用服务器绑定对象发送事件是在服务器端点绑定到实现时发送事件的标准方法。不过，有时可能会要求直接在 fidl::ServerEnd<TicTacToe> 对象上发送事件，而不设置服务器绑定。

fidl::WireSendEvent 接受对 fidl::ServerEnd<Protocol> 的常量引用。它不支持 zx::unowned_channel，以降低在其他位置关闭句柄后使用端点的可能性。

成果

假设有一个方法：

protocol TicTacToe {
    MakeMove(struct {
      row uint8;
      col uint8;
    }) -> (struct {
      new_state GameState;
    }) error MoveError;
};

FIDL 将在完成器上生成与具有错误类型的方法相对应的便捷方法。根据 Reply“变体”，完成器将具有 ReplySuccess 和/或 ReplyError 方法，直接响应成功或错误数据，而无需构造联合。

对于受管理变种，这两种方法都可用：

  • void ReplySuccess(GameState new_state)
  • void ReplyError(MoveError error)

由于 ReplyError 不需要堆分配，因此调用方分配的变种只有 ReplySuccess：

  • void ReplySuccess(fidl::BufferSpan _buffer, GameState new_state)

请注意，传入的缓冲区用于保存整个响应，而不仅仅是与成功变体对应的数据。

您还可以使用定期生成的 Reply 方法：

  • void Reply(TicTacToe_MakeMove_Result result)：自有变体。
  • void Reply(fidl::BufferSpan _buffer, TicTacToe_MakeMove_Result result)：调用方分配的变体。

自有变体和调用方分配的变体使用 TicTacToe_MakeMove_Result 的参数，该参数作为具有以下两个变体的联合形式生成：Response（一个 TicTacToe_MakeMove_Response）和 Err（一个 MoveError）。TicTacToe_MakeMove_Response 作为结构体生成，其中响应参数作为其字段。在本例中，它具有单个字段 new_state，它是一个 GameState。

未知互动处理

服务器端

如果将协议声明为 open 或 ajar，生成的 fidl::WireServer<Protocol> 类型也将继承 fidl::UnknownMethodHandler<Protocol>。UnknownMethodHandler 定义了服务器必须实现的单个抽象方法（称为 handle_unknown_method），其中包含以下签名：

virtual void handle_unknown_method(UnknownMethodMetadata<Protocol> metadata,
                                   UnknownMethodCompleter::Sync& completer) = 0;

提供的 UnknownMethodMetadata 是一个具有一个或两个字段的结构体，具体取决于协议是 ajar 还是 open。元数据结构体如下所示，为简单起见，省略了模板参数：

struct UnknownMethodMetadata {
  // Ordinal of the method that was called.
  uint64_t method_ordinal;
  // Whether the method that was called was a one-way method or a two-way
  // method. This field is only defined if the protocol is open, since ajar
  // protocols only handle one-way methods.
  UnknownMethodType unknown_method_type;
};

UnknownMethodType 是包含两个变体（kOneWay 和 kTwoWay）的枚举，用于指示调用的是哪种方法。

UnknownMethodCompleter 与单向方法使用的完成器类型相同。

客户端

客户端无法判断服务器是否知道 flexible 单向方法。对于 flexible 双向方法，如果服务器无法识别该方法，则 fidl::WireResult 的 fidl::Status 为 ZX_ERR_NOT_SUPPORTED，且原因为 fidl::Reason::kUnknownMethod。kUnknownMethod 原因仅适用于灵活的双向方法。

除了 kUnknownMethod 的 Reason 可能会收到错误之外，客户端上的 strict 和 flexible 方法之间没有 API 差异。

对于 open 和 ajar 协议，生成的 fidl::WireAsyncEventHandler<Protocol> 和 fidl::WireSyncEventHandler<Protocol> 将继承自 fidl::UnknownEventHandler<Protocol>。UnknownEventHandler 定义了一个事件处理脚本必须实现的方法（名为 handle_unknown_event），并使用以下签名：

virtual void handle_unknown_event(UnknownEventMetadata<Protocol> metadata) = 0;

UnknownEventMetadata 采用以下布局，为简单起见，省略了模板参数：

struct UnknownEventMetadata {
  // Ordinal of the event that was received.
  uint64_t event_ordinal;
};

协议构成

FIDL 没有继承的概念，并会生成上述所有组合协议的完整代码。换句话说，

protocol A {
    Foo();
};

protocol B {
    compose A;
    Bar();
};

提供的 API 与为以下内容生成的代码相同：

protocol A {
    Foo();
};

protocol B {
    Foo();
    Bar();
};

除了方法序数外，生成的代码完全相同。

协议和方法属性

过渡风格

对于带有 @transitional 属性注解的协议方法，协议类中的 virtual 方法具有默认的 Close(ZX_NOT_SUPPORTED) 实现。这样一来，缺少方法替换项的协议类的实现便可成功编译。

可检测到

使用 @discoverable 属性注解的协议会导致 FIDL 工具链针对协议类生成额外的 static const char Name[] 字段，其中包含完整协议名称。

FIDL 传输格式的持久化和独立使用

尚不支持单独使用 FIDL 传输格式，例如对各个 FIDL 域对象进行编码和解码 (https://fxbug.dev/42163274)。

测试基架

FIDL 工具链还会生成一个名为 wire_test_base.h 的文件，其中包含用于测试 FIDL 客户端和服务器实现的便捷代码。如需使用这些标头，依赖于带有 _testing 后缀（my_library_cpp_testing 而不是 my_library_cpp）的绑定目标标签。

服务器测试库

测试基头文件包含每个协议的类，为该类的每个方法提供桩实现，因此可以仅实现测试期间使用的方法。这些类是 fidl::testing::WireTestBase<Protocol> 或 fidl::testing::TestBase<Protocol> 的模板特化，其中 Protocol 是存根的 FIDL 协议（例如，对于协议 games.tictactoe/TicTacToe，测试基底是 fidl::testing::WireTestBase<games_tictactoe::TicTacToe> 或 fidl::testing::TestBase<games_tictactoe::TicTacToe>）。

针对上面列出的同一 TicTacToe 协议，生成了测试基子类 fidl::WireServer<TicTacToe> 和 fidl::Server<TicTacToe>（请参阅协议），提供了以下方法：

  • virtual ~WireTestBase() = default 或 virtual ~TestBase() = default：析构函数。
  • virtual void NotImplemented_(const std::string& name, ::fidl::CompleterBase& completer) = 0：被替换的纯虚拟方法，用于定义未实现的方法的行为。

测试库为虚拟协议方法 StartGame 和 MakeMove 提供了实现，实现后分别仅调用 NotImplemented_("StartGame", completer) 和 NotImplemented_("MakeMove", completer)。

同步事件处理脚本测试基准

测试基本标头包含每个协议的类，用于为该类的每个事件提供桩实现，因此可以只实现测试期间使用的事件。与服务器测试库类似，这些类是 fidl::testing::WireSyncEventHandlerTestBase<Protocol> 的模板特化，其中 Protocol 是存根的 FIDL 协议。

针对上面列出的同一 TicTacToe 协议，生成了测试基础子类 fidl::WireSyncEventHandler<TicTacToe>（请参阅协议），并提供以下事件：

  • virtual ~WireSyncEventHandlerTestBase() = default：析构函数。
  • virtual void NotImplemented_(const std::string& name) = 0：被替换的纯虚拟方法，用于定义未实现事件的行为。

测试库提供了虚拟协议事件 OnOpponentMove 的实现，该实现只需调用 NotImplemented_("OnOpponentMove") 即可。