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

Статья
08/07/2023

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

Синтаксис

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

Параметры

[in] Instance

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

[in] FileObject

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

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

[in] ReturnSingleEntry

Задайте значение TRUE , если должна быть возвращена только одна запись, в противном случае — FALSE . Если этот параметр имеет значение TRUE, FltQueryDirectoryFile возвращает только первую найденную запись.

[in, optional] FileName

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

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

[in] RestartScan

Установите значение TRUE , если проверка начинается с первой записи в каталоге. Установите значение FALSE , если возобновляет проверку после предыдущего вызова. Вызывающий объект должен задать для этого параметра значение TRUE при первом вызове FltQueryDirectoryFile .

[out, optional] LengthReturned

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

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

FltQueryDirectoryFile возвращает STATUS_SUCCESS или соответствующее состояние ошибки. Обратите внимание, что набор возвращаемых значений состояния ошибок зависит от файловой системы.

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

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

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

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

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

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

Примечание

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

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

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

Вызывающие файлы FltQueryDirectoryFile должны выполняться в среде IRQL = PASSIVE_LEVEL и с включенными apcs. Дополнительные сведения см. в разделе Отключение APC.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")