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

Статья
07/11/2023

Подпрограмма ZwQueryDirectoryFile возвращает различные сведения о файлах в каталоге, указанном заданным дескриптором файла.

Синтаксис

NTSYSAPI NTSTATUS ZwQueryDirectoryFile(
  [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

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

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

[in] ReturnSingleEntry

Задайте значение TRUE , если должна быть возвращена только одна запись, в противном случае — FALSE . Если этот параметр имеет значение TRUE, ZwQueryDirectoryFile возвращает только первую найденную запись.

[in, optional] FileName

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

Если значение FileName не равно NULL, в проверку каталога включаются только те файлы, имена которых соответствуют строке FileName .
Если FileName имеет значение NULL, все файлы включаются, если ReturnSingleEntry имеет значение FALSE; один файл включается, если returnSingleEntry имеет значение TRUE.

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

[in] RestartScan

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

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

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

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

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

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

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

При каждом вызове ZwQueryDirectoryFile возвращает столько структур FILE_XXXX_INFORMATION (по одной на запись каталога), сколько может содержаться полностью в буфере, на который указывает FileInformation:

При первом вызове ZwQueryDirectoryFile возвращает STATUS_SUCCESS только в том случае, если выходной буфер содержит хотя бы одну полную структуру.
При последующих вызовах, если выходной буфер не содержит структур, ZwQueryDirectoryFile возвращает STATUS_SUCCESS но устанавливает IoStatusBlock-Information> = 0, чтобы уведомить вызывающий объект об этом условии. В этом случае вызывающий объект должен выделить буфер большего размера и снова вызвать ZwQueryDirectoryFile . Сведения о оставшихся записях не передаются. Таким образом, за исключением перечисленных выше случаев, когда возвращается только одна запись, ZwQueryDirectoryFile необходимо вызывать по крайней мере дважды для перечисления содержимого всего каталога.

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

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

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

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

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

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

Примечание

Если вызов функции ZwQueryDirectoryFile выполняется в пользовательском режиме, следует использовать имя "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(storport), PowerIrpDDis(wdm)