FltGetTunneledName-Funktion (fltkernel.h)

Artikel
10/30/2024

Die FltGetTunneledName Routine ruft den tunnelierten Namen für eine Datei ab, wobei der normalisierte Name für die Datei durch einen vorherigen Aufruf von FltGetFileNameInformation, FltGetFileNameInformationUnsafeoder FltGetDestinationFileNameInformationzurückgegeben wird.

Syntax

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

Parameter

[in] CallbackData

Zeiger auf die Rückrufdatenstruktur für den E/A-Vorgang (FLT_CALLBACK_DATA). Dieser Parameter ist erforderlich und kann nicht NULL-werden.

[in] FileNameInformation

Zeigen Sie auf eine FLT_FILE_NAME_INFORMATION Struktur, die normalisierte Namensinformationen enthält, die von einem vorherigen Aufruf von FltGetFileNameInformation, FltGetFileNameInformationUnsafeoder FltGetDestinationFileNameInformation für die Datei zurückgegeben werden.

[out] RetTunneledFileNameInformation

Zeigen Sie auf eine vom Aufrufer zugewiesene Variable, die die Adresse einer neu zugeordneten Struktur empfängt, die den Tunneldateinamen enthält. Wenn kein Tunnelname gefunden wird, empfängt diese Variable NULL-. Dieser Parameter ist erforderlich und kann bei eingaben nicht NULL- werden.

Rückgabewert

FltGetTunneledName gibt STATUS_SUCCESS zurück, wenn der tunnelierte Name gefunden wird oder kein Tunnelname für die Datei vorhanden ist. Andernfalls wird ein NTSTATUS-Wert zurückgegeben, z. B. folgendes:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName ein Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode.

Bemerkungen

Dateisysteme wie NTFS und FAT verwenden einen Cache pro Volume, um Dateinamen und andere Metadaten für Dateien, die umbenannt, verknüpft oder gelöscht werden, kurz beizubehalten. Dateinamentunnelung kann dazu führen, dass die letzte Komponente in normalisierten Dateinameninformationen, die von einem Voraboperationsaufruf an FltGetFileNameInformation, FltGetFileNameInformationUnsafeoder FltGetDestinationFileNameInformation ungültig werden.

Wenn ein Minifiltertreiber normalisierte Dateinameninformationen in der Voraboperationsrückrufroutine (PFLT_PRE_OPERATION_CALLBACK) für eine Erstellung (IRP_MJ_CREATE) abruft, hardlink (IRP_MJ_SET_INFORMATION mit FILE_INFORMATION_CLASS auf FileLinkInformationfestgelegt) oder umbenennen (IRP_MJ_SET_INFORMATION mit FILE_INFORMATION_CLASS auf FileRenameInformationfestgelegt) sie muss FltGetTunneledName aus der Postoperation-Rückrufroutine (PFLT_POST_OPERATION_CALLBACK) aufrufen, um die richtigen Dateinameninformationen für die Datei abzurufen.

Nur normalisierte Dateinameninformationen sind durch Tunneling betroffen. Der Filter-Manager kann nicht sicherstellen, dass die endgültige Komponente normalisiert wird, bis der Erstellungs-, Hardlink- oder Umbenennungsvorgang tatsächlich erfolgt ist, da tunneling dazu führen kann, dass ein kurzer Name in einen langen Namen geändert wird. Daher muss ein Minifiltertreiber FltGetTunneledName aus der Postoperation-Rückrufroutine aufrufen, um zu bestimmen, ob die in der Voroperationsrückrufroutine abgerufenen normalisierten Dateinameninformationen gültig sind.

Weitere Informationen zu normalisierten Dateinameninformationen finden Sie unter FLT_FILE_NAME_INFORMATION.

Minifiltertreiber, die nur kurze oder geöffnete Dateinameninformationen abrufen, sollten nicht FltGetTunneledNameaufrufen.

Nach dem Aufrufen von FltGetFileNameInformation, FltGetFileNameInformationUnsafeoder FltGetDestinationFileNameInformation in der Preoperation-Rückrufroutine, Der Minifiltertreiber muss den zurückgegebenen FileNameInformation Zeiger in der CompletionContext-Struktur der Preoperation-Rückrufroutine speichern, sodass der Postoperationsrückruf diesen Zeiger im FileNameInformation Parameter an FltGetTunneledNameübergeben kann.

Anmerkung

Dateinamentunnel wirken sich auf diese Weise nur auf Erstellungs-, Hardlink- und Umbenennungsvorgänge aus. Sie wirkt sich nicht auf andere E/A-Vorgänge aus, z. B. Lese- und Schreibzugriff.

Die folgenden gekoppelten Vorgänge können dazu führen, dass der Dateiname Namen tunnelt wird:

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

Wenn kein Tunnelname für die Datei gefunden wird, empfängt der parameter RetTunneledFileNameInformationNULL.

Nach einem erfolgreichen Aufruf von FltGetTunneledNameist der Aufrufer für das Freigeben der RetTunneledFileNameInformation und FileNameInformation Zeiger verantwortlich, wenn sie nicht mehr benötigt werden, indem sie FltReleaseFileNameInformationaufrufen.

FltGetTunneledName- sollte nur aus der Postoperationsrückrufroutine eines Minifiltertreibers für IRP_MJ_CREATE oder IRP_MJ_SET_INFORMATION aufgerufen werden. Das Aufrufen FltGetTunneledName aus einer Postoperation-Rückrufroutine für jeden anderen Typ von E/A-Vorgängen oder das Aufrufen aus einer Voroperationsrückrufroutine ist ein Programmierfehler.

Der Aufrufer darf den Inhalt der im RetTunneledFileNameInformation Parameter zurückgegebenen Struktur nicht ändern, da diese Struktur vom Filter-Manager zwischengespeichert wird, damit alle Minifiltertreiber sie verwenden können.

Das Dateitunneling ermöglicht die Kompatibilität mit Programmen, die auf Dateisystemen angewiesen sind, Dateimetainformationen für einen kurzen Zeitraum beizubehalten; Zum Beispiel für den sicheren Speichervorgang. Das Tunneln behält die Zuordnung zwischen dem langen und dem kurzen (8.3)-Namen einer Datei bei. Wenn ein Dateiname aus einem Verzeichnis entfernt wird (umbenennen oder löschen), werden sein kurzes und langes Namenspaar und die Erstellungszeit in einem Tunnelcache gespeichert, der durch den Namen schlüsselt, der entfernt wurde. Wenn einem Verzeichnis ein Name hinzugefügt wird (umbenennen oder erstellen), wird der Cache durchsucht, um festzustellen, ob Informationen wiederhergestellt werden sollen. Der Cache ist pro Instanz eines Verzeichnisses wirksam. Wenn ein Verzeichnis gelöscht wird, wird der Cache entfernt.