Sending Packets from a Connectionless Protocol Driver (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.
A connectionless protocol driver can call NdisSendto transmit a single packet. It passes in a pointer to a packet descriptor with chained buffer descriptors, mapping the buffered data to be sent. Alternatively, a connectionless protocol driver can transmit several packets using NdisSendPackets. In this case, it passes in a pointer to an array of pointers to one or more packet descriptors.
You can choose to call NdisSendor NdisSendPacketsbased upon the driver's requirements and on the characteristics of the underlying miniport driver.
A connectionless protocol driver should call NdisRequestwith an OID_GEN_MAXIMUM_SEND_PACKETSquery request when it has bound itself to an underlying miniport driver. This OID allows the protocol driver to determine the maximum number of send packets that the underlying driver will accept in a packet array.
If the miniport driver supports only single-packet send operations, either at its MiniportSendor its MiniportSendPacketsfunction, the value returned from an OID_GEN_MAXIMUM_SEND_PACKETS will be one or, possibly, NDIS_STATUS_NOT_SUPPORTED. Either of these return values implies the protocol driver is likely to call NdisSendrather than NdisSendPackets. If the underlying driver returns a value greater than one, both drivers' performance will be better if the protocol driver sends an array of packets with NdisSendPackets.
If OOB information is passed between the protocol driver and the miniport driver, either NdisSendor NdisSendPacketscan be called. In either case, the underlying driver can read the OOB data using NDIS-supplied macros
Whenever a protocol driver calls NdisSend, it relinquishes ownership of the given packet resources until the send completes, either synchronously or asynchronously. If the status returned by NdisSendis something other than NDIS_STATUS_PENDING, the send completes synchronously and ownership of the protocol-allocated packet resources reverts to the protocol driver. If the status returned by NdisSendis NDIS_STATUS_PENDING, when the send subsequently completes, NDIS passes the final status of the send and the protocol-allocated packet descriptor to the ProtocolSendCompletefunction.
When a protocol driver calls NdisSendPacketsto transmit one or more packets, send operations are always asynchronous. The protocol driver relinquishes ownership of the packet resources that it allocated until NDIS returns each packet descriptor and the final status of the send operation to ProtocolSendComplete.
As a consequence, a protocol driver never reads the Statusmember in the OOB block associated with a packet descriptor on return from NdisSend(or NdisSendPackets). The protocol driver cannot learn the status of its send request in this manner because this member is in use by NDIS to track the progress of an in-transition send request and is volatile until the packet descriptor is returned to ProtocolSendComplete. A protocol driver always obtains the status of a transmit request either by examining the value returned by NdisSendor from the Statusparameter passed to ProtocolSendComplete.
A protocol driver can request the transmission of an array of packets of different priorities by arranging the packets it receives from clients. The protocol driver should place the highest priority packets at the beginning of the array. NDIS always preserves the order of packets in any array passed to NdisSendPackets, even if NDIS queues some of the packets internally.
NDIS does not attempt to examine and make queuing decisions based on any of the OOB data associated with the packet descriptors given to NdisSendPackets(or to NdisSend). Unless a protocol driver has special knowledge of the manner in which the underlying miniport driver handles packet priorities or the TimeToSendtime stamps, the protocol should assume that the underlying miniport driver transmits all packets in the order in which they are received. Consequently, a protocol should order the packet arrays it sends according to the order in which those packets should be transmitted over the network.