FltAllocateExtraCreateParameterList-Funktion (fltkernel.h)

Artikel
02/26/2024

Die FltAllocateExtraCreateParameterList-Routine weist ausgelagerten Poolspeicher für eine zusätzliche ECP-Listenstruktur (Create Parameter) zu und generiert einen Zeiger auf diese Struktur.

Syntax

NTSTATUS FLTAPI FltAllocateExtraCreateParameterList(
  [in]  PFLT_FILTER                  Filter,
  [in]  FSRTL_ALLOCATE_ECPLIST_FLAGS Flags,
  [out] PECP_LIST                    *EcpList
);

Parameter

[in] Filter

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

[in] Flags

Definiert Optionen für die Poolzuordnung. Wenn das FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA-Flag mit dem Flags-Parameter mithilfe eines bitweisen OR-Vorgangs kombiniert wird, wird jedem von der Routine zugeordneten Pool das Speicherkontingent des aktuellen Prozesses in Rechnung gestellt.

[out] EcpList

Empfängt einen Zeiger auf eine initialisierte ECP-Listenstruktur. Wenn die Routine keinen ausreichenden Pool zuordnet, ist *EcpListNULL, und die Routine gibt status Code STATUS_INSUFFICIENT_RESOURCES zurück.

Rückgabewert

FltAllocateExtraCreateParameterList kann einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameterList konnte nicht genügend Arbeitsspeicher für eine ECP-Listenstruktur zuweisen. In diesem Fall ist *EcpListNULL.
STATUS_SUCCESS	Die ECP-Listenstruktur wurde erfolgreich zugeordnet und initialisiert. In diesem Fall wird im *EcpList-Parameter ein Zeiger auf die initialisierte Listenstruktur zurückgegeben.

Hinweise

Ob das Betriebssystem automatisch Arbeitsspeicher freigibt, den FltAllocateExtraCreateParameterList zuordnet, hängt davon ab, wann FltAllocateExtraCreateParameterList aufgerufen wird, wie in den folgenden Situationen gezeigt:

Ein Aufrufer kann FltAllocateExtraCreateParameterList aufrufen, um die ECP_LIST zuzuordnen und eine oder mehrere ECP-Kontextstrukturen hinzuzufügen, bevor der Aufrufer die FltCreateFileEx2-Routine aufruft . In dieser Situation gibt das Betriebssystem keine ecp-Kontextstrukturen frei. Daher kann der Aufrufer mehrere Aufrufe an FltCreateFileEx2 mit demselben ECP-Satz ausführen. Wenn der Aufrufer mit dem ECP_LIST fertig ist, muss der Aufrufer die FltFreeExtraCreateParameterList-Routine aufrufen, um die ECP_LIST frei zu geben.
Während ein Dateisystemfiltertreiber eine IRP_MJ_CREATE-Anforderung verarbeitet, kann der Dateisystemfiltertreiber FltInsertExtraCreateParameter aufrufen, um ein ECP an eine vorhandene ECP_LIST anzufügen. Wenn die ECP_LIST nicht vorhanden ist, muss der Aufrufer FltAllocateExtraCreateParameterList aufrufen, um die ECP_LIST zu erstellen. In diesem Fall werden die ECP_LIST und die ECP-Kontextstruktur automatisch vom E/A-Manager bereinigt, wenn der Erstellungsvorgang abgeschlossen ist. Dadurch kann der ECP eines Filtertreibers ordnungsgemäß über die Verarbeitung von Analysepunkten verteilt werden. Für diesen Prozess müssen möglicherweise mehrere IRP_MJ_CREATE Anforderungen generiert werden.

Wenn das FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA-Flag wie oben beschrieben mit dem Flags-Parameter verwendet wird, wird ein normaler auslagerungsfähiger Pool zugeordnet. Andernfalls wird ein ausgelagerter Pool mithilfe einer internen Lookaside-Liste zugeordnet.

ECP_LIST-Struktur

ECP_LIST ist eine nicht transparente Struktur, die vom Betriebssystem deklariert wird. ECP_LIST enthält eine Liste mit zusätzlichen ECP-Einträgen (Create Parameter).

Die FltAllocateExtraCreateParameterList-Routine muss verwendet werden, um Arbeitsspeicher für die ECP_LIST-Struktur zuzuweisen. Der von FltAllocateExtraCreateParameterList zugewiesene Arbeitsspeicher wird nicht automatisch vom Betriebssystem freigegeben. Die Zuordnung muss explizit aufgehoben werden, indem die FltFreeExtraCreateParameterList-Routine aufgerufen wird. Beachten Sie, dass alle verbleibenden ECP-Listenelemente automatisch freigegeben werden, wenn FltFreeExtraCreateParameterList aufgerufen wird.

Der PECP_LIST Datentyp wird verwendet, um einen Zeiger auf eine Variable vom Typ ECP_LIST zu deklarieren.

Syntax

struct ECP_LIST {
  ;      // Reserved.
};

Die ECP_LIST-Struktur wird in Ntifs.h deklariert (include Ntifs.h).

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Diese Routine ist ab Windows Vista verfügbar.
Zielplattform	Universell
Header	fltkernel.h (fltkernel.h einschließen)
Bibliothek	FltMgr.lib
IRQL	<= APC_LEVEL