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

Статья
03/10/2023

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

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [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,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

Параметры

[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.

FileInformationClass

Тип возвращаемых сведений о файлах в каталоге. Тип возвращаемых сведений о файлах в каталоге. FileInformationClass может иметь одно из следующих FILE_INFORMATION_CLASS значений .

Значение	Значение
FileDirectoryInformation (1)	Возвращает структуру FILE_DIRECTORY_INFORMATION для каждого файла.
FileFullDirectoryInformation (2)	Возвращает структуру FILE_FULL_DIR_INFORMATION для каждого файла.
FileBothDirectoryInformation (3)	Возвращает структуру FILE_BOTH_DIR_INFORMATION для каждого файла.
FileNamesInformation (12)	Возвращает структуру FILE_NAMES_INFORMATION для каждого файла.
FileObjectIdInformation (29)	Возвращает структуру FILE_OBJECTID_INFORMATION для каждого файла с идентификатором объекта на томе. Этот класс данных действителен только для специального каталога "\$Extend\$ObjId:$O:$INDEX_ALLOCATION" на томах NTFS.
FileQuotaInformation (32)	Возвращает одну структуру FILE_QUOTA_INFORMATION для каждого пользователя тома, к которому применены квоты. Этот информационный класс действителен только для специального каталога "\$Extend\$Quota:$Q:$INDEX_ALLOCATION" на томах NTFS.
FileReparsePointInformation (33)	Возвращает одну структуру FILE_REPARSE_POINT_INFORMATION для каждого файла, который имеет точку повторного преобразования на томе. Этот класс информации действителен только для специального каталога "\$Extend\$Reparse:$R:$INDEX_ALLOCATION" на томах NTFS и ReFS.
FileIdBothDirectoryInformation (37)	Возвращает структуру FILE_ID_BOTH_DIR_INFORMATION для каждого файла.
FileIdFullDirectoryInformation (38)	Возвращает FILE_ID_FULL_DIR_INFORMATION структуру для каждого файла.
FileIdGlobalTxDirectoryInformation (50)	Возвращает структуру FILE_ID_GLOBAL_TX_DIR_INFORMATION для каждого файла.
FileIdExtdDirectoryInformation (60)	Возвращает структуру FILE_ID_EXTD_DIR_INFORMATION для каждого файла.
FileIdExtdBothDirectoryInformation (63)	Возвращает структуру FILE_ID_EXTD_BOTH_DIR_INFORMATION для каждого файла.

[in] QueryFlags

Один или несколько флагов, содержащихся в SL_QUERY_DIRECTORY_MASK. Возможные значения указаны в следующей таблице.

Значение	Значение
SL_RESTART_SCAN (0x00000001)	Проверка начнется с первой записи в каталоге. Если этот флаг не установлен, проверка возобновится с того места, где был завершен последний запрос.
SL_RETURN_SINGLE_ENTRY (0x00000002)	Обычно возвращаемый буфер упаковывается с таким количеством подходящих записей каталога. Если этот флаг установлен, файловая система будет возвращать только одну запись каталога одновременно. Это делает операцию менее эффективной.
SL_INDEX_SPECIFIED (0x00000004)	Проверка должна начинаться с указанной индексируемой позиции в каталоге. Этот флаг можно задать только при создании собственного IRP_MJ_DIRECTORY_CONTROL IRP; индекс указывается в IRP. Способ указания позиции зависит от файловой системы.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Все фильтры файловой системы, выполняющие виртуализацию каталогов или JIT-расширение, должны просто передавать запрос в файловую систему и возвращать записи, которые в настоящее время находятся на диске. Не все файловые системы поддерживают этот флаг.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	Файловые системы поддерживают сведения об курсоре каталога FileObject. Если несколько потоков выполняют запросы с использованием одного объекта FileObject, доступ к структуре per-FileObject осуществляется в одном потоке, чтобы предотвратить повреждение состояния курсора. Этот флаг указывает файловой системе не обновлять сведения о состоянии курсора fileObject, что позволяет нескольким потокам выполнять параллельные запросы с помощью одного дескриптора. Он ведет себя так, как если бы SL_RESTART_SCAN указывается при каждом вызове. Если шаблон дикого карта задан при следующем вызове, операция не будет выполняться там, где закончился последний запрос. Это обеспечивает поддержку истинно асинхронных запросов к каталогу. Если этот флаг используется в транзакции TxF, операция завершится ошибкой. Не все файловые системы поддерживают этот флаг.

[in, optional] FileName

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

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

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

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

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

Код возврата	Значение
STATUS_BUFFER_OVERFLOW	Выходной буфер недостаточно велик для возврата полного имени файла.
STATUS_BUFFER_TOO_SMALL	Выходной буфер недостаточно велик, по крайней мере для базовой структуры, определяемой FileInformationClass.
STATUS_INVALID_INFO_CLASS	Указан недопустимый класс FileInformationClass или класс сведений действителен только для специального условия (например, допустимо только для специального каталога).
STATUS_INVALID_PARAMETER	Один из параметров недопустим для файловой системы.

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

Требования

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