FltAllocateContext-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltAllocateContext Routine weist eine Kontextstruktur für einen angegebenen Kontexttyp zu.

Syntax

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

Parameter

[in] Filter

Undurchsichtiger Filterzeiger für den Aufrufer. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

[in] ContextType

Ein FLT_CONTEXT_TYPE Wert, der den Typ des zuzuordnenden Kontexts angibt. ContextType- kann eine der folgenden Sein:

Wert	Bedeutung
FLT_VOLUME_CONTEXT (0x0001)	Weisen Sie einen Volumekontext zu.
FLT_INSTANCE_CONTEXT (0x0002)	Weisen Sie einen Instanzkontext zu.
FLT_FILE_CONTEXT (0x0004)	Weisen Sie einen Dateikontext zu.
FLT_STREAM_CONTEXT (0x0008)	Ordnen Sie einen Datenstromkontext zu.
FLT_STREAMHANDLE_CONTEXT (0x0010)	Ordnen Sie einen Datenstromhandlekontext zu.
FLT_TRANSACTION_CONTEXT (0x0020)	Zuordnen eines Transaktionskontexts.
FLT_SECTION_CONTEXT (0x0040)	Weisen Sie einen Abschnittskontext zu. Verfügbar ab Windows 8.

[in] ContextSize

Die Größe des vom Minifiltertreiber definierten Kontexts in Bytes. Muss größer als Null und kleiner als oder gleich MAXUSHORT-sein; für Kontexte mit fester Größe muss kleiner oder gleich der in der FLT_CONTEXT_REGISTRATION-Struktur angegebenen Size sein. Ein Minifilter verwendet diesen Teil des Kontexts, um kontextspezifische Informationen für sich selbst beizubehalten. FltMgr behandelt diesen Teil der Kontextstruktur als undurchsichtig. Dieser Parameter ist erforderlich und darf nicht null sein.

[in] PoolType

Der Typ des pools, der zugewiesen werden soll. Dieser Parameter ist erforderlich und muss eine der folgenden Sein. Eine detaillierte Beschreibung der einzelnen Typen finden Sie unter POOL_TYPE. Weitere Informationen finden Sie in den Hinweisen.

Wert	Bedeutung
NonPagedPool-	Nicht ausserbbarer Systemspeicher. PoolType- muss NonPagedPool sein, wenn ContextType- FLT_VOLUME_CONTEXT ist.
PagedPool-	Auslagerungsfähiger Systemspeicher.
NonPagedPoolNx-	No-execute (NX)-Nichtseitenpool.

[out] ReturnedContext

Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Adresse des neu zugewiesenen Kontexts empfängt. Der Aufrufer ist für das Aufrufen FltReleaseContext verantwortlich, um diesen Kontext freizugeben, wenn er nicht mehr benötigt wird.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	Die Zuordnungsinformationen für den Kontext des angegebenen Typs wurden zum Zeitpunkt der Filterregistrierung nicht bereitgestellt. ODER bei Kontexten mit fester Größe ist die angeforderte ContextSize- größer als die in der FLT_CONTEXT_REGISTRATION Struktur für die angegebene ContextType-angegebene Size .
STATUS_FLT_DELETING_OBJECT	Der im Filter Parameter angegebene Minifiltertreiber wird heruntergerissen. Dies ist ein Fehlercode.
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext ein Poolzuordnungsfehler aufgetreten ist. Dies ist ein Fehlercode.
STATUS_INVALID_BUFFER_SIZE	ContextSize- darf nicht größer als MAXUSHORT-sein. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Für den ContextType- oder den ContextSize-Parameter wurde ein ungültiger Wert angegeben. Dies ist ein Fehlercode.
STATUS_NOT_SUPPORTED	Das Dateisystem unterstützt keine Kontexte pro Datenstrom. Dies ist ein Fehlercode.

Bemerkungen

Weitere Informationen zu Kontexten finden Sie unter Informationen zu Minifilterkontexten.

FltAllocateContext weist einen Kontext des angegebenen Typs aus dem angegebenen Pool zu. Ab Windows 11 hängt davon ab, ob der Speicher, auf den ReturnedContext verweist, wie folgt ab:

Der Arbeitsspeicher wird für Kontexte mit variabler Größe garantiert nulliert.
Der Speicherinhalt wird für Kontexte mit fester Größe definiert, die von einer vom Aufrufer bereitgestellten Rückruffunktion zugewiesen werden.
Andernfalls kann nicht davon ausgegangen werden, dass der Arbeitsspeicher für Kontexte mit fester Größe aufgrund des Lookaside-Listenverhaltens null ist. Das heißt, ein aus der Lookaside-Liste zurückgegebener Eintrag ist möglicherweise nicht null, wenn es sich um Speicher handelt, der zuvor in die Lookaside-Liste freigegeben wurde, im Gegensatz zu einer neuen Zuordnung.

Vor Windows 11 werden die Inhalte des zurückgegebenen Kontexts nicht nulliert.

Das Festlegen PoolType- auf einen ungültigen Wert kann zu unerwartetem Verhalten führen, z. B. dazu, dass Lookaside-Listen umgangen werden, was zu einem Verlust der Leistungsvorteile von Lookaside-Listen führt. Bei Kontexten mit einer ContextAllocateCallback- Rückruffunktion ist das Verhalten aufgrund eines ungültigen PoolType- implementierungsabhängig.

Nachdem der Kontext zugewiesen wurde, kann er für ein Objekt festgelegt werden, indem der ReturnedContext Zeiger an die entsprechende Setkontextroutine aus der folgenden Tabelle übergeben wird.

Kontexttyp	Set-Context Routine
FLT_FILE_CONTEXT	FltSetFileContext- (beginnend mit Windows Vista)
FLT_INSTANCE_CONTEXT	FltSetInstanceContext-
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan (ab Windows 8)
FLT_STREAM_CONTEXT	FltSetStreamContext-
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext-
FLT_TRANSACTION_CONTEXT	FltSetTransactionContext- (beginnend mit Windows Vista)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

Wenn ein Minifiltertreiber FltRegisterFilter aus der DriverEntry-Routine aufruft, muss er jeden kontexttyp registrieren, den er verwendet. Weitere Informationen finden Sie im Referenzeintrag für die FLT_CONTEXT_REGISTRATION-Struktur und Registrieren von Kontexttypen.

FltAllocateContext initialisiert nicht den Inhalt des Für den Minifiltertreiber spezifischen Teils der Kontextstruktur.

Rufen Sie FltGetContexts oder die entsprechende Get-Context-Routine aus der folgenden Tabelle auf, um den Kontext für ein Objekt abzurufen.

Kontexttyp	Get-Context Routine
FLT_FILE_CONTEXT	FltGetFileContext- (beginnend mit Windows Vista)
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext- (ab Windows 8)
FLT_STREAM_CONTEXT	FltGetStreamContext-
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext-
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext (beginnend mit Windows Vista)
FLT_VOLUME_CONTEXT	FltGetVolumeContext

Kontexte werden referenziert, und bei einer erfolgreichen Rückgabe von FltAllocateContext-wurde der Kontext, auf den ReturnedContext verweist, initialisiert, um eine Verweisanzahl von 1 zu haben. Ein Kontext wird automatisch freigegeben, wenn seine Bezugsanzahl null erreicht. Rufen Sie FltReferenceContextauf, um die Verweisanzahl in einem Kontext zu erhöhen.

Rufen Sie FltReleaseContext-auf, um die Verweisanzahl für einen Kontext zu erhöhen.

Da Kontexte referenziert werden, ist es in der Regel nicht erforderlich, sie zu löschen. Um einen Kontext explizit zu löschen, rufen Sie FltDeleteContext oder die entsprechende Delete-Context-Routine aus der folgenden Tabelle auf.

Kontexttyp	Delete-Context Routine
FLT_FILE_CONTEXT	FltDeleteFileContext (beginnend mit Windows Vista)
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan (ab Windows 8)
FLT_STREAM_CONTEXT	FltDeleteStreamContext-
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext-
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext (beginnend mit Windows Vista)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext