zx_channel_read_etc

摘要

阅读来自某个频道的消息。

声明

#include <zircon/syscalls.h>

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);

说明

如需查看完整说明，请参阅 zx_channel_read()。

这两种形式的读取行为相同，只不过 zx_channel_read() 会返回一个 在 zx_channel_read_etc() 返回时，原始 zx_handle_t 处理值的数组 以下形式的 zx_handle_info_t 结构的数组：

typedef struct {
    zx_handle_t handle;     // handle value
    zx_obj_type_t type;     // type of object, see ZX_OBJ_TYPE_
    zx_rights_t rights;     // handle rights
    uint32_t unused;        // set to zero
} zx_handle_info_t;

在通过通道与不可信的一方通信时，建议您 使用 zx_channel_read_etc() 表单，以及每个标识名类型和权利 对照预期值进行验证

权限

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

返回值

这两种形式的读取均在成功时返回 ZX_OK，前提是 actual_bytes 和 actual_handles（如果为非 NULL）包含确切字节数 和句柄读取次数

错误

ZX_ERR_BAD_HANDLE handle 不是有效的句柄。

ZX_ERR_WRONG_TYPE handle 不是频道句柄。

ZX_ERR_INVALID_ARGS 如果 bytes、handles、actual_bytes 或 actual_handles 是非 NULL 值和无效的指针。

ZX_ERR_ACCESS_DENIED 句柄没有 ZX_RIGHT_READ。

ZX_ERR_SHOULD_WAIT 通道没有要读取的消息， 开放渠道。

ZX_ERR_PEER_CLOSED 通道没有要读取的消息， 这个渠道已关闭。

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 是元素数量的计数 （而非以字节为单位）。

另请参阅