Sending Packets on a VC (NDIS 5.1)
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.
To send packets over the network, a connection-oriented client or call manager calls NdisCoSendPackets. A connection-oriented client associated with an MCM driver also calls NdisCoSendPackets. An MCM driver, however, never calls NdisCoSendPackets; instead, since the interface between the call manager and MCM driver is internal to the MCM driver, the MCM driver passes packets directly to the NIC without notifying NDIS.
The following figure shows a client or call manager sending packets through a miniport driver.
.png)
The next figure shows a client sending packets through an MCM driver.
.png)
Before calling NdisCoSendPackets, the client or call manager should set up an array of packet pointers in the same order that the packets should be sent over the wire. The client or a call manager then calls NdisCoSendPackets, passing (among other things) a pointer to the array of packet pointers and an NdisVcHandlethat identifies the VC on which the packets should be sent.
As soon as the client or call manager 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 (OOB) data blocks associated with the packet descriptors, including any medium-specific buffers specified in the OOB blocks
A call to NdisCoSendPacketscauses NDIS to call the miniport driver's MiniportCoSendPacketsfunction. MiniportCoSendPacketsshould transmit each packet in the array sequentially, preserving the order of packets in the array. MiniportCoSendPacketscan call NdisQueryPacketto extract information, such as the number of buffer descriptors chained to the packet and the total size in bytes of the requested transfer.
MiniportCoSendPacketscan call NdisGetFirstBufferFromPacket(Safe), NdisQueryBuffer(Safe), or NdisQueryBufferOffsetto extract information about individual buffers containing the data to be transmitted. MiniportCoSendPacketscan retrieve protocol-supplied OOB information associated with each packet by using the appropriate NDIS_GET_PACKET_XXX macros. The MiniportCoSendPacketsfunction usually ignores the Statusmember of the NDIS_PACKET_OOB_DATA block, but it can set this member to the same status that it subsequently passes to NdisMCoSendComplete.
Rather than relying on NDIS to queue and resubmit send packets whenever MiniportCoSendPacketshas insufficient resources to transmit the given packets, a connection-oriented miniport driver manages its own internal packet queuing. The miniport driver must hold incoming send packets in its internal queue until they can be transmitted over the network. This queue preserves the protocol-determined ordering of packet descriptors incoming to the miniport's MiniportCoSendPacketsfunction.
A connection-oriented miniport driver must complete each incoming send packet with NdisMCoSendComplete. It cannot call NdisMSendResourcesAvailable. A connection-oriented miniport driver should never pass STATUS_INSUFFICIENT_RESOURCES to NdisMCoSendCompletewith a protocol-allocated packet descriptor that was originally submitted to its MiniportCoSendPacketsfunction.
The call to NdisMCoSendCompletecauses NDIS to call the ProtocolCoSendCompletefunction of the client that initiated the send operation. ProtocolCoSendCompleteperforms any postprocessing necessary for a completed transmit operation, such as notifying the client that originally requested the protocol to send data over the network on the VC.
Completion of a send operation usually implies that the underlying NIC driver actually has transmitted the given packet over the network. However, the driver of an "intelligent" NIC can consider a send complete as soon as it downloads the net packet to its NIC.
After ProtocolCoSendCompleteis called, the driver regains ownership of the following protocol-allocated resources:
The packet descriptor
All buffer descriptors chained to the packet descriptor that map buffers containing the net packet data and any protocol-allocated buffers mapped by these descriptors
Any OOB block associated with the packet descriptor
Any protocol-allocated buffer specified in the OOB block
Although NDIS always submits protocol-supplied packet arrays to the underlying miniport driver in the protocol-determined order passed in calls to NdisCoSendPackets, the underlying driver can complete the given packets in random order. That is, every bound protocol can rely on NDIS to submit the packets the protocol passes to NdisCoSendPacketsin FIFO order to the underlying driver, but no protocol can rely on that underlying driver to call NdisMCoSendCompletewith those packets in the same order.