實作 HLCPP FIDL 伺服器

必要條件

本教學課程的設計是以「編譯 FIDL」教學課程為基礎。如需完整的 FIDL 教學課程，請參閱總覽。

總覽

本教學課程說明如何實作 FIDL 通訊協定 (fuchsia.examples.Echo)，並在 Fuchsia 上執行該通訊協定。這個通訊協定包含每種方法各一個：立即執行並忘記方法、雙向方法和事件：

@discoverable
closed protocol Echo {
    strict EchoString(struct {
        value string:MAX_STRING_LENGTH;
    }) -> (struct {
        response string:MAX_STRING_LENGTH;
    });
    strict SendString(struct {
        value string:MAX_STRING_LENGTH;
    });
    strict -> OnString(struct {
        response string:MAX_STRING_LENGTH;
    });
};

本文件說明如何完成以下工作：

  • 實作 FIDL 通訊協定。
  • 在 Fuchsia 上建構及執行套件。
  • 提供 FIDL 通訊協定。

本教學課程會先建立要提供給 Fuchsia 裝置並執行的元件。然後逐步新增功能，讓伺服器順利啟動。

如果您想自行編寫程式碼，請刪除下列目錄：

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

建立元件

如何建立元件：

  1. 將 main() 函式新增至 examples/fidl/hlcpp/server/main.cc：

    #include <stdio.h>

int main(int argc, const char** argv) {
  printf("Hello, world!\n");
  return 0;
}

  2. 在 examples/fidl/hlcpp/server/BUILD.gn 中宣告伺服器的目標：

    import("//build/components.gni")


# Declare an executable for the server. This produces a binary with the
# specified output name that can run on Fuchsia.
executable("bin") {
  output_name = "fidl_echo_hlcpp_server"
  sources = [ "main.cc" ]
}

# Declare a component for the server, which consists of the manifest and the
# binary that the component will run.
fuchsia_component("echo-server") {
  component_name = "echo_server"
  manifest = "meta/server.cml"
  deps = [ ":bin" ]
}

# Declare a package that contains a single component, our server.
fuchsia_package("echo-hlcpp-server") {
  package_name = "echo-hlcpp-server"
  deps = [ ":echo-server" ]
}

    如要讓伺服器元件開始運作，有三個已定義的目標：

    • 用於 Fuchsia 的伺服器原始執行檔。
    • 這個元件會設定為只執行伺服器可執行檔，並使用元件的資訊清單檔案加以說明。
    • 接著，元件會放入套件中，這是 Fuchsia 上的軟體發行單位。在這種情況下，套件只包含單一元件。

    如要進一步瞭解套件、元件和建構方式，請參閱「建構元件」頁面。

  3. 在 examples/fidl/hlcpp/server/meta/server.cml 中新增元件資訊清單：

    {
    include: [ "syslog/client.shard.cml" ],

    // Information about the program to run.
    program: {
        // Use the built-in ELF runner.
        runner: "elf",

        // The binary to run for this component.
        binary: "bin/fidl_echo_hlcpp_server",
    },

    // Capabilities provided by this component.
    capabilities: [
        { protocol: "fuchsia.examples.Echo" },
    ],
    expose: [
        {
            protocol: "fuchsia.examples.Echo",
            from: "self",
        },
    ],
}

  4. 將伺服器新增至建構設定：

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

  5. 建構 Fuchsia 映像檔：

    fx build

實作伺服器

新增對 FIDL 程式庫的依附元件

  1. 在 examples/fidl/hlcpp/server/BUILD.gn 中，將 fuchsia.examples FIDL 程式庫目標新增為 executable 的依附元件：

    executable("bin") {
  output_name = "fidl_echo_hlcpp_server"
  sources = [ "main.cc" ]
  deps = [ "//examples/fidl/fuchsia.examples" ]
}

  2. 在 examples/fidl/hlcpp/server/main.cc 頂端匯入 HLCPP 繫結：

    #include <fuchsia/examples/cpp/fidl.h>

新增通訊協定的導入方式

將以下內容新增至 main() 函式的 main.cc 中：

class EchoImpl : public fuchsia::examples::Echo {
 public:
  void EchoString(std::string value, EchoStringCallback callback) override { callback(value); }
  void SendString(std::string value) override {
    if (event_sender_) {
      event_sender_->OnString(value);
    }
  }

  fuchsia::examples::Echo_EventSender* event_sender_;
};

實作內容包含下列元素：

  • 這個類別會將產生的通訊協定類別設為子類別，並覆寫其與通訊協定方法相對應的純虛擬方法。
  • EchoString 的方法會呼叫回呼，以要求值回應。
  • SendString 的方法不會採用回呼，因為這個方法沒有回應。而是使用 Echo_EventSender 傳送 OnString 事件。
  • 這個類別包含 Echo_EventSender 的指標。這會在稍後的 main() 函式中設定。

您可以執行下列指令，驗證實作方式是否正確：

fx build

提供通訊協定

如要執行實作 FIDL 通訊協定的元件，請向元件管理員提出要求，將該 FIDL 通訊協定公開給其他元件。接著，元件管理員會將 echo 通訊協定的所有要求轉送至我們的伺服器。

如要執行這些要求，元件管理員需要通訊協定的名稱，以及當有任何傳入要求連線至符合指定名稱的通訊協定時應呼叫的處理常式。

傳遞至此的處理程序是函式，該函式會接收管道 (其遠端端點由用戶端擁有)，並將其繫結至已使用伺服器實作方式初始化的 fidl::Binding。fidl::Binding 是 FIDL 執行階段的類別，可接收 FIDL 通訊協定實作項目和管道，然後在管道上監聽傳入的要求。接著，它會解碼要求、將要求轉送至伺服器類別的正確方法，並將任何回應寫回用戶端。我們的主要方法會持續監聽非同步迴圈的傳入要求。

通訊協定開啟的生命週期一文會進一步說明這項完整程序。

新增依附元件

這段新程式碼需要下列額外依附元件：

  • "//sdk/lib/async-loop:async-loop-cpp" 和 "//sdk/lib/async-loop:async-loop-default"：這些程式庫包含非同步迴圈程式碼。
  • "//sdk/lib/sys/cpp"：元件架構 C++ 執行階段，其中包含用於與元件環境互動的公用程式碼。

  1. 在 examples/fidl/hlcpp/server/BUILD.gn 中，將程式庫目標新增為 executable 的依附元件：

    executable("bin") {
  output_name = "fidl_echo_hlcpp_server"
  sources = [ "main.cc" ]
  deps = [
    "//examples/fidl/fuchsia.examples:fuchsia.examples_hlcpp",
    "//sdk/lib/async-loop:async-loop-cpp",
    "//sdk/lib/async-loop:async-loop-default",
    "//sdk/lib/sys/cpp",
  ]
}

  2. 請在 examples/fidl/hlcpp/server/main.cc 頂端匯入以下依附元件：

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

初始化事件迴圈

第一個方面是使用非同步迴圈：

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

  EchoImpl impl;
  fidl::Binding<fuchsia::examples::Echo> binding(&impl);
  impl.event_sender_ = &binding.events();
  fidl::InterfaceRequestHandler<fuchsia::examples::Echo> handler =
      [&](fidl::InterfaceRequest<fuchsia::examples::Echo> request) {
        binding.Bind(std::move(request));
      };
  auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
  context->outgoing()->AddPublicService(std::move(handler));

  printf("Running echo server\n");
  return loop.Run();
}

程式碼會先初始化迴圈，並將其註冊為目前執行緒的預設調度器。這會先執行，因為 main() 函式中的非同步程式碼會向預設調度器註冊本身，而預設調度器是靜態執行緒本機變數 (因此不需要在程式碼的其餘部分中明確傳遞)。在主要函式的結尾，程式碼會執行非同步迴圈。

初始化繫結

接著，程式碼會初始化上述的 fidl::Binding：

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

  EchoImpl impl;
  fidl::Binding<fuchsia::examples::Echo> binding(&impl);
  impl.event_sender_ = &binding.events();
  fidl::InterfaceRequestHandler<fuchsia::examples::Echo> handler =
      [&](fidl::InterfaceRequest<fuchsia::examples::Echo> request) {
        binding.Bind(std::move(request));
      };
  auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
  context->outgoing()->AddPublicService(std::move(handler));

  printf("Running echo server\n");
  return loop.Run();
}

繫結需要下列兩項才能執行：

  • 通訊協定的實作項目。
  • 繫結會監聽該通訊協定的訊息。繫結會先使用回音實作方式初始化，之後再繫結至管道。

程式碼也會設定事件傳送者，用於將事件傳送至用戶端。使用 Binding 上的 events() 方法取得事件傳送者，然後傳遞至 EchoImpl 類別。

定義通訊協定要求處理常式

接下來，程式碼為來自用戶端的傳入要求定義處理常式：

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

  EchoImpl impl;
  fidl::Binding<fuchsia::examples::Echo> binding(&impl);
  impl.event_sender_ = &binding.events();
  fidl::InterfaceRequestHandler<fuchsia::examples::Echo> handler =
      [&](fidl::InterfaceRequest<fuchsia::examples::Echo> request) {
        binding.Bind(std::move(request));
      };
  auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
  context->outgoing()->AddPublicService(std::move(handler));

  printf("Running echo server\n");
  return loop.Run();
}
  • 「傳入要求」並非針對 Echo 通訊協定的特定方法提出要求，而是用戶端連線至 Echo 通訊協定實作的一般要求。
  • 要求定義為 fidl::InterfaceRequest<Echo>。這是一個圍繞管道的類型安全包裝函式，可指出兩件事：
    • InterfaceRequest 表示這是管道的伺服器端 (也就是用戶端已連線至管道的遠端)
    • 範本參數 Echo 表示用戶端預期實作 Echo 通訊協定的伺服器會自行繫結至此管道。此類型的用戶端類比 (即在用戶端端使用此管道的另一端代表類型) 為 fidl::InterfaceHandle<Echo>。
  • 處理程序只需取得從用戶端傳送的管道，並將其繫結至 Echo 繫結。
  • 發生這種情況後，Binding 會根據 Echo 通訊協定開始處理管道上的訊息。這是通訊協定要求管線化的範例，我們會在後續教學課程中深入探討這個主題。

註冊通訊協定要求處理常式

最後，程式碼會向元件管理員註冊處理常式：

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

  EchoImpl impl;
  fidl::Binding<fuchsia::examples::Echo> binding(&impl);
  impl.event_sender_ = &binding.events();
  fidl::InterfaceRequestHandler<fuchsia::examples::Echo> handler =
      [&](fidl::InterfaceRequest<fuchsia::examples::Echo> request) {
        binding.Bind(std::move(request));
      };
  auto context = sys::ComponentContext::CreateAndServeOutgoingDirectory();
  context->outgoing()->AddPublicService(std::move(handler));

  printf("Running echo server\n");
  return loop.Run();
}

第一個行會初始化並提供傳出目錄，其中包含此元件向其他元件公開的通訊協定，而第二行會將處理常式新增至傳出目錄。

除了處理程序之外，隱含的第二個參數是這個處理程序應註冊至的名稱。根據預設，這個參數是傳入的通訊協定名稱，這是因為 Echo 通訊協定上有 [Discoverable] 屬性而產生。換句話說，執行這行程式碼後，您應該可以在元件的 /out 目錄中呼叫 ls，並查看名為 fuchsia.examples.Echo 的項目。

測試伺服器

重建：

fx build

然後執行伺服器元件：

ffx component run /core/ffx-laboratory:echo_server fuchsia-pkg://fuchsia.com/echo-hlcpp-server#meta/echo_server.cm

，該值由

您應該會在裝置記錄 (ffx log) 中看到類似以下的輸出內容：

[ffx-laboratory:echo_server][][I] Running echo server

伺服器現已開始執行，並等待傳入的要求。下一個步驟是編寫可傳送 Echo 通訊協定要求的用戶端。目前，您可以直接終止伺服器元件：

ffx component destroy /core/ffx-laboratory:echo_server