Edit

FSCTL_ENUM_EXTERNAL_BACKING control code

  • Article

The FSCTL_ENUM_EXTERNAL_BACKING control code begins or continues an enumeration of files on a volume that have a backing source. For each successful completion of the request, an identifier for the backed file is returned. All backed files are enumerated regardless of which external provider is backing it. Successive FSCTL_ENUM_EXTERNAL_BACKING requests are required to enumerate all the backed files on the volume.

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

Parameters

  • Instance [in]: FltFsControlFile only. Opaque instance pointer for the caller. This parameter is required and cannot be NULL.

  • FileObject [in]: FltFsControlFile only. The file pointer object specifying the volume to be dismounted. This parameter is required and cannot be NULL.

  • FileHandle [in]: ZwFsControlFile only. The file handle of the volume to be dismounted. This parameter is required and cannot be NULL.

  • FsControlCode [in]: Control code for the operation. Use FSCTL_ENUM_EXTERNAL_BACKING for this operation.

  • InputBuffer [in]: None. Set to NULL.

  • InputBufferLength [in]: Set to 0.

  • OutputBuffer [out]: A pointer to the output buffer, which must have a size large enough to receive one or more WOF_EXTERNAL_FILE_ID structures.

  • OutputBufferLength [out]: Size of the output buffer pointed to by OutputBuffer. OutputBufferLength must be >= sizeof(WOF_EXTERNAL_FILE_ID).

  • LengthReturned [out]: Specifies the number of bytes written into OutputBuffer on successful completion.

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 output buffer pointed to by OutputBuffer and specified by OutputBufferLength is too small.
STATUS_NO_MORE_FILES No more files on the volume have a backing source.
STATUS_INTERNAL_ERROR The requested volume is not accessible.
STATUS_INVALID_DEVICE_REQUEST The backing service is not present or not started.

Remarks

The WOF_EXTERNAL_FILE_ID structure returned in OutputBuffer contains unique file identifiers for backed files. The structure is defined in ntifs.h as the following.

typedef struct _WOF_EXTERNAL_FILE_ID {
    FILE_ID_128 FileId;
} WOF_EXTERNAL_FILE_ID, *PWOF_EXTERNAL_FILE_ID;

A FSCTL_ENUM_EXTERNAL_BACKING request is issued successively to retrieve the identifiers for each file on the volume having backing source. When all the files are enumerated, the STATUS_NO_MORE_FILES status code is returned.

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_GET_EXTERNAL_BACKING