FSCTL_ENUM_EXTERNAL_BACKING control code

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

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.

TermDescription

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

Version

Available starting with Windows 8.1 Update.

Header

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

See also

FltFsControlFile
ZwFsControlFile
FSCTL_GET_EXTERNAL_BACKING

 

 

Send comments about this topic to Microsoft

Show: