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

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 [in]

The size, in bytes, of the buffer pointed to by the OutputBuffer parameter. This value must be at least sizeof(FSCTL_OFFLOAD_READ_OUTPUT).

Return value

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

Return codeDescription
STATUS_INVALID_DEVICE_REQUEST

The handle specified is not a valid file handle.

STATUS_INVALID_PARAMETER

File size is less than PAGE_SIZE.

-or-

InputBufferLength < sizeof(FSCTL_OFFLOAD_READ_INPUT).

-or-

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.
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

TheFileOffset 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_RESOUCES

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.

Requirements

Version

Available starting with Windows 8.

Header

Ntifs.h (include Ntifs.h or Fltkernel.h)

See also

FltFsControlFile
ZwFsControlFile
FSCTL_OFFLOAD_READ_INPUT
FSCTL_OFFLOAD_READ_OUTPUT

 

 

Send comments about this topic to Microsoft

Mostrar:
© 2014 Microsoft