FsRtlRemovePerStreamContext-Funktion (ntifs.h)

Artikel
10/04/2023

FsRtlRemovePerStreamContext entfernt eine Pro-Stream-Kontextstruktur aus der Liste der streambasierten Kontexte, die einem Dateistream zugeordnet sind.

Syntax

PFSRTL_PER_STREAM_CONTEXT FsRtlRemovePerStreamContext(
  [in]           PFSRTL_ADVANCED_FCB_HEADER StreamContext,
  [in, optional] PVOID                      OwnerId,
  [in, optional] PVOID                      InstanceId
);

Parameter

[in] StreamContext

Zeiger auf die FSRTL_ADVANCED_FCB_HEADER-Struktur für den Dateistream. Um diesen Zeiger aus einem Dateiobjekt abzurufen, verwenden Sie das Makro FsRtlGetPerStreamContextPointer .

[in, optional] OwnerId

Wird verwendet, um Kontextinformationen zu identifizieren, die zu einem bestimmten Filtertreiber gehören.

[in, optional] InstanceId

Wird verwendet, um nach einem bestimmten instance eines Streamkontexts zu suchen. Falls nicht angegeben, wird einer der Kontexte, die dem Filtertreiber gehören, entfernt und zurückgegeben.

Wenn weder die OwnerId noch die InstanceId angegeben wird, wird jeder zugeordnete Kontext pro Stream entfernt und zurückgegeben.

Rückgabewert

FsRtlRemovePerStreamContext gibt einen Zeiger auf den pro Stream entfernten Kontext zurück. Wenn keine Übereinstimmung gefunden wurde oder das Dateisystem keine Filterkontexte unterstützt, gibt FsRtlRemovePerStreamContext NULL zurück.

Hinweise

Ein Dateisystemfiltertreiber ruft FsRtlRemovePerStreamContext auf, um seine eigene Pro-Stream-Kontextstruktur aus der Liste der streambasierten Kontexte zu entfernen, die einem Dateistream zugeordnet sind.

FsRtlRemovePerStreamContext entfernt nur die erste übereinstimmende Kontextstruktur pro Stream, die gefunden wurde. Wenn zusätzliche übereinstimmende Kontexte pro Stream vorhanden sind, muss der Filtertreiber FsRtlRemovePerStreamContext so oft wie erforderlich aufrufen, um sie alle zu entfernen.

Diese Routine sollte nur verwendet werden, wenn ein Filtertreiber die Kontextinformationen verwerfen muss, die er einem Dateidatenstrom zugeordnet hat, während der Stream noch geöffnet ist. Ein Filtertreiber kann beispielsweise FsRtlRemovePerStreamContext in den folgenden Fällen aufrufen:

Wenn sie eine Anforderung von einer Benutzermodusanwendung empfängt, um die Protokollierung von E/A-Anforderungen auf einem bestimmten Volume zu beenden.
Wenn erkannt wird, dass eine Datei oder ein Verzeichnis umbenannt wurde.

Wenn ein Dateistream geschlossen wird, ist das Dateisystem dafür verantwortlich, sicherzustellen, dass alle diesem Stream zugeordneten Kontexte pro Stream entfernt und freigegeben werden. Dazu muss das Dateisystem FsRtlTeardownPerStreamContexts für den Dateisteuerungsblock (FCB) oder ein anderes Streamkontextobjekt für den Dateistream aufrufen. FsRtlTeardownPerStreamContexts führt die FilterContexts-Liste durch, entfernt jeden Eintrag und ruft die FreeCallback-Routine auf.

Daher sollte ein Dateisystemfiltertreiber FsRtlRemovePerStreamContext nicht innerhalb einer IRP_MJ_CLOSE oder IRP_MJ_PNP Dispatchroutine aufrufen. Ein solcher Aufruf wäre nicht nur unnötig, sondern könnte auch den Aufruf von FsRtlTeardownPerStreamContexts des Dateisystems beeinträchtigen.

Ein Dateisystemfiltertreiber sollte FsRtlRemovePerStreamContext nicht innerhalb der FreeCallback-Routine einer Pro-Stream-Kontextstruktur aufrufen. Dies liegt daran, dass das zugrunde liegende Dateisystem die FreeCallback-Routine aufruft, nachdem die Kontextstruktur bereits aus der FilterContexts-Liste entfernt wurde.

Verwenden Sie zum Initialisieren einer Kontextstruktur pro Stream das Makro FsRtlInitPerStreamContext .

Um eine initialisierte Pro-Stream-Kontextstruktur einem Dateistream zuzuordnen, rufen Sie FsRtlInsertPerStreamContext auf.

Um eine streambasierte Kontextstruktur abzurufen, die einem Dateistream zugeordnet ist, rufen Sie FsRtlLookupPerStreamContext auf.

FsRtlRemovePerStreamContext kann nur auf Dateisystemen verwendet werden, die Filterkontexte unterstützen.

Weitere Informationen finden Sie unter Nachverfolgen Per-Stream Kontexts in einem Legacy-Dateisystemfiltertreiber.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 SP4-Updaterollup; Windows XP
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL