FltSetInstanceContext-Funktion (fltkernel.h)

  • Artikel

FltSetInstanceContext legt einen Kontext für einen Minifiltertreiber instance fest.

Syntax

NTSTATUS FLTAPI FltSetInstanceContext(
  [in]  PFLT_INSTANCE             Instance,
  [in]  FLT_SET_CONTEXT_OPERATION Operation,
  [in]  PFLT_CONTEXT              NewContext,
  [out] PFLT_CONTEXT              *OldContext
);

Parameter

[in] Instance

Undurchsichtiger instance Zeiger für die instance.

[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 die instance festgelegt ist, auf die der Parameter Instance verweist, ersetzt FltSetInstanceContext diesen Kontext durch den in NewContext angegebenen Kontext. Andernfalls wird NewContext als Kontext für Instance festgelegt.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Wenn bereits ein Kontext für diese Instanz festgelegt ist, gibt FltSetInstanceContext STATUS_FLT_CONTEXT_ALREADY_DEFINED zurück und ersetzt nicht den vorhandenen Kontext oder erhöht die Verweisanzahl nicht. Wenn noch kein Kontext festgelegt ist, legt die Routine NewContext als Kontext für Instance fest und erhöht die Verweisanzahl.

[in] NewContext

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

[out] OldContext

Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Adresse des vorhandenen instance Kontexts empfängt, sofern bereits festgelegt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt hinweise.

Rückgabewert

FltSetInstanceContext gibt STATUS_SUCCESS oder einen geeigneten 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 den Parameter Operation angegeben wurde, gibt dieser Fehlercode an, dass bereits ein Kontext an den instance angefügt ist. An eine instance kann nur ein Kontext angefügt werden.
STATUS_FLT_CONTEXT_ALREADY_LINKED Der Kontext, auf den der NewContext-Parameter verweist, ist bereits mit einem -Objekt verknüpft. Anders ausgedrückt: Dieser Fehlercode gibt an, dass NewContext aufgrund eines erfolgreichen vorherigen Aufrufs einer FltSetXxx-Kontextroutine bereits verwendet wird.
STATUS_FLT_DELETING_OBJECT Die im Parameter Instance angegebene instance wird abgerissen. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER Es wurde ein ungültiger Parameter übergeben. Der NewContext-Parameter verweist beispielsweise nicht auf einen gültigen Dateikontext, oder für den Parameter 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 FltSetInstanceContext auf, um einen instance Kontext an einen aufrufereigenen Minifiltertreiber instance anzufügen oder um einen vorhandenen instance Kontext zu entfernen oder zu ersetzen. Ein Minifiltertreiber kann nur einen Kontext an einen instance anfügen.

Verweisanzahl

Wenn FltSetInstanceContext erfolgreich ist:

  • Die Verweisanzahl für NewContext wird erhöht. Wenn der Kontext, auf den NewContext verweist, nicht mehr benötigt wird, muss der Minifilter FltReleaseContext aufrufen, um seine Verweisanzahl zu verringern.

Andernfalls, wenn FltSetInstanceContext fehlschlägt:

  • Die Verweisanzahl für NewContext bleibt unverändert.
  • Wenn OldContext nicht NULL ist und nicht auf NULL_CONTEXT zeigt, ist OldContext ein Zeiger, auf den verwiesen wird, auf den kontext, der derzeit dem instance zugeordnet ist. Der Filter, der FltSetInstanceContext aufruft , muss schließlich FltReleaseContext auch für OldContext aufrufen, wenn der Kontextzeiger nicht mehr benötigt wird.

Unabhängig vom Erfolg:

  • Der Filter, der FltSetInstanceContext aufruft , muss FltReleaseContext aufrufen, um die Verweisanzahl für das NewContext-Objekt zu verringern, das von FltAllocateContext erhöht wurde.

Weitere Informationen finden Sie unter Verweisen auf Kontexte.

Andere Kontextvorgänge

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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar und unterstützt in Microsoft Windows 2000 Update Rollup 1 für SP4, Windows XP SP2, Windows Server 2003 SP1 und höheren Versionen des Betriebssystems.
Zielplattform Universell
Header fltkernel.h (fltkernel.h einschließen)
Bibliothek FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Weitere Informationen

FltAllocateContext

FltDeleteContext

FltDeleteInstanceContext

FltGetInstanceContext

FltReleaseContext