FltGetDestinationFileNameInformation-Funktion (fltkernel.h)
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:
- delete(Name)/create(Name)
- delete(Name)/rename(Source, Name)
- rename(name, newname)/create(name)
- rename(name, newname)/rename(source, name)
Anforderungen
Anforderung | Wert |
---|---|
Zielplattform- | Universal |
Header- | fltkernel.h (include Fltkernel.h) |
Library | FltMgr.lib |
DLL- | Fltmgr.sys |
IRQL- | <= APC_LEVEL |
Siehe auch
FltGetFileNameInformationUnsafe-