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

另请参阅

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

IO_STATUS_BLOCK

UNICODE_STRING

NtCreateFile

NtOpenFile