Zx_channel_write_etc

摘要

向频道撰写消息。

声明

#include <zircon/syscalls.h>

zx_status_t zx_channel_write_etc(zx_handle_t handle,
                                 uint32_t options,
                                 const void* bytes,
                                 uint32_t num_bytes,
                                 zx_handle_disposition_t* handles,
                                 uint32_t num_handles);

说明

与 zx_channel_write() 一样，它会尝试写入 num_bytes 的消息 由 handle 指定的通道的字节和 num_handles 句柄，但在 另外，它会对 使用 zx_handle_disposition_t 数组传递的 handles：

typedef struct zx_handle_disposition {
    zx_handle_op_t operation;
    zx_handle_t handle;
    zx_obj_type_t type;
    zx_rights_t rights;
    zx_status_t result;
} zx_handle_disposition_t;

在 zx_handle_disposition_t 中，handle 是执行操作的源句柄。 rights 是所需的最终权利（而非掩码），并且必须设置 result 发送至 ZX_OK。所有来源句柄都必须包含 ZX_RIGHT_TRANSFER，但 可以在右侧移除该文档，使其不再适用于邮件 接收器。

type 用于验证调用者所确定的对象类型 handle 正确的值。ZX_OBJ_TYPE_NONE 可以跳过验证 或某个 zx_obj_type_t 定义的类型。

对 handle 应用的操作是以下各项之一：

handle 将具有 rights 功能，这些权限可以是 ZX_RIGHT_SAME_RIGHTS 或ZX_RIGHT_NONE。此外，此操作还可以 ZX_RIGHT_TRANSFER（位于右侧），以便接收器无法使用该功能。

如果有任何操作失败，系统会将该源句柄的错误代码写入 result， zx_channel_write_etc() 的返回值中提供了第一次失败。全部 尝试 handles 数组中的操作，即使一个或多个操作失败也是如此。

每个条目的所有操作都必须成功才能写入消息。成功时，处理 会附加在邮件中，并通过 。

将 handle（正在写入的通道的句柄）包含在 handles 数组（在消息中发送的标识名）。

一条信息中最多可以发送 ZX_CHANNEL_MAX_MSG_HANDLES 个标识名， 也就是 64

消息中可以发送的字节数上限是 ZX_CHANNEL_MAX_MSG_BYTES。 也就是 65536

消息由 zx_channel_read() 或 zx_channel_read_etc() 排空。未能排空 及时发送讯息会导致消耗过多的内核内存，从而可能使系统 异常。如需了解详情，请参阅 IPC 限制。

ZX_CHANNEL_WRITE_USE_IOVEC 选项

在指定 ZX_CHANNEL_WRITE_USE_IOVEC 选项后，bytes 为 解释为 zx_channel_iovec_t 的数组，指定 按顺序复制到消息中。num_bytes 用于指定 bytes 中的 zx_channel_iovec_t 数组元素。

typedef struct zx_channel_iovec {
  const void* buffer;      // User-space bytes.
  uint32_t capacity;       // Number of bytes.
  uint32_t reserved;       // Reserved.
} zx_channel_iovec_t;

最多只能有 ZX_CHANNEL_MAX_MSG_IOVEC 或 8192 具有 capacity 总和的 bytes 数组的 zx_channel_iovec_t 个元素 所有zx_channel_iovec_t不超过 ZX_CHANNEL_MAX_MSG_BYTES 或 65536 字节。buffer 无需对齐，且仅当满足以下条件时才可以为 NULL： capacity 为零。reserved 必须设置为零。

要么全部复制 zx_channel_iovec_t，要么不发送消息 且邮件不会被发送。用于发送标识名的用法不变。

权限

handle 的类型必须为 ZX_OBJ_TYPE_CHANNEL 且包含 ZX_RIGHT_WRITE。

每个 handles 条目都必须具有 ZX_RIGHT_TRANSFER。

返回值

如果成功，zx_channel_write_etc() 会返回 ZX_OK。

错误

ZX_ERR_BAD_HANDLE handle 不是有效的句柄，其中的任何源句柄 handles 不是有效的句柄，或者存在重复的句柄 在 handles 数组中（如果 ZX_HANDLE_OP_DUPLICATE 标志不存在）。

ZX_ERR_WRONG_TYPE handle 不是频道标识名或任何来源标识名 与 handles 中的对象类型 type 不匹配。

ZX_ERR_INVALID_ARGS bytes 是无效指针，handles 是无效的指针、options 为非零值或 operation 不是 ZX_HANDLE_OP_MOVE 或 ZX_HANDLE_OP_DUPLICATE 之一，或者任何来源 handles[i]->handle 中的句柄在 whandle[i]->rights。 如果指定了 ZX_CHANNEL_WRITE_USE_IOVEC 选项， 如果 buffer 字段包含ZX_ERR_INVALID_ARGS 指针无效或预留字段为非零。

ZX_ERR_NOT_SUPPORTED handle 包含在 handles 数组中。

“ZX_ERR_ACCESS_DENIED”标识名不含 ZX_RIGHT_WRITE 或 句柄中的任何源句柄都不包含 ZX_RIGHT_TRANSFER，或者 在句柄中，任何源句柄均不含 ZX_RIGHT_DUPLICATE 已指定 ZX_HANDLE_OP_DUPLICATE 操作。

ZX_ERR_PEER_CLOSED 通道的另一端是关闭的。

ZX_ERR_NO_MEMORY 因内存不足而失败。 用户空间没有好办法处理这种（不太可能）错误。 在将来的版本中，此错误不会再发生。

ZX_ERR_OUT_OF_RANGE num_bytes 或 num_handles 大于 ZX_CHANNEL_MAX_MSG_BYTES 或 ZX_CHANNEL_MAX_MSG_HANDLES。 如果指定了 ZX_CHANNEL_WRITE_USE_IOVEC 选项， ZX_ERR_OUT_OF_RANGE如果num_bytes超过 ZX_CHANNEL_MAX_MSG_IOVEC，或者 iovec 容量的总和超过 ZX_CHANNEL_MAX_MSG_BYTES。

备注

如果调用方移除了附加到句柄的 ZX_RIGHT_TRANSFER 给邮件，则该邮件的读者将收到一个句柄， 写入其他任何频道，但仍可根据其 权利；如果不需要，可以关闭。

另请参阅