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 类型的元素计数。

bytes 的长度（以字节为单位）存储在 actual_bytes -标识名的数量存储在 所指向的位置 actual_handles。actual_bytes 或 actual_bytes 中的任何一个都可以为 NULL， 在这种情况下，系统会忽略它们。

通道消息可同时包含字节数据和句柄负载， 只能阅读全文。不能只读取部分内容。

bytes 缓冲区在 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 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 那么系统将舍弃该消息。

另请参阅