FltQueryDirectoryFileEx 函数 (fltkernel.h)

项目
08/07/2023

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 结构的指针，该结构包含包含 (或多个文件的名称的 Unicode 字符串（如果在 FileObject 指定的目录中) 使用通配符）。此参数是可选的，可以为 NULL。如果 fileName 为 NULL，则包含所有文件。

如果 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。