FltSetFileContext-Funktion (fltkernel.h)
Die FltSetFileContext-Routine legt einen Kontext für eine Datei fest.
Syntax
NTSTATUS FLTAPI FltSetFileContext(
[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 Zeiger auf einen Minifiltertreiber instance für den Aufrufer. Dieser Parameter ist erforderlich und darf nicht NULL sein.
[in] FileObject
Zeiger auf ein Dateiobjekt für die Datei. Dieser Parameter ist erforderlich und darf nicht NULL sein.
[in] Operation
Ein Flag, das den Typ des Vorgangs angibt, den FltSetFileContext ausführen soll. Dieser Parameter muss eines der folgenden Flags sein:
| Flag | Bedeutung |
|---|---|
| FLT_SET_CONTEXT_REPLACE_IF_EXISTS | Wenn bereits ein Kontext für die Datei festgelegt ist, auf die der FileObject-Parameter verweist, ersetzt FltSetFileContext diesen Kontext durch den in NewContext angegebenen Kontext. Andernfalls wird NewContext in die Liste der Kontexte für die Datei eingefügt. |
| FLT_SET_CONTEXT_KEEP_IF_EXISTS | Wenn bereits ein Kontext für die Datei festgelegt ist, auf die FileObject verweist, gibt FltSetFileContext 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 den in NewContext angegebenen Kontext in die Liste der Kontexte für die Datei ein und erhöht die Verweisanzahl. |
[in] NewContext
Ein Zeiger auf den neuen Kontext, der für die Datei 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 Dateikontexts für die instance empfängt, auf die der Instance-Parameter verweist, sofern bereits eine festgelegt ist. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt hinweise.
Rückgabewert
Die FltSetFileContext-Routine 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 die Datei angefügt ist. |
| 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. |
| STATUS_NOT_SUPPORTED | Dateikontexte werden für diese Datei nicht unterstützt. Dies ist ein Fehlercode. |
Hinweise
Weitere Informationen zu Kontexten finden Sie unter Informationen zu Minifilterkontexten.
Ein Minifiltertreiber ruft FltSetFileContext auf, um einen eigenen Dateikontext für eine Datei festzulegen oder zu ersetzen. Ein Minifiltertreiber kann nur einen Kontext pro Minifiltertreiber instance an die Datei anfügen.
FltSetFileContext kann nicht für ein ungeöffnetes FileObject aufgerufen werden. Daher kann FltSetFileContext nicht über einen Voraberstellungsrückruf für eine Datei aufgerufen werden, da die Datei zu diesem Zeitpunkt noch nicht geöffnet wurde. Ein Minifiltertreiber kann jedoch den Dateikontext im Rückruf vor der Erstellung zuordnen und einrichten, ihn mithilfe des Vervollständigungskontextparameters an den Rückruf nach der Erstellung übergeben und den Dateikontext für die Datei festlegen, die dem Datenstrom im Rückruf nach der Erstellung entspricht.
Verweisanzahl
Wenn FltSetFileContext 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 FltSetFileContext 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 der Datei zugeordnet ist. Der Filter, der FltSetFileContext 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 FltSetFileContext 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:
Um einen neuen Kontext zuzuordnen, rufen Sie FltAllocateContext auf.
Um einen Dateikontext abzurufen, rufen Sie FltGetFileContext auf.
Um einen Dateikontext zu löschen, rufen Sie FltDeleteFileContext oder FltDeleteContext auf.
Um zu bestimmen, ob Dateikontexte für eine bestimmte Datei unterstützt werden, rufen Sie FltSupportsFileContexts oder FltSupportsFileContextsEx auf.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar und unterstützt ab Windows Vista. |
| Zielplattform | Universell |
| Header | fltkernel.h (fltkernel.h einschließen) |
| Bibliothek | Fltmgr.lib |
| DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |