FSCTL_SUSPEND_OVERLAY control code
The FSCTL_SUSPEND_OVERLAY control code suspends a backing source attached to a volume, preventing access to the backing source and allowing it to be modified or removed.
To perform this operation, call FltFsControlFile or ZwFsControlFile with the following parameters.
BOOL
WINAPI
DeviceIoControl( (HANDLE) hDevice, // handle to device
(DWORD) FSCTL_SUSPEND_OVERLAY, // dwIoControlCode
(LPDWORD) lpInBuffer, // input buffer
(DWORD) nInBufferSize, // size of input buffer
(LPDWORD) lpOutBuffer, // output buffer
(DWORD) nOutBufferSize, // size of output buffer
(LPDWORD) lpBytesReturned, // number of bytes returned
(LPOVERLAPPED) lpOverlapped ); // OVERLAPPED structure
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 volume for which the overlay is updated. This parameter is required and cannot be NULL.
FileHandle [in]: ZwFsControlFile only. The handle of the volume for which the overlay is updated. This parameter is required and cannot be NULL.
FsControlCode [in]: The control code for the operation. Use FSCTL_SUSPEND_OVERLAY for this operation.
InputBuffer [in]: A pointer to the input buffer, which must contain a WOF_EXTERNAL_INFO structure. When required, additional provider specific data is included immediately after WOF_EXTERNAL_INFO. If the provider is a WIM file, a WIM_PROVIDER_SUSPEND_OVERLAY_INPUT structure is included after WOF_EXTERNAL_INFO.
InputBufferLength [in]: Set to sizeof(WOF_EXTERNAL_INFO) plus the size of any additional provider input data.
OutputBuffer [out]: Not used. Set to NULL.
OutputBufferLength [in]: Set to 0.
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_ACCESS_DENIED | The requestor does not have administrative privileges. |
| STATUS_BUFFER_TOO_SMALL | The length of the input buffer pointed to by InputBuffer, and specified by InputBufferLength, is too small. |
| STATUS_INTERNAL_ERROR | The requested volume is not accessible. |
| STATUS_INVALID_DEVICE_REQUEST | The backing service is not present or not started. |
Remarks
When the backing source to remove is a Windows Imaging Format (WIM) file, the input buffer will contain a WOF_EXTERNAL_INFO structure followed by a WIM_PROVIDER_SUSPEND_OVERLAY_INPUT structure. The InputBufferLength in this case will be sizeof(WOF_EXTERNAL_INFO) + sizeof(WIM_PROVIDER_REMOVE_OVERLAY_INPUT). The DataSourceId value in WIM_PROVIDER_SUSPEND_OVERLAY_INPUT must be for a WIM file previously added in an FSCTL_ADD_OVERLAY request.
Additional backing providers will define their own specific input parameter structures.
Requirements
| Requirement type | Requirement |
|---|---|
| Header | Ntifs.h (include Ntifs.h or Fltkernel.h) |