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

Статья
12/05/2023

Подпрограмма FltGetDestinationFileNameInformation запрашивает имя файла для родительского каталога назначения, а затем создает полное имя конечного пути для файла или каталога, который переименовывается или для которого создается жесткая ссылка NTFS.

Синтаксис

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

Параметры

[in] Instance

Указатель непрозрачного экземпляра для экземпляра драйвера минифильтра, подключенного к тому, где находится файл.

[in] FileObject

Указатель на объект file для файла. Этот параметр является обязательным и не может иметь значение NULL.

[in, optional] RootDirectory

Для операций компоновки: Если ссылка должна быть создана в том же каталоге, что и файл, с которым связана ссылка, или значение FileName содержит полный путь к создаваемой ссылке, этот параметр имеет значение NULL. В противном случае это дескриптор для каталога, в котором должна быть создана ссылка.

Для операций переименования: Если файл не перемещается в другой каталог или fileName содержит полный путь, этот параметр имеет значение NULL. В противном случае это дескриптор для каталога, в котором находится файл после переименования.

[in] FileName

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

Для операций переименования: Указатель на строку расширенных символов, содержащую новое имя файла.

[in] FileNameLength

Длина в байтах строки расширенных символов, на которую указывает FileName .

[in] NameOptions

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

Ниже приведены значения флагов формата имени. Можно указать только один флаг формата имени. (Обратите внимание, что FLT_FILE_NAME_SHORT не является допустимым значением флага для этого параметра.)

Значение флага формата имени	Значение
FLT_FILE_NAME_NORMALIZED	Параметр FileName получает нормализованное имя назначения для файла.
FLT_FILE_NAME_OPENED	Параметр FileName получает имя назначения для файла на основе имени, которое использовалось при открытии файла. Это имя файла не нормализовано.

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

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

Ниже приведены значения флагов имени файла. Можно указать любое сочетание этих флагов. (Обратите внимание, что FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE не является релевантным флагом для этого параметра, так как FltGetDestinationFileNameInformation не используется в обратном вызове после создания.)

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

[out] RetFileNameInformation

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

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

FltGetDestinationFileNameInformation возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений:

Код возврата	Описание
STATUS_FLT_INVALID_NAME_REQUEST	Это значение возвращается по любой из следующих причин: (1) FltGetDestinationFileNameInformation не может получить сведения об имени файла, если поле TopLevelIrp текущего потока не равно NULL, так как результирующая рекурсия файловой системы может привести к взаимоблокировкам или переполнениям стека. (2) FLT_FILE_NAME_SHORT был указан для флага формата имени в параметре NameOptions .
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation обнаружил сбой выделения пула. Это код ошибки.
STATUS_INVALID_PARAMETER	Для параметра NameOptions указано недопустимое значение. Это код ошибки.
STATUS_MOUNT_POINT_NOT_RESOLVED	Имя конечного пути содержит точку подключения, которая разрешается в том, отличный от тома, в котором находится файл. (Так как операция переименования или создания жесткой связи может выполняться только в пределах тома, а не в томах, операция завершается сбоем.) Это код ошибки.

Минифильтры обычно вызывают FltGetDestinationFileNameInformation в подпрограмме обратного вызова перед операцией для операции переименования или создания жесткой ссылки, что означает, что имя целевого файла, скорее всего, не существует. Имя назначения:

Для переименования файла имя файла будет иметь, если переименование будет выполнено успешно. Например, при переименовании name1 в name2имя_2 является целевым именем.
Для операции создания жесткой ссылки — имя, добавляемое в файловую систему. Например, при добавлении жесткой ссылки name2 в существующий файл с именем name1имя_2 является целевым именем.

FltGetDestinationFileNameInformation возвращает сведения об имени конечного файла в нормализованном или открытом формате. Дополнительные сведения об этих форматах см. в разделе структура FLT_FILE_NAME_INFORMATION .

Указатель объекта файла, передаваемый для параметра FileObject, должен быть элементом FileObjectструктуры FLT_RELATED_OBJECTS операции или указателем Data-Iopb-TargetFileObject>> для операции, где Data — это структура данных обратного вызова для операции (FLT_CALLBACK_DATA). Указатель на объект файла не может быть элементом Data-Iopb-Parameters.SetFileInformation.FileObject>>, так как это поле не используется одинаково в файловых системах.

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

Операцию переименования или создания жесткой связи можно выполнить только в пределах тома, а не в томах. Таким образом, такая операция завершается ошибкой, если имя пути назначения содержит точку подключения, которая разрешается в том, отличный от тома, в котором находится файл. Дополнительные сведения об операциях переименования см. в разделе структура FILE_RENAME_INFORMATION . Дополнительные сведения об операциях создания жесткой компоновки см. в разделе структуры FILE_LINK_INFORMATION .

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

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

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

Дополнительные сведения о нормализованных именах файлов см. в разделе 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