FltGetFileNameInformation-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltGetFileNameInformation Routine gibt Nameninformationen für eine Datei oder ein Verzeichnis zurück.

Syntax

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parameter

[in] CallbackData

Zeiger auf eine FLT_CALLBACK_DATA-Struktur, bei der es sich um die Rückrufdatenstruktur für den E/A-Vorgang handelt. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

[in] NameOptions

Ein FLT_FILE_NAME_OPTIONS Wert, der Flags enthält, die das Format der zurückgegebenen Namensinformationen sowie die Abfragemethode angeben, die der Filter-Manager verwenden soll. Der Aufrufer muss ein Namensformat-Flag und ein Abfragemethodenflagge enthalten. Zusätzliche Flags können von Namensanbieter-Minifiltertreibern verwendet werden, um Namensabfrageoptionen anzugeben. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

Im Folgenden sind die Flagwerte für das Dateinamenformat aufgeführt. Es können nur eine der folgenden Flags angegeben werden. Eine Erläuterung dieser Formate finden Sie unter FLT_FILE_NAME_INFORMATION.

Name Format Flag Value	Bedeutung
FLT_FILE_NAME_NORMALIZED	Der FileNameInformation Parameter empfängt die Adresse einer Struktur, die den normalisierten Namen für die Datei enthält.
FLT_FILE_NAME_OPENED	Der FileNameInformation Parameter empfängt die Adresse einer Struktur, die den Namen enthält, der beim Öffnen der Datei verwendet wurde.
FLT_FILE_NAME_SHORT	Der FileNameInformation Parameter empfängt die Adresse einer Struktur, die den kurzen (8.3)-Namen für die Datei enthält. Der Kurzname besteht aus bis zu 8 Zeichen, gefolgt von einem Punkt und bis zu 3 weiteren Zeichen. Der Kurzname für eine Datei enthält nicht den Volumenamen, den Verzeichnispfad oder den Datenstromnamen. Ungültig im Vorerstellungspfad.

Im Folgenden sind die Flagwerte der Dateinamenabfragemethode aufgeführt. Es können nur eine der folgenden Flags angegeben werden.

Attributwert der Abfragemethode	Bedeutung
FLT_FILE_NAME_QUERY_DEFAULT	Wenn es zurzeit nicht sicher ist, das Dateisystem nach dem Dateinamen abzufragen, FltGetFileNameInformation führt nichts aus. Andernfalls fragt FltGetFileNameInformation den Namenscache des Filter-Managers nach den Dateinameninformationen ab. Wenn der Name nicht im Cache gefunden wird, fragt FltGetFileNameInformation das Dateisystem ab und speichert das Ergebnis zwischen.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation fragt den Namencache des Filter-Managers nach den Dateinameninformationen ab. FltGetFileNameInformation fragt das Dateisystem nicht ab.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation fragt das Dateisystem nach den Dateinameninformationen ab. FltGetFileNameInformation den Namencache des Filter-Managers nicht abfragt und das Ergebnis der Dateisystemabfrage nicht zwischenspeichert.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformation fragt den Namencache des Filter-Managers nach den Dateinameninformationen ab. Wenn der Name im Cache nicht gefunden wird und dies derzeit sicher ist, fragt FltGetFileNameInformation das Dateisystem nach den Dateinameninformationen ab und speichert das Ergebnis zwischen.

Namensanbieter-Minifilter verwenden die folgenden Flags, um die Eigenschaften von Dateinamenvorgängen anzugeben.

Name Provider Flag Value	Bedeutung
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	Ein Namensanbieter-Minifilter kann dieses Flag verwenden, um anzugeben, dass eine Namensabfrageanforderung an sich selbst (der Namensanbieter-Minifilter) umgeleitet werden soll, anstatt von den Namenanbietern im Stapel zu erfüllen.
FLT_FILE_NAME_DO_NOT_CACHE	Dieses Flag zeigt an, dass der aus dieser Abfrage abgerufene Name nicht zwischengespeichert werden soll. Namensanbieter-Minifilter verwenden dieses Kennzeichen, wenn sie Zwischenabfragen ausführen, um einen Namen zu generieren.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	Ein Namensanbieter-Minifilter kann dieses Flag verwenden, um anzugeben, dass es sicher ist, den Namen im Post-Create-Pfad abzufragen, auch wenn STATUS_REPARSE zurückgegeben wurde. Es liegt in der Verantwortung des Aufrufers, sicherzustellen, dass das FileObject->FileName Feld nicht geändert wurde. Verwenden Sie dieses Kennzeichen nicht mit Bereitstellungspunkten oder symbolischen Verknüpfungspunkten.

[out] FileNameInformation

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. FltGetFileNameInformation diese Struktur aus seitenseitigem Pool zuordnet. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

Rückgabewert

Wenn die Namensinformationen erfolgreich zurückgegeben werden, gibt FltGetFileNameInformation STATUS_SUCCESS zurück. Andernfalls wird ein entsprechender NTSTATUS-Wert zurückgegeben, z. B. einen der folgenden:

Rückgabecode	Beschreibung
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation kann in keinem der folgenden Situationen Dateinameninformationen abrufen, wenn die Abfrage nicht aus dem Namenscache des Filter-Managers erfüllt werden kann: Im Auslagerungs-E/A-Pfad. Wenn das TopLevelIrp- Feld des aktuellen Threads nicht NULL-ist, da die resultierende Dateisystem-Rekursion zu Deadlocks oder Stapelüberläufen führen kann. (Weitere Informationen zu diesem Problem finden Sie unter IoGetTopLevelIrp.) Nach Abschluss eines IRP_MJ_CLEANUP Vorgangs; das heißt, im Nachbereinigungs-, Pre-Close- oder Post-Close-Pfad (das Zieldateiobjekt hat den FO_CLEANUP_COMPLETE Flag festgelegt). In einer Voraboperation (PFLT_PRE_OPERATION_CALLBACK) oder einer Postoperationsroutine (PFLT_POST_OPERATION_CALLBACK) für eine der folgenden Vorgänge: IRP_MJ_ACQUIRE_FOR_CC_FLUSH IRP_MJ_ACQUIRE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_CC_FLUSH IRP_MJ_RELEASE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION In einer Postoperationsrückrufroutine für IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION. Wenn alle APCs deaktiviert sind; das heißt, wenn KeAreAllApcsDisabled TRUE zurückgibt. FltGetFileNameInformation kann den Kurznamen einer Datei nicht im Vorerstellungspfad abrufen. STATUS_FLT_INVALID_NAME_REQUEST ist ein Fehlercode.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation ein Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Wird zurückgegeben, wenn ein ungültiger Parameter übergeben wird, z. B. einen der folgenden: Der parameter FileNameInformation kann nicht NULL-werden. Der parameter CallbackData kann nicht NULL-werden. STATUS_INVALID_PARAMETER ist ein Fehlercode.
STATUS_FLT_NAME_CACHE_MISS	Die Dateinameninformationen werden im Namenscache nicht gefunden, und NameOptions- enthält FLT_FILE_NAME_QUERY_CACHE_ONLY. -oder- Die Dateinameninformationen werden im Namenscache nicht gefunden, wenn NameOptions- FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP enthält und die Dateinameninformationen nicht vom Dateisystem abgefragt werden können. Ein zusätzlicher Aufruf von FltGetFileNameInformation mit FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY in NameOptions- möglicherweise die Dateinameninformationen zurückgeben.
STATUS_NOT_SAME_DEVICE	Die Datei, die während der Voraberstellung abgefragt wird, befindet sich auf einem anderen Volume als das übergeordnete Verzeichnis. Dieser Fehler wird für normalisierte Namensabfragen zurückgegeben, bei denen es sich bei der Datei um eine Verbindung oder einen Symlink handelte, die auf ein anderes Volume aufgelöst wurde.
STATUS_ACCESS_DENIED	Wenn der Benutzer die Datei anhand der Datei-ID geöffnet hat, aber keine Traverseberechtigungen für den gesamten Pfad hat, schlägt FltGetFileNameInformation mit diesem Rückgabewert fehl. STATUS_ACCESS_DENIED ist ein Fehlercode. -oder- Die Datei ist eine Systemdatei, deren Zugriff verweigert wurde.

Bemerkungen

FltGetFileNameInformation die angeforderten Namensinformationen für die Datei oder das Verzeichnis zurück, die das Ziel des vorgangs ist, der durch CallbackDataim angegebenen Format beschrieben wird. Die Datei oder das Verzeichnis muss noch nicht vom Dateisystem geöffnet werden.

Wenn der CallbackData->Iopb->OperationFlags Member das SL_OPEN_TARGET_DIRECTORY bitweise Flag enthält, enthält FltGetFileNameInformation den Namen des enthaltenden (übergeordneten) Verzeichnisses für die angegebene Datei zurück. Dieser Name ist der tatsächliche Pfad, den der Erstellungsvorgang öffnet.

Um den Inhalt der FLT_FILE_NAME_INFORMATION Struktur zu analysieren, die von FltGetFileNameInformationzurückgegeben wird, rufen Sie FltParseFileNameInformationauf. (Weitere Informationen zu Dateinamenformaten finden Sie unter FLT_FILE_NAME_INFORMATION.)

Nach einem erfolgreichen Aufruf von FltGetFileNameInformationist der Aufrufer dafür verantwortlich, den im FileNameInformation Parameter zurückgegebenen Zeiger freizugeben, wenn der Zeiger nicht mehr benötigt wird. Der Aufrufer führt dies durch Aufrufen FltReleaseFileNameInformation.

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

Wenn FltGetFileNameInformation in der Preoperation-Rückrufroutine aufgerufen wird, um den geöffneten Namen abzurufen, FltGetFileNameInformation erfolgreich, auch wenn der Pfad zur geöffneten Datei nicht auf dem Volume vorhanden ist.

Wenn FltGetFileNameInformation in der Preoperation-Rückrufroutine aufgerufen wird, um den normalisierten Namen abzurufen, FltGetFileNameInformation erfolgreich, auch wenn die endgültige Komponente des geöffneten Pfads für die geöffnete Datei nicht auf dem Volume vorhanden ist.

Anmerkung

Die Server message Block (SMB)-Unterstützung für die Abfrage normalisierter Dateinamen auf einem Remotevolume variiert in verschiedenen Windows 10-Versionen. Weitere Informationen finden Sie im MS-SMB2 Protokoll-.

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 Preoperation-Rückrufroutine (PFLT_PRE_OPERATION_CALLBACK) abruft, indem eine Routine wie FltGetFileNameInformationaufgerufen wird, muss er FltGetTunneledName aus seiner Postoperationsrückrufroutine (PFLT_POST_OPERATION_CALLBACK) aufrufen, um die richtigen Dateinameninformationen für die Datei abzurufen.

Für Windows 8.1 und frühere Versionen kann FltGetFileNameInformation einen Streamtyp enthalten,nur, wenn der Aufruf aus dem vorab erstellten Rückruf eines Filters aufgerufen wird. Um zwischen dem Standarddatenstrom einer Datei und metadatendatenströmen zu unterscheiden, sollte dieser Aufruf im Voraberstellungsvorgang erfolgen. Der resultierende Datenstromtyp bleibt während der gesamten Lebensdauer der Datei gültig.

Vor Windows 8 hat der Filter-Manager den normalisierten Namen für eine Datei oder ein Verzeichnis erhalten, indem die Namensinformationen für jede Komponente des Dateipfads erfasst werden. Dies erforderte mehrere Abfragen an das Dateisystem, um den vollständigen Pfad zu kompilieren. Ab Windows 8 unterstützen lokale Dateisysteme die FileNormalizedNameInformation Dateiinformationsklasse, und es ist nur eine einzelne Abfrage erforderlich, um den normalisierten Namen abzurufen. Remotedateisysteme unterstützen möglicherweise die FileNormalizedNameInformation Dateiinformationsklasse nicht. Wenn dies der Fall ist, ist eine Abfrage für jede Komponente des Dateipfads noch erforderlich, um den normalisierten Namen zusammenzustellen. Unter bestimmten Netzwerkbedingungen kann eine vollständige Namensabfrage einen erheblichen Zeitaufwand für den Abschluss erfordern.

Weitere Informationen zu normalisierten Dateinameninformationen finden Sie unter FLT_FILE_NAME_INFORMATION.

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(Quelle, Name)
umbenennen (Name, neuer Name)/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 Rückgabewert)