比較新的 C++ 和高階 C++ 語言繫結

快速參考指引

以下說明如何識別 C++ 程式碼中的特定類型/函式/ID 是否屬於新的 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++ 繫結，且同樣適用於自然網域物件和接線網域物件。「Natural」(自然) 是指新 C++ 繫結中的自然網域物件。「線」是指新 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();
  });

如需完整的程式碼清單和說明，請參閱畫布範例。

以下是實作伺服器最常見的方式：

// 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 {
    // ...
  }
};

如需完整的程式碼清單和說明，請參閱畫布範例。

新增 C++ 繫結

新的 C++ 繫結可提供兩個產生的網域物件系列，以及支援這些類型的對應用戶端和伺服器 API，藉此支援低階和高階用途。

自然類型

• 經過最佳化處理，符合高階服務程式設計需求。
• 使用慣用的 C++ 類型 (例如 std::vector、std::optional 和 std::string) 表示資料結構。
• 使用智慧指標管理堆積分配的物件。
• 請使用「zx::handle」管理帳號代碼擁有權。
• 可在連接線 (例如 fidl::StringView) 和自然類型表示法 (例如 std::string) 之間轉換資料。

線型類型

• 經過最佳化處理，可滿足低階系統程式設計的需求，同時提供比 C 繫結更多的安全性和功能略為高。
• 代表資料結構，其記憶體版面配置與傳輸格式相同，即符合 C++ 標準版面配置。才能順利進行編碼和解碼
• 產生的結構是基礎緩衝區的檢視畫面；它們並不擁有記憶體。
• 支援就地存取 FIDL 訊息。
• 讓您精細控管記憶體配置。
• 使用自有的帳號代碼類型，例如 zx::handle。請注意，由於產生的結構是基礎緩衝區的檢視畫面，因此，只有在其本身擁有基礎緩衝區時，父項結構才會擁有子項控點。舉例來說，FIDL 結構擁有所有以內嵌儲存的控制代碼，但包含控點的 FIDL 向量向量會表示為向量檢視畫面，而且這類檢視畫面不會擁有外行控制代碼。

用戶端 API 和伺服器 API

• 程式碼產生器產生的程式碼比 C 繫結更多。這包括建構函式、解構器、複製/移動函式、網域物件系列之間的轉換、通訊協定用戶端實作，以及純虛擬伺服器介面。
• 使用者可將提供的伺服器介面設為子類別，並覆寫每項作業的純虛擬方法，藉此實作伺服器。
• 支援同步處理和非同步呼叫的用戶端，以及同步和非同步事件處理作業。
• 需要 C++17 以上版本。

如要開始使用，請參閱新 C++ 教學課程。

高階 C++ 繫結

• 經過最佳化處理，符合高階服務程式設計需求。
• 使用慣用的 C++ 類型 (例如 std::vector、std::optional 和 std::string) 表示資料結構。
• 使用智慧指標管理堆積分配的物件。
• 使用 zx::handle (libzx) 管理擁有權。
• 能將資料從現有 FIDL 緩衝區轉換為慣用的堆積已配置物件。
• 可將資料從慣用的堆積配置物件 (例如 std::string) 轉換為就地緩衝區 (例如做為 fidl::StringView)。
• 程式碼產生器產生的程式碼比 C 繫結更多。這包括建構函式、解構器、通訊協定 Proxy、通訊協定虛設常式、複製/移動函式，以及往返就地緩衝區的轉換。
• 用戶端會將提供的虛設常式設為子類別，並為每個作業實作虛擬方法，藉此執行通訊協定分派作業。
• 支援非同步和同步用戶端。然而，非同步用戶端並不安全。
• 需要 C++14 以上版本。

如要開始使用，請參閱 HLCPP 教學課程。

摘要