NdisReturnPackets (Windows CE 5.0)
This function releases ownership of one or more packets after a protocol has consumed the received data.
VOID NdisReturnPackets(PNDIS_PACKET* PacketsToReturn,UINTNumberOfPackets);
Parameters
- PacketsToReturn
[in] Pointer to an array of pointers to packet descriptors to be returned to the underlying driver that allocated them for a receive indication. - NumberOfPackets
[in] Specifies the number of pointers in the array.
Return Values
None.
Remarks
An NDIS intermediate driver should call NdisReturnPacket as soon as possible after its ProtocolReceivePacket function has returned control. Otherwise, both the underlying driver that supports multipacket receive indications and the bound protocol driver that processes them suffer a performance degradation.
When an underlying NIC driver runs low on available packet pool for receive indications or its NIC runs low on empty receive buffers, the miniport can force the NDIS library to call every bound protocol driver's ProtocolReceive function, each time with a single packet descriptor, until the miniport has regained ownership of its packet descriptors and the NIC has receive buffers available for incoming net packets. A ProtocolReceive function cannot begin post-processing a packet of received data and forwarding the processed data to clients until the driver's ProtocolReceiveComplete function is called.
For a packet descriptor passed in to its ProtocolReceivePacket function, a highest-level protocol driver can process its copy of received data and forward the processed data to clients immediately because the protocol can control how long it retains ownership of the resources allocated by the indicating driver. Assuming a highest-level protocol driver does not manipulate the data that it indicates to its clients, the protocol can even set up the range of data within the receive buffer of interest to its client, and make a receive indication to its clients by forwarding the input packet descriptor to those clients.
If an intermediate protocol driver's ProtocolReceivePacket function returns a nonzero reference count to an input packet descriptor, that driver must call NdisReturnPackets one or more times. After ProtocolReceivePacket calls NdisReturnPackets with a particular packet descriptor the number of times indicated in the reference count, the NDIS library returns the packet descriptor to the driver that made the indication.
A protocol driver can rely on NDIS to manage the reference count for every receive packet passed to ProtocolReceivePacket. When the reference count for a packet descriptor originally set to the return from ProtocolReceivePacket resets to 0, the NDIS library calls the indicating driver's MiniportReturnPacket function with the released packet descriptor.
NdisReturnPackets cannot be called from ProtocolReceivePacket.
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Ndis.h.
See Also
NdisAllocatePacket | NdisFreePacket | NdisMIndicateReceivePacket | MiniportReturnPacket | ProtocolReceiveComplete | ProtocolReceive | ProtocolReceivePacket
Send Feedback on this topic to the authors