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

Статья
10/30/2024

подпрограмма 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 задано значение FileLinkInformation), или операция переименования (IRP_MJ_SET_INFORMATION с FILE_INFORMATION_CLASS для FileRenameInformation), он должен вызывать FltGetTunneledName из подпрограммы обратного вызова после операции (PFLT_POST_OPERATION_CALLBACK) для получения правильных сведений о имени файла.

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

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

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

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

Заметка

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

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

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 (include Fltkernel.h)
библиотеки	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL