NdisReturnPackets function

Article
06/19/2017

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisReturnPackets releases ownership of one or more packets after a protocol has consumed the received data.

Syntax

VOID NdisReturnPackets(
  _In_ PNDIS_PACKET *PacketsToReturn,
  _In_ UINT         NumberOfPackets
);

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 value

None

Remarks

An NDIS intermediate driver should call NdisReturnPackets as soon as possible after its ProtocolReceivePacket or ProtocolCoReceivePacket 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.

An NDIS intermediate driver or NDIS protocol driver must not call NdisReturnPackets to return a particular NDIS packet until the ProtocolReceivePacket or ProtocolCoReceivePacket function that received that packet has completed and returned a reference count for that packet.

When an underlying NIC driver runs low on available packet pool for receive indications or when its NIC runs low on empty receive buffers, it sets a packet descriptor's associated OOB block Status to NDIS_STATUS_RESOURCES:

If the underlying NIC driver is a connectionless driver, this forces the NDIS library to call every bound protocol driver's ProtocolReceive function with a single packet descriptor at a time until the miniport driver has regained ownership of its packet descriptors and the NIC has receive buffers available for incoming net packets.
If the underlying NIC driver is a connection-oriented driver, this forces the NDIS library to call every bound protocol driver's ProtocolCoReceivePacket function with a single packet descriptor at a time until the miniport driver has regained ownership of its packet descriptors and the NIC has receive buffers available for incoming net packets.

A ProtocolReceive function cannot begin postprocessing 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 a connectionless protocol's ProtocolReceivePacket function or to a connection-oriented protocol's ProtocolCoReceivePacket function with an associated OOB Status of NDIS_STATUS_SUCCESS, 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 massage the data 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 client(s) by forwarding the input packet descriptor to those clients.

If an intermediate protocol driver's Protocol(Co)ReceivePacket function returns a nonzero reference count to an input packet descriptor, that driver must call NdisReturnPackets one or more times. When it has called NdisReturnPackets with a particular packet descriptor as many times as the value returned by Protocol(Co)ReceivePacket, the NDIS library returns the packet descriptor to the driver that made the indication. For a highest level protocol that forwards an input packet descriptor to its clients, those clients return the packet descriptor to the NDIS driver that allocated it by making calls to TdiReturnChainedReceives.

A protocol driver can rely on NDIS to manage the reference count for every receive packet passed to the Protocol(Co)ReceivePacket function. When the reference count for a packet descriptor originally set to the return from Protocol(Co)ReceivePacket goes to zero, the NDIS library calls the indicating driver's MiniportReturnPacket function with the released packet descriptor.

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisReturnNetBufferListsinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL