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

Статья
08/07/2023

Подпрограмма FltGetTunneledName извлекает туннелированное имя файла, учитывая нормализованное имя, возвращенное для файла при предыдущем вызове FltGetFileNameInformation, FltGetFileNameInformationUnsafe или FltGetDestinationFileNameInformation.

Синтаксис

NTSTATUS FLTAPI FltGetTunneledName(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  PFLT_FILE_NAME_INFORMATION FileNameInformation,
  [out] PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);

Параметры

[in] CallbackData

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

[in] FileNameInformation

Указатель на структуру FLT_FILE_NAME_INFORMATION , содержащую нормализованные сведения о имени, возвращенные предыдущим вызовом FltGetFileNameInformation, FltGetFileNameInformationUnsafe или FltGetDestinationFileNameInformation для файла.

[out] RetTunneledFileNameInformation

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

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

FltGetTunneledName возвращает STATUS_SUCCESS, если туннелированного имени найдено или если для файла нет туннелированного имени. В противном случае возвращается значение NTSTATUS, например следующее:

Код возврата	Описание
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName столкнулся с ошибкой выделения пула. Это код ошибки.

Файловые системы, такие как NTFS и FAT, используют кэш туннеля для каждого тома для краткого сохранения имен файлов и других метаданных для переименовываемых, связанных или удаляемых файлов. Туннелирование имен файлов может привести к тому, что окончательный компонент в нормализованных сведениях об имени файла, возвращаемых вызовом fltGetFileNameInformation, FltGetFileNameInformationUnsafe или FltGetDestinationFileNameInformation , становится недействительным.

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

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

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

Драйверы минифильтра, которые извлекают только короткие или открытые сведения об имени файла, не должны вызывать FltGetTunneledName.

После вызова FltGetFileNameInformation, FltGetFileNameInformationUnsafe или FltGetDestinationFileNameInformation в процедуре обратного вызова перед работой драйвер минифильтра должен сохранить возвращенный указатель FileNameInformation в структуре CompletionContext подпрограммы обратного вызова перед операции, чтобы послеоперационный вызов смог передать этот указатель в параметре FileNameInformation в FltGetTunneledName.

Примечание

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

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

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

Если для файла не найдено туннелированного имени, параметр RetTunneledFileNameInformation получает значение NULL.

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

FltGetTunneledName следует вызывать только из подпрограммы обратного вызова драйвера мини-фильтра после операции для IRP_MJ_CREATE или IRP_MJ_SET_INFORMATION. Вызов FltGetTunneledName из подпрограммы обратного вызова после операции после операции ввода-вывода для любого другого типа операции ввода-вывода или вызов из подпрограммы обратного вызова перед операцией является ошибкой программирования.

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

Туннелирование файлов обеспечивает совместимость с программами, которые используют файловые системы для сохранения метаданных файлов в течение короткого периода времени; например, для безопасного процесса сохранения. Туннелирование сохраняет связь между длинным и коротким (8.3) именами файла. При удалении имени файла из каталога (переименование или удаление) его пары коротких и длинных имен и время создания сохраняются в кэше туннеля, ключом к которому является удаленное имя. При добавлении имени в каталог (переименование или создание) выполняется поиск в кэше, чтобы определить, есть ли информация для восстановления. Кэш действует для каждого экземпляра каталога. При удалении каталога удаляется его кэш.

Требования

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