ALLOCATE_FUNCTION_EX回呼函式 (wdm.h)

發行項
02/29/2024

當用戶端從空白的 lookaside 清單要求專案時， LookasideListAllocateEx 例程會為新的 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

指定要配置給新外觀清單項目的記憶體類型。呼叫端會將此參數設定為有效的 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 參數值是傳遞至 ExInitializeLosideListEx 的相同 PoolType 參數值。

如果，在 ExInitializeLookasideListEx 呼叫 Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL，LookasideListAllocateEx 例程收到的 PoolType 參數是POOL_RAISE_IF_ALLOCATION_FAILURE位 OR，以及傳遞至 ExInitializeLosideListEx 的 PoolType 參數值。 LookasideListAllocateEx 例程可以將其 PoolType 參數值傳遞至 ExAllocatePoolWithTag 例程。

如果，在 ExInitializeLookasideListEx 呼叫 Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE，LookasideListAllocateEx 例程收到的 PoolType 參數是POOL_QUOTA_FAIL_INSTEAD_OF_RAISE位 OR，以及傳遞至 ExInitializeLoitializeLoitisideListEx 的 PoolType 值。 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 例程，以動態配置清單的緩衝區。未使用的緩衝區會儲存為清單中的專案。 lookaside 清單中的所有專案都是統一大小的緩衝區，驅動程式會在清單初始化時指定。

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

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

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

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

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

LookasideListAllocateEx 例程會呼叫與要求專案之 ExAllocateFromLookasideListEx 的呼叫相同 IRQL。對於要求位於分頁記憶體中專案的呼叫，呼叫端必須執行 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_，請參閱標註函式行為。