實作 FIDL 用戶端

必要條件

本教學課程的設計是以 FIDL 伺服器教學課程為基礎。如需完整的 FIDL 教學課程,請參閱總覽

總覽

本教學課程會實作 FIDL 通訊協定的用戶端,並針對先前教學課程中建立的伺服器執行用戶端。本教學課程中的用戶端為非同步。同步用戶端有其他教學課程

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

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

建立元件

examples/fidl/hlcpp/client 建立新的元件專案:

  1. main() 函式新增至 examples/fidl/hlcpp/client/main.cc

    int main(int argc, const char** argv) {
      printf("Hello, world!\n");
      return 0;
    }
    
  2. examples/fidl/hlcpp/client/BUILD.gn 中為用戶端宣告目標:

    import("//build/components.gni")
    
    
    # Declare an executable for the client.
    executable("bin") {
      output_name = "fidl_echo_hlcpp_client"
      sources = [ "main.cc" ]
    }
    
    fuchsia_component("echo-client") {
      component_name = "echo_client"
      manifest = "meta/client.cml"
      deps = [ ":bin" ]
    }
    
  3. examples/fidl/hlcpp/client/meta/client.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_client",
        },
    
        // Capabilities used by this component.
        use: [
            { protocol: "fuchsia.examples.Echo" },
        ],
    }
    
    
  4. 建立元件後,請確認您可以將其新增至建構設定:

    fx set core.x64 --with //examples/fidl/hlcpp/client:echo-client
    
  5. 建構 Fuchsia 映像檔:

    fx build
    

編輯 GN 依附元件

  1. 新增下列依附元件:

      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. 然後在 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>
    

    伺服器教學課程會說明納入這些依附元件的理由。

連線至伺服器

本節中的步驟說明如何在 main() 函式中新增程式碼,以將用戶端連線至伺服器並向伺服器發出要求。

初始化事件迴圈

如同在伺服器中,程式碼會先設定非同步迴圈,讓用戶端能夠在不阻斷的情況下,監聽來自伺服器的回應。

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

  printf("Async loop starting\n");
  loop.Run();
  printf("Async loop finished\n");
  return num_responses == 2 ? 0 : 1;
}

初始化 Proxy 類別

在 FIDL 的上下文中,proxy 是指由 FIDL 繫結產生的程式碼,可讓使用者向伺服器發出遠端程序呼叫。在 HLCPP 中,Proxy 會採用類別的形式,其中的方法會對應至每個 FIDL 通訊協定方法。

接著,程式碼會為 Echo 通訊協定建立 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();
    }
  };

  printf("Async loop starting\n");
  loop.Run();
  printf("Async loop finished\n");
  return num_responses == 2 ? 0 : 1;
}
  • fuchsia::examples::EchoPtr 是繫結產生的 fidl::InterfaceRequest<fuchsia::examples::Echo> 別名。
  • 與伺服器中使用的 fidl::Binding<fuchsia::examples::Echo> 類似,fidl::InterfaceRequest<fuchsia::examples::Echo> 會透過 FIDL 通訊協定和管道設定參數,並透過管道代理要求,並監聽傳入的回應和事件。
  • 程式碼會呼叫 EchoPtr::NewRequest(),該函式會建立管道、將類別繫結至管道的其中一端,並傳回管道的另一端。
  • 管道的傳回端會傳遞至 sys::ServiceDirectory::Connect()
    • 與伺服器端對 context->out()->AddPublicService() 的呼叫相似,Connect 在此處有隱含的第二個參數,即通訊協定名稱 ("fuchsia.examples.Echo")。這就是前一個教學課程中定義的處理常式輸入來源:用戶端將其傳遞至 Connect,再由 Connect 傳遞至處理常式。

請注意,這段程式碼假設 /svc 已包含 Echo 通訊協定的例項。根據預設,由於元件架構提供的沙箱,因此並非如此。

設定錯誤處理常式

最後,程式碼會設定 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();
    }
  };

  printf("Async loop starting\n");
  loop.Run();
  printf("Async loop finished\n");
  return num_responses == 2 ? 0 : 1;
}

將要求傳送至伺服器

程式碼會向伺服器提出兩項要求:

  • EchoString 要求
  • SendString 要求
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();
    }
  };

  printf("Async loop starting\n");
  loop.Run();
  printf("Async loop finished\n");
  return num_responses == 2 ? 0 : 1;
}

對於 EchoString,程式碼會傳入回呼來處理回應。SendString 不需要這類回呼,因為該方法沒有任何回應。

設定事件處理常式

接著,程式碼會為任何傳入的 OnString 事件設定處理常式:

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

  printf("Async loop starting\n");
  loop.Run();
  printf("Async loop finished\n");
  return num_responses == 2 ? 0 : 1;
}

終止事件迴圈

程式碼會等待收到 EchoString 方法的回應和 OnString 事件 (在目前實作中,會在收到 SendString 要求後傳送),然後才會退出迴圈。程式碼只有在同時收到回應和事件時,才會傳回成功的結束代碼:

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

  printf("Async loop starting\n");
  loop.Run();
  printf("Async loop finished\n");
  return num_responses == 2 ? 0 : 1;
}

執行用戶端

為了讓用戶端和伺服器使用 Echo 通訊協定進行通訊,元件架構必須將 fuchsia.examples.Echo 能力從伺服器路由至用戶端。在本教學課程中,我們會使用

  1. 設定建構作業,加入提供的套件,其中包含回音領域、伺服器和用戶端:

    fx set core.x64 --with //examples/fidl/hlcpp:echo-hlcpp-client
    
  2. 建構 Fuchsia 映像檔:

    fx build
    
  3. 執行 echo_realm 元件。這會建立用戶端和伺服器元件執行個體,並轉送功能:

    ffx component run /core/ffx-laboratory:echo_realm fuchsia-pkg://fuchsia.com/echo-hlcpp-client#meta/echo_realm.cm
    
  4. 啟動 echo_client 執行個體:

    ffx component start /core/ffx-laboratory:echo_realm/echo_client
    

當用戶端嘗試連線至 Echo 通訊協定時,伺服器元件就會啟動。您應該會在裝置記錄 (ffx log) 中看到類似以下的輸出內容:

[echo_server][][I] Running echo server
[echo_client][][I] Got event hi
[echo_client][][I] Got response hello

終止領域元件,停止執行並清理元件例項:

ffx component destroy /core/ffx-laboratory:echo_realm