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

Статья
12/21/2024

Подпрограмма 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, для события или ApcRoutine.

[in, optional] Event

Необязательный дескриптор для события, созданного вызывающим. Если этот параметр указан, вызывающий объект будет помещен в состояние ожидания до завершения запрошенной операции, и заданное событие имеет состояние Signaled. Этот параметр является необязательным и может иметь значение NULL. Значение 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] QueryFlags

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

[in, optional] FileName

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

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

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

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

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

Замечания

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

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

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

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

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

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 10 версии 1709
заголовка	ntifs.h
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")