输入/输出 IO 抽象

当 Sandwich 库需要传输数据流时，它通过通用的 I/O 接口实现。换句话说，Sandwich 不会强制隧道对等体之间数据传输的方式。

该 I/O 接口提供了三个由用户定义的高级别 API 调用：

read：读取底层传输的指定字节数 write：将缓冲区写入底层传输 它还包含一个通用对象的视图，可以表示实际传输所需的任何状态。I/O 对象始终由隧道拥有，使 I/O API 能够访问其父隧道，例如获取隧道的当前状态。

I/O 接口还支持异步操作，并且可以为此类目的返回特定的错误代码。

C API

I/O 接口通过 SandwichCIOSettings 结构在 C API 中进行描述。

以下是在 C++ 中将数据转发到套接字的 I/O 结构的示例：

  1. /// \brief Read from a socket.
  2. ///
  3. /// This method is a SandwichCIOReadFunction.
  4. auto SandwichReadFromSocket(
  5.     void *uarg, void *buf, const size_t count,
  6.     [[maybe_unused]] const enum ::SandwichTunnelState state,
  7.     enum ::SandwichIOError *err) -> size_t {
  8.   *err = SANDWICH_IOERROR_OK;
  10.   const auto fd = static_cast<int>(reinterpret_cast<uintptr_t>(uarg));
  12.   ssize_t r{0};
  14.   do {
  15.     if (r = ::read(fd, buf, count); r > -1) {
  16.       return static_cast<size_t>(r);
  17.     }
  18.   } while ((r == -1) && (errno == EINTR));
  20.   switch (errno) {
  21.   case 0: {
  22.     return *err = SANDWICH_IOERROR_OK, 0;
  23.   }
  24.   case EINPROGRESS:
  25.   case EINTR: {
  26.     return *err = SANDWICH_IOERROR_IN_PROGRESS, 0;
  27.   }
  29.   case EWOULDBLOCK:
  30. #if EWOULDBLOCK != EAGAIN
  31.   case EAGAIN:
  32. #endif
  33.   {
  34.     return *err = SANDWICH_IOERROR_WOULD_BLOCK, 0;
  35.   }
  37.   case ENOTSOCK:
  38.   case EPROTOTYPE:
  39.   case EBADF: {
  40.     return *err = SANDWICH_IOERROR_INVALID, 0;
  41.   }
  42.   case EACCES:
  43.   case EPERM:
  44.   case ETIMEDOUT:
  45.   case ENETUNREACH:
  46.   case ECONNREFUSED: {
  47.     return *err = SANDWICH_IOERROR_REFUSED, 0;
  48.   }
  50.   default: {
  51.     return *err = SANDWICH_IOERROR_UNKNOWN, 0;
  52.   }
  53.   }
  54. }
  56. /// \brief Write to a socket.
  57. ///
  58. /// This method is a SandwichCIOWriteFunction.
  59. auto SandwichWriteToSocket(
  60.     void *uarg, const void *buf, const size_t count,
  61.     [[maybe_unused]] const enum ::SandwichTunnelState state,
  62.     enum ::SandwichIOError *err) -> size_t {
  63.   *err = SANDWICH_IOERROR_OK;
  65.   const auto fd = static_cast<int>(reinterpret_cast<uintptr_t>(uarg));
  67.   ssize_t w{0};
  69.   do {
  70.     if (w = ::write(fd, buf, count); w > -1) {
  71.       return static_cast<size_t>(w);
  72.     }
  73.   } while ((w == -1) && (errno == EINTR));
  75.   switch (errno) {
  76.   case 0: {
  77.     return *err = SANDWICH_IOERROR_OK, 0;
  78.   }
  79.   case EINPROGRESS:
  80.   case EINTR: {
  81.     return *err = SANDWICH_IOERROR_WOULD_BLOCK, 0;
  82.   }
  83.   case ENOTSOCK:
  84.   case EPROTOTYPE:
  85.   case EBADF: {
  86.     return *err = SANDWICH_IOERROR_INVALID, 0;
  87.   }
  88.   case EACCES:
  89.   case EPERM:
  90.   case ETIMEDOUT:
  91.   case ENETUNREACH:
  92.   case ECONNREFUSED: {
  93.     return *err = SANDWICH_IOERROR_REFUSED, 0;
  94.   }
  96.   default: {
  97.     return *err = SANDWICH_IOERROR_UNKNOWN, 0;
  98.   }
  99.   }
  100. }
  102. /// \brief Close a socket.
  103. ///
  104. /// This method is a SandwichCIOCloseFunction.
  105. void CloseSocket(void *uarg) {
  106.   const auto fd = static_cast<int>(reinterpret_cast<uintptr_t>(uarg));
  107.   ::close(fd);
  108. }
  110. /// \brief Global CIO settings structure for sockets.
  111. constexpr struct ::SandwichCIOSettings SandwichSocketCIOSettings = {
  112.     .read = SandwichReadFromSocket,
  113.     .write = SandwichWriteToSocket,
  114.     .uarg = nullptr};