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

Статья
08/07/2023

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

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

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, операция завершится сбоем. Не все файловые системы поддерживают этот флаг.

FileName

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

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

LengthReturned

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

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

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

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

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

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

При первом вызове FltQueryDirectoryFileEx, если структура, созданная для первой найденной записи, слишком велика, чтобы поместиться в выходной буфер, возвращается только фиксированная часть структуры. Фиксированная часть состоит из всех полей структуры, кроме конечной строки FileName . Подсистема ввода-вывода обеспечивает достаточный размер буфера для хранения фиксированной части соответствующей структуры FILE_XXX_INFORMATION (только при первом вызове, а не при последующих вызовах). В этом случае FltQueryDirectoryFileEx возвращает значение состояния STATUS_BUFFER_OVERFLOW. Кроме того, при первом вызове FltQueryDirectoryFileEx, если в каталоге FileObject нет файла, соответствующего параметру 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 и с включенными apcs. Дополнительные сведения см. в разделе Отключение APC.