NdisAllocateNetBufferAndNetBufferList 函数 (ndis/nblapi.h)

项目
08/07/2023

调用 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 函数。调用方传递给 NdisAllocateNetBufferListPool 的 NET_BUFFER_LIST_POOL_PARAMETERS 结构的 fAllocateNetBuffer 成员必须设置为 TRUE，DataSize 成员设置为零。

[in] ContextSize

要为调用方保留的NET_BUFFER_LIST_CONTEXT结构中已用数据空间量。 ContextSize 必须是MEMORY_ALLOCATION_ALIGNMENT定义的值的倍数。

[in] ContextBackFill

调用方所需的) (回填空间 (未使用的数据 空间量。 NDIS 将此值添加到 ContextSize 并分配额外的空间。 ContextBackFill 必须是MEMORY_ALLOCATION_ALIGNMENT定义的值的倍数。

[in, optional] MdlChain

指向 MDL 链的指针，NDIS 使用该链初始化预分配NET_BUFFER结构。 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结构的池。若要创建此类池，必须调用NET_BUFFER_LIST_POOL_PARAMETERS 结构的 fAllocateNetBuffer 成员设置为 TRUE，DataSize 成员设置为零的 NdisAllocateNetBufferListPool 函数。

注意必须从 NDIS 缓冲池分配NET_BUFFER和 NET_BUFFER_LIST 结构。驱动程序不得从其专用内存池或堆栈分配和初始化 NET_BUFFER_LIST 或 NET_BUFFER 结构。

调用 NdisFreeNetBufferList 函数以释放 NET_BUFFER_LIST 结构。

当预分配NET_BUFFER拥有NET_BUFFER时，可以通过使用另一个 MDL 链重新初始化来重复使用预分配NET_BUFFER，但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 及更高版本中受支持。
目标平台	通用
标头	ndis/nblapi.h (包括 ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL
DDI 符合性规则	Irql_NetBuffer_Function (ndis) 、NdisAllocateNetBufferList (ndis) 、NdisAllocateNetBufferList_InitFail (ndis)