FltGetFileNameInformationUnsafe-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltGetFileNameInformationUnsafe Routine gibt Nameninformationen 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

Zeigen Sie auf ein Dateiobjekt für die Datei oder das Verzeichnis. Das Dateiobjekt muss zurzeit 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ückgegebenen Namensinformationen sowie die abfragemethode angeben, die vom Filter-Manager verwendet werden soll. Dieser Parameter ist erforderlich und kann nicht auf NULL-festgelegt werden.

In der folgenden Tabelle werden die Namensformatkennzeichnungswerte beschrieben. Es kann nur eine der Flags angegeben werden. Weitere Informationen zu diesen Formaten finden Sie unter FLT_FILE_NAME_INFORMATION.

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

In der folgenden Tabelle werden die Flagwerte der Abfragemethode beschrieben. Es kann nur eine 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 im Cache nicht gefunden wird und dies derzeit sicher ist, fragt FltGetFileNameInformationUnsafe das Dateisystem nach den Dateinameninformationen ab und speichert das Ergebnis zwischen.

[out] FileNameInformation

Zeigen Sie auf eine vom Aufrufer zugewiesene Variable, die die Adresse einer vom System zugewiesenen FLT_FILE_NAME_INFORMATION Struktur empfängt. FltGetFileNameInformationUnsafe weist diese Struktur aus seitenseitigem Pool zu. Wenn diese Informationen nicht mehr benötigt werden, muss der Aufrufer die Struktur freigeben, indem FltReleaseFileNameInformationaufgerufen wird. Dieser Parameter ist erforderlich und kann nicht auf NULL-festgelegt werden.

Rückgabewert

FltGetFileNameInformationUnsafe gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert wie einen der folgenden zurück:

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

Bemerkungen

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

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

Im Auslagerungs-E/A-Pfad.
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 Nachbereinigungs-, Pre-Close- oder Post-Close-Pfad (das Zieldateiobjekt hat den FO_CLEANUP_COMPLETE Flag festgelegt).
In einer Preoperation (PFLT_PRE_OPERATION_CALLBACK) oder postoperation (PFLT_POST_OPERATION_CALLBACK) Rückrufroutine 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 Postoperationsrückrufroutine für IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION.
Wenn alle APCs deaktiviert sind; das heißt, wenn KeAreAllApcsDisabled TRUE zurückgibt.

Für Windows Vista/Server 2008 und höher kann ein Minifilter, z. B. in seiner DriverEntry- Routine, noch keine Filterinstanz verwenden, NULL für den Parameter Instance verwenden. Auf diese Weise können DriverEntry Routinen auf Dateinameninformationen zugreifen. Mit Ausnahme dieses Falls ist ein NULL Wert für den Instanzparameter für die Systemverwendung reserviert.

Bei Erstellungs-, Hardlink- und Umbenennungsvorgängen kann das Tunneln von Dateinamen die endgültige Komponente in normalisierten Dateinameninformationen ungültig machen, die ein Minifiltertreiber in einer Voraboperationsrückrufroutine abruft. Wenn ein Minifiltertreiber normalisierte Dateinameninformationen in einer Preoperation-Rückrufroutine (PFLT_PRE_OPERATION_CALLBACK) abruft, indem eine Routine wie FltGetFileNameInformationUnsafeaufgerufen wird, muss er FltGetTunneledName aus seiner Postoperationsrückrufroutine (PFLT_POST_OPERATION_CALLBACK) aufrufen, um die richtigen Dateinameninformationen für die Datei abzurufen.

Weitere Informationen zu normalisierten Dateinameninformationen finden Sie unter FLT_FILE_NAME_INFORMATION.