FltQueryDirectoryFile routine

The FltQueryDirectoryFile routine returns various kinds of information about files in the directory specified by a given file object.

Syntax


NTSTATUS FltQueryDirectoryFile(
  _In_      PFLT_INSTANCE          Instance,
  _In_      PFILE_OBJECT           FileObject,
  _Out_     PVOID                  FileInformation,
  _In_      ULONG                  Length,
  _In_      FILE_INFORMATION_CLASS FileInformationClass,
  _In_      BOOLEAN                ReturnSingleEntry,
  _In_opt_  PUNICODE_STRING        FileName,
  _In_      BOOLEAN                RestartScan,
  _Out_opt_ PULONG                 LengthReturned
);

Parameters

Instance [in]

Opaque pointer to the minifilter driver instance that initiates the I/O.

FileObject [in]

Pointer to the file object that represents the directory to be scanned.

FileInformation [out]

Pointer to a buffer that receives the desired information about the file. The structure of the information returned in the buffer is defined by the FileInformationClass parameter.

Length [in]

Size, in bytes, of the buffer pointed to by FileInformation. The caller should set this parameter according to the given FileInformationClass.

FileInformationClass [in]

Type of information to be returned about files in the directory. One of the values in the following table can be used.

ValueMeaning

FileBothDirectoryInformation

Return a FILE_BOTH_DIR_INFORMATION structure for each file.

FileDirectoryInformation

Return a FILE_DIRECTORY_INFORMATION structure for each file.

FileFullDirectoryInformation

Return a FILE_FULL_DIR_INFORMATION structure for each file.

FileIdBothDirectoryInformation

Return a FILE_ID_BOTH_DIR_INFORMATION structure for each file.

FileIdFullDirectoryInformation

Return a FILE_ID_FULL_DIR_INFORMATION structure for each file.

FileNamesInformation

Return a FILE_NAMES_INFORMATION structure for each file.

FileObjectIdInformation

Return a FILE_OBJECTID_INFORMATION structure for each file. This information class is valid only for NTFS volumes starting with Microsoft Windows 2000.

FileReparsePointInformation

Return a single FILE_REPARSE_POINT_INFORMATION structure for the directory.

 

ReturnSingleEntry [in]

Set to TRUE if only a single entry should be returned, FALSE otherwise. If this parameter is TRUE, FltQueryDirectoryFile returns only the first entry that is found.

FileName [in, optional]

Pointer to a caller-allocated Unicode string that contains the name of a file (or multiple files, if wildcards are used) within the directory specified by FileObject. This parameter is optional and can be NULL.

If FileName is not NULL, only files whose names match the FileName string are included in the directory scan. If FileName is NULL, all files are included. If RestartScan is FALSE, the value of FileName is ignored.

RestartScan [in]

Set to TRUE if the scan is to start at the first entry in the directory. Set to FALSE if resuming the scan from a previous call. The caller must set this parameter to TRUE when calling FltQueryDirectoryFile for the first time.

LengthReturned [out, optional]

Receives the number of bytes actually written to the given FileInformation buffer.

Return value

FltQueryDirectoryFile returns STATUS_SUCCESS or an appropriate error status. Note that the set of error status values that can be returned is file-system-specific.

Remarks

FltQueryDirectoryFile returns information about files that are contained in the directory that is represented by FileObject.

The first call to FltQueryDirectoryFile determines the set of entries to be included in the directory scan for all subsequent calls, based on the values of ReturnSingleEntry, FileName, and RestartScan. If there is at least one matching entry, FltQueryDirectoryFile creates a FILE_XXX_INFORMATION structure (see the above table) for each entry in turn and stores the structure into the buffer.

Assuming that at least one matching directory entry is found, the number of entries for which information is returned is the smallest of the following:

  • One entry, if ReturnSingleEntry is TRUE and FileName is NULL.

  • The number of entries that match the FileName string, if FileName is not NULL. (Note that if the string contains no wildcards, there can be at most one matching entry.)

  • The number of entries whose information fits into the specified buffer.

  • The number of entries contained in the directory.

On the first call to FltQueryDirectoryFile, if the structure created for the first entry found too large to fit into the output buffer, only the fixed portion of the structure is returned. The fixed portion consists of all fields of the structure except the final FileName string. On the first call, but not on subsequent ones, the I/O system ensures that the buffer is large enough to hold the fixed portion of the appropriate FILE_XXX_INFORMATION structure. When this happens, FltQueryDirectoryFile returns an appropriate status value such as STATUS_BUFFER_OVERFLOW. Also on the first call to FltQueryDirectoryFile, if there is no file in the FileObject directory that matches the FileName parameter, FltQueryDirectoryFile returns an appropriate status value such as STATUS_NO_SUCH_FILE.

On each call, FltQueryDirectoryFile returns as many FILE_XXX_INFORMATION structures (one per directory entry) as can be contained entirely in the buffer pointed to by FileInformation. As long as the output buffer contains at least one complete structure, the status value returned is STATUS_SUCCESS. No information about any remaining entries is reported. Thus, except in the cases listed above where only one entry is returned, FltQueryDirectoryFile must be called at least twice to enumerate the contents of an entire directory (for example, when the FileName parameter contains one or more wildcard characters or is NULL).

The final call to FltQueryDirectoryFile returns an empty output buffer and reports an appropriate status value such as STATUS_NO_MORE_FILES.

Note   When FltQueryDirectoryFile is called multiple times on the same directory, it is possible that the number of entries for which information is returned will be less than expected. This is because the set of entries to be included in the directory scan is fixed on the first call to FltQueryDirectoryFile. In subsequent calls, FltQueryDirectoryFile resumes the directory scan wherever it left off in this same enumeration. However, between calls to FltQueryDirectoryFile, the actual directory entries can change so that they are no longer in sync with the original enumeration.
 

FltQueryDirectoryFile returns zero in any member of a FILE_XXX_INFORMATION structure that is not supported by the file system.

For information about other file information query routines, see File Objects.

Callers of FltQueryDirectoryFile must be running at IRQL = PASSIVE_LEVEL and with APCs enabled. For more information, see Disabling APCs.

Requirements

Target platform

Universal

Version

This routine is available starting with Windows Vista.

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

DLL

Fltmgr.sys

IRQL

PASSIVE_LEVEL (see Remarks section)

See also

FILE_BOTH_DIR_INFORMATION
FILE_DIRECTORY_INFORMATION
FILE_FULL_DIR_INFORMATION
FILE_ID_BOTH_DIR_INFORMATION
FILE_ID_FULL_DIR_INFORMATION
FILE_NAMES_INFORMATION
FILE_OBJECTID_INFORMATION
FILE_REPARSE_POINT_INFORMATION
FltCreateFile
FltCreateFileEx
UNICODE_STRING
ZwQueryDirectoryFile

 

 

Send comments about this topic to Microsoft

Show: