FltAllocateExtraCreateParameter-Funktion (fltkernel.h)

Artikel
02/26/2024

Die FltAllocateExtraCreateParameter-Routine weist einen ausgelagerten Speicherpool für eine benutzerdefinierte ECP-Kontextstruktur (Extra Create Parameter) 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 Optionen für die Poolzuordnung. Im Folgenden wird beschrieben, wie ein Pool zugeordnet wird, wenn mindestens einer der aufgeführten Flagwerte mit dem Flags-Parameter mithilfe eines bitweisen OR-Vorgangs kombiniert wird:

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL: Nicht ausgelagerter Pool wird zugewiesen. Wenn dieser Flagwert nicht verwendet wird, wird der ausgelagerte Pool zugeordnet.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA: Für alle Pools, die von dieser Routine zugewiesen werden, wird das Speicherkontingent des aktuellen Prozesses in Rechnung gestellt.

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

[in, optional] CleanupCallback

Optionaler Zeiger auf eine Minifilter-definierte Bereinigungsrückrufroutine vom Typ PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. Die Cleanup-Rückrufroutine wird aufgerufen, wenn die ECP-Struktur (erstellt von der 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 Tag-Parameter von ExAllocatePoolWithTag.

[out] EcpContext

Empfängt einen Zeiger auf die zugeordnete ECP-Kontextstruktur. Wenn die Routine keinen ausreichenden Pool zuweisen konnte, ist *EcpContextNULL, und die Routine gibt status Code 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 zuweisen. In diesem Fall ist EcpContextNULL.
STATUS_SUCCESS	Die ECP-Struktur wurde erfolgreich zugeordnet. In diesem Fall wird ein Zeiger auf die zugeordnete Struktur im EcpContext-Parameter zurückgegeben.

Hinweise

Standardmäßig weist die FltAllocateExtraCreateParameter-Routine einen 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 zugeordnet. Nachdem dieser Pool zugewiesen und die ECP-Kontextstruktur initialisiert wurde, wird die FltInsertExtraCreateParameter-Routine verwendet, um die ECP-Kontextstruktur (ECP-Listenelement) in eine ECP-Listenstruktur (ECP-Liste) einzufügen.

Der Speicherpool, der von der FltAllocateExtraCreateParameter-Routine zugewiesen wird, wird nicht automatisch vom Betriebssystem freigegeben. Dieser Speicherpool muss schließlich mithilfe 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 frei zu geben. Die ECP-Liste besteht weiterhin.
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 während der Verarbeitung einer IRP_MJ_CREATE Anforderung einen ECP an eine vorhandene oder neu erstellte ECP_LIST anfügt, wird dieser ECP automatisch bereinigt, wenn der IRP abgeschlossen ist. Daher muss ein Filtertreiber keine ecPs sauber, die dynamisch hinzugefügt werden. Dadurch kann das ECP eines Filtertreibers ordnungsgemäß über die Analysepunkte verteilt werden – ein Prozess, für den mehrere IRP_MJ_CREATE Anforderungen generiert werden müssen.