Функция NtQueryDirectoryFile (ntifs.h)

Статья
08/07/2023

Подпрограмма 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 для объекта файла, представляющего каталог, для которого запрашиваются сведения. Объект файла должен быть открыт для асинхронного ввода-вывода, если вызывающий объект указывает значение, отличное от NULL, для event или ApcRoutine.

[in, optional] Event

Необязательный дескриптор для события, созданного вызывающим абонентом. Если указан этот параметр, вызывающий объект будет переведен в состояние ожидания, пока запрошенная операция не будет завершена, а заданному событию будет присвоено состояние Signaled. Этот параметр является необязательным и может иметь значение NULL. Он должен иметь значение NULL, если вызывающий объект будет ожидать, пока FileHandle не будет установлен в состояние Signaled.

[in, optional] ApcRoutine

Адрес необязательной подпрограммы APC, предоставляемой вызывающим абонентом, которая вызывается по завершении запрошенной операции. Этот параметр является необязательным и может иметь значение NULL. Если с объектом файла связан объект завершения ввода-вывода, этот параметр должен иметь значение NULL.

[in, optional] ApcContext

Необязательный указатель на область контекста, определяемую вызывающим объектом, если вызывающий объект предоставляет APC или объект завершения ввода-вывода связан с объектом файла. После завершения операции этот контекст передается в APC, если он был указан, или включается в сообщение о завершении, которое диспетчер ввода-вывода отправляет в связанный объект завершения ввода-вывода.

Этот параметр является необязательным и может иметь значение NULL. Он должен иметь значение NULL, если ApcRoutine имеет значение NULL и с объектом файла не связан объект завершения ввода-вывода.

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK , которая получает окончательное состояние завершения и сведения об операции. Для успешных вызовов, возвращающих данные, в элементе Information структуры возвращается число байтов, записанных в буфер FileInformation.

[out] FileInformation

Указатель на буфер, который получает нужные сведения о файле. Структура сведений, возвращаемых в буфере, определяется параметром FileInformationClass .

[in] Length

Размер (в байтах) буфера, на который указывает FileInformation. Вызывающий объект должен задать этот параметр в соответствии с заданным fileInformationClass.

[in] FileInformationClass

Тип возвращаемых сведений о файлах в каталоге. Тип возвращаемых сведений о файлах в каталоге. Список возможных значений см. в параметре FileInformationClassобъекта NtQueryDirectoryFileEx .

[in] ReturnSingleEntry

Задайте значение TRUE , если должна возвращаться только одна запись, в противном случае — ЗНАЧЕНИЕ FALSE . Если этот параметр имеет значение TRUE, NtQueryDirectoryFile возвращает только первую найденную запись.

[in, optional] FileName

Необязательный указатель на выделенную вызывающим объектом строку Юникода, содержащую имя файла (или несколько файлов, если используются подстановочные знаки) в каталоге, указанном FileHandle. Этот параметр является необязательным и может иметь значение NULL.

Если fileName не равно NULL, в сканирование каталога включаются только те файлы, имена которых соответствуют строке FileName . Если fileName имеет значение NULL, включаются все файлы.

FileName используется в качестве выражения поиска и записывается при первом вызове NtQueryDirectoryFile для заданного дескриптора. Последующие вызовы NtQueryDirectoryFile будут использовать выражение поиска, заданное в первом вызове. Параметр FileName , переданный в последующие вызовы, будет игнорироваться.

[in] RestartScan

Задайте значение TRUE , если сканирование начинается с первой записи в каталоге. При возобновлении проверки из предыдущего вызова задайте значение FALSE .

При вызове подпрограммы NtQueryDirectoryFile для определенного дескриптора параметр RestartScan обрабатывается так, как если бы ему было присвоено значение TRUE, независимо от его значения. При последующих вызовах NtQueryDirectoryFile учитывается значение параметра RestartScan .

Возвращаемое значение

Подпрограмма NtQueryDirectoryFileвозвращает STATUS_SUCCESS или соответствующее состояние ошибки. Набор возвращаемых значений состояния ошибки зависит от файловой системы. NtQueryDirectoryFileтакже возвращает количество байтов, фактически записанных в данный буфер FileInformation в элементе InformationioStatusblock. Список возможных кодов ошибок см. в статье NtQueryDirectoryFileEx .

При условии, что найдена по крайней мере одна соответствующая запись каталога, количество записей, для которых возвращаются сведения, является *наименьшим из следующих:

Одна запись, если ReturnSingleEntry имеет значение TRUE , а FileName — NULL.
Количество записей, соответствующих строке FileName , если FileName не равно NULL. (Обратите внимание, что если строка не содержит подстановочных знаков, может быть не более одной совпадающей записи.)
Количество записей, сведения о которых помещаются в указанный буфер.
Количество записей, содержащихся в каталоге.

При первом вызове NtQueryDirectoryFile, если структура, созданная для первой найденной записи, слишком велика для размещения в выходном буфере, подпрограмма записывает фиксированную часть структуры в выходной буфер. Затем подпрограмма записывает в выходной буфер столько строки FileName , сколько поместится. (Фиксированная часть структуры состоит из всех полей, кроме конечной строки FileName . При первом вызове, но не при последующих вызовах, система ввода-вывода гарантирует, что буфер достаточно велик, чтобы вместить фиксированную часть соответствующей структуры FILE_XXX_INFORMATION .) В этом случае NtQueryDirectoryFile возвращает соответствующее значение состояния, например STATUS_BUFFER_OVERFLOW.

При каждом вызове NtQueryDirectoryFile возвращает столько FILE_XXXX_INFORMATION структур (по одной на запись каталога), сколько может содержаться полностью в буфере, на который указывает FileInformation. При первом вызове NtQueryDirectoryFile возвращает STATUS_SUCCESS, только если выходной буфер содержит хотя бы одну полную структуру. При последующих вызовах, если выходной буфер не содержит структур, NtQueryDirectoryFile возвращает STATUS_SUCCESS но задает IoStatusblock-Information> = 0, чтобы уведомить вызывающую сторону об этом условии. В этом случае вызывающий объект должен выделить буфер большего размера и снова вызвать NtQueryDirectoryFile . Информация о оставшихся записях не сообщается. Таким образом, за исключением перечисленных выше случаев, когда возвращается только одна запись, ntQueryDirectoryFile необходимо вызывать по крайней мере дважды для перечисления содержимого всего каталога.

При вызове NtQueryDirectoryFile вы можете увидеть изменения, внесенные в каталог, которые происходят параллельно с вызовами NtQueryDirectoryFile . Это поведение зависит от реализации базовой файловой системы.

Последний вызов NtQueryDirectoryFile возвращает пустой выходной буфер и сообщает соответствующее значение состояния, например STATUS_NO_MORE_FILES.

Если ntQueryDirectoryFile вызывается несколько раз в одном каталоге, а другая операция изменяет содержимое этого каталога, любые изменения могут быть видны или не будут видны в зависимости от времени выполнения операций.

NtQueryDirectoryFileвозвращает ноль в любом элементе структуры FILE_XXXX_INFORMATION , которая не поддерживается файловой системой.

Вызывающие файлы NtQueryDirectoryFile должны выполняться в среде IRQL = PASSIVE_LEVEL и с включенными специальными APC ядра.

Дополнительные сведения о других процедурах запроса сведений о файлах см. в разделе Объекты файлов.

Примечание

Если вызов функции NtQueryDirectoryFile происходит в пользовательском режиме, следует использовать имя NtQueryDirectoryFile вместо ZwQueryDirectoryFile.

Для вызовов из драйверов режима ядра версии NtXXX и ZwXXX подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXXX и ZwXXX см. в разделе Использование версий Nt и Zw для процедур собственных системных служб.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	HwStorPortProhibitedDIs, PowerIrpDDis