FltAllocatePoolAlignedWithTag-Funktion (fltkernel.h)

Artikel
02/06/2025

FltAllocatePoolAlignedWithTag weist einen geräteausrichtungsbezogenen Puffer für die Verwendung in einem nicht zwischengespeicherten E/A-Vorgang zu.

Syntax

PVOID FLTAPI FltAllocatePoolAlignedWithTag(
  [in] PFLT_INSTANCE Instance,
  [in] POOL_TYPE     PoolType,
  [in] SIZE_T        NumberOfBytes,
  [in] ULONG         Tag
);

Parameter

[in] Instance

Undurchsichtiger Instanzzeiger für eine vom Aufrufer gehörende Minifiltertreiberinstanz, die an das Volume angefügt ist. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

[in] PoolType

Typ des zuzuweisenden Pools. Eine der folgenden:

NonPagedPool-

PagedPool-

NonPagedPoolCacheAligned-

PagedPoolCacheAligned-

Eine Beschreibung der verfügbaren Poolspeichertypen finden Sie unter POOL_TYPE.

[in] NumberOfBytes

Anzahl der zuzuordnenden Bytes. Dieser Parameter ist erforderlich und kann null sein.

[in] Tag

Gibt das Pooltag für den zugewiesenen Arbeitsspeicher an. Treiber geben das Pooltag normalerweise als Zeichenfolge von 1 bis vier 7-Bit-ASCII-Zeichen an, getrennt durch einfache Anführungszeichen (z. B. "abcd"). Dieser Parameter ist erforderlich und darf nicht null sein.

Rückgabewert

Wenn nicht genügend freier Pool verfügbar ist, um die Anforderung zu erfüllen, gibt FltAllocatePoolAlignedWithTag einen NULL- Zeiger zurück. Andernfalls gibt FltAllocatePoolAlignedWithTag einen Zeiger auf den neu zugeordneten Puffer zurück.

Bemerkungen

FltAllocatePoolAlignedWithTag weist einen Puffer zu, der gemäß dem zugrunde liegenden Gerät für das angegebene Volume ausgerichtet ist. Solche geräteausrichteten Puffer sind für nicht zwischengespeicherte E/A erforderlich. (Sie können auch für zwischengespeicherte E/A verwendet werden.) Beim Aufrufen von Routinen, die nicht zwischengespeicherte E/A ausführen, z. B. FltReadFile- und FltWriteFile-, sollten Minifiltertreiber FltAllocatePoolAlignedWithTag anstelle von ExAllocatePoolWithTagaufrufen.

Wenn der Aufrufer einen Wert von Null für den parameter NumberOfBytes angibt, weist FltAllocatePoolAlignedWithTag die kleinste Speichermenge zu, die die Ausrichtungsanforderung erfüllt.

Das System ordnet das vom Tag Parameter angegebene Pooltag dem zugeordneten Puffer zu. Programmiertools, z. B. der Windows-Debugger (WinDbg), können das Pooltag anzeigen, das jedem zugeordneten Puffer zugeordnet ist. Der Wert des Pooltags wird normalerweise in umgekehrter Reihenfolge angezeigt. Wenn beispielsweise ein Aufrufer "Fred" als Wert des Tag-Parameters übergibt, wird dieser Wert als "derF" angezeigt, wenn der Pool gedumpt wird oder wenn die Poolnutzung im Debugger nachverfolgt wird.

Weitere Informationen zur Speicherverwaltung finden Sie unter Speicherverwaltung.

Wenn der Puffer, der FltAllocatePoolAlignedWithTag zugeordnet wird, nicht mehr benötigt wird, ist der Aufrufer dafür verantwortlich, ihn durch Aufrufen von FltFreePoolAlignedWithTagaufzurufen.

Aufrufer von FltAllocatePoolAlignedWithTag- können nur bei IRQL-DISPATCH_LEVEL ausgeführt werden, wenn ein "NonPaged"-XxxPoolType- angegeben ist. Andernfalls müssen Aufrufer unter IRQL <= APC_LEVEL ausgeführt werden.