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_handle_t 句柄值，而 zx_channel_read_etc() 会返回一个如下形式的 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 句柄不是有效的句柄。

ZX_ERR_WRONG_TYPE 标识名不是频道标识名。

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 由于内存不足而失败。 用户空间没有什么方法来处理此（不太可能）错误。在以后的 build 中，此错误不会再发生。

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

备注

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

另请参阅