FltGetFileNameInformation-Funktion (fltkernel.h)

Artikel
08/07/2023

Die FltGetFileNameInformation-Routine gibt Namensinformationen 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 darf nicht NULL sein.

[in] NameOptions

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

Im Folgenden werden die Werte des Dateinamenformatflags aufgeführt. Es kann nur eines 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 Parameter FileNameInformation empfängt die Adresse einer Struktur, die den normalisierten Namen für die Datei enthält.
FLT_FILE_NAME_OPENED	Der Parameter FileNameInformation empfängt die Adresse einer Struktur, die den Namen enthält, der beim Öffnen der Datei verwendet wurde.
FLT_FILE_NAME_SHORT	Der Parameter FileNameInformation empfängt die Adresse einer Struktur, die den kurzen Namen (8.3) 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 Streamnamen. Ungültig im Voraberstellungspfad.

Im Folgenden werden die Werte für die Abfragemethode für den Dateinamen aufgeführt. Es kann nur eines der folgenden Flags angegeben werden.

Flagwert der Abfragemethode	Bedeutung
FLT_FILE_NAME_QUERY_DEFAULT	Wenn es derzeit nicht sicher ist, das Dateisystem nach dem Dateinamen abzufragen, führt FltGetFileNameInformation 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 Namenscache 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 fragt nicht den Namenscache des Filter-Managers ab und speichert das Ergebnis der Dateisystemabfrage nicht zwischen.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformation fragt den Namenscache des Filter-Managers nach den Dateinameninformationen ab. Wenn der Name nicht im Cache 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 (den Namensanbieter-Minifilter) umgeleitet werden soll, anstatt von den Namenanbietern unten im Stapel erfüllt zu werden.
FLT_FILE_NAME_DO_NOT_CACHE	Dieses Flag gibt an, dass der aus dieser Abfrage abgerufene Name nicht zwischengespeichert werden soll. Namensanbieter-Minifilter verwenden dieses Flag, 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 Pfad nach der Erstellung abzufragen, auch wenn STATUS_REPARSE zurückgegeben wurde. Es liegt in der Verantwortung des Aufrufers sicherzustellen, dass das Feld FileObject-FileName> nicht geändert wurde. Verwenden Sie dieses Flag nicht mit Bereitstellungspunkten oder symbolischen Verbindungsreparsepunkten.

[out] FileNameInformation

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. FltGetFileNameInformation ordnet diese Struktur aus einem ausgelagerten Pool zu. Dieser Parameter ist erforderlich und darf nicht NULL sein.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation kann unter keinen der folgenden Umstände Dateinameninformationen abrufen, wenn die Abfrage nicht aus dem Namenscache des Filter-Managers erfüllt werden kann: Im E/A-Pfad für paging. Wenn das TopLevelIrp-Feld des aktuellen Threads nicht NULL ist, da die resultierende Dateisystemrekursion 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 Post-sauber Up-, Pre-Close- oder Post-Close-Pfad (für das Zieldateiobjekt ist das flag FO_CLEANUP_COMPLETE festgelegt). In einer Rückrufroutine für preoperation (PFLT_PRE_OPERATION_CALLBACK) oder Postoperation (PFLT_POST_OPERATION_CALLBACK) für einen 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 Rückrufroutine nach der Operation 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 im Voraberstellungspfad nicht abrufen. STATUS_FLT_INVALID_NAME_REQUEST ist ein Fehlercode.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation ist ein Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Wird zurückgegeben, wenn ein ungültiger Parameter übergeben wird, z. B. einer der folgenden: Der FileNameInformation-Parameter darf nicht NULL sein. Der Parameter CallbackData darf nicht NULL sein. STATUS_INVALID_PARAMETER ist ein Fehlercode.
STATUS_FLT_NAME_CACHE_MISS	Die Dateinameninformationen werden nicht im Namenscache gefunden, und NameOptions enthält FLT_FILE_NAME_QUERY_CACHE_ONLY. Oder Die Dateinameninformationen werden nicht im Namenscache 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 festgelegt ist, gibt möglicherweise die Dateinameninformationen zurück.
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 die Datei eine Verbindung oder ein Symlink war, der auf ein anderes Volume aufgelöst wurde.
STATUS_ACCESS_DENIED	Wenn der Benutzer die Datei anhand der Datei-ID geöffnet hat, aber nicht über Durchlaufberechtigungen für den gesamten Pfad verfügt, schlägt FltGetFileNameInformation mit diesem Rückgabewert fehl. STATUS_ACCESS_DENIED ist ein Fehlercode. Oder Die Datei ist eine Systemdatei, deren Zugriff verweigert wird.

Hinweise

FltGetFileNameInformation gibt die angeforderten Namensinformationen für die Datei oder das Verzeichnis zurück, das das Ziel des von CallbackData beschriebenen Vorgangs ist, im angegebenen Format. 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, gibt FltGetFileNameInformation für einen Voraberstellungsvorgang 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 FltGetFileNameInformation zurückgegeben wird, rufen Sie FltParseFileNameInformation auf. (Weitere Informationen zu Dateinamenformaten finden Sie unter FLT_FILE_NAME_INFORMATION.)

Nach einem erfolgreichen Aufruf von FltGetFileNameInformation ist der Aufrufer dafür verantwortlich, den im FileNameInformation-Parameter zurückgegebenen Zeiger freizugeben, wenn der Zeiger nicht mehr benötigt wird. Dazu ruft der Aufrufer FltReleaseFileNameInformation auf.

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

Wenn FltGetFileNameInformation in der Rückrufroutine vor der Operation für einen Erstellungsvorgang zum Abrufen des geöffneten Namens aufgerufen wird, ist FltGetFileNameInformation erfolgreich, auch wenn der Pfad zur geöffneten Datei auf dem Volume nicht vorhanden ist.

Wenn FltGetFileNameInformation in der Rückrufroutine für einen Erstellungsvorgang zum Abrufen des normalisierten Namens aufgerufen wird, ist FltGetFileNameInformation erfolgreich, auch wenn die letzte Komponente des Pfads zur geöffneten Datei auf dem Volume nicht vorhanden ist.

Hinweis

Die SMB-Unterstützung (Server Message Block) zum Abfragen normalisierter Dateinamen auf einem Remotevolume variiert je nach Windows 10 Versionen. Weitere Informationen finden Sie im MS-SMB2-Protokoll .

Bei Erstellungs-, Hardlink- und Umbenennungsvorgängen kann das Tunneln von Dateinamen dazu führen, dass die letzte Komponente in normalisierten Dateinameninformationen, die ein Minifiltertreiber in einer Preoperation-Rü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 FltGetFileNameInformation aufruft, muss fltGetTunneledName aus seiner Postoperation-Rückrufroutine (PFLT_POST_OPERATION_CALLBACK) aufgerufen werden, um die richtigen Dateinameninformationen für die Datei abzurufen.

Für Windows 8.1 und früheren Versionen kann FltGetFileNameInformation einen Streamtypnur enthalten, wenn sie aus dem Voraberstellungsrückruf eines Filters aufgerufen wird. Um zwischen dem Standarddatenstrom einer Datei und dem Metadatenstream zu unterscheiden, sollte dieser Aufruf im Vorgang vor der Erstellung erfolgen. Der resultierende Streamtyp 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 abgerufen, indem er die Namensinformationen für jede Komponente des Dateipfads sammelt. Dies erforderte mehrere Abfragen an das Dateisystem, um den vollständigen Pfad zu kompilieren. Ab Windows 8 unterstützen lokale Dateisysteme die Dateiinformationsklasse FileNormalizedNameInformation, und zum Abrufen des normalisierten Namens ist nur eine einzelne Abfrage erforderlich. Remotedateisysteme unterstützen die Dateiinformationsklasse FileNormalizedNameInformation möglicherweise nicht. In diesem Fall ist weiterhin eine Abfrage für jede Komponente des Dateipfads erforderlich, um den normalisierten Namen zusammenzustellen. Unter bestimmten Netzwerkbedingungen kann eine vollständige Namensabfrage einen erheblichen Zeitaufwand erfordern.

Weitere Informationen zu normalisierten Dateinamen finden Sie unter FLT_FILE_NAME_INFORMATION.

Hinweis

Das Tunneln von Dateinamen wirkt sich nur auf diese Weise auf Erstellungs-, Hardlink- 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:

delete (name)/create(name)
delete (name)/rename(source, name)
umbenennen (name, newname)/create(name)
umbenennen (name, newname)/rename(source,name)

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	fltkernel.h (include Fltkernel.h)
Bibliothek	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (siehe Rückgabewert)