FltSetStreamContext-Funktion (fltkernel.h)

  • Artikel

Die FltSetStreamContext-Routine legt einen Kontext für einen Dateistream fest.

Syntax

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

Parameter

[in] Instance

Ein undurchsichtiger instance Zeiger für den Minifiltertreiber instance dessen Kontext in die Liste der kontextgebundenen Kontexte eingefügt, entfernt oder ersetzt werden soll.

[in] FileObject

Ein Zeiger auf ein Dateiobjekt für den Dateistream.

[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 ein Kontext bereits für Instance festgelegt ist, ersetzt FltSetStreamContext ihn durch den in NewContext angegebenen Kontext. Andernfalls wird NewContext in die Liste der Kontexte für den Dateistream eingefügt.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Wenn bereits ein Kontext für diese Instanz festgelegt ist, gibt FltSetStreamContext 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 den Dateidatenstrom ein und erhöht die Verweisanzahl.

[in] NewContext

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

[out] OldContext

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Adresse des vorhandenen Streamkontexts 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 abschnitt Hinweise.

Rückgabewert

Die FltSetStreamContext-Routine 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 Dateidatenstrom bereits ein Streamkontext 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 Die im Parameter Instance angegebene instance wird abgerissen. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER Es wurde ein ungültiger Parameter übergeben. Beispielsweise zeigt der NewContext-Parameter nicht auf einen gültigen Streamkontext, oder für den Operation-Parameter wurde ein ungültiger Wert angegeben. Dies ist ein Fehlercode.
STATUS_NOT_SUPPORTED Das Dateisystem unterstützt keine streambasierten Kontexte für diesen Dateistream. Dies ist ein Fehlercode.

Hinweise

Weitere Informationen zu Kontexten finden Sie unter Informationen zu Minifilterkontexten.

Ein Minifiltertreiber ruft FltSetStreamContext auf, um einen Streamkontext an einen Dateidatenstrom anzufügen oder einen vorhandenen Streamkontext zu entfernen oder zu ersetzen. Ein Minifiltertreiber kann einen Kontext pro Minifiltertreiber instance an den Dateidatenstrom anfügen.

FltSetStreamContext kann nicht für ein ungeöffnetes FileObject aufgerufen werden. Daher kann er nicht über einen Voraberstellungsrückruf für einen Stream aufgerufen werden, da der Stream zu diesem Zeitpunkt noch nicht geöffnet wurde. Ein Minifiltertreiber kann jedoch den Streamkontext im Rückruf vor der Erstellung zuordnen und einrichten, ihn mithilfe des Vervollständigungskontextparameters an den Rückruf nach der Erstellung übergeben und den Streamkontext für den Stream im Rückruf nach der Erstellung festlegen.

Verweisanzahl

Wenn FltSetStreamContext 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 FltSetStreamContext 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 Stream zugeordnet ist. Der Filter, der FltSetStreamContext aufruft , muss FltReleaseContext auch für OldContext aufrufen, wenn der Kontextzeiger nicht mehr benötigt wird.

Unabhängig vom Erfolg:

  • Der Filter, der FltSetStreamContext 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:

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

Weitere Informationen

FltAllocateContext

FltDeleteContext

FltDeleteStreamContext

FltGetStreamContext

FltReleaseContext