NdisAllocatePacketPoolEx 函数 (ndis.h)

  • 项目

注意 NDIS 5. x 已弃用，由 NDIS 6 取代。 x。 有关新的 NDIS 驱动程序开发，请参阅 从 Windows Vista 开始的网络驱动程序。 有关移植 NDIS 5 的信息。 NDIS 6 的 x 驱动程序。 x，请参阅 将 NDIS 5.x 驱动程序移植到 NDIS 6.0。

此函数为数据包描述符池分配和初始化存储块。

语法

void NdisAllocatePacketPoolEx(
  [out] PNDIS_STATUS Status,
  [out] PNDIS_HANDLE PoolHandle,
  [in]  UINT         NumberOfDescriptors,
  [in]  UINT         NumberOfOverflowDescriptors,
  [in]  UINT         ProtocolReservedLength
);

参数

[out] Status

指向调用方提供的变量，此函数在该变量中返回数据包池分配的状态。

[out] PoolHandle

指向调用方提供的变量，此函数在该变量中返回数据包池的句柄。 此句柄是驱动程序随后调用的 NdisXXX数据包 函数的必需参数。

[in] NumberOfDescriptors

指定池应包含的数据包描述符数，以便预期正常使用。 可分配的最大 NumberOfDescriptors 为0xFFFF。 如果尝试分配的次数超过此值， NdisAllocatePacketPoolEx 将返回 状态 NDIS_STATUS_RESOURCES。

[in] NumberOfOverflowDescriptors

指定为溢出情况保留的数据包描述符数，即在使用 NumberOfDescriptors 指定的所有描述符时。 如果此参数和 NumberOfDescriptors 的总和超过 0xFFFF，NdisAllocatePacketPoolEx 将减少作为此参数提供的值，使 NumberOfDescriptors 和 NumberOfOverflowDescriptors 总数等于0xFFFF。

[in] ProtocolReservedLength

指定要为每个数据包描述符的 ProtocolReserved 数组分配的字节数。 对于在接收指示中使用的数据包描述符，此参数的大小为 4* (PVOID) 。

返回值

无

备注

下表显示了此函数的可能返回值。

状态 说明
NDIS_STATUS_SUCCESS 当驱动程序需要数据包描述符来指示更高级别的驱动程序或将数据包向下发送到较低级别的驱动程序时，驱动程序可以调用 NdisAllocatePacket 。
NDIS_STATUS_RESOURCES 尝试分配数据包池失败，可能是由于内存不足。 此返回不一定意味着后续调用将失败。 但是，调用方可能会尝试减少 NumberOfDescriptors 并 立即再次调用。

成功调用 NdisAllocatePacketPoolEx 会返回数据包池的句柄，调用方应保存该句柄。 通常，驱动程序接下来会使用此句柄调用 NdisAllocatePacket 一次或多次，以分配一组数据包描述符。

NdisAllocatePacketPoolEx 仅静态分配足够的内存来容纳 NumberOfDescriptors 指定的数据包描述符数。 可通过调用 NdisAllocatePacket 从池中分配的数据包描述符总数为0xFFFF或最初传递给 NdisAllocatePacketPoolEx 的 NumberOfDescriptors 和 NumberOfOverflowDescriptors 之和。 溢出描述符仅在溢出情况下动态分配，也就是说，当给定 的 NumberOfDescriptors 已分配并且仍在使用时。

NumberOfDescriptors 和 NumberOfOverflowDescriptors 之和是驱动程序在必须调用 NdisFreePacket 以将数据包描述符返回到数据包池免费列表之前可以调用 NdisAllocatePacket 的次数的有效限制。 如果尚未分配溢出描述符， NdisFreePacket 会将数据包描述符返回到静态分配的池。 如果已分配一个或多个溢出描述符， NdisFreePacket 会将数据包描述符返回到系统内存，而不是返回到池。

NdisAllocatePacketPoolEx 的调用方应将 NumberOfDescriptors 设置为预期正常负载所需的数据包描述符数。 驱动程序应将 NumberOfOverflowDescriptors 设置为满足预期峰值负载所需的其他描述符的数量。 如果从池中分配了 numberOfDescriptors (numberOfDescriptors 加上 NumberOfOverflowDescriptors) 的可能数据包描述符总数，则对 NdisAllocatePacket 的调用将返回NDIS_STATUS_RESOURCES。

当发送或指示的数据包返回到分配驱动程序时，它可以在调用 NdisReinitializePacket 并使用缓冲区描述符链再次设置后重用每个数据包描述符，或者驱动程序可以调用 NdisFreePacket 将该数据包返回到免费列表。 重新初始化和重用从数据包池分配的数据包比释放和重新分配数据包要快得多，然后必须重新分配它们。 在驱动程序使用数据包描述符调用 NdisReinitializePacket 之前，它必须保存指向链接到数据包描述符的缓冲区描述符的指针，因为 NdisReinitializePacket 将缓冲区链的头设置为 NULL。

当驱动程序不再需要数据包描述符时，它会调用 [ (nf-ndis-ndisfreepacketpool.md) 以释放它使用 NdisAllocatePacketPoolEx 分配的存储。

操作系统版本：Windows CE .NET 4.0 及更高版本。

要求

要求 值
Header ndis.h
Library Ndis.lib
IRQL IRQL <= DISPATCH_LEVEL

另请参阅