FsRtlAllocateExtraCreateParameter-Funktion (ntifs.h)

Artikel
02/26/2024

Die FsRtlAllocateExtraCreateParameter-Routine weist Arbeitsspeicher 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 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 von FsRtlAllocateExtraCreateParameter zugewiesenen Pools 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 filterdefinierte Bereinigungsrückrufroutine vom Typ PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. Die Cleanup-Rückrufroutine wird aufgerufen, wenn die ECP-Struktur (erstellt von der 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 Tag-Parameter von ExAllocatePoolWithTag.

[out] EcpContext

Empfängt einen Zeiger auf die zugeordnete ECP-Kontextstruktur. Wenn die Routine keinen ausreichenden Pool zuordnen konnte, lautet der Wert, auf den ecpContext verweist, NULL, und FsRtlAllocateExtraCreateParameter gibt status Code STATUS_INSUFFICIENT_RESOURCES zurück.

Rückgabewert

FltAllocateExtraCreateParameter gibt einen status Code zurück, z. B. einen der folgenden:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	FsRtlAllocateExtraCreateParameter 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 FsRtlAllocateExtraCreateParameter-Routine einen ausgelagerten Speicherpool für eine ECP-Kontextstruktur zu. Wenn die FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL Bitmaske wie im Flags-Parameter beschrieben verwendet wird, wird ein nicht ausgelagerter Speicherpool zugeordnet. Nachdem dieser Pool zugeordnet 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 IoCreateFileEx verwendet werden, ist die vorherige Beschreibung richtig. In diesem Fall gibt das System keine der ECPs frei, sodass der Aufrufer mehrere Aufrufe an IoCreateFileEx mit demselben ECP-Satz tätigen kann. 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.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Die FsRtlAllocateExtraCreateParameter-Routine ist ab Windows Vista verfügbar.
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL