FSCTL_SET_EXTERNAL_BACKING control code

The FSCTL_SET_EXTERNAL_BACKING control code sets the backing source for a file, such as a Windows Image Format (WIM) file or compressed file, by an external backing provider. Content for externally backed files may be sourced on volumes other than on volume where the file resides.

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 of the file for which backing is set. This parameter is required and cannot be NULL.

  • FileHandle [in]: ZwFsControlFile only. The handle of the file for which backing is set. This parameter is required and cannot be NULL.

  • FsControlCode [in]: The control code for the operation. Use FSCTL_SET_EXTERNAL_BACKING for this operation.

  • InputBuffer [in]: A pointer to the input buffer, which contains WOF_EXTERNAL_INFO structure followed by the provider data. For WIM backed files, WOF_EXTERNAL_INFO is followed by a WIM_PROVIDER_EXTERNAL_INFO structure.

  • InputBufferLength [in]: Size of the data provided in the InputBuffer.

  • OutputBuffer [out]: None. Set to NULL.

  • OutputBufferLength [in]: Set to 0.

Return Value

FltFsControlFile or ZwFsControlFile returns STATUS_SUCCESS if the operation succeeds. Otherwise, the appropriate NTSTATUS values is returned.

Remarks

When the backing provider for the data source added is the WIM provider, the input buffer will contain a WOF_EXTERNAL_INFO structure followed by a WIM_PROVIDER_EXTERNAL_INFO structure. The InputBufferLength in this case will be sizeof(WOF_EXTERNAL_INFO) + sizeof(WIM_PROVIDER_EXTERNAL_INFO).

Individually compressed files offer good compression for data which will not be modified, including executable files. If these are opened for write the file will be transparently decompressed. To specify an individually compressed file,, the input buffer will contain a WOF_EXTERNAL_INFO structure followed by a FILE_PROVIDER_EXTERNAL_INFO_V1 structure. The InputBufferLength in this case will be sizeof(WOF_EXTERNAL_INFO) + sizeof(FILE_PROVIDER_EXTERNAL_INFO_V1). Individual compressed files are available starting with Windows 10.

Requirements

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

See also

FltFsControlFile

ZwFsControlFile

FSCTL_DELETE_EXTERNAL_BACKING

FSCTL_GET_EXTERNAL_BACKING

WIM_PROVIDER_EXTERNAL_INFO

WOF_EXTERNAL_INFO