BuildIoRingReadFile function (ioringapi.h)

Article
02/22/2024

Performs an asynchronous read from a file using an I/O ring. This operation is similar to calling ReadFileEx.

Syntax

HRESULT BuildIoRingReadFile(
  HIORING           ioRing,
  IORING_HANDLE_REF fileRef,
  IORING_BUFFER_REF dataRef,
  UINT32            numberOfBytesToRead,
  UINT64            fileOffset,
  UINT_PTR          userData,
  IORING_SQE_FLAGS  sqeFlags
);

Parameters

ioRing

An HIORING representing a handle to the I/O ring which will perform the read operation.

fileRef

An IORING_HANDLE_REF specifying the file to read.

dataRef

An IORING_BUFFER_REF specifying the buffer into which the file is read. The provided buffer must have a size of at least numberOfBytesToRead bytes.

numberOfBytesToRead

The number of bytes to read.

fileOffset

The offset into the file to begin reading.

userData

A UINT_PTR value identifying the file read operation. Specify this value when cancelling the operation with a call to BuildIoRingCancelRequest. If an app implements cancellation behavior for the operation, the userData value must be unique. Otherwise, the value is treated as opaque by the system and can be anything, including 0.

sqeFlags

Return value

Returns an HRESULT including, but not limited to the following:

Value	Description
S_OK	Success
IORING_E_SUBMISSION_QUEUE_FULL	The submission queue is full, and no additional entries are available to build. The application must submit the existing entries and wait for some of them to complete before adding more operations to the queue.
IORING_E_UNKNOWN_REQUIRED_FLAG	The application provided a required flag that is not known to the implementation. Library code should check the IoRingVersion field of the IORING_INFO obtained from a call to GetIoRingInfo to determine the API version of an I/O ring which determines the operations and flags that are supported. Applications should know the version they used to create the I/O ring and therefore should not provide unsupported flags at runtime.

Remarks

Check I/O ring support for read file operations by calling IsIoRingOpSupported and specifying IORING_OP_READ for the op parameter.

Requirements

Requirement	Value
Minimum supported client	Windows Build 22000
Minimum supported server	Windows Build 22000
Header	ioringapi.h

Share via