FltQueryDirectoryFile 函数（fltkernel.h）

项目
12/21/2024

FltQueryDirectoryFile 例程返回有关给定文件对象指定的目录中文件的各种信息。使用 FltQueryDirectoryFileEx 进行更高的查询控制。

语法

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

参数

[in] Instance

指向启动 I/O 的筛选器驱动程序实例的不透明指针。

[in] FileObject

指向表示要扫描的目录的文件对象的指针。

[out] FileInformation

指向接收有关文件的所需信息的缓冲区的指针。缓冲区中返回的信息的结构由 FileInformationClass 参数定义。

[in] Length

FileInformation指向的缓冲区的大小（以字节为单位）。调用方应根据给定 FileInformationClass设置此参数。

[in] FileInformationClass

要返回的有关目录中文件的信息类型。有关可能值列表，请参阅 NtQueryDirectoryFileEx 的 FileInformationClass 参数。

[in] ReturnSingleEntry

如果只返回单个条目，则设置为 TRUE，否则 FALSE。如果此参数 TRUE，FltQueryDirectoryFile 仅返回找到的第一个条目。

[in, optional] FileName

指向调用方分配的 Unicode 字符串的指针，该字符串包含由 fileObject 指定的目录中的文件名称（或多个文件（如果使用通配符）。此参数是可选的，可以 NULL。

如果 FileName 未 NULL，则目录扫描中仅包含与 FileName 字符串匹配的文件。如果 FileNameNULL，则包括所有文件。如果 RestartScanFALSE，则忽略 FileName 的值。

[in] RestartScan

如果扫描从目录中的第一个条目开始，则设置为 TRUE。如果从上一个调用恢复扫描，则设置为 FALSE。调用方首次 调用 fltQueryDirectoryFile 时，调用方必须将此参数设置为 TRUE。

[out, optional] LengthReturned

接收实际写入给定 FileInformation 缓冲区的字节数。

返回值

FltQueryDirectoryFile 返回STATUS_SUCCESS或适当的错误状态。请注意，可以返回的错误状态值集特定于文件系统。

言论

FltQueryDirectoryFile 返回有关由 fileObject 表示的目录中的文件的信息。

对 FltQueryDirectoryFile 的第一次调用 根据 ReturnSingleEntry、FileName和 RestartScan的值来确定目录扫描中要包括的所有条目集。如果至少有一个匹配项，FltQueryDirectoryFile 为每个条目创建FILE_XXX_INFORMATION 结构（请参阅上表），并将结构存储到缓冲区中。

假设找到至少一个匹配的目录条目，返回其信息的条目数是下列项中最小的：

如果 ReturnSingleEntryTRUE，并且 FileNameNULL，则返回一个条目。
如果 FileName 未 NULL，则与 FileName 字符串匹配的条目数。（请注意，如果字符串不包含通配符，则最多可以有一个匹配项。
其信息适合指定缓冲区的条目数。
目录中包含的条目数。

在第一次调用 FltQueryDirectoryFile时，如果为第一个条目创建的结构太大而无法容纳到输出缓冲区中，则只返回结构的固定部分。固定部分包含结构的所有字段，但最终 FileName 字符串除外。在第一次调用（而不是后续调用中）时，I/O 系统可确保缓冲区足够大，足以容纳适当FILE_XXX_INFORMATION 结构的固定部分。发生这种情况时，FltQueryDirectoryFile 返回适当的状态值，例如STATUS_BUFFER_OVERFLOW。此外，在首次调用 FltQueryDirectoryFile时，如果 FileObject 目录中没有与 FileName 参数匹配的文件，FltQueryDirectoryFile 将返回适当的状态值，例如STATUS_NO_SUCH_FILE。

每次调用时，FltQueryDirectoryFile 返回尽可能多的 FILE_XXX_INFORMATION 结构（每个目录条目一个），就像 FileInformation指向的缓冲区中一样。只要输出缓冲区至少包含一个完整的结构，则返回的状态值STATUS_SUCCESS。不会报告任何剩余条目的相关信息。因此，除了上面列出的只返回一个条目的情况下，FltQueryDirectoryFile 必须至少调用两次才能枚举整个目录的内容（例如，当 FileName 参数包含一个或多个通配符或 NULL时）。

对 FltQueryDirectoryFile 的最终调用 返回空输出缓冲区，并报告相应的状态值，例如STATUS_NO_MORE_FILES。

注意

在同一目录中多次调用 FltQueryDirectoryFile 时，可能会返回信息的条目数小于预期。这是因为在首次调用 fltQueryDirectoryFile 时，目录扫描中包含的条目集是固定的。在后续调用中，FltQueryDirectoryFile 恢复目录扫描，无论它在此相同的枚举中离开的位置。但是，在调用 FltQueryDirectoryFile之间，实际的目录条目可以更改，以便它们不再与原始枚举同步。

FltQueryDirectoryFile 在文件系统不支持的 FILE_XXX_INFORMATION 结构的任何成员中返回零。

有关其他文件信息查询例程的信息，请参阅文件对象。

FltQueryDirectoryFile 的调用方必须在 IRQL = PASSIVE_LEVEL 且启用了 APC 的情况下运行。有关详细信息，请参阅禁用 APC。

要求

要求	价值
最低支持的客户端	Windows Vista
目标平台	普遍
标头	fltkernel.h （包括 Fltkernel.h）
库	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL（请参阅“备注”部分）