NdisSendPackets function
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.
NdisSendPackets forwards a multipacket send request, possibly with associated out-of-band information, to the underlying driver.
Syntax
VOID NdisSendPackets(
_In_ NDIS_HANDLE NdisBindingHandle,
_In_ PPNDIS_PACKET PacketArray,
_In_ UINT NumberOfPackets
);
Parameters
NdisBindingHandle [in]
Specifies the handle returned by NdisOpenAdapter that identifies the target NIC or the virtual adapter of the next-lower driver to which the caller is bound. If the underlying driver is a connection-oriented miniport driver, the protocol must call NdisCoSendPackets, rather than NdisSend.PacketArray [in]
Pointer to an array of pointers to 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 has already set up with any timestamp and/or medium-specific out-of-band information, such as packet priority, relevant to the underlying driver.NumberOfPackets [in]
Specifies the number of pointers in the packet array.
Return value
None
Remarks
Each element in the given array is a pointer to an NDIS_PACKET-type descriptor, and each packet descriptor can have caller-set TimeToSend and/or MediaSpecificInformation and MediaSpecificSize values in its associated NDIS_PACKET_OOB_DATA block. The caller must allocate each such packet descriptor with NdisAllocatePacket.
A protocol can set up this timestamp with the NDIS_SET_PACKET_TIME_TO_SEND and any out-of-band information that accompanies the send request with NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO before it calls NdisSendPackets. The underlying driver retrieves this information with the reciprocal NDIS_GET_PACKET_XXX macros.
If necessary, a protocol also can call NdisSetPacketFlags to set the packet descriptor's flags with information for the underlying driver.
If the underlying NIC driver does not export a MiniportSendPackets handler, the NDIS library makes a sequence of calls, one for each packet in the supplied array, to that driver's MiniportSend function. NDIS submits packets individually to an underlying driver's MiniportSend function in the same order as they arrive in the supplied array.
NDIS submits packet arrays to an underlying driver's MiniportSendPackets function in the same order as they are passed to NdisSendPackets, but an underlying serialized miniport driver can return a subset of packets in any incoming array to NDIS by setting NDIS_STATUS_RESOURCES in the out-of-band data block for a single array element. When this occurs, NDIS queues that packet and all subsequent packets in the array for resubmission to the MiniportSendPackets function later.
For serialized miniports, NDIS always preserves the protocol-determined order of send packets, whether passed in calls to NdisSend or NdisSendPackets, and sees that they are given to the underlying driver in FIFO order. Before a protocol driver calls NdisSendPackets with an array of packet descriptor pointers, the protocol must ensure that the array of pointers has been set up in the same order as the packets should be sent over the wire.
The caller of NdisSendPackets should test the returned status for each packet in such an array individually when its ProtocolSendComplete function is called with the completion Status. While NDIS submits packets for transmission in the FIFO order determined by the sending protocol, underlying drivers might complete such sends in random order.
If the underlying driver is a deserialized miniport driver, it must accept all incoming send packets and queue them internally, if necessary. A deserialized miniport driver should preserve the protocol-determined ordering of packet descriptors that bound protocols submit to NdisSendPackets while they are held in its internal queue. A deserialized driver always completes sends asynchronously. Consequently, protocols bound to a deserialized miniport driver should always consider the Status value passed in to their ProtocolSendComplete functions the final status of the requested send.
As soon as a protocol calls NdisSendPackets, it relinquishes ownership of the following:
All packet descriptors 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 out-of-band data blocks
The protocol regains ownership of these resources, one packet at a time, as its ProtocolSendComplete function is called with each packet descriptor in the array given to NdisSendPackets.
When a packet descriptor is returned to ProtocolSendComplete, it can call NdisReinitializePacket to prepare the packet for reuse after saving the buffer descriptors chained to the packet descriptor with calls to an NdisUnchainBufferAtXxx function. Reusing such a packet descriptor yields better performance than returning the descriptor to driver-allocated packet pool with NdisFreePacket and, then, reallocating it for another send later.
ProtocolSendComplete also can prepare the out-of-band block associated with the given packet descriptor for reuse if the protocol supplies any out-of-band information. Alternatively, the protocol can explicitly reinitialize the members it uses when setting up the packet descriptor for a subsequent send.
An NDIS intermediate driver must repackage each incoming send from still higher level protocols in fresh packet descriptors before passing such a send request to the underlying miniport driver with NdisSendPackets(or NdisSend).
Requirements
Target platform |
Universal |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisSendNetBufferListsinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
<= DISPATCH_LEVEL |
See also
NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO