FsRtlRemovePerStreamContext-Funktion (ntifs.h)

Artikel
12/21/2024

FsRtlRemovePerStreamContext entfernt eine Kontextstruktur pro Datenstrom aus der Liste der datenstrombezogenen Kontexte, die einem Dateidatenstrom 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

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

[in, optional] OwnerId

Wird verwendet, um Kontextinformationen als Zugehörigkeit zu einem bestimmten Filtertreiber zu identifizieren.

[in, optional] InstanceId

Wird verwendet, um nach einer bestimmten Instanz eines Pro-Stream-Kontexts zu suchen. Falls nicht angegeben, wird ein Kontext, der dem Filtertreiber gehört, entfernt und zurückgegeben.

Wenn weder die OwnerId noch die InstanceId- angegeben wird, werden alle zugeordneten Datenstromkontexte entfernt und zurückgegeben.

Rückgabewert

FsRtlRemovePerStreamContext gibt einen Zeiger auf den Pro-Stream-Kontext zurück, der entfernt wird. Wenn keine Übereinstimmung gefunden wird oder das Dateisystem Filterkontexte nicht unterstützt, gibt FsRtlRemovePerStreamContext NULL zurück.

Bemerkungen

Ein Dateisystemfiltertreiber ruft FsRtlRemovePerStreamContext- auf, um seine eigene Kontextstruktur pro Stream aus der Liste der datenstrombezogenen Kontexte zu entfernen, die einem Dateidatenstrom zugeordnet sind.

FsRtlRemovePerStreamContext entfernt nur die erste übereinstimmende Kontextstruktur pro Stream, die gefunden wird. Wenn zusätzliche Übereinstimmungen pro Datenstromkontext vorhanden sind, muss der Filtertreiber FsRtlRemovePerStreamContext- so oft aufrufen, wie erforderlich, 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 Datenstrom noch geöffnet ist. Beispielsweise kann ein Filtertreiber 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 Dateidatenstrom geschlossen wird, ist das Dateisystem dafür verantwortlich, sicherzustellen, dass alle Datenstromkontexte, die diesem Datenstrom zugeordnet sind, entfernt und freigegeben werden. Dazu muss das Dateisystem FsRtlTeardownPerStreamContexts für den Dateisteuerungsblock (FCB) oder ein anderes Streamkontextobjekt für den Dateidatenstrom aufrufen. FsRtlTeardownPerStreamContexts- führt die FilterContexts-Liste durch, wobei jeder Eintrag entfernt und die FreeCallback-Routine aufgerufen wird.

Daher sollte ein Dateisystemfiltertreiber nicht FsRtlRemovePerStreamContext- innerhalb einer IRP_MJ_CLOSE- oder IRP_MJ_PNP Dispatch-Routine aufrufen. Ein solcher Aufruf wäre nicht nur unnötig, sondern kann auch den Aufruf des Dateisystems an FsRtlTeardownPerStreamContextsbeeinträchtigen.

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

Um eine Kontextstruktur pro Datenstrom zu initialisieren, verwenden Sie das FsRtlInitPerStreamContext Makro.

Rufen Sie FsRtlInsertPerStreamContextauf, um eine initialisierte Kontextstruktur pro Datenstrom zuzuordnen.

Rufen Sie FsRtlLookupPerStreamContextauf, um eine Kontextstruktur pro Datenstrom abzurufen, die einem Dateidatenstrom zugeordnet ist.

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

Weitere Informationen finden Sie unter Tracking Per-Stream Context in einem Legacy File System Filter Driver.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 SP4 Update Rollup; Windows XP
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	<= APC_LEVEL