NdisSendPackets (Windows Embedded CE 6.0)

1/6/2010

This function forwards a multipacket send request, possibly with associated out-of-band information, to the underlying driver.

Syntax

VOID NdisSendPackets(
  NDIS_HANDLE NdisBindingHandle,
  PPNDIS_PACKET PacketArray,
  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.

• PacketArray
  [in] Points 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 time stamp 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 time stamp 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 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 it sets up the array of pointers in the order that 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, it must accept all incoming send packets and queue them internally, if necessary. A deserialized miniport 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 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 a driver-allocated packet pool with NdisFreePacket and, then, reallocating it for a later send.

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 send requests to the underlying miniport with NdisSendPackets or NdisSend.

Requirements

See Also

Reference

NDIS Library Functions
MediaSpecificInformation
MiniportSend
MiniportSendPackets
NDIS_PACKET_OOB_DATA
NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO
NDIS_SET_PACKET_TIME_TO_SEND
NdisAllocateBuffer
NdisAllocatePacket
NdisFreePacket
NdisOpenAdapter
NdisReinitializePacket
NdisSend
NdisSetPacketFlags
NdisUnchainBufferAtBack
NdisUnchainBufferAtFront
ProtocolSendComplete