摘要
向频道撰写消息。
声明
#include <zircon/syscalls.h>
zx_status_t zx_channel_write(zx_handle_t handle,
uint32_t options,
const void* bytes,
uint32_t num_bytes,
const zx_handle_t* handles,
uint32_t num_handles);
说明
zx_channel_write() 尝试写入 num_bytes 的消息
指定通道的字节和 num_handles 个句柄
handle。如果指针 handles 和 bytes 的
分别为 0。
成功后，handles 数组中所有 num_handles 个句柄 会附加在邮件中，并可供读者查看 从通道的另一端发送该消息。
所有标识名都会被舍弃，并且无法再供调用方在
成功或失败如果需要标识名，请使用 zx_channel_write_etc()
以供发件人保留
包含 handle（正在写入的频道的句柄）无效 to) 包含在 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() 会返回 ZX_OK。
错误
ZX_ERR_BAD_HANDLE handle 不是有效的句柄，其中的任何元素
handles 不是有效的句柄，或者
handles 数组中的句柄。
ZX_ERR_WRONG_TYPE handle 不是频道标识名。
ZX_ERR_INVALID_ARGS bytes 是无效指针：handles
是无效的指针，或者 options 包含无效的选项位。
如果指定了 ZX_CHANNEL_WRITE_USE_IOVEC 选项，
如果 buffer 字段包含ZX_ERR_INVALID_ARGS
指针无效或预留字段为非零。
在“handles”数组中找到了“ZX_ERR_NOT_SUPPORTED”handle。
执行写入的通道的句柄不能包含在
handles 数组。换言之，不能将频道标识名写入自己的频道。
确保 handle 不在 handles 数组中，从而修复该错误。
ZX_ERR_ACCESS_DENIED handle 不含 ZX_RIGHT_WRITE 或
handles 中的任何元素都不包含 ZX_RIGHT_TRANSFER。
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 选项，
如果 num_bytes 大于ZX_ERR_OUT_OF_RANGE
ZX_CHANNEL_MAX_MSG_IOVEC 或 iovec 容量的总和超过
ZX_CHANNEL_MAX_MSG_BYTES。
备注
num_handles 是 handles 中元素数量的计数 而不是以字节为单位的大小。
消息的字节大小限制尚未最终确定。