摘要
讀取來自管道的訊息。
宣告
#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
。
傳回值
如為 actual_bytes 和 actual_handles (非 NULL),這兩種形式的讀取作業都會傳回 ZX_OK
,並以確切的位元組數和處理次數讀取作業。
錯誤
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
因記憶體不足而失敗。使用者空間無法以任何方式處理這個錯誤 (極可能) 錯誤。日後的建構作業不會再發生這個錯誤。
ZX_ERR_BUFFER_TOO_SMALL
提供的位元組或帳號代碼緩衝區過小 (在這種情況下,接收訊息所需的最小大小會寫入 actual_bytes 和 actual_handles)。如果 options 已設定 ZX_CHANNEL_READ_MAY_DISCARD
,則會捨棄訊息。
附註
num_handles 和 actual_handles 包含的元素數量,而非以位元組為單位。
另請參閱
zx_channel_call()
zx_channel_create()
zx_channel_read()
zx_channel_write()
zx_channel_write_etc()
zx_handle_close()
zx_handle_replace()
zx_object_wait_async()
zx_object_wait_many()
zx_object_wait_one()