FltAllocateContext-Funktion (fltkernel.h)

Artikel
03/16/2024

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 darf nicht NULL sein.

[in] ContextType

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

Wert	Bedeutung
FLT_VOLUME_CONTEXT (0x0001)	Ordnen Sie einen Volumekontext zu.
FLT_INSTANCE_CONTEXT (0x0002)	Ordnen Sie einen instance Kontext zu.
FLT_FILE_CONTEXT (0x0004)	Ordnen Sie einen Dateikontext zu.
FLT_STREAM_CONTEXT (0x0008)	Ordnen Sie einen Streamkontext zu.
FLT_STREAMHANDLE_CONTEXT (0x0010)	Ordnen Sie einen Streamhandlekontext zu.
FLT_TRANSACTION_CONTEXT (0x0020)	Ordnen Sie einen Transaktionskontext zu.
FLT_SECTION_CONTEXT (0x0040)	Ordnen Sie einen Abschnittskontext zu. Verfügbar ab Windows 8.

[in] ContextSize

Die Größe des durch den Minifiltertreiber definierten Teils des Kontexts in Bytes. Muss größer als 0 und kleiner als oder gleich MAXUSHORT sein; für Kontexte mit fester Größe muss kleiner oder gleich der größe sein, die in der FLT_CONTEXT_REGISTRATION-Struktur angegeben ist. Ein Minifilter verwendet diesen Teil des Kontexts, um kontextspezifische Informationen für sich selbst zu verwalten. FltMgr behandelt diesen Teil der Kontextstruktur als undurchsichtig. Dieser Parameter ist erforderlich und darf nicht 0 sein.

[in] PoolType

Der Typ des zuzuweisenden Pools. Dieser Parameter ist erforderlich und muss einer der folgenden sein. Eine ausführliche Beschreibung der einzelnen Typen finden Sie unter POOL_TYPE . Weitere Informationen finden Sie unter Hinweise.

Wert	Bedeutung
NonPagedPool	Nicht auslässiger Systemspeicher. PoolType muss NonPagedPool sein, wenn ContextType FLT_VOLUME_CONTEXT ist.
PagedPool	Auslagerungsfähiger Systemspeicher.
NonPagedPoolNx	Nx-Pool (No-Execute) ohne Auslagerung.

[out] ReturnedContext

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

Rückgabewert

FltAllocateContext gibt STATUS_SUCCESS oder einen entsprechenden 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 größe , die in der FLT_CONTEXT_REGISTRATION-Struktur für den angegebenen ContextType angegeben ist.
STATUS_FLT_DELETING_OBJECT	Der minifilter-Treiber, der im Filter-Parameter angegeben ist, wird abgerissen. Dies ist ein Fehlercode.
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext ist ein Poolzuordnungsfehler aufgetreten. 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 ContextSize-Parameter wurde ein ungültiger Wert angegeben. Dies ist ein Fehlercode.
STATUS_NOT_SUPPORTED	Das Dateisystem unterstützt keine Streamkontexte. Dies ist ein Fehlercode.

Hinweise

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 wie folgt ab, ob der Speicher, auf den ReturnedContext verweist, auf null gesetzt ist:

Der Arbeitsspeicher wird für Kontexte variabler Größe garantiert auf Null gesetzt.
Der Arbeitsspeicherinhalt 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 Suchlistenverhaltens auf Null gesetzt wird. Das heißt, ein von der Lookaside-Liste zurückgegebener Eintrag wird möglicherweise nicht auf Null gesetzt, wenn es sich um Arbeitsspeicher handelt, der zuvor für die Suchliste freigegeben wurde, im Gegensatz zu einer neuen Zuordnung.

Vor Windows 11 wird der Inhalt des zurückgegebenen Kontexts nicht auf null gesetzt.

Das Festlegen von PoolType auf einen ungültigen Wert kann zu unerwartetem Verhalten führen, z. B. dazu, dass Lookaside-Listen umgangen werden, was zum Verlust der Leistungsvorteile von Suchlisten führt. Für Kontexte mit einer ContextAllocateCallback-Rückruffunktion ist das Verhalten aufgrund eines ungültigen PoolType-Typs 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.

Inhaltstyp	Set-Context Routine
FLT_FILE_CONTEXT	FltSetFileContext (ab 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 (ab Windows Vista)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

Wenn ein Minifiltertreiber FltRegisterFilter über seine DriverEntry-Routine aufruft, muss er jeden von ihm verwendeten Kontexttyp registrieren. Weitere Informationen finden Sie im Referenzeintrag für die FLT_CONTEXT_REGISTRATION-Struktur und unter Registrieren von Kontexttypen.

FltAllocateContext initialisiert nicht den Inhalt des Teils der Kontextstruktur, der für den Minifiltertreiber spezifisch ist.

Um den Kontext für ein Objekt abzurufen, rufen Sie FltGetContexts oder die entsprechende get-context-Routine aus der folgenden Tabelle auf.

Inhaltstyp	Get-Context Routine
FLT_FILE_CONTEXT	FltGetFileContext (ab 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 (ab Windows Vista )
FLT_VOLUME_CONTEXT	FltGetVolumeContext

Kontexte werden gezählt, und bei einer erfolgreichen Rückgabe von FltAllocateContext wurde der Kontext, auf den returnedContext verweist, mit einer Verweisanzahl von 1 initialisiert. Ein Kontext wird automatisch freigegeben, wenn seine Verweisanzahl 0 (null) erreicht. Um die Verweisanzahl in einem Kontext zu erhöhen, rufen Sie FltReferenceContext auf.

Um die Verweisanzahl für einen Kontext zu verringern, rufen Sie FltReleaseContext auf.

Da Kontexte referenziert sind, 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.

Inhaltstyp	Delete-Context Routine
FLT_FILE_CONTEXT	FltDeleteFileContext (ab 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 (ab Windows Vista)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext