FltGetDestinationFileNameInformation-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltGetDestinationFileNameInformation Routine fragt den Dateinamen für das übergeordnete Verzeichnis des Ziels ab und erstellt dann einen vollständigen Zielpfadnamen für eine Datei oder ein Verzeichnis, das umbenannt wird oder für die eine NTFS-Hardlink erstellt wird.

Syntax

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
);

Parameter

[in] Instance

Undurchsichtiger Instanzzeiger für eine Minifiltertreiberinstanz, die an das Volume angefügt ist, in dem sich die Datei befindet.

[in] FileObject

Zeigen Sie auf das Dateiobjekt für die Datei. Dieser Parameter ist erforderlich und kann nicht NULL sein.

[in, optional] RootDirectory

Für Verknüpfungsvorgänge: Wenn der Link im selben Verzeichnis erstellt werden soll wie die Datei, mit der eine Verknüpfung hergestellt wird, oder wenn FileName den vollständigen Pfadnamen für den zu erstellenden Link enthält, ist dieser Parameter NULL. Andernfalls handelt es sich um ein Handle für das Verzeichnis, in dem der Link erstellt werden soll.

Für Umbenennungsvorgänge: Wenn die Datei nicht in ein anderes Verzeichnis verschoben wird oder FileName den vollständigen Pfadnamen enthält, ist dieser Parameter NULL. Andernfalls handelt es sich um ein Handle für das Verzeichnis, in dem sich die Datei befindet, nachdem sie umbenannt wurde.

[in] FileName

Für Verknüpfungsvorgänge: Zeiger auf eine breite Zeichenfolge mit dem Namen, der dem neu erstellten Link zugewiesen werden soll.

Für Umbenennungsvorgänge: Zeiger auf eine breite Zeichenfolge, die den neuen Namen für die Datei enthält.

[in] FileNameLength

Die Länge der Zeichenfolge mit breitem Zeichen in Bytes, auf die FileName verweist.

[in] NameOptions

Ein FLT_FILE_NAME_OPTIONS Wert, der Flags enthält, die das Format der zurückgegebenen Namensinformationen angeben, die Abfragemethode, die der Filter-Manager verwenden soll, und zusätzliche Dateinamenkennzeichnungen. Dieser Parameter ist erforderlich und kann nicht NULL sein.

Im Folgenden sind die Namensformat-Flagwerte aufgeführt. Es kann nur ein Namensformat-Flag angegeben werden. (Beachten Sie, dass FLT_FILE_NAME_SHORT kein gültiger Flagwert für diesen Parameter ist.)

Name Format Flag Value	Bedeutung
FLT_FILE_NAME_NORMALIZED	Der parameter FileName empfängt den normalisierten Zielnamen für die Datei.
FLT_FILE_NAME_OPENED	Der FileName Parameter empfängt den Zielnamen für die Datei basierend auf dem Namen, der beim Öffnen der Datei verwendet wurde. Dieser Dateiname ist nicht normalisiert.

Im Folgenden sind die Flagwerte der Abfragemethode aufgeführt. Es kann nur ein Abfragemethodenflags angegeben werden.

Attributwert der Abfragemethode	Bedeutung
FLT_FILE_NAME_QUERY_DEFAULT	Wenn es derzeit nicht sicher ist, das Dateisystem nach dem Zieldateinamen abzufragen, FltGetDestinationFileNameInformation nichts tut. Andernfalls fragt FltGetDestinationFileNameInformation den Namenscache des Filter-Managers nach den Dateinameninformationen für das übergeordnete Verzeichnis des Ziels ab und fügt dann den Zielnamen an. Wenn der resultierende Name im Cache nicht gefunden wird, fragt FltGetDestinationFileNameInformation das Dateisystem ab und speichert das Ergebnis zwischen.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetDestinationFileNameInformation fragt den Namenscache des Filter-Managers nach den Dateinameninformationen für das übergeordnete Verzeichnis des Ziels ab und fügt dann den Zielnamen an. Das Dateisystem wird nicht abfragt.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetDestinationFileNameInformation fragt das Dateisystem nach den Dateinameninformationen für das übergeordnete Verzeichnis des Ziels ab und fügt dann den Zielnamen an. Er fragt nicht den Namenscache des Filter-Managers ab und speichert das Ergebnis der Dateisystemabfrage nicht zwischen.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetDestinationFileNameInformation fragt den Namenscache des Filter-Managers nach den Dateinameninformationen für das übergeordnete Verzeichnis des Ziels ab und fügt dann den Zielnamen an. Wenn der Name im Cache nicht gefunden wird und dies derzeit sicher ist, fragt FltGetDestinationFileNameInformation das Dateisystem nach den Dateinameninformationen ab und speichert das Ergebnis zwischen.

Im Folgenden sind die Dateinamenkennzeichnungswerte aufgeführt. Eine beliebige Kombination dieser Flags kann angegeben werden. (Beachten Sie, dass FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE kein relevantes Flag für diesen Parameter ist, da FltGetDestinationFileNameInformation nicht in einem Rückruf nach dem Erstellen verwendet wird.)

Dateiname-Flagwert	Bedeutung
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation leitet die Namensanforderung an die aufrufende Filterinstanz weiter.
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation den abgerufenen Dateinamen nicht zwischenspeichert. Namensanbieter-Minifilter verwenden dieses Kennzeichen, wenn sie Zwischenabfragen ausführen, um einen Namen zu generieren.

[out] RetFileNameInformation

Zeigen Sie auf eine vom Aufrufer zugewiesene Variable, die die Adresse einer vom System zugewiesenen FLT_FILE_NAME_INFORMATION Struktur empfängt, die die Dateinameninformationen enthält. FltGetDestinationFileNameInformation weist diese Struktur aus seitenseitigem Pool zu. Dieser Parameter ist erforderlich und kann nicht NULL sein.

Rückgabewert

FltGetDestinationFileNameInformation gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert wie einen der folgenden zurück:

Rückgabecode	Beschreibung
STATUS_FLT_INVALID_NAME_REQUEST	Dieser Wert wird aus einem der folgenden Gründe zurückgegeben: (1) FltGetDestinationFileNameInformation kann keine Dateinameninformationen abrufen, wenn das TopLevelIrp Feld des aktuellen Threads nicht NULL ist, da die resultierende Dateisystem-Rekursion zu Deadlocks oder Stapelüberläufenführen kann. (2) FLT_FILE_NAME_SHORT wurde für das Namensformat-Flag im NameOptions Parameter angegeben.
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation ein Poolzuordnungsfehler aufgetreten ist. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Für den parameter NameOptions wurde ein ungültiger Wert angegeben. Dies ist ein Fehlercode.
STATUS_MOUNT_POINT_NOT_RESOLVED	Der Name des Zielpfads enthält einen Bereitstellungspunkt, der zu einem anderen Volume als dem, in dem sich die Datei befindet, aufgelöst wird. (Da ein Umbenennungs- oder Hardlink-Erstellungsvorgang nur innerhalb eines Volumes und nicht über Volumes hinweg ausgeführt werden kann, schlägt der Vorgang fehl.) Dies ist ein Fehlercode.

Bemerkungen

Minifilter rufen in der Regel FltGetDestinationFileNameInformation in einer preoperation callback routine für einen Umbenennungs- oder Hardlink-Erstellungsvorgang auf, was bedeutet, dass der Zieldateiname höchstwahrscheinlich nicht vorhanden ist. Der Name "destination" lautet:

Bei einer Dateibenennung hat der Name die Datei, wenn die Umbenennung erfolgreich ist. Wenn Sie z. B. Name1 in Name2umbenennen, ist Name2 der Zielname.
Bei einem HardLink-Creation-Vorgang wird der Name dem Dateisystem hinzugefügt. Wenn Sie beispielsweise den Hardlink Name2 der vorhandenen Datei namens Name1hinzufügen, ist Name2 der Zielname.

FltGetDestinationFileNameInformation gibt die Zieldateinameninformationen im normalisierten oder "geöffneten Dateiformat" zurück. Weitere Informationen zu diesen Formaten finden Sie in der FLT_FILE_NAME_INFORMATION Struktur.

Der Dateiobjektzeiger, der für den FileObject Parameter übergeben wird, muss entweder das FileObject Member der FLT_RELATED_OBJECTS Struktur für den Vorgang oder die Data->Iopb->TargetFileObject Zeiger für den Vorgang sein, wobei Data die Rückrufdatenstruktur für den Vorgang ist (FLT_CALLBACK_DATA). Der Dateiobjektzeiger kann nicht der Data->Iopb->Parameters.SetFileInformation.FileObject Member sein, da dieses Feld nicht einheitlich über Dateisysteme hinweg verwendet wird.

Wenn der Benutzer die Datei mithilfe der Datei-ID geöffnet hat, aber keine Traverseberechtigung für den gesamten Pfad besitzt, gibt FltGetDestinationFileNameInformation nur den Teil des Pfads zurück, für den der Benutzer über Berechtigungen verfügt.

Ein Umbenennungs- oder Hardlink-Erstellungsvorgang kann nur innerhalb eines Volumes und nicht über Volumes ausgeführt werden. Daher schlägt ein solcher Vorgang fehl, wenn der Zielpfadname einen Bereitstellungspunkt enthält, der zu einem anderen Volume als dem, in dem sich die Datei befindet, aufgelöst wird. Weitere Informationen zu Umbenennungsvorgängen finden Sie in der FILE_RENAME_INFORMATION Struktur. Weitere Informationen zu Hardlink-Erstellungsvorgängen finden Sie in den FILE_LINK_INFORMATION Strukturen.

Nach einem erfolgreichen Aufruf von FltGetDestinationFileNameInformationist der Aufrufer dafür verantwortlich, den im RetFileNameInformation Parameter zurückgegebenen Zeiger freizugeben, wenn er nicht mehr benötigt wird, indem FltReleaseFileNameInformationaufgerufen wird.

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

Bei Erstellungs-, Hardlink- und Umbenennungsvorgängen kann die endgültige Komponente in normalisierten Dateinameninformationen dazu führen, dass ein Minifiltertreiber in einer Voroperationsrückrufroutine ungültig wird. Wenn ein Minifiltertreiber normalisierte Dateinameninformationen in einer Voraboperationsrückrufroutine (PFLT_PRE_OPERATION_CALLBACK) abruft, indem eine Routine wie FltGetDestinationFileNameInformationaufgerufen wird, muss FltGetTunneledName aus dem Postoperationsrückruf Routine aufgerufen werden, um die richtigen Dateinameninformationen für die Datei abzurufen.

Weitere Informationen zu normalisierten Dateinameninformationen finden Sie unter FLT_FILE_NAME_INFORMATION.

Dateinamentunnel wirken sich auf diese Weise nur auf Erstellungs-, Hardlink- und Umbenennungsvorgänge aus. Es 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: