zx_channel_call_etc

摘要

向频道发送消息并等待回复。

声明

#include <zircon/syscalls.h>

zx_status_t zx_channel_call_etc(zx_handle_t handle,
                                uint32_t options,
                                zx_time_t deadline,
                                zx_channel_call_etc_args_t* args,
                                uint32_t* actual_bytes,
                                uint32_t* actual_handles);

说明

zx_channel_call_etc() 将请求写入通道并阻止，直到它为止 收到响应。它是 zx_channel_call() 的扩展， 纳入了 zx_channel_write_etc() 的功能， zx_channel_read_etc() 用于写入和读取阶段，而不是较基本的阶段 zx_channel_write() 和 zx_channel_read()。请参阅 zx_channel_call() 频道调用的完整说明。

调用 zx_channel_call_etc() 的效果类似于执行 对 zx_channel_write_etc()、zx_object_wait_one() 和 zx_channel_read_etc()。不过，它们的主要区别在于 zx_channel_call_etc() 会等待接收的邮件与外发的邮件相匹配 消息的事务 ID。提供给 zx_channel_read_etc() 和 zx_channel_write_etc() 改为通过 zx_channel_call_etc_args_t:

typedef struct {
    const void* wr_bytes;
    zx_handle_disposition_t* wr_handles;
    void *rd_bytes;
    zx_handle_info_t* rd_handles;
    uint32_t wr_num_bytes;
    uint32_t wr_num_handles;
    uint32_t rd_num_bytes;
    uint32_t rd_num_handles;
} zx_channel_call_etc_args_t;

ZX_CHANNEL_WRITE_USE_IOVEC 选项

在指定 ZX_CHANNEL_WRITE_USE_IOVEC 选项后，wr_bytes 为 解释为 zx_channel_iovec_t 的数组，指定 按顺序复制到消息中。num_wr_bytes 用于指定 wr_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 wr_bytes 数组的 zx_channel_iovec_t 个元素，其总和为 所有zx_channel_iovec_t中的capacity不超过 ZX_CHANNEL_MAX_MSG_BYTES 或 65536 字节。buffer 无需对齐， 仅当 capacity 为零时，才能为 NULL。reserved 必须设置为零。

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

权限

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

args 的所有 wr_handle 都必须具有 ZX_RIGHT_TRANSFER。

返回值

zx_channel_call_etc() 会在操作成功时返回 ZX_OK 以及字节数和 回复消息中的句柄计数通过 actual_bytes 返回， actual_handles。

错误

ZX_ERR_BAD_HANDLE handle 不是有效的句柄，其中的任何元素 handles 不是有效的句柄，或者句柄存在重复 （位于 handles 数组中）。

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

ZX_ERR_INVALID_ARGS 提供的指针中的任何一个无效或 null， 或 wr_num_bytes 小于 4，或 options 为非零值，或任何来源 wr_handles[i]-&gt;handle 中的句柄在 wr_handle[i]-&gt;rights。 如果指定了 ZX_CHANNEL_WRITE_USE_IOVEC 选项， 如果 buffer 字段包含ZX_ERR_INVALID_ARGS 指针无效或预留字段为非零。

“ZX_ERR_ACCESS_DENIED”标识名不含 ZX_RIGHT_WRITE 或 句柄中的任何元素都不包含 ZX_RIGHT_TRANSFER。

ZX_ERR_PEER_CLOSED 频道的另一端已关闭或变为 已在等待回复时关闭。

ZX_ERR_CANCELED 句柄在等待回复时失效（例如，已关闭）。

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

ZX_ERR_OUT_OF_RANGE wr_num_bytes 或 wr_num_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_ERR_BUFFER_TOO_SMALL rd_num_bytes 或 rd_num_handles 位数过小 以包含回复消息。

ZX_ERR_NOT_SUPPORTED handles 中的一个句柄是 handle （正在写入的通道的句柄）。