FSCTL_OFFLOAD_WRITE control code
The FSCTL_OFFLOAD_WRITE control code initiates an offload write for a block of data in a storage system that supports offload write primitives.
To perform this operation, minifilter drivers call FltFsControlFile with the following parameters, and file systems, redirectors, and legacy file system filter drivers call 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 write to. This parameter is required and cannot be NULL.
FileHandle [in]: ZwFsControlFile only. The file handle of the file to write to. This parameter is required and cannot be NULL.
FsControlCode [in]: The control code for the operation. Use FSCTL_OFFLOAD_WRITE for this operation.
InputBuffer [in]: A pointer to a FSCTL_OFFLOAD_WRITE_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_WRITE_INPUT).
OutputBuffer [out]: A pointer to a FSCTL_OFFLOAD_WRITE_INPUT structure, which contains the size and offset of a data block to read.
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_NOT_SUPPORTED | Offload read operations are not supported on this volume. |
| STATUS_OFFLOAD_WRITE_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_TOO_LATE | A write operation was attempted to a volume after it was dismounted. |
| 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 | Read or write access cannot be granted due to the current file locking state. |
| STATUS_END_OF_FILE | The FileOffset member ofFSCTL_OFFLOAD_WRITE_INPUT begins after end-of-file (EOF). |
| STATUS_DISMOUNTED_VOLUME | An offload write cannot occur on a dismounted volume. |
| STATUS_MEDIA_WRITE_PROTECTED | The volume is read only. |
| STATUS_INSUFFICIENT_RESOUCES | Insufficient resources are available to complete the request. |
| STATUS_BUFFER_TOO_SMALL | InputBufferLength is too small for InputBuffer to contain anFSCTL_OFFLOAD_WRITE_INPUT structure, or OutputBufferLength is too small for OutputBuffer to receive an FSCTL_OFFLOAD_WRITE_OUTPUT structure. |
Remarks
Offload read is available for normal files only. See the description for STATUS_OFFLOAD_WRITE_FILE_NOT_SUPPORTED for a list of unsupported file types.
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_OUTPUT). - One or more of these members ofFSCTL_OFFLOAD_WRITE_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. TransferOffset is not a multiple of the logical sector size of the volume. Size is not the size of theFSCTL_OFFLOAD_WRITE_INPUT structure. FileOffset > Valid Data Length (VDL) for the file. FileOffset + CopyLength > MAXULONGLONG.
Requirements
| Requirement type | Requirement |
|---|---|
| Minimum supported client | Windows 8 |
| Header | Ntifs.h (include Ntifs.h or Fltkernel.h) |