Multipacket Sends from Connection-Oriented Miniport Drivers (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.
Before transmitting data, a connection-oriented miniport driver typically creates and always activates a virtual connection (VC) on which to send the data. The miniport driver then uses its MiniportCoSendPacketsfunction to send the data. After the data is sent, the miniport driver deactivates and sometimes deletes the VC on which it sent the data. For more information about creating, activating, deactivating, and deleting VCs, see Creating, Activating, Deactivating, and Deleting Virtual Connections.
The following figure illustrates a multipacket send from a connection-oriented miniport driver.
.png)
The definition of MiniportCoSendPacketsis:
VOID
MiniportCoSendPackets(
IN NDIS_HANDLE MiniportVcContext,
IN PPNDIS_PACKET PacketArray,
IN UINT NumberofPackets
);
The MiniportVcContextidentifies the virtual circuit (VC) on which the packet or packets are to be transmitted. The VC was created with a connection-oriented client's or call manager/MCM's call to NdisCoCreateVc, which caused NDIS to call the miniport driver's MiniportCoCreateVcfunction.
Each PacketArrayis a pointer to an array of pointers to one or more packet descriptors. The miniport driver is responsible for sending packets in the priority order specified by the protocol driver. NDIS does not order packets it receives from a protocol driver but passes them to the miniport driver in the order that NDIS received them from the miniport driver.
A miniport driver is not required to check the packet size; rather, the miniport driver should assume that a protocol driver will never send a packet that is too large. The protocol driver queries the miniport driver during initialization to determine the maximum packet size it supports. The protocol is responsible for passing only packets of a size supported by the miniport driver.
Each packet descriptor has associated out-of-band (OOB) data, as described in Packet Out-of-Band Data. The OOB block lets a protocol driver specify a time-to-send ( TimeToSend) to a cooperating miniport driver that supports priority sends. Although a connection-oriented miniport driver can set the Statusmember of the OOB block before returning from MiniportCoSendPackets, this member is ignored by NDIS. The other members of the NDIS_PACKET_OOB_DATA block are read-only to the miniport driver.
The NDIS library ignores the OOB block in all packet descriptors it submits to the MiniportCoSendPacketsfunctions of connection-oriented miniport drivers. NDIS assumes that connection-oriented miniport drivers will complete each packet descriptor input to their MiniportCoSendPacketsfunctions asynchronously with NdisMCoSendComplete. Consequently, MiniportCoSendPacketsusually 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 MiniportCoSendPacketslacks the resources to transmit the packets, a connection-oriented miniport driver manages its own internal packet queuing. Such a miniport driver is responsible for holding incoming send packets in its internal queue until they can be transmitted over the network. The miniport driver must also preserve the protocol-determined ordering of packet descriptors passed to its MiniportCoSendPacketsfunction. A connection-oriented miniport driver must complete each incoming send packet with NdisMCoSendComplete.
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 return of such a status would effectively fail the send operation requested by the protocol, resulting in NDIS returning the packet descriptor and all associated resources to the protocol that originally allocated it.