ALLOCATE_FUNCTION_EX回调函数（wdm.h）

项目
02/07/2025

LookasideListAllocateEx 例程为新的 lookaside 列表项分配存储，当客户端从空的 lookaside 列表中请求条目时。

语法

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

参数

[in] PoolType

指定要为新的 lookaside-list 条目分配的存储类型。调用方将此参数设置为有效的 POOL_TYPE 枚举值，并且可能具有以下标志位之一的按位 OR：

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

有关POOL_RAISE_IF_ALLOCATION_FAILURE标志的详细信息，请参阅 ExAllocatePoolWithTag。有关POOL_QUOTA_FAIL_INSTEAD_OF_RAISE标志的详细信息，请参阅 ExAllocatePoolWithQuotaTag。

如果，在初始化 lookaside 列表的 ExInitializeLookasideListEx 调用中， Flags 参数为零，LookasideListAllocateEx 例程接收的 PoolType 参数与传递给 ExInitializeLookasideListEx的 PoolType 参数值相同。

如果在 ExInitializeLookasideListEx 调用中， Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL，LookasideListAllocateEx 例程接收的 PoolType 参数是POOL_RAISE_IF_ALLOCATION_FAILURE的按位 OR 和传递给 ExInitializeLookasideListEx的 PoolType 参数值。 LookasideListAllocateEx 例程可以将其 PoolType 参数值传递给 ExAllocatePoolWithTag 例程。

如果，在 ExInitializeLookasideListEx 调用中， Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE，PoolType 参数，LookasideListAllocateEx 例程接收的按位 POOL_QUOTA_FAIL_INSTEAD_OF_RAISE OR 和传递给 ExInitializeLookasideListEx的 PoolType 值。 LookasideListAllocateEx 例程可以将其 PoolType 参数值传递给 ExAllocatePoolWithQuotaTag 例程。

[in] NumberOfBytes

指定要分配的 lookaside 列表项的大小（以字节为单位）。

[in] Tag

指定用于标记新 lookaside-list 条目的已分配存储的四字节池标记。有关池标记的详细信息，请参阅 ExAllocatePoolWithTag中标记参数的说明。

[in, out] Lookaside

指向描述外观列表的 LOOKASIDE_LIST_EX 结构的指针。此结构以前由 ExInitializeLookasideListEx 例程初始化。

返回值

LookasideListAllocateEx 返回指向分配的 lookaside-list 条目的指针。如果例程无法分配条目，它将返回 NULL 。

言论

创建 lookaside 列表的驱动程序可以实现 LookasideListAllocateEx 例程来动态分配列表的缓冲区。未使用的缓冲区存储为列表中的条目。外观列表中的所有条目都是统一大小的缓冲区，驱动程序在初始化列表时指定该缓冲区。

驱动程序提供指向自定义 LookasideListAllocateEx 例程的指针，作为初始化 lookaside 列表的 ExInitializeLookasideListEx 调用中的输入参数。如果驱动程序将此参数设置为 NULL，则查找列表将改用默认分配例程。

驱动程序调用 ExAllocateFromLookasideListEx 例程，以从 lookaside 列表中分配条目。如果列表为空（不包含任何条目），ExAllocateFromLookasideListEx 调用 LookasideListAllocateEx 来动态分配新条目的存储。 LookasideListAllocateEx 在分配成功时返回指向新分配项的指针。否则，它将返回 NULL 。

PoolType、NumberOfBytes、Tag和 Lookaside 参数包含与初始化 lookaside 列表的 ExInitializeLookasideListEx 调用中作为输入参数传递的值相同。

LookasideListAllocateEx 例程可以使用 lookaside 参数访问驱动程序与 lookaside 列表关联的专用上下文数据。有关详细信息，请参阅 ExInitializeLookasideListEx中的代码示例。

有关外观列表的详细信息，请参阅使用 Lookaside 列表。

LookasideListAllocateEx 例程与调用 ExAllocateFromLookasideListEx 调用的 IRQL 相同。对于请求驻留在分页内存中的条目的调用，调用方必须运行 IRQL <= APC_LEVEL。对于请求驻留在非分页内存中的条目的调用，调用方必须运行 IRQL <= DISPATCH_LEVEL。

例子

若要定义 LookasideListAllocateEx 回调例程，必须首先提供一个函数声明来标识要定义的回调例程的类型。 Windows 为驱动程序提供一组回调函数类型。使用回调函数类型声明函数有助于驱动程序代码分析、静态驱动程序验证程序（SDV）和其他验证工具查找错误，这是为 Windows作系统编写驱动程序的要求。

例如，若要定义 LookasideListAllocateEx 名为 MyLookasideListAllocateEx的回调例程，请使用FREE_FUNCTION_EX类型，如以下代码示例所示：

FREE_FUNCTION_EX MyLookasideListFreeEx;

然后，按如下所示实现回调例程：

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

FREE_FUNCTION_EX函数类型在 Wdm.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 _Use_decl_annotations_ 注释添加到函数定义。 _Use_decl_annotations_ 批注可确保使用应用于头文件中FREE_FUNCTION_EX函数类型的批注。有关函数声明要求的详细信息，请参阅使用 WDM 驱动程序的函数角色类型来声明函数。有关 _Use_decl_annotations_的信息，请参阅批注函数行为。