FltQueryDirectoryFileEx 函数（fltkernel.h）

项目
07/16/2024

FltQueryDirectoryFileEx 返回有关给定文件对象指定的目录中文件的各种信息。

语法

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

参数

Instance

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

FileObject

指向表示要查询的目录的文件对象的指针。

FileInformation

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

Length

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

FileInformationClass

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

QueryFlags

SL_QUERY_DIRECTORY_MASK中包含的一个或多个标志。下表中指定了可能的值。

价值	意义
SL_RESTART_SCAN（0x00000001）	如果设置了此标志，扫描将从目录中的第一个条目开始。如果未设置此标志，扫描将从最后一个查询结束的位置恢复。
SL_RETURN_SINGLE_ENTRY（0x00000002）	通常，返回缓冲区打包了任意数量的匹配目录条目。如果设置了此标志，则文件系统一次只返回一个目录条目。这会使操作效率更低。
SL_INDEX_SPECIFIED（0x00000004）	如果设置了此标志，扫描应从目录中的指定索引位置开始。仅当生成自己的 IRP_MJ_DIRECTORY_CONTROL IRP时，才能设置此标志;索引在 IRP 中指定。指定位置的方式因文件系统而异。
SL_RETURN_ON_DISK_ENTRIES_ONLY（0x00000008）	如果设置了此标志，执行目录虚拟化或实时扩展的任何文件系统筛选器都应将请求传递到文件系统并返回当前位于磁盘上的条目。并非所有文件系统都支持此标志。
SL_NO_CURSOR_UPDATE_QUERY（0x00000010）	文件系统维护每个FileObject 目录游标信息。当多个线程使用相同的 FileObject执行查询时，将单线程访问 per-FileObject 结构，以防止游标状态损坏。此标志指示文件系统不要按FileObject 更新游标状态信息，从而允许多个线程使用相同的句柄并行查询。它的行为就像在每个调用中指定SL_RESTART_SCAN一样。如果下一次调用中提供了通配符模式，则操作将不会选取最后一个查询结束的位置。这允许真正的异步目录查询支持。如果在 TxF 事务中使用此标志，操作将失败。并非所有文件系统都支持此标志。

FileName

指向调用方分配的 UNICODE_STRING 结构的指针，该结构包含文件的名称（或使用多个文件（如果使用通配符），FileObject指定的目录中。此参数是可选的，可以 NULL。如果 fileNameNULL，则包括所有文件。

如果 FileName 未 NULL，则目录扫描中仅包含与 FileName 字符串匹配的文件。如果设置了 QueryFlagsResetScan 标志，则忽略 fileName 的值。

LengthReturned

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

返回值

FltQueryDirectoryFileEx 返回STATUS_SUCCESS或适当的错误代码。可以返回的错误状态值集特定于文件系统。

言论

FltQueryDirectoryFileEx 返回 FileObject所表示的目录中的文件的相关信息。

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

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

如果 QueryFlags 中设置了SL_RETURN_SINGLE_ENTRY标志，并且 FileName设置为 NULL，则为一个条目。
如果 FileName 未 NULL，则与 FileName 字符串匹配的条目数。（请注意，如果字符串不包含通配符，则最多可以有一个匹配项。
其信息适合 FileInformation指向的缓冲区中的条目数。
目录中包含的条目数。

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

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

对 FltQueryDirectoryFileEx 的最终调用将返回空输出缓冲区，并报告STATUS_NO_MORE_FILES的非错误状态值。

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

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

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