NdisCoSendPackets 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.

NdisCoSendPackets forwards a multipacket send on a particular VC to the underlying NIC driver for transmission over the network.

Syntax

VOID NdisCoSendPackets(
  _In_ NDIS_HANDLE   NdisVcHandle,
  _In_ PPNDIS_PACKET PacketArray,
  _In_ UINT          NumberOfPackets
);

Parameters

NdisVcHandle [in]
Specifies the handle to the VC, thereby identifying the target of the send.
PacketArray [in]
Pointer to an array of pointers to caller-allocated packet descriptors. Each packet descriptor in the array has chained buffer descriptors mapping buffers containing the data that the underlying NIC driver should transmit over the wire.

Each packet descriptor also has an associated NDIS_PACKET_OOB_DATA block, which the caller can set up with any timestamp and/or medium-specific out-of-band information relevant to the underlying driver and network medium.
NumberOfPackets [in]
Specifies the number of pointers at PacketArray.

Return value

None

Remarks

A call to NdisCoSendPackets causes NDIS to call the NIC driver's MiniportCoSendPackets function. NDIS submits packet arrays to the underlying driver's MiniportCoSendPackets function in the same order as they are passed to NdisCoSendPackets. Before a protocol calls NdisCoSendPackets, it should set up the array of packet pointers in the same order as the packets should be sent over the wire.

The caller of NdisCoSendPackets should test the returned status for each packet descriptor in such an array individually when its ProtocolCoSendComplete function is called. While NDIS always submits packets for transmission in the FIFO order determined by the sending protocol, the underlying NIC driver might complete such sends in random order.

As soon as a protocol calls NdisCoSendPackets, it relinquishes ownership of the following:

All packet descriptors accessible at PacketArray
All buffers mapped by the buffer descriptors chained to those packet descriptors
All out-of-band data blocks associated with the packet descriptors, including any medium-specific buffers specified in the OOB blocks

The allocating protocol regains ownership of these resources, one packet descriptor at a time, as its ProtocolCoSendComplete function is called with each packet descriptor in the array that it passed to NdisCoSendPackets.

Then, ProtocolCoSendComplete can either release the resources the protocol allocated or prepare these resources for reuse. During periods of average-to-high network I/O traffic, reusing the packet descriptors and buffers that a protocol allocates yields better performance than releasing buffers and the packet descriptor, only to reallocate them almost immediately for a subsequent send. However, any protocol that manages its usage of system resources carefully would not retain a large set of reusable packet descriptors with mapped buffers indefinitely after a period of high traffic falls into a sustained period of very low I/O demand. When ProtocolCoSendComplete reuses packet descriptors, it must save the buffer descriptors chained to each input packet descriptor with calls to an NdisUnchainBufferAtXxx function before it calls NdisReinitializePacket with the input packet descriptor.

Requirements

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