FltGetDestinationFileNameInformation-Funktion (fltkernel.h)

Artikel
12/05/2023

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, die umbenannt wird oder für die ein harter NTFS-Link 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 instance Zeiger für einen Minifiltertreiber instance, der an das Volume angefügt ist, auf dem sich die Datei befindet.

[in] FileObject

Zeiger auf das Dateiobjekt für die Datei. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in, optional] RootDirectory

Für Linkvorgänge: Wenn der Link im selben Verzeichnis wie die Datei erstellt werden soll, mit der verknüpft 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 Linkvorgänge: Zeiger auf eine Breitzeichenzeichenfolge, die den Namen enthält, der dem neu erstellten Link zugewiesen werden soll.

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

[in] FileNameLength

Länge der Breitzeichenzeichenfolge in Bytes, auf die FileName verweist.

[in] NameOptions

Ein FLT_FILE_NAME_OPTIONS Wert, der Flags enthält, die das Format der zurückzugebenden Namensinformationen, die vom Filter-Manager zu verwendende Abfragemethode und zusätzliche Dateinamenflags angeben. Dieser Parameter ist erforderlich und darf nicht NULL sein.

Im Folgenden werden die Werte des Namensformatflags aufgeführt. Es kann nur ein Namensformatflag 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 FileName-Parameter 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 Werte des Abfragemethodenflags aufgeführt. Es kann nur ein Abfragemethodenflag angegeben werden.

Flagwert der Abfragemethode	Bedeutung
FLT_FILE_NAME_QUERY_DEFAULT	Wenn es derzeit nicht sicher ist, das Dateisystem nach dem Namen der Zieldatei abzufragen, führt FltGetDestinationFileNameInformation nichts aus. 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 nicht im Cache 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. Sie fragt nicht den Namenscache des Filter-Managers ab und speichert nicht das Ergebnis der Dateisystemabfrage 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 nicht im Cache gefunden wird und dies derzeit sicher ist, fragt FltGetDestinationFileNameInformation das Dateisystem nach den Dateinameninformationen ab und speichert das Ergebnis zwischen.

Im Folgenden sind die Werte des Dateinamenflags 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 in einem Rückruf nach der Erstellung nicht verwendet wird.)

Dateinameflagwert	Bedeutung
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation leitet die Namensanforderung an den aufrufenden Filter weiter, instance abgeschlossen werden soll.
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation speichert den abgerufenen Dateinamen nicht zwischen. Namensanbieter-Minifilter verwenden dieses Flag, wenn sie Zwischenabfragen ausführen, um einen Namen zu generieren.

[out] RetFileNameInformation

Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Adresse einer systemseitig zugewiesenen FLT_FILE_NAME_INFORMATION-Struktur empfängt, die die Dateinameninformationen enthält. FltGetDestinationFileNameInformation ordnet diese Struktur aus einem ausgelagerten Pool zu. Dieser Parameter ist erforderlich und darf nicht NULL sein.

Rückgabewert

FltGetDestinationFileNameInformation gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden:

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 Dateisystemrekursion Zu Deadlocks oder Stapelüberläufen führen kann. (2) FLT_FILE_NAME_SHORT wurde für das Namensformatflag im Parameter NameOptions angegeben.
STATUS_INSUFFICIENT_RESOURCES	Bei FltGetDestinationFileNameInformation ist ein Poolzuordnungsfehler aufgetreten. 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 in ein anderes Volume als das Volume aufgelöst wird, in dem sich die Datei befindet. (Da ein Umbenennungs- oder Hartlinkerstellungsvorgang nur innerhalb eines Volumes und nicht über Volumes hinweg ausgeführt werden kann, schlägt der Vorgang fehl.) Dies ist ein Fehlercode.

Hinweise

Minifilter rufen in der Regel FltGetDestinationFileNameInformation in einer Rückrufroutine für eine Voraboperation für einen Umbenennungs- oder Hartlinkerstellungsvorgang auf. Dies bedeutet, dass der Name der Zieldatei höchstwahrscheinlich nicht vorhanden ist. Der Name des "Ziels" lautet:

Bei einer Dateibenennung der Name der Datei, wenn die Umbenennung erfolgreich ist. Wenn Sie beispielsweise name1 in Name2 umbenennen, ist name2 der Zielname.
Bei einem Vorgang zum Erstellen einer endgültigen Verknüpfung der Name, der dem Dateisystem hinzugefügt wird. Wenn Sie z. B. den fest verknüpften Namen2 zur vorhandenen Datei namens name1 hinzufügen, ist name2 der Zielname.

FltGetDestinationFileNameInformation gibt die Informationen zum Namen der Zieldatei entweder im normalisierten format oder im Format "geöffnete Datei" 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 der FileObject-Member der FLT_RELATED_OBJECTS-Struktur für den Vorgang oder der Data-Iopb-TargetFileObject-Zeiger>> für den Vorgang sein, wobei Data die Rückrufdatenstruktur für den Vorgang ist (FLT_CALLBACK_DATA). Der Dateiobjektzeiger darf nicht der Data-Iopb-Parameters.SetFileInformation.FileObject-Member>> sein, da dieses Feld nicht einheitlich in dateisystemübergreifend verwendet wird.

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

Ein Umbenennungs- oder Hartlinkerstellungsvorgang kann nur innerhalb eines Volumes und nicht über Volumes hinweg ausgeführt werden. Daher schlägt ein solcher Vorgang fehl, wenn der Name des Zielpfads einen Bereitstellungspunkt enthält, der in ein anderes Volume als das Volume aufgelöst wird, in dem sich die Datei befindet. Weitere Informationen zu Umbenennungsvorgängen finden Sie in der FILE_RENAME_INFORMATION-Struktur . Weitere Informationen zu Erstellungsvorgängen für feste Verknüpfungen finden Sie in den FILE_LINK_INFORMATION-Strukturen .

Nach einem erfolgreichen Aufruf von FltGetDestinationFileNameInformation ist der Aufrufer dafür verantwortlich, den im RetFileNameInformation-Parameter zurückgegebenen Zeiger freizugeben, wenn er beim Aufrufen von FltReleaseFileNameInformation nicht mehr benötigt wird.

Der Aufrufer darf den Inhalt der im Parameter RetFileNameInformation zurückgegebenen Struktur nicht ändern, da diese Struktur vom Filter-Manager zwischengespeichert wird, sodass sie von allen Minifiltertreibern verwendet werden kann.

Bei Erstellungs-, Festverknüpfungs- und Umbenennungsvorgängen kann das Tunneln von Dateinamen dazu führen, dass die letzte Komponente in normalisierten Dateinameninformationen, die ein Minifiltertreiber in einer Voroperationsrückrufroutine abruft, ungültig wird. Wenn ein Minifiltertreiber normalisierte Dateinameninformationen in einer PFLT_PRE_OPERATION_CALLBACK-Routine (Preoperation Callback) abruft, indem er eine Routine wie FltGetDestinationFileNameInformation aufruft, muss er FltGetTunneledName aus seiner Postoperation-Rückrufroutine aufrufen, um die richtigen Dateinameninformationen für die Datei abzurufen.

Weitere Informationen zu normalisierten Dateinamen finden Sie unter FLT_FILE_NAME_INFORMATION.

Das Tunneln von Dateinamen wirkt sich nur auf diese Weise auf Erstellungs-, Festverknüpfungs- und Umbenennungsvorgänge aus. Andere E/A-Vorgänge wie Lese- und Schreibvorgänge sind davon nicht betroffen.

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