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

Статья
12/22/2024

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

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

[in] ReturnSingleEntry

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

[in, optional] FileName

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

Если Имя_файла не 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 также возвращает количество байтов, фактически записанных в указанный буфер File Information FileInformation в элемент е information IoStatusBlock. Список возможных кодов ошибок см. в NtQueryDirectoryFileEx.

Замечания

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

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

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

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

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

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

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

При каждом вызове ZwQueryDirectoryFile возвращает столько FILE__INFORMATION структур XXX (по одному на запись каталога), сколько можно полностью содержать в буфере, на который указывает 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 Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP.
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
правил соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)