NtDoc

No description available.

Windows hardware development documentation (fsctl-offload-read)

FSCTL_OFFLOAD_READ control code

The FSCTL_OFFLOAD_READ control code initiates an offload read for a block of data in a storage system that supports offload read primitives.

To perform this operation, call FltFsControlFile or ZwFsControlFile with the following parameters.

Parameters

Instance [in]: FltFsControlFile only. An opaque instance pointer for the caller. This parameter is required and cannot be NULL.
FileObject [in]: FltFsControlFile only. The file pointer object specifying the file to read from. This parameter is required and cannot be NULL.
FileHandle [in]: ZwFsControlFile only. The file handle of the file to read from. This parameter is required and cannot be NULL.
FsControlCode [in]: The control code for the operation. Use FSCTL_OFFLOAD_READ for this operation.
InputBuffer [in]: A pointer to a FSCTL_OFFLOAD_READ_INPUT structure, which contains the size and offset of a data block to read.
InputBufferLength [in]: The size, in bytes, of the buffer pointed to by InputBuffer. This value is sizeof(FSCTL_OFFLOAD_READ_INPUT).
OutputBuffer [out]: A pointer to a FSCTL_OFFLOAD_READ_OUTPUT structure, which receives the results of the offload read operation.
OutputBufferLength [out]: The size, in bytes, of the buffer pointed to by the OutputBuffer parameter. This value must be at least sizeof(FSCTL_OFFLOAD_READ_OUTPUT).

Status block

FltFsControlFile or ZwFsControlFile returns STATUS_SUCCESS if the operation succeeds. Otherwise, the appropriate function might return one of the following NTSTATUS values.

Code	Meaning
STATUS_INVALID_DEVICE_REQUEST	The handle specified is not a valid file handle
STATUS_INVALID_PARAMETER	A parameter is invalid. See Remarks.
STATUS_VOLUME_DISMOUNTED	The file system volume is dismounted.
STATUS_NOT_SUPPORTED	Offload read operations are not supported on this volume.
STATUS_OFFLOAD_READ_FILE_NOT_SUPPORTED	The requested file type is not supported. Offload operations are not supported on these file types: A transacted file (TxF); Non-user files; Compressed files; Encrypted files; Sparse files; NTFS Metatdata files.
STATUS_FILE_DELETED	The data stream for this file is invalid.
STATUS_FILE_CLOSED	The file handle is closed.
STATUS_INVALID_HANDLE	The file handle specified is invalid.
STATUS_FILE_LOCK_CONFLICT	Insufficient read access due to the current file locking state.
STATUS_END_OF_FILE	The FileOffset member of FSCTL_OFFLOAD_READ_INPUT begins after end-of-file (EOF).
STATUS_DISMOUNTED_VOLUME	An offload read cannot occur on a dismounted volume.
STATUS_INSUFFICIENT_RESOURCES	Insufficient resources are available to complete the request.
STATUS_BUFFER_TOO_SMALL	OutputBufferLength is too small for OutputBuffer to receive an FSCTL_OFFLOAD_READ_OUTPUT structure.

Remarks

Offload read is available for normal files only. See the description for STATUS_OFFLOAD_READ_FILE_NOT_SUPPORTED for a list of unsupported file types.

It is possible for reads to start beyond the Valid Data Length (VDL), but not beyond EOF.

When STATUS_INVALID_PARAMETER is returned, the error could be one of the following invalid parameters:

File size is less than PAGE_SIZE.
InputBufferLength < sizeof(FSCTL_OFFLOAD_READ_INPUT).
One or more of these members of FSCTL_OFFLOAD_READ_INPUT are incorrect:
- FileOffset is not a multiple of the logical sector size of the volume.
- CopyLength is not a multiple of the logical sector size of the volume.
- Size is not the size of the FSCTL_OFFLOAD_READ_INPUT structure.
- FileOffset + CopyLength > MAXULONGLONG.

Requirements

Requirement type	Requirement
Minimum supported client	Windows 8
Header	Ntifs.h (include Ntifs.h or Fltkernel.h)

FSCTL_OFFLOAD_READ - NtDoc