FltAllocateExtraCreateParameter-Funktion (fltkernel.h)

Artikel
02/06/2025

Die FltAllocateExtraCreateParameter Routine weist den ausgelagerten Speicherpool für eine benutzerdefinierte zusätzliche Create-Parameter-Kontextstruktur (ECP) zu und generiert einen Zeiger auf diese Struktur.

Syntax

NTSTATUS FLTAPI FltAllocateExtraCreateParameter(
  [in]           PFLT_FILTER                                    Filter,
  [in]           LPCGUID                                        EcpType,
  [in]           ULONG                                          SizeOfContext,
  [in]           FSRTL_ALLOCATE_ECP_FLAGS                       Flags,
  [in, optional] PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  [in]           ULONG                                          PoolTag,
  [out]          PVOID                                          *EcpContext
);

Parameter

[in] Filter

Undurchsichtiger Filterzeiger für den Minifiltertreiber. Dieser Zeiger identifiziert den Minifiltertreiber eindeutig und bleibt konstant, solange der Minifiltertreiber geladen wird.

[in] EcpType

Zeiger auf eine benutzerdefinierte GUID, die den Typ der ECP-Kontextstruktur angibt. Weitere Informationen finden Sie unter Verwenden von GUIDs in Treibern.

[in] SizeOfContext

Die Größe der benutzerdefinierten Kontextstruktur in Bytes.

[in] Flags

Definiert Poolzuordnungsoptionen. Im Folgenden wird beschrieben, wie der Pool zugewiesen wird, wenn mindestens eine der aufgelisteten Flagwerte mit dem Flags Parameter kombiniert wird, indem ein bitweiser OR-Vorgang verwendet wird:

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL – Nicht ausgelagerter Pool wird zugewiesen. Wenn dieser Flagwert nicht verwendet wird, wird der ausgelagerte Pool zugewiesen.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA – Alle von dieser Routine zugewiesenen Pools werden mit dem Speicherkontingent des aktuellen Prozesses belastet.

Wenn mehr als ein Flag verwendet wird, treten alle Effekte auf, die den verwendeten Flagwerten zugeordnet sind.

[in, optional] CleanupCallback

Optionaler Zeiger auf eine minifilterdefinierte Bereinigungsrückrufroutine vom Typ PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. Die Bereinigungsrückrufroutine wird aufgerufen, wenn die ECP-Struktur (erstellt durch die FltAllocateExtraCreateParameter Routine) gelöscht wird. Legen Sie diesen Parameter auf NULL- fest, wenn keine Bereinigungsrückrufroutine anwendbar ist.

[in] PoolTag

Gibt das Pooltag für den zugewiesenen Arbeitsspeicher an. Weitere Informationen finden Sie im parameter Tag von ExAllocatePoolWithTag.

[out] EcpContext

Empfängt einen Zeiger auf die zugeordnete ECP-Kontextstruktur. Wenn die Routine nicht genügend Pool zuordnen konnte, wird *EcpContext-NULL- und die Routine gibt statuscode STATUS_INSUFFICIENT_RESOURCES zurück.

Rückgabewert

FltAllocateExtraCreateParameter kann einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameter konnte nicht genügend Arbeitsspeicher für eine ECP-Struktur zuordnen. In diesem Fall wird EcpContext-NULL-.
STATUS_SUCCESS	Die ECP-Struktur wurde erfolgreich zugeordnet. In diesem Fall wird ein Zeiger auf die zugeordnete Struktur im EcpContext--Parameter zurückgegeben.

Bemerkungen

Standardmäßig weist die FltAllocateExtraCreateParameter Routine den ausgelagerten Speicherpool für eine benutzerdefinierte ECP-Kontextstruktur zu. Wenn die FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL Bitmaske wie oben beschrieben verwendet wird, wird ein nicht ausgelagerter Speicherpool zugewiesen. Nachdem dieser Pool zugewiesen wurde und die ECP-Kontextstruktur initialisiert wurde, wird die FltInsertExtraCreateParameter Routine verwendet, um die ECP-Kontextstruktur (ECP-Listenelement) in eine ECP-Listenstruktur (ECP-Listenstruktur) einzufügen.

Der vom FltAllocateExtraCreateParameter Routine zugewiesene Speicherpool wird vom Betriebssystem nicht automatisch freigegeben. Dieser Speicherpool muss schließlich mit einer der folgenden Methoden freigegeben werden:

Rufen Sie die FltRemoveExtraCreateParameter Routine auf, um die ECP-Kontextstruktur aus der ECP-Liste zu entfernen, und rufen Sie dann die FltFreeExtraCreateParameter Routine auf, um die ECP-Kontextstruktur selbst freizugeben. Die ECP-Liste ist weiterhin vorhanden.
Rufen Sie die FltFreeExtraCreateParameterList Routine auf . Dadurch wird die ECP-Liste einschließlich aller Listenelemente (ECP-Kontextstrukturen) freigegeben. Die ECP-Liste wird zerstört.

Wenn jedoch ein Dateisystem- oder Dateisystemfiltertreiber ein ECP an eine vorhandene oder neu erstellte ECP_LIST anfügt, während eine IRP_MJ_CREATE-Anforderung verarbeitet wird, wird dieses ECP automatisch bereinigt, wenn das IRP abgeschlossen ist. Daher muss ein Filtertreiber keine ECPs bereinigen, die dynamisch hinzugefügt werden. Dadurch kann der ECP eines Filtertreibers über die Analysepunkte hinweg ordnungsgemäß verteilt werden – ein Prozess, der mehrere IRP_MJ_CREATE Anforderungen generieren kann.