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

Статья
08/07/2023

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

Синтаксис

NTSYSAPI NTSTATUS ZwQueryDirectoryFileEx(
  [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]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

Параметры

[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] QueryFlags

Один или несколько флагов, содержащихся в SL_QUERY_DIRECTORY_MASK. Список возможных значений см. в параметре QueryFlagsntQueryDirectoryFileEx .

[in, optional] FileName

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 10 версии 1709
Верхняя часть	ntifs.h
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")