FltSetStreamHandleContext-Funktion (fltkernel.h)

  • Artikel

Die FltSetStreamHandleContext-Routine legt einen Kontext für ein Streamhandle fest.

Syntax

NTSTATUS FLTAPI FltSetStreamHandleContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PFILE_OBJECT              FileObject,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Parameter

[in] Instance

Ein undurchsichtiger instance-Zeiger für den Minifiltertreiber instance dessen Kontext in die Liste der an das Streamhandle angefügten Kontexte eingefügt, daraus entfernt oder ersetzt werden soll.

[in] FileObject

Ein Zeiger auf ein Dateiobjekt für den Dateistream. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] Operation

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

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

[in] NewContext

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

[out, optional] OldContext

Ein Zeiger auf eine vom Aufrufer zugeordnete Variable, die die Adresse des vorhandenen Streamhandleskontexts für den Instance-Parameter 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

Die FltSetStreamHandleContext-Routine gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden Fehlercodes:

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 bereits ein Kontext an das Streamhandle angefügt ist.
STATUS_FLT_CONTEXT_ALREADY_LINKED Der Kontext, auf den NewContext 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 angegebene Instanz 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 Streamhandlekontext, oder für Operation wurde ein ungültiger Wert angegeben.
STATUS_NOT_SUPPORTED Es ist eine nicht unterstützte Situation aufgetreten, z. B. das Dateisystem unterstützt keine Streamkontexte für diesen Dateidatenstrom, oder der Aufrufer hat ein NULL FileObject bereitgestellt.

Hinweise

Weitere Informationen zu Kontexten finden Sie unter Informationen zu Minifilterkontexten.

Die FltSetStreamHandleContext-Routine fügt einen Kontext für einen Minifiltertreiber hinzu, entfernt oder ersetzt instance einem Streamhandle. Ein Minifiltertreiber kann einen Kontext pro Minifiltertreiber instance an das Streamhandle anfügen.

FltSetStreamHandleContext kann nicht für ein ungeöffnetes FileObject aufgerufen werden. Daher kann FltSetStreamHandleContext nicht aus einem vorab erstellten Rückruf für einen Stream aufgerufen werden, da der Stream zu diesem Zeitpunkt noch nicht geöffnet wurde. Ein Minifilter kann jedoch den Streamhandlekontext im Rückruf vor der Erstellung zuordnen und einrichten, ihn mithilfe des Vervollständigungskontextparameters an den Rückruf nach der Erstellung übergeben und den Streamhandlekontext für den Stream im Rückruf nach der Erstellung festlegen.

Verweisanzahl

Wenn FltSetStreamHandleContext erfolgreich ist:

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

Andernfalls, wenn FltSetStreamHandleContext fehlschlägt :

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

Unabhängig vom Erfolg:

  • Der Filter, der FltSetStreamHandleContext 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öher.
Zielplattform Universell
Header fltkernel.h (fltkernel.h einschließen)
Bibliothek Fltmgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Weitere Informationen

FltAllocateContext

FltDeleteContext

FltDeleteStreamHandleContext

FltGetStreamHandleContext

FltReleaseContext