ntQueryDirectoryFile 函数 (ntifs.h)
NtQueryDirectoryFile 例程返回有关给定文件句柄指定的目录中文件的各种信息。
语法
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
[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] BOOLEAN ReturnSingleEntry,
[in, optional] PUNICODE_STRING FileName,
[in] BOOLEAN RestartScan
);
参数
[in] FileHandle
NtCreateFile 或 NtOpenFile 为文件对象返回的句柄，该文件对象表示要为其请求信息的目录。 如果调用方为 Event 或 ApcRoutine 指定了非 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
要返回的有关目录中文件的信息的类型。 要返回的有关目录中文件的信息的类型。 有关可能值的列表，请参阅 NtQueryDirectoryFileEx 的 FileInformationClass 参数。
[in] ReturnSingleEntry
如果只应返回单个条目，则设置为 TRUE ;否则设置为 FALSE 。 如果此参数为 TRUE， 则 NtQueryDirectoryFile 仅返回找到的第一个条目。
[in, optional] FileName
如果在 FileHandle 指定的目录中) 使用通配符，则为指向调用方分配的 Unicode 字符串的可选指针，该字符串包含 (或多个文件的名称。 此参数是可选的，可以为 NULL。
如果 FileName 不为 NULL，则目录扫描中仅包含名称与 FileName 字符串匹配的文件。 如果 FileName 为 NULL，则包含所有文件。
FileName 用作搜索表达式，并在首次调用 NtQueryDirectoryFile 时捕获给定句柄。 对 NtQueryDirectoryFile 的 后续调用将使用在第一次调用中设置的搜索表达式。 传递给后续调用的 FileName 参数将被忽略。
[in] RestartScan
如果扫描要从目录中的第一个条目开始，则设置为 TRUE 。 如果从上一次调用恢复扫描，则设置为 FALSE 。
当为特定句柄调用 NtQueryDirectoryFile 例程时，无论其值如何， RestartScan 参数都会被视为设置为 TRUE。 在后续 的 NtQueryDirectoryFile 调用中，将遵循 RestartScan 参数的值。
返回值
NtQueryDirectoryFile例程返回STATUS_SUCCESS或适当的错误状态。 可返回的错误状态值集是特定于文件系统的。 NtQueryDirectoryFile还返回 IoStatusblock的 Information 成员中实际写入给定 FileInformation 缓冲区的字节数。 有关一些可能的错误代码的列表，请参阅 NtQueryDirectoryFileEx 。
注解
NtQueryDirectoryFile 例程返回 FileHandle 表示的目录中包含的文件的相关信息。
如果提供，FileName 参数的值将确定目录扫描中包含的条目，以扫描给定 FileHandle 对 NtQueryDirectoryFile 的所有后续调用。
如果至少有一个匹配项， NtQueryDirectoryFile 会为每个条目创建 FILE_XXX_INFORMATION 结构，并将其存储在缓冲区中。
假设找到至少一个匹配的目录条目，则返回信息的条目数为以下项中的 *最小 ：
- 如果 ReturnSingleEntry 为 TRUE 且 FileName 为 NULL，则为一个条目。
- 如果 FileName 不为 NULL，则为与 FileName 字符串匹配的条目数。 (请注意，如果字符串不包含通配符，则最多可以有一个匹配项。)
- 其信息适合指定缓冲区的条目数。
- 目录中包含的条目数。
首次调用 NtQueryDirectoryFile 时，如果为找到的第一个条目创建的结构太大，无法容纳到输出缓冲区中，则例程会将结构的固定部分写入输出缓冲区。 然后，该例程会尽可能多地写入输出缓冲区中的 FileName 字符串。 (结构的固定部分由除最终 FileName 字符串之外的所有字段组成。在第一次调用（而不是后续调用时）时，I/O 系统确保缓冲区足够大，足以容纳相应 FILE_XXX_INFORMATION structure.) 发生这种情况时， NtQueryDirectoryFile 将返回适当的状态值，例如STATUS_BUFFER_OVERFLOW。
每次调用时，NtQueryDirectoryFile 返回FILE_XXX_INFORMATION结构 (每个目录条目) 一个结构，因为可以完全包含在 FileInformation 指向的缓冲区中。 在第一次调用时，仅当输出缓冲区至少包含一个完整结构时， NtQueryDirectoryFile 才返回STATUS_SUCCESS。 在后续调用中，如果输出缓冲区不包含任何结构，则 NtQueryDirectoryFile 返回STATUS_SUCCESS但设置 IoStatusblock-Information> = 0 以通知调用方此情况。 在这种情况下，调用方应分配更大的缓冲区并再次调用 NtQueryDirectoryFile 。 不会报告有关任何剩余条目的信息。 因此，除非上面列出的只返回一个条目，否则必须至少调用两次 NtQueryDirectoryFile 来枚举整个目录的内容。
调用 NtQueryDirectoryFile 时，你可能会看到对目录所做的更改与 NtQueryDirectoryFile 调用并行发生。 此行为取决于基础文件系统的实现。
对 NtQueryDirectoryFile 的最终调用将返回空输出缓冲区，并报告适当的状态值，例如STATUS_NO_MORE_FILES。
如果在同一目录上多次调用 NtQueryDirectoryFile ，并且某些其他操作更改了该目录的内容，则根据操作的时间，可能会看到或看不到任何更改。
NtQueryDirectoryFile在文件系统不支持的 FILE_XXX_INFORMATION 结构的任何成员中返回零。
NtQueryDirectoryFile 的调用方必须在 IRQL = PASSIVE_LEVEL下运行，并且启用了特殊内核 APC。
有关其他文件信息查询例程的信息，请参阅 文件对象。
注意
如果在用户模式下调用 NtQueryDirectoryFile 函数，则应使用名称“NtQueryDirectoryFile”而不是“ZwQueryDirectoryFile”。
对于来自内核模式驱动程序的调用，Windows 本机系统服务例程的 NtXXX 和 ZwXXX 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXXX 和 ZwXXX 版本之间的关系的详细信息，请参阅 使用本机系统服务例程的 Nt 和 Zw 版本。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows XP |
| 目标平台 | 通用 |
| 标头 | ntifs.h (包括 Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (请参阅“备注”部分) |
| DDI 符合性规则 | HwStorPortProhibitedDDI、PowerIrpDDis |