NdisAllocatePacketPoolEx 函式 (ndis.h)

  • 發行項

注意 NDIS 5. x 已被取代，且由 NDIS 6 取代。 x。 如需新的 NDIS 驅動程式開發，請參閱 從 Windows Vista 開始的網路驅動程式。 如需移植 NDIS 5 的相關信息。 x 驅動程式至 NDIS 6。 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 的總和是驅動程式在呼叫 NdisAllocatePacket 之前可以呼叫 NdisAllocatePacket 多少次的有效限制，才能呼叫 NdisFreePacket，以將封包描述元傳回封包集區的免費清單。 未配置溢位描述元時， NdisFreePacket 會將封包描述元傳回靜態配置的集區。 如果已配置一或多個溢位描述元， NdisFreePacket 會將封包描述元傳回至系統記憶體，而不是傳回集區。

NdisAllocatePacketPoolEx 的呼叫端應該將 NumberOfDescriptors 設定為預期正常載入所需的封包描述元數目。 驅動程式應將 NumberOfOverflowDescriptors 設定為容納預期尖峰負載所需的額外描述項數目。 如果封包描述項總數 (NumberOfDescriptors 加上 NumberOfOverflowDescriptors) 已從集區配置，則呼叫 NdisAllocatePacket 會傳回NDIS_STATUS_RESOURCES。

當傳送或指示的封包傳回給配置驅動程式時，它可以在呼叫 NdisReinitializePacket 之後重複使用每個封包描述元，並使用緩衝區描述元鏈結再次設定，或者驅動程式可以呼叫 NdisFreePacket 將該封包傳回至免費清單。 重新初始化和重複使用從封包集區配置的封包，比釋放快得多，然後必須重新配置它們。 在驅動程式使用封包描述元呼叫 NdisReinitializePacket 之前，它必須將指標儲存至鏈結至封包描述元的緩衝區描述元，因為 NdisReinitializePacket 會將緩衝區鏈的前端設定為 NULL。

當驅動程式不再需要封包描述元時，它會呼叫 [ (nf-ndis-ndisfreepacketpool.md) ，以釋放它以 NdisAllocatePacketPoolEx 配置的記憶體。

操作系統版本：Windows CE .NET 4.0 和更新版本。

規格需求

需求 值
標頭 ndis.h
程式庫 Ndis.lib
IRQL IRQL <= DISPATCH_LEVEL

另請參閱