NdisAllocatePacketPool

  • Article

This function allocates and initializes a block of storage for a pool of packet descriptors.

VOID NdisAllocatePacketPool(
  PNDIS_STATUS Status,
  PNDIS_HANDLE PoolHandle,
  UINT NumberOfDescriptors,
  UINT ProtocolReservedLength
);

Parameters

  • Status
    [out] Pointer to a caller-supplied variable in which this function returns the status of the packet pool allocation.
  • PoolHandle
    [out] Handle to the packet pool. This handle is a required parameter to the NDIS packet functions that the driver calls subsequently.
  • NumberOfDescriptors
    [in] Specifies the number of packet descriptors that the pool should contain.
  • ProtocolReservedLength
    [in] Specifies the number of bytes to be allocated for the ProtocolReserved array of each packet descriptor. For packet descriptors that are to be used in receive indications, this parameter can be at most 16 bytes.

Return Values

The following table shows the possible return values for this function.

Value Description
NDIS_STATUS_SUCCESS The driver can make calls to the NdisAllocatePacket function when it needs packet descriptors to make indications up to higher-level drivers or to send packets down to lower-level drivers.
NDIS_STATUS_RESOURCES The attempt to allocate a packet pool failed, possibly due to a shortage of memory. However, the caller might attempt to decrease the NumberOfDescriptors parameter and call again immediately.

Remarks

The caller should save the handle returned by this function. Usually, the driver next calls the NdisAllocatePacket function one or more times with this handle to allocate a set of packet descriptors. The NumberofDescriptors specified in the call to this function is the effective limit on how many times the driver can call NdisAllocatePacket before it must call the NdisFreePacket function to return a packet descriptor to the free list for the packet pool.

Because packets sent or indicated are returned to the allocating driver, it can reuse each packet descriptor after calling the NdisReinitializePacket function and setting it up again with a chain of buffer descriptors, or the driver can call the NdisFreePacket function to return that packet to the free list. Reinitializing and reusing packets allocated from the packet pool is far faster than freeing and reallocating them. Before a driver calls NdisReinitializePacket with a packet descriptor, it must save the pointers to buffer descriptors that are chained to the packet descriptor, because NdisReinitializePacket sets the head of the buffer chain to NULL.

When the driver no longer needs the packet pool, it calls the NdisFreePacketPool function to release the packet pool storage.

The driver must release any spin lock that it is holding before calling this function.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ndis.h.

See Also

NdisAllocatePacket | NdisFreePacket | NdisFreePacketPool | NdisMIndicateReceivePacket | NdisReinitializePacket | NdisUnchainBufferAtBack | NdisUnchainBufferAtFront

 Last updated on Tuesday, May 18, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.