Функция FltQueryDirectoryFileEx (fltkernel.h)

Статья
07/16/2024

FltQueryDirectoryFileEx возвращает различные виды сведений о файлах в каталоге, указанном заданным объектом файла.

Синтаксис

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

Параметры

Instance

Непрозрачный указатель на экземпляр драйвера мини-фильтра, инициирующий этот ввод-вывод.

FileObject

Указатель на объект файла, представляющий запрашиваемый каталог.

FileInformation

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

Length

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

FileInformationClass

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

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)	Файловые системы поддерживают сведения о курсоре каталогаFileObjectfileObject. Если несколько потоков выполняют запросы с помощью одного и того же FileObject, доступ к структуре FileObjectfileObject позволяет предотвратить повреждение состояния курсора. Этот флаг сообщает файловой системе, что не обновляет данные о состоянии курсораFileObject, что позволяет нескольким потокам выполнять запросы параллельно с помощью одного дескриптора. Он ведет себя так, как если бы SL_RESTART_SCAN указывается при каждом вызове. Если шаблон подстановочной карточки указан при следующем вызове, операция не будет выбирать место окончания последнего запроса. Это позволяет поддерживать истинные асинхронные запросы к каталогу. Если этот флаг используется внутри транзакции TxF, операция завершится ошибкой. Не все файловые системы поддерживают этот флаг.

FileName

Указатель на структуру, выделенную вызывающим UNICODE_STRING со строкой Юникода, содержащей имя файла (или несколько файлов, если используются подстановочные знаки), в каталоге, указанном FileObject. Этот параметр является необязательным и может быть null. Если fileNameзначение NULL, все файлы включаются.

Если Имя_файла не null, в сканирование каталога включены только файлы, имена которых соответствуют строке fileName . Если установлен флаг QueryFlagsResetScan, значение FileName игнорируется.

LengthReturned

Получает количество байтов, записанных в указанный буфер FileInformation.

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

FltQueryDirectoryFileEx возвращает STATUS_SUCCESS или соответствующий код ошибки. Набор значений состояния ошибки, которые могут быть возвращены, зависят от файловой системы.

Замечания

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

Первый вызов FltQueryDirectoryFileEx определяет набор записей, которые необходимо включить в проверку каталога для всех последующих вызовов, исходя из значений QueryFlags и FileName. Если есть по крайней мере одна соответствующая запись, FltQueryDirectoryFileEx создает структуру FILE_XXX_INFORMATION (см. приведенную выше таблицу) для каждой записи в свою очередь и сохраняет структуру в буфере.

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

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

При первом вызове FltQueryDirectoryFileEx, если структура, созданная для первой найденной записи, слишком велика, чтобы поместиться в выходной буфер, возвращается только фиксированная часть структуры. Фиксированная часть состоит из всех полей структуры, кроме последней строки FileName. Подсистема ввода-вывода гарантирует, что буфер достаточно велик для хранения фиксированной части соответствующей FILE_XXX_INFORMATION структуры (только при первом вызове и не при последующих вызовах). В этом случае FltQueryDirectoryFileEx возвращает значение состояния STATUS_BUFFER_OVERFLOW. Кроме того, при первом вызове FltQueryDirectoryFileEx, если в каталоге fileObj ect отсутствует файл, соответствующий параметру fileName , FltQueryDirectoryFileEx возвращает STATUS_NO_SUCH_FILE.

При каждом вызове FltQueryDirectoryFileEx возвращает столько FILE_xxx_INFORMATION структур (по одной записи каталога), сколько можно полностью содержать в буфере, на который указывает FileInformation. Если выходной буфер содержит по крайней мере одну полную структуру, возвращаемое значение состояния STATUS_SUCCESS. Никаких сведений о оставшихся записях не сообщается. Таким образом, за исключением случаев, перечисленных выше, когда возвращается только одна запись, FltQueryDirectoryFileEx необходимо вызвать по крайней мере дважды, чтобы перечислить содержимое всего каталога (например, если параметр FileName содержит один или несколько подстановочных знаков или NULL).

Последний вызов FltQueryDirectoryFileEx возвращает пустой выходной буфер и сообщает о значении состояния без ошибок STATUS_NO_MORE_FILES.

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

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

Вызывающие FltQueryDirectoryFileEx должны работать в IRQL = PASSIVE_LEVEL и с включенными API. Дополнительные сведения см. в разделе Отключение API.