FsRtlAllocateExtraCreateParameter-Funktion (ntifs.h)

Artikel
12/21/2024

Die FsRtlAllocateExtraCreateParameter Routine weist Speicher für eine zusätzliche EcP-Kontextstruktur (Create Parameter) zu und generiert einen Zeiger auf diese Struktur.

Syntax

NTSTATUS FsRtlAllocateExtraCreateParameter(
  [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] EcpType

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

[in] SizeOfContext

Die Größe der 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 pools, die von FsRtlAllocateExtraCreateParameter zugewiesen werden, 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 filterdefinierte Bereinigungsrückrufroutine vom Typ PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. Die Bereinigungsrückrufroutine wird aufgerufen, wenn die ECP-Struktur (erstellt durch die FsRtlAllocateExtraCreateParameter 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 der von EcpContext verweisende Wert NULL- und FsRtlAllocateExtraCreateParameter den Statuscode STATUS_INSUFFICIENT_RESOURCES zurückgeben.

Rückgabewert

FltAllocateExtraCreateParameter gibt einen Statuscode wie einen der folgenden zurück:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	FsRtlAllocateExtraCreateParameter konnte nicht genügend Arbeitsspeicher für eine ECP-Struktur zuordnen. In diesem Fall ist 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 FsRtlAllocateExtraCreateParameter Routine den ausgelagerten Speicherpool für eine ECP-Kontextstruktur zu. Wenn die FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL Bitmaske wie im parameter Flags 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_LIST) einzufügen.

Wenn der Aufrufer ECP_LIST zuweist und ein oder mehrere ECPs in einem Aufruf von IoCreateFileExverwendet werden, ist die vorherige Beschreibung richtig. In diesem Fall gibt das System keines der ECPs frei, sodass der Aufrufer mehrere Aufrufe an IoCreateFileEx mit demselben ECP-Satz tätigen kann. 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.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Die FsRtlAllocateExtraCreateParameter-Routine ist ab Windows Vista verfügbar.
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	<= APC_LEVEL