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 列舉值，而且可能具有下列其中一個旗標位的位 ORs：

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，PoolType 參數，LookasideListAllocateEx 例程所接收的位 POOL_RAISE_IF_ALLOCATION_FAILURE OR，以及傳遞 至 exInitializeLookasideListEx的 PoolType 参數值。 LookasideListAllocateEx 例程可以將其 PoolType 參數值傳遞至 ExAllocatePoolWithTag 例程。

如果，在 ExInitializeLookasideListEx 呼叫中， Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE，LookasideListAllocateEx 例程所接收的 PoolType 參數是POOL_QUOTA_FAIL_INSTEAD_OF_RAISE位 OR，以及傳遞 至 ExInitializeLookasideListExPoolType 值。 LookasideListAllocateEx 例程可以傳遞其 PoolType 參數值，而不需修改，即可將 ExAllocatePoolWithQuotaTag 例程傳遞。

[in] NumberOfBytes

指定要配置之 lookaside 清單專案的大小，以位元組為單位。

[in] Tag

指定用來標記新 lookaside-list 專案之已配置記憶體的四位元組集區標記。如需集區卷標的詳細資訊，請參閱 ExAllocatePoolWithTag中 Tag 參數的描述。

[in, out] Lookaside

描述外觀清單之 LOOKASIDE_LIST_EX 結構的指標。此結構先前由 exInitializeLookasideListEx 例程初始化。

傳回值

LookasideListAllocateEx 會傳回配置之 lookaside-list 專案的指標。如果例程無法配置專案，它會傳回 NULL 。

言論

建立 lookaside 列表的驅動程式可以實作 LookasideListAllocateEx 例程，以動態配置清單的緩衝區。未使用中的緩衝區會儲存為清單中的專案。外觀清單中的所有專案都是統一大小的緩衝區，驅動程式會在初始化清單時指定此緩衝區。

驅動程式會提供自定義 LookasideListAllocateEx 例程的指標，做為初始化 lookaside 清單之 ExInitializeLookasideListEx 呼叫中的輸入參數。如果驅動程式將此參數設定為 NULL，則 lookaside 清單會改用預設配置例程。

驅動程式會呼叫 ExAllocateFromLookasideListEx 例程，以從 lookaside 列表中配置專案。如果清單是空的（不包含任何專案），ExAllocateFromLookasideListEx 會呼叫 LookasideListAllocateEx 動態配置新項目的記憶體。 LookasideListAllocateEx 如果配置成功，則會傳回新配置專案的指標。否則，它會傳回NULL 。

PoolType、NumberOfBytes、Tag和 Lookaside 參數包含與初始化 lookaside 列表 ExInitializeLookasideListEx 呼叫中作為輸入參數傳遞的相同值。

LookasideListAllocateEx 例程可以使用 Lookaside 參數來存取驅動程式與 lookaside 列表相關聯的私人內容數據。如需詳細資訊，請參閱 ExInitializeLookasideListEx中的程式碼範例。

如需 lookaside 列表的詳細資訊，請參閱使用 Lookaside 清單。

LookasideListAllocateEx 例程呼叫的 IRQL，與要求輸入 的 exAllocateFromLookasideListEx 呼叫相同。對於要求位於分頁記憶體中的專案呼叫，呼叫端必須執行 IRQL <= APC_LEVEL。對於要求位於非分頁記憶體中的專案呼叫，呼叫端必須執行 IRQL <= DISPATCH_LEVEL。

例子

若要定義 LookasideListAllocateEx 回呼例程，您必須先提供函式宣告，以識別您要定義的回呼例程類型。 Windows 提供一組驅動程式的回呼函式類型。使用回呼函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證器（SDV）和其他驗證工具尋找錯誤，而且是撰寫 Windows作系統驅動程式的需求。

例如，若要定義名為 MyLookasideListAllocateEx的 LookasideListAllocateEx 回呼例程，請使用 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_的相關信息，請參閱批注函式行為。