Функция ZwQueryDirectoryFile (ntifs.h)
Подпрограмма 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 .
Комментарии
Подпрограмма ZwQueryDirectoryFile возвращает сведения о файлах, содержащихся в каталоге, представленном FileHandle.
Если этот параметр указан, FileName определяет записи, включенные в проверку каталога для всех последующих вызовов ZwQueryDirectoryFile для заданного FileHandle.
Если имеется хотя бы одна соответствующая запись, ZwQueryDirectoryFile создает структуру FILE_XXX_INFORMATION для каждой записи и сохраняет ее в буфере.
При условии, что найдена хотя бы одна соответствующая запись каталога, число записей, для которых возвращаются сведения, является наименьшим из следующих:
- Одна запись, если 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) |
См. также раздел
FILE_REPARSE_POINT_INFORMATION
Использование версий Nt и Zw собственных процедур системных служб