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

Статья
12/21/2024

Подпрограмма 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

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

[in] ReturnSingleEntry

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

[in, optional] FileName

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

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

[in] RestartScan

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

[out, optional] LengthReturned

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

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

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

Замечания

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

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

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

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

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

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

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

Заметка

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

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista
целевая платформа	Всеобщий
заголовка	fltkernel.h (include Fltkernel.h)
библиотеки	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")