NdisAllocateNetBufferAndNetBufferList 函式 (ndis/nblapi.h)

發行項
02/27/2024

呼叫 NdisAllocateNetBufferAndNetBufferList 函式，以配置和初始化以預先配置 NET_BUFFER 結構初始化的NET_BUFFER_LIST 結構。

語法

NDIS_EXPORTED_ROUTINE NET_BUFFER_LIST * NdisAllocateNetBufferAndNetBufferList(
  [in]           NDIS_HANDLE          PoolHandle,
  [in]           USHORT               ContextSize,
  [in]           USHORT               ContextBackFill,
  [in, optional] __drv_aliasesMem MDL *MdlChain,
  [in]           ULONG                DataOffset,
  [in]           SIZE_T               DataLength
);

參數

[in] PoolHandle

先前從傳回的NET_BUFFER_LIST結構集區句柄 NdisAllocateNetBufferListPool 函式。 NET_BUFFER_LIST_POOL_PARAMETERS結構的fAllocateNetBuffer 成員，呼叫端傳遞給 NdisAllocateNetBufferListPool 的 fAllocateNetBuffer 成員必須設定為 TRUE，且 DataSize 成員設定為零。

[in] ContextSize

NET_BUFFER_LIST_CONTEXT 結構中要保留給呼叫端的已使用數據空間量。 ContextSize 必須是MEMORY_ALLOCATION_ALIGNMENT所定義的多個值。

[in] ContextBackFill

呼叫端所需的 未使用資料空間 量 (回填空間) 。 NDIS 會將此值新增至 ContextSize ，並配置額外的空間。 ContextBackFill 必須是MEMORY_ALLOCATION_ALIGNMENT所定義的多個值。

[in, optional] MdlChain

NDIS 用來初始化預先配置NET_BUFFER結構的 MDL 鏈結指標。 MdlChain 可以是 NULL。

[in] DataOffset

從緩衝區的開頭到 MDL 鏈結中 已使用數據空間 的開頭，的初始位移，以位元組為單位。此位移前的數據空間是 未使用的數據空間。因此，這個值也代表 MDL 鏈結中可用回填空間的初始數量。如果 MdlChain 為 NULL，DataOffset 必須為 0。

[in] DataLength

MDL 鏈結中 已使用之數據空間 的長度，以位元組為單位。如果 MdlChain 為 NULL，DataLength 必須為 0。

傳回值

NdisAllocateNetBufferAndNetBufferList 會傳回已配置之NET_BUFFER_LIST結構的指標。 NET_BUFFER_LIST 結構包含NET_BUFFER結構。如果配置失敗，則此指標為 NULL。

備註

NdisAllocateNetBufferAndNetBufferList 函式配置的結構必須來自集區，其中包含與預先配置NET_BUFFER結構配對的NET_BUFFER_LIST結構。若要建立這類集區，您必須呼叫 NdisAllocateNetBufferListPool 函式，其中NET_BUFFER_LIST_POOL_PARAMETERS結構的 fAllocateNetBuffer 成員設定為 TRUE，而 DataSize 成員設定為零。

注意NET_BUFFER 和 NET_BUFFER_LIST 結構必須從 NDIS 緩衝池配置。驅動程式不得從其私人記憶體集區或堆疊配置和初始化 NET_BUFFER_LIST 或 NET_BUFFER 結構。

呼叫 NdisFreeNetBufferList 函式以釋放 NET_BUFFER_LIST 結構。

NET_BUFFER中的預先配置NET_BUFFER可以重複使用，方法是在擁有NET_BUFFER時，使用另一個 MDL 鏈結重新初始化它，但NET_BUFFER中的 DataOffset、DataLength、CurrentMdl 和 CurrentMdlOffset 字段必須與新的 MDL 鏈結一致。

例如，如果原始 MDL 鏈結包含 XDataLength 和 YDataOffset，而 CurrentMdl 會從原始 MDL 鏈結中的第二個 MDL (M) 開始，CurrentMdlOffset 為 Z。然後，NET_BUFFER_DATA中的 MdlChain 字段必須指向包含 X'DataLength 和 Y'DataOffset 的新 MDL 鏈結。如果 CurrentMdl 開頭為新 MDL 鏈結中的第三個 MDL (M') ， 則 CurrentMdlOffset 為 Z'，而且必須使用下列宏來設定 NET_BUFFER中的字段：

NET_BUFFER_FIRST_MDL(_NB) = New MDL chain;
NET_BUFFER_DATA_LENGTH(_NB) = X';
NET_BUFFER_DATA_OFFSET(_NB) = Y';
NET_BUFFER_CURRENT_MDL(_NB) = M';
NET_BUFFER_CURRENT_MDL_OFFSET(_NB) = Z';

規格需求

需求	值
最低支援的用戶端	NDIS 6.0 和更新版本支援。
目標平台	Universal
標頭	ndis/nblapi.h (包含 ndis.h)
程式庫	Ndis.lib
IRQL	<= DISPATCH_LEVEL
DDI 合規性規則	Irql_NetBuffer_Function (ndis) 、NdisAllocateNetBufferList (ndis) ，NdisAllocateNetBufferList_InitFail (ndis)