zx_channel_read

总结

阅读某个频道中的消息。

声明

#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_channel_read() 会尝试将 handle 指定的通道中的第一条消息读取到提供的 bytes 和/或 handles 缓冲区中。

参数 num_bytes 和 num_handles 用于指定各个读取缓冲区的大小。num_bytes 是字节数，而 num_handles 是 zx_handle_t 类型的元素数量。

字节的长度（以字节为单位）存储在 actual_bytes 所指向的位置。句柄的数量存储在 actual_handles 指向的位置。actual_bytes 或 actual_handles 可为 NULL，在这种情况下，它们将被忽略。

通道消息可能包含字节数据和处理载荷，并且只能被读取完整。不能进行部分读取。

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

通过频道与不可信方通信时，建议使用 zx_channel_read_etc() 形式，并根据预期值验证每种句柄类型和权限。

权限

handle 必须为 ZX_OBJ_TYPE_CHANNEL 类型，且具有 ZX_RIGHT_READ。

返回值

成功时返回 ZX_OK。如果为非 NULL，actual_bytes 和 actual_handles 指向的位置包含读取的字节数和句柄的确切数量。

错误

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，则会舍弃消息。

另请参阅