FltSetVolumeContext-Funktion (fltkernel.h)

Artikel
08/07/2023

FltSetVolumeContext legt einen Kontext für ein Volume fest.

Syntax

NTSTATUS FLTAPI FltSetVolumeContext(
  [in]            PFLT_VOLUME               Volume,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Parameter

[in] Volume

Undurchsichtiger Volumezeiger für das Volume.

[in] Operation

Flag, das Details des auszuführenden Vorgangs angibt. Dieser Parameter muss einer der folgenden Sein:

Flag	Bedeutung
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Wenn bereits ein Kontext für Volume festgelegt ist, ersetzt FltSetVolumeContext ihn durch NewContext>. Andernfalls wird NewContext in die Liste der Kontexte für das Volume eingefügt.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Wenn bereits ein Kontext für dieses Volume festgelegt ist, gibt FltSetVolumeContext STATUS_FLT_CONTEXT_ALREADY_DEFINED zurück und ersetzt nicht den vorhandenen Kontext oder erhöht die Verweisanzahl. Wenn noch kein Kontext festgelegt wurde, fügt die Routine NewContext in die Liste der Kontexte für das Volume ein und erhöht die Verweisanzahl.

[in] NewContext

Zeiger auf den neuen Kontext, der für das Volume festgelegt werden soll. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[out, optional] OldContext

Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Adresse des vorhandenen Volumekontexts für Volume empfängt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen zu diesem Parameter finden Sie im abschnitt Hinweise.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Wenn FLT_SET_CONTEXT_KEEP_IF_EXISTS für Operation angegeben wurde, gibt dieser Fehlercode an, dass dem Volume bereits ein Kontext angefügt ist.
STATUS_FLT_CONTEXT_ALREADY_LINKED	Der Kontext, auf den der NewContext-Parameter verweist, ist bereits mit einem Objekt verknüpft. Mit anderen Worten, dieser Fehlercode gibt an, dass NewContext aufgrund eines erfolgreichen vorherigen Aufrufs einer FltSetXxxContext-Routine bereits verwendet wird.
STATUS_FLT_DELETING_OBJECT	Das angegebene Volume wird abgerissen. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter übergeben. Beispielsweise verweist der NewContext-Parameter nicht auf einen gültigen Volumekontext, oder für Operation wurde ein ungültiger Wert angegeben. Dies ist ein Fehlercode.

Hinweise

Weitere Informationen zu Kontexten finden Sie unter Informationen zu Minifilterkontexten.

Ein Minifiltertreiber ruft FltSetVolumeContext auf, um einen Kontext an ein Volume anzufügen oder einen vorhandenen Volumekontext zu entfernen oder zu ersetzen. Ein Minifiltertreiber kann nur einen Kontext an ein Volume anfügen.

Verweisanzahl

Wenn FltSetVolumeContext erfolgreich ist:

Die Verweisanzahl für NewContext wird erhöht. Wenn NewContext nicht mehr benötigt wird, muss der Minifilter FltReleaseContext aufrufen, um die Verweisanzahl zu verringern.

Andernfalls, wenn FltSetVolumeContext fehlschlägt :

Die Verweisanzahl für NewContext bleibt unverändert.
Wenn OldContext nicht NULL ist und nicht auf NULL_CONTEXT verweist, ist OldContext ein Verweiszeiger auf den Kontext, der derzeit dem Volume zugeordnet ist. Der Filter, der FltSetVolumeContext aufruft , muss auch FltReleaseContext für OldContext aufrufen, wenn der Kontextzeiger nicht mehr benötigt wird.

Unabhängig vom Erfolg:

Der Filter, der FltSetVolumeContext aufruft , muss FltReleaseContext aufrufen, um die Verweisanzahl für das NewContext-Objekt zu verringern, das von FltAllocateContext inkrementiert wurde.

Weitere Informationen finden Sie unter Verweisen auf Kontexte.

Andere Kontextvorgänge

Weitere Informationen finden Sie unter Festlegen von Kontexten und Freigeben von Kontexten:

Um einen neuen Kontext zuzuordnen, rufen Sie FltAllocateContext auf.
Um einen Volumekontext abzurufen, rufen Sie FltGetVolumeContext auf.
Um einen Volumekontext zu löschen, rufen Sie FltDeleteVolumeContext oder FltDeleteContext auf.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar und unterstützt in Microsoft Windows 2000 Updaterollup 1 für SP4, Windows XP SP2, Windows Server 2003 SP1 und höher.
Zielplattform	Universell
Header	fltkernel.h (include Fltkernel.h)
Bibliothek	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL