FltGetFileNameInformationUnsafe-Funktion (fltkernel.h)

Artikel
08/07/2023

Die FltGetFileNameInformationUnsafe-Routine gibt Namensinformationen für eine geöffnete Datei oder ein geöffnetes Verzeichnis zurück.

Syntax

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parameter

[in] FileObject

Zeiger auf ein Dateiobjekt für die Datei oder das Verzeichnis. Das Dateiobjekt muss derzeit geöffnet sein. Dieser Parameter ist erforderlich und kann nicht auf NULL festgelegt werden.

[in, optional] Instance

Instanzzeiger für den Aufrufer. Dieser Parameter kann auf NULL festgelegt werden.

[in] NameOptions

Ein FLT_FILE_NAME_OPTIONS Wert, der Flags enthält, die das Format der zurückzugebenden Namensinformationen sowie die vom Filter-Manager zu verwendende Abfragemethode angeben. Dieser Parameter ist erforderlich und kann nicht auf NULL festgelegt werden.

In der folgenden Tabelle werden die Werte des Namensformatflags beschrieben. Es kann nur eines der Flags angegeben werden. Weitere Informationen zu diesen Formaten finden Sie unter FLT_FILE_NAME_INFORMATION.

Wert	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.

In der folgenden Tabelle werden die Werte des Abfragemethodenflags beschrieben. Es kann nur eines der Flags angegeben werden.

Wert	Bedeutung
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe fragt den Namenscache des Filter-Managers nach den Dateinameninformationen ab. Wenn der Name nicht im Cache gefunden wird, fragt FltGetFileNameInformationUnsafe das Dateisystem ab und speichert das Ergebnis zwischen.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe fragt den Namenscache des Filter-Managers nach den Dateinameninformationen ab. FltGetFileNameInformationUnsafe fragt das Dateisystem nicht ab.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe fragt das Dateisystem nach den Dateinameninformationen ab. FltGetFileNameInformationUnsafe fragt nicht den Namenscache des Filter-Managers ab und speichert das Ergebnis der Dateisystemabfrage nicht zwischen.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformationUnsafe fragt den Namenscache des Filter-Managers nach den Dateinameninformationen ab. Wenn der Name nicht im Cache gefunden wird und dies derzeit sicher ist, fragt FltGetFileNameInformationUnsafe das Dateisystem nach den Dateinameninformationen ab und speichert das Ergebnis zwischen.

[out] FileNameInformation

Zeiger auf eine vom Aufrufer zugeordnete Variable, die die Adresse einer systemseitig zugeordneten FLT_FILE_NAME_INFORMATION-Struktur empfängt. FltGetFileNameInformationUnsafe ordnet diese Struktur aus einem ausgelagerten Pool zu. Wenn diese Informationen nicht mehr benötigt werden, muss der Aufrufer die -Struktur freigeben, indem er FltReleaseFileNameInformation aufruft. Dieser Parameter ist erforderlich und kann nicht auf NULL festgelegt werden.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_FLT_INVALID_NAME_REQUEST	Das Dateiobjekt, auf das der FileObject-Parameter verweist, ist derzeit nicht geöffnet. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Für den FileNameInformation-Parameter wurde ein ungültiger Wert übergeben. Dies ist ein Fehlercode.

Hinweise

Die FltGetFileNameInformationUnsafe-Routine wird bereitgestellt, damit Sie den Namen eines Dateiobjekts außerhalb des Kontexts eines E/A-Vorgangs für dieses Dateiobjekt abfragen können. Andernfalls müssen Sie FltGetFileNameInformation aufrufen.

Im Gegensatz zur FltGetFileNameInformation-Routine schützt FltGetFileNameInformationUnsafe den Aufrufer nicht vor den folgenden Arten von Umständen, bei denen das Abfragen von Namensinformationen im Dateisystem für andere Abfragemethoden als FLT_FILE_NAME_QUERY_CACHE_ONLY zu Deadlocks führen kann:

Im E/A-Pfad für paging.
Wenn das TopLevelIrp-Feld des aktuellen Threads nicht NULL ist. Weitere Informationen 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.

Wenn ein Minifilter für Windows Vista/Server 2008 und höher noch keinen Filter instance hat, z. B. in der DriverEntry-Routine, kann er für den Parameter Instance verwendet NULL werden. Dadurch können DriverEntry-Routinen auf Dateinameninformationen zugreifen. Außer in diesem Fall ist ein NULL Wert für den parameter instance für die Systemverwendung reserviert.

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

Weitere Informationen zu normalisierten Dateinamen finden Sie unter FLT_FILE_NAME_INFORMATION.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	fltkernel.h (fltkernel.h einschließen)
Bibliothek	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (siehe Hinweise)