zwQueryDirectoryFileEx 函数 (ntifs.h)

ZwQueryDirectoryFileEx 例程返回有关给定文件句柄指定的目录中文件的各种信息。

语法

NTSYSAPI NTSTATUS ZwQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
  [in]           FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

参数

[in] FileHandle

ZwCreateFileZwOpenFile 为表示要请求其信息的目录的文件对象返回的句柄。 如果调用方为 EventApcRoutine 指定了非 NULL 值,则必须为异步 I/O 打开文件对象。

[in, optional] Event

调用方创建的事件的可选句柄。 如果提供此参数,调用方将进入等待状态,直到请求的操作完成,并将给定事件设置为“已发出信号”状态。 此参数是可选的,可以为 NULL。 如果调用方将等待 FileHandle 设置为“已发出信号”状态,则必须为 NULL。

[in, optional] ApcRoutine

调用方提供的可选 APC 例程的地址,该例程将在请求的操作完成时调用。 此参数是可选的,可以为 NULL。 如果存在与文件对象关联的 I/O 完成对象,则此参数必须为 NULL。

[in, optional] ApcContext

如果调用方提供 APC 或 I/O 完成对象与文件对象关联,则为指向调用方确定的上下文区域的可选指针。 操作完成后,如果指定了一个上下文,则此上下文将传递给 APC,或者作为 I/O 管理器发布到关联的 I/O 完成对象的完成消息的一部分包含在内。

此参数是可选的,可以为 NULL。 如果 ApcRoutine 为 NULL 并且没有与文件对象关联的 I/O 完成对象,则它必须为 NULL。

[out] IoStatusBlock

指向 IO_STATUS_BLOCK 结构的指针,该结构接收最终完成状态和有关操作的信息。 对于返回数据的成功调用,写入 FileInformation 缓冲区的字节数将在结构的 Information 成员中返回。

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

[in] QueryFlags

SL_QUERY_DIRECTORY_MASK中包含的一个或多个标志。 有关可能值的列表,请参阅 NtQueryDirectoryFileExQueryFlags 参数。

[in, optional] FileName

如果在 FileHandle 指定的目录中) 使用通配符,则为指向调用方分配的 Unicode 字符串的可选指针,该字符串包含 (或多个文件的名称。 此参数是可选的:

  • 如果 FileName 不为 NULL,则目录扫描中仅包含名称与 FileName 字符串匹配的文件。
  • 如果 FileName 为 NULL:
    • 如果未在 QueryFlags 中设置SL_RETURN_SINGLE_ENTRY,则包含所有文件。
    • 如果设置了SL_RETURN_SINGLE_ENTRY,则仅包含一个文件。

FileName 用作搜索表达式,并在首次调用给定句柄的 ZwQueryDirectoryFileEx 时捕获。 对 ZwQueryDirectoryFileEx 的后续调用将使用第一次调用中设置的搜索表达式。 传递给后续调用的 FileName 参数将被忽略。

返回值

ZwQueryDirectoryFileEx 返回STATUS_SUCCESS或适当的错误状态。 可返回的错误状态值集是特定于文件系统的。 ZwQueryDirectoryFileEx 还返回 IoStatusBlock的 Information 成员中实际写入给定 FileInformation 缓冲区的字节数。 有关一些可能的错误代码的列表,请参阅 NtQueryDirectoryFileEx

注解

ZwQueryDirectoryFileEx 返回 FileHandle 表示的目录中包含的文件的相关信息。

如果提供,FileName 将确定目录扫描中包含的条目,以便针对给定 FileHandleZwQueryDirectoryFileEx 的所有后续调用。

如果至少有一个匹配项, ZwQueryDirectoryFileEx 将为每个条目创建 FILE_XXX_INFORMATION 结构,并将其存储在缓冲区中。

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

  • 如果在 QueryFlags 中设置了SL_RETURN_SINGLE_ENTRY且 FileName 为 NULL,则为一个条目。
  • 如果 FileName 不为 NULL,则为与 FileName 字符串匹配的条目数。 如果字符串不包含通配符,则最多可以有一个匹配项。
  • 其信息适合指定缓冲区的条目数。
  • 目录中包含的条目数。

首次调用 ZwQueryDirectoryFileEx 时,如果它为找到的第一个条目创建的结构太大,无法放入输出缓冲区,则此例程将执行以下操作:

  • 将 结构的固定部分写入 FileInformation 的输出缓冲区。 固定部分包含除最终 FileName 字符串之外的所有字段。 在第一次调用(而不是后续调用时)时,I/O 系统确保缓冲区足够大,可以容纳相应 FILE_XXX_INFORMATION 结构的固定部分。
  • 尽可能多地写入输出缓冲区的 FileName 字符串。
  • 返回适当的状态值,例如STATUS_BUFFER_OVERFLOW。

每次调用时,ZwQueryDirectoryFileEx 返回FILE_XXX_INFORMATION结构 (每个目录条目) 一个结构,可以完全包含在 FileInformation 指向的缓冲区中:

  • 在第一次调用时,仅当输出缓冲区至少包含一个完整结构时, ZwQueryDirectoryFileEx 才返回STATUS_SUCCESS。
  • 在后续调用中,如果输出缓冲区不包含任何结构,则 ZwQueryDirectoryFileEx 返回STATUS_SUCCESS但设置 IoStatusBlock-Information> = 0 以通知调用方此情况。 在这种情况下,调用方应分配更大的缓冲区并再次调用 ZwQueryDirectoryFileEx 。 不会报告有关任何剩余条目的信息。 因此,除了上面列出的只返回一个条目的情况外,必须至少调用 两次 ZwQueryDirectoryFileEx 才能枚举整个目录的内容。

调用 ZwQueryDirectoryFileEx 时,可能会看到对目录所做的更改与 ZwQueryDirectoryFileEx 调用并行发生。 此行为取决于基础文件系统的实现。

ZwQueryDirectoryFileEx 的最后一次调用将返回空输出缓冲区,并报告适当的状态值,例如STATUS_NO_MORE_FILES。

如果在同一目录上多次调用 ZwQueryDirectoryFileEx ,而其他一些操作更改了该目录的内容,则根据操作的时间安排,可能会或可能不会看到任何更改。

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

ZwQueryDirectoryFileEx 的调用方必须在 IRQL = PASSIVE_LEVEL 且启用了特殊内核 APC 的情况下运行。

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

注意

如果对 ZwQueryDirectoryFileEx 函数的调用在用户模式下发生,则应使用名称“NtQueryDirectoryFileEx”而不是“ZwQueryDirectoryFileEx”。

对于来自内核模式驱动程序的调用,Windows Native System Services 例程的 NtXxxZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXxxZwXxx 版本之间的关系的详细信息,请参阅 使用本机系统服务例程的 Nt 和 Zw 版本

要求

要求
最低受支持的客户端 Windows 10 版本 1709
标头 ntifs.h
IRQL PASSIVE_LEVEL (请参阅“备注”部分)

另请参阅

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

UNICODE_STRING

使用本机系统服务例程的 Nt 和 Zw 版本

ZwCreateFile

ZwOpenFile