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

Статья
08/07/2023

Подпрограмма FltGetFileNameInformation возвращает сведения об имени файла или каталога.

Синтаксис

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Параметры

[in] CallbackData

Указатель на структуру FLT_CALLBACK_DATA , которая является структурой данных обратного вызова для операции ввода-вывода. Этот параметр является обязательным и не может иметь значение NULL.

[in] NameOptions

Значение FLT_FILE_NAME_OPTIONS , содержащее флаги, указывающие формат возвращаемых сведений об имени, а также метод запроса, используемый диспетчером фильтров. Вызывающий объект должен содержать флаг формата имени и флаг метода запроса. Дополнительные флаги могут использоваться драйверами мини-фильтра поставщика имен для указания параметров запроса имени. Этот параметр является обязательным и не может иметь значение NULL.

Ниже приведены значения флагов формата имени файла. Можно указать только один из следующих флагов. Описание этих форматов см. в разделе FLT_FILE_NAME_INFORMATION.

Значение флага формата имени	Значение
FLT_FILE_NAME_NORMALIZED	Параметр FileNameInformation получает адрес структуры, содержащей нормализованное имя файла.
FLT_FILE_NAME_OPENED	Параметр FileNameInformation получает адрес структуры, содержащей имя, которое использовалось при открытии файла.
FLT_FILE_NAME_SHORT	Параметр FileNameInformation получает адрес структуры, содержащей короткое (8.3) имя файла. Короткое имя состоит из 8 символов, за которым сразу же следует точка и еще до 3 символов. Краткое имя файла не включает имя тома, путь к каталогу или имя потока. Недопустимо в пути предварительного создания.

Ниже приведены значения флага метода запроса имени файла. Можно указать только один из следующих флагов.

Значение флага метода запроса	Значение
FLT_FILE_NAME_QUERY_DEFAULT	Если в настоящее время не безопасно запрашивать имя файла в файловой системе, FltGetFileNameInformation ничего не делает. В противном случае FltGetFileNameInformation запрашивает в кэше имен диспетчера фильтров сведения об имени файла. Если имя не найдено в кэше, FltGetFileNameInformation запрашивает файловую систему и кэширует результат.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation запрашивает в кэше имен диспетчера фильтров сведения об имени файла. FltGetFileNameInformation не запрашивает файловую систему.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation запрашивает в файловой системе сведения об имени файла. FltGetFileNameInformation не запрашивает кэш имен диспетчера фильтров и не кэшируют результаты запроса файловой системы.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformation запрашивает в кэше имен диспетчера фильтров сведения об имени файла. Если имя не найдено в кэше и в настоящее время это безопасно, FltGetFileNameInformation запрашивает в файловой системе сведения об имени файла и кэширует результат.

Минифильтры поставщика имен используют следующие флаги для указания свойств операций с именами файлов.

Значение флага поставщика имен	Значение
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	Минифильтр поставщика имен может использовать этот флаг, чтобы указать, что запрос запроса имени должен быть перенаправлен на себя (минифильтр поставщика имен), а не удовлетворяться поставщиками имен ниже в стеке.
FLT_FILE_NAME_DO_NOT_CACHE	Этот флаг указывает, что имя, полученное из этого запроса, не должно кэшироваться. Минифильтры поставщика имен используют этот флаг при выполнении промежуточных запросов для создания имени.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	Минифильтр поставщика имен может использовать этот флаг, чтобы указать, что можно безопасно запрашивать имя в пути после создания, даже если был возвращен STATUS_REPARSE. Вызывающий объект отвечает за то, чтобы не было изменено поле FileObject-FileName>. Не используйте этот флаг с точками подключения или точками повторного анализа символических ссылок.

[out] FileNameInformation

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

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

Если сведения об имени возвращаются успешно, Функция FltGetFileNameInformation возвращает STATUS_SUCCESS. В противном случае возвращается соответствующее значение NTSTATUS, например одно из следующих значений:

Код возврата	Описание
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation не может получить сведения об имени файла в следующих случаях, если запрос не может быть выполнен из кэша имен диспетчера фильтров: В пути ввода-вывода подкачки. Если поле TopLevelIrp текущего потока не равно NULL, так как результирующая рекурсия файловой системы может привести к взаимоблокировкам или переполнению стека. (Дополнительные сведения об этой проблеме см. в разделе IoGetTopLevelIrp.) После завершения операции IRP_MJ_CLEANUP ; то есть в пути после очистки, перед закрытием или после закрытия (для целевого объекта файла установлен флаг FO_CLEANUP_COMPLETE). В процедуре обратного вызова перед операцией (PFLT_PRE_OPERATION_CALLBACK) или после операции (PFLT_POST_OPERATION_CALLBACK) для любой из следующих операций: IRP_MJ_ACQUIRE_FOR_CC_FLUSH IRP_MJ_ACQUIRE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_CC_FLUSH IRP_MJ_RELEASE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION В процедуре обратного вызова после операции для IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION. Если все ПТР отключены; то есть, когда KeAreAllApcsDisabled возвращает значение TRUE. FltGetFileNameInformation не может получить короткое имя файла в предварительно созданном пути. STATUS_FLT_INVALID_NAME_REQUEST — это код ошибки.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation столкнулся с ошибкой выделения пула. Это код ошибки.
STATUS_INVALID_PARAMETER	Возвращается при передаче недопустимого параметра, например одного из следующих: Параметр FileNameInformation не может иметь значение NULL. Параметр CallbackData не может иметь значение NULL. STATUS_INVALID_PARAMETER — это код ошибки.
STATUS_FLT_NAME_CACHE_MISS	Сведения об имени файла не находятся в кэше имен, а NameOptions включает FLT_FILE_NAME_QUERY_CACHE_ONLY. -или- Сведения об имени файла не находятся в кэше имен, если NameOptions включает FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP, а сведения об имени файла не могут быть запрошены из файловой системы. Дополнительный вызов FltGetFileNameInformation с FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY, заданным в NameOptions, может вернуть сведения об имени файла.
STATUS_NOT_SAME_DEVICE	Файл, запрашиваемый во время предварительного создания, находится на томе, отличном от его родительского каталога. Эта ошибка возвращается для запросов нормализованных имен, где файл был соединением или символьной ссылкой, разрешенной в другой том.
STATUS_ACCESS_DENIED	Если пользователь открыл файл по идентификатору файла, но не имеет привилегий обхода для всего пути, FltGetFileNameInformation завершается ошибкой с этим возвращаемым значением. STATUS_ACCESS_DENIED — это код ошибки. -или- Файл является системным файлом, доступ к которым запрещен.

FltGetFileNameInformation возвращает запрошенные сведения о имени файла или каталога, которые являются целью операции, описанной CallbackData, в указанном формате. Файл или каталог еще не нужно открывать в файловой системе.

Если для операции предварительного создания элемент CallbackData-Iopb-OperationFlags>> содержит флаг SL_OPEN_TARGET_DIRECTORY битового, FltGetFileNameInformation возвращает имя содержащего (родительского) каталога для заданного файла. Это имя является фактическим путем, который открывает операция создания.

Чтобы проанализировать содержимое структуры FLT_FILE_NAME_INFORMATION, возвращаемой FltGetFileNameInformation, вызовите Метод FltParseFileNameInformation. (Дополнительные сведения о форматах имен файлов см. в разделе FLT_FILE_NAME_INFORMATION.)

После успешного вызова FltGetFileNameInformation вызывающий объект отвечает за освобождение указателя, возвращенного в параметре FileNameInformation , когда указатель больше не нужен. Вызывающий объект делает это путем вызова FltReleaseFileNameInformation.

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

Если метод FltGetFileNameInformation вызывается в подпрограмме обратного вызова перед операцией создания для получения открытого имени, FltGetFileNameInformation завершается успешно, даже если путь к открываемему файлу не существует на томе.

Если fltGetFileNameInformation вызывается в подпрограмме обратного вызова перед операцией создания для получения нормализованного имени, FltGetFileNameInformation завершается успешно, даже если конечный компонент пути к открываемому файлу не существует на томе.

Примечание

Поддержка SMB для запроса нормализованных имен файлов на удаленном томе зависит от разных версий Windows 10. Дополнительные сведения см. в статье Протокол MS-SMB2 .

В операциях создания, жесткого связывания и переименования туннелирование имен файлов может привести к тому, что окончательный компонент в нормализованных сведениях о имени файла, которые драйвер минифильтра получает в подпрограмме обратного вызова перед операцией, становится недействительным. Если драйвер минифильтра получает нормализованные сведения об имени файла в процедуре обратного вызова перед операции (PFLT_PRE_OPERATION_CALLBACK), вызывая подпрограмму , например FltGetFileNameInformation, он должен вызвать FltGetTunneledName из своей подпрограммы обратного вызова после операции (PFLT_POST_OPERATION_CALLBACK), чтобы получить правильные сведения об имени файла.

Для Windows 8.1 и более ранних версий FltGetFileNameInformation может включать тип потокатолько при вызове из обратного вызова фильтра перед созданием. Чтобы различать потоки файлов по умолчанию и потоки метаданных, этот вызов следует выполнить в операции предварительного создания. Результирующий тип потока будет оставаться действительным на протяжении всего времени существования файла.

До Windows 8 диспетчер фильтров получал нормализованное имя файла или каталога, собирая сведения об именах для каждого компонента пути к файлу. Для этого требовалось несколько запросов к файловой системе для компиляции полного пути. Начиная с Windows 8, локальные файловые системы поддерживают класс сведений о файле FileNormalizedNameInformation, и для получения нормализованного имени требуется только один запрос. Удаленные файловые системы могут не поддерживать класс fileNormalizedNameInformation . В этом случае для сборки нормализованного имени по-прежнему требуется запрос для каждого компонента пути к файлу. При определенных условиях сети запрос на полное имя может потребовать значительного времени.

Дополнительные сведения о нормализованных имени файлах см. в разделе FLT_FILE_NAME_INFORMATION.

Примечание

Таким образом туннелирование имен файлов влияет только на операции создания, жесткого связывания и переименования. Это не влияет на другие операции ввода-вывода, такие как чтение и запись.

Следующие связанные операции могут привести к туннелирование имени файла:

delete (name)/create(name)
delete (name)/rename(source, name)
rename (name, newname)/create(name)
rename (name, newname)/rename(source,name)

Требования

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