ALLOCATE_FUNCTION_EX Rückruffunktion (wdm.h)
Die LookasideListAllocateEx-Routine ordnet den Speicher für einen neuen Lookaside-list-Eintrag zu, wenn ein Client einen Eintrag aus einer leeren Lookaside-Liste anfordert.
Syntax
ALLOCATE_FUNCTION_EX AllocateFunctionEx;
PVOID AllocateFunctionEx(
[in] POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes,
[in] ULONG Tag,
[in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}
Parameter
[in] PoolType
Gibt den Speichertyp an, der für den neuen Eintrag lookaside-list zugeordnet werden soll. Der Aufrufer legt diesen Parameter auf einen gültigen POOL_TYPE Enumerationswert und möglicherweise auf bitweise ORs diesen Wert mit einem der folgenden Flagbits fest:
POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE
Weitere Informationen zum POOL_RAISE_IF_ALLOCATION_FAILURE-Flag finden Sie unter ExAllocatePoolWithTag. Weitere Informationen zum POOL_QUOTA_FAIL_INSTEAD_OF_RAISE-Flag finden Sie unter ExAllocatePoolWithQuotaTag.
Wenn im ExInitializeLookasideListEx-Aufruf, der die Lookaside-Liste initialisiert hat, der Parameter Flags null ist, ist der PoolType-Parameter , den die LookasideListAllocateEx-Routine empfängt, derselbe PoolType-Parameterwert , der an ExInitializeLookasideListEx übergeben wurde.
Wenn im ExInitializeLookasideListEx-AufrufFlags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, ist der PoolType-Parameter , den die LookasideListAllocateEx-Routine empfängt, der bitweise OR von POOL_RAISE_IF_ALLOCATION_FAILURE und der PoolType-Parameterwert , der an ExInitializeLookasideListEx übergeben wurde. Die LookasideListAllocateEx-Routine kann ihren PoolType-Parameterwert ohne Änderung an die ExAllocatePoolWithTag-Routine übergeben.
Wenn im ExInitializeLookasideListEx-Aufruf Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, ist der PoolType-Parameter , den die LookasideListAllocateEx-Routine empfängt, der bitweise OR von POOL_QUOTA_FAIL_INSTEAD_OF_RAISE und der PoolType-Wert , der an ExInitializeLookasideListEx übergeben wurde. Die LookasideListAllocateEx-Routine kann ihren PoolType-Parameterwert ohne Änderung an die ExAllocatePoolWithQuotaTag-Routine übergeben.
[in] NumberOfBytes
Gibt die Größe des zuzuordnenden Eintrags lookaside-list in Bytes an.
[in] Tag
Gibt das Vier-Byte-Pooltag an, das verwendet werden soll, um den zugeordneten Speicher für den neuen Eintrag lookaside-list zu markieren. Weitere Informationen zu Pooltags finden Sie in der Beschreibung des Tags-Parameters in ExAllocatePoolWithTag.
[in, out] Lookaside
Ein Zeiger auf eine LOOKASIDE_LIST_EX Struktur, die die Suchliste beschreibt. Diese Struktur wurde zuvor von der ExInitializeLookasideListEx-Routine initialisiert.
Rückgabewert
LookasideListAllocateEx gibt einen Zeiger auf den zugeordneten Lookaside-list-Eintrag zurück. Wenn die Routine einen Eintrag nicht zuordnen kann, wird NULL zurückgegeben.
Hinweise
Ein Treiber, der eine Lookaside-Liste erstellt, kann eine LookasideListAllocateEx-Routine implementieren, um Puffer für die Liste dynamisch zuzuweisen. Ein Puffer, der nicht verwendet wird, wird als Eintrag in der Liste gespeichert. Alle Einträge in einer Lookaside-Liste sind Puffer einer einheitlichen Größe, die der Treiber angibt, wenn die Liste initialisiert wird.
Der Treiber stellt einen Zeiger auf eine benutzerdefinierte LookasideListAllocateEx-Routine als Eingabeparameter im ExInitializeLookasideListEx-Aufruf bereit, der die Lookaside-Liste initialisiert. Wenn der Treiber diesen Parameter auf NULL festlegt, verwendet die Lookaside-Liste stattdessen eine Standardzuordnungsroutine.
Ein Treiber ruft die ExAllocateFromLookasideListEx-Routine auf, um einen Eintrag aus einer Lookaside-Liste zuzuordnen. Wenn die Liste leer ist (keine Einträge enthält), ruft ExAllocateFromLookasideListExLookasideListAllocateEx auf, um den Speicher für einen neuen Eintrag dynamisch zuzuordnen. LookasideListAllocateEx gibt einen Zeiger auf den neu zugeordneten Eintrag zurück, wenn die Zuordnung erfolgreich ist. Andernfalls wird NULL zurückgegeben.
Die Parameter PoolType, NumberOfBytes, Tag und Lookaside enthalten dieselben Werte, die als Eingabeparameter im ExInitializeLookasideListEx-Aufruf übergeben wurden, der die Lookaside-Liste initialisierte.
Die LookasideListAllocateEx-Routine kann den Lookaside-Parameter verwenden, um auf private Kontextdaten zuzugreifen, die der Treiber der Lookaside-Liste zugeordnet hat. Weitere Informationen finden Sie im Codebeispiel in ExInitializeLookasideListEx.
Weitere Informationen zu Lookaside-Listen finden Sie unter Verwenden von Lookaside-Listen.
Die LookasideListAllocateEx-Routine wird in derselben IRQL wie der Aufruf von ExAllocateFromLookasideListEx aufgerufen, der den Eintrag anfordert. Für einen Aufruf, der einen Eintrag anfordert, der sich im ausgelagerten Arbeitsspeicher befindet, muss der Aufrufer IRQL <= APC_LEVEL ausführen. Für einen Aufruf, der einen Eintrag anfordert, der sich im nicht auslagerten Arbeitsspeicher befindet, muss der Aufrufer IRQL <= DISPATCH_LEVEL ausführen.
Beispiele
Um eine LookasideListAllocateEx-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.
Um beispielsweise eine LookasideListAllocateEx-Rückrufroutine mit dem Namen MyLookasideListAllocateExzu definieren, verwenden Sie den typ FREE_FUNCTION_EX, wie in diesem Codebeispiel gezeigt:
FREE_FUNCTION_EX MyLookasideListFreeEx;
Implementieren Sie dann Ihre Rückrufroutine wie folgt:
_Use_decl_annotations_
VOID
MyLookasideListFreeEx(
PVOID Buffer,
PLOOKASIDE_LIST_EX Lookaside
)
{
// Function body
}
Der FREE_FUNCTION_EX Funktionstyp ist in der Wdm.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den FREE_FUNCTION_EX Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Verhalten von Funktionen mit Anmerkungen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Desktop |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Weitere Informationen finden Sie im Abschnitt mit den Hinweisen. |