zx_channel_read - zx_channel_read_etc

zx_channel_read - zx_channel_read_etc

名称

channel_read —— 向channel写入消息

概要

#include <zircon/syscalls.h>
zx_status_t zx_channel_read(zx_handle_t handle, uint32_t options,
                            void* bytes, zx_handle_t* handles,
                            uint32_t num_bytes, uint32_t num_handles,
                            uint32_t* actual_bytes, uint32_t* actual_handles);
zx_status_t zx_channel_read_etc(zx_handle_t handle, uint32_t options,
                                void* bytes, zx_handle_info_t* handles,
                                uint32_t num_bytes, uint32_t num_handles,
                                uint32_t* actual_bytes, uint32_t* actual_handles);

描述

channel_read()和channel_read_etc() 尝试将句柄指定的channel中的第一条消息读入到提供的bytes和/或handles缓冲区中。

参数num_bytes和num_handles用于指定相应读缓冲区的大小。 channel消息可以包含字节数据和句柄有效载荷，并且仅可以完整地被读取，而部分读取是不可能的。

bytes缓冲区在handles缓冲区之前被写入。如果这两个缓冲区重叠，写入handles的内容将覆盖掉重叠的bytes部分。

两种形式的读取行为相同，只是channel_read() 返回原始zx_handle_t句柄值的数组，而channel_read_etc() 返回zx_handle_info_t形式的结构体数组：

typedef struct {
    zx_handle_t handle;     // handle值
    zx_obj_type_t type;     // 对象类型，参考ZX_OBJ_TYPE_
    zx_rights_t rights;     // handle权限
    uint32_t unused;        // 置为0
} zx_handle_info_t;

通过channel与不受信任方通信时，建议使用channel_read_etc() 形式，并根据预期值验证每个返回句柄的类型和权限。

权限

handle必须具有ZX_RIGHT_READ权限。

返回值

两种形式的读取，成功皆返回ZX_OK，并且actual_bytes和actual_handles（如果非NULL）包含准确的读取字节数的句柄数量。

错误码

ZX_ERR_BAD_HANDLE：handle是无效句柄。

ZX_ERR_WRONG_TYPE：handle不是channel类型句柄。

ZX_ERR_INVALID_ARGS 任何bytes，handles，actual_bytes或actual_handles之一是非NULL的无效指针。

ZX_ERR_ACCESS_DENIED：handle不具有ZX_RIGHT_WRITE权限。

ZX_ERR_SHOULD_WAIT: channel不包含可读的消息。

ZX_ERR_PEER_CLOSED：channel的另一侧已关闭。

ZX_ERR_NO_MEMORY：由于内存不足导致的失败。而用户空间无法处理这个（不太可能发生的）错误。在将来的构建版本中，将不再出现此错误。

ZX_ERR_BUFFER_TOO_SMALL：提供的bytes或handles缓冲区太小（在这种情况下，接收消息所需的最小大小将写入actual_bytes和actual_handles中，前提是它们为非NULL）。如果options设置了ZX_CHANNEL_READ_MAY_DISCARD选项，则丢弃该消息。

注释

num_handles和actual_handles是handles数组中元素个数的计数，而不是其（以字节为单位）的大小。

另见