W_CO_SEND_PACKETS_HANDLER callback function

Article
06/19/2017

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.

The MiniportCoSendPackets is required for connection-oriented miniports. MiniportCoSendPackets is called to transfer some number of packets, specified as an array of pointers, over the network.

Syntax

W_CO_SEND_PACKETS_HANDLER MiniportCoSendPackets;

VOID MiniportCoSendPackets(
  _In_ NDIS_HANDLE   MiniportVcContext,
  _In_ PPNDIS_PACKET PacketArray,
  _In_ UINT          NumberOfPackets
)
{ ... }

Parameters

MiniportVcContext [in]
Specifies the handle to a miniport driver-allocated context area in which the miniport driver maintains its per-VC state. The miniport driver supplied this handle to NDIS from its MiniportCoCreateVc function.
PacketArray [in]
Pointer to the initial element in a packet array, with each element specifying the address of a packet descriptor for a packet to be transmitted, along with an associated out-of-band data block containing information such as the packet priority, an optional timestamp, and the per-packet status to be set by MiniportCoSendPackets.
NumberOfPackets [in]
Specifies the number of pointers to packet descriptors at PacketArray.

Return value

None

Remarks

MiniportCoSendPackets is called by NDIS in response to a request by a bound protocol driver to send a ordered list of data packets across the network.

MiniportCoSendPackets should transmit each packet in any given array sequentially. MiniportCoSendPackets can call NdisQueryPacket to extract information, such as the number of buffer descriptors chained to the packet and the total size in bytes of the requested transfer. It can call NdisGetFirstBufferFromPacket, NdisGetFirstBufferFromPacketSafe, NdisQueryBuffer, NdisQueryBufferSafe, or NdisQueryBufferOffset to extract information about individual buffers containing the data to be transmitted.

MiniportCoSendPackets can retrieve protocol-supplied out-of-band information associated with each packet by using the appropriate NDIS_GET_PACKET_XXX macros.

MiniportCoSendPackets can use only the eight-byte area at MiniportReserved within the NDIS_PACKET structure for its own purposes.

The NDIS library ignores the OOB block in all packet descriptors it submits to MiniportCoSendPackets and assumes that every connection-oriented miniport driver is a deserialized driver that will complete each input packet descriptor asynchronously with NdisMCoSendComplete. Consequently, such a deserialized driver's MiniportCoSendPackets function usually ignores the Status member of the NDIS_PACKET_OOB_DATA block, but it can set this member to the same status as it subsequently passes to NdisMCoSendComplete.

Rather than relying on NDIS to queue and resubmit send packets whenever MiniportCoSendPackets has insufficient resources to transmit the given packets, a deserialized miniport driver manages its own internal packet queuing. Such a driver is responsible for holding incoming send packets in its internal queue until they can be transmitted over the network and for preserving the protocol-determined ordering of packet descriptors incoming to its MiniportCoSendPackets function. A deserialized miniport driver must complete each incoming send packet with NdisMCoSendComplete, and it cannot call NdisMSendResourcesAvailable.

A deserialized miniport driver should never pass STATUS_INSUFFICIENT_RESOURCES to NdisMCoSendComplete with a protocol-allocated packet descriptor that was originally submitted to its MiniportCoSendPackets function. Such a returned status effectively fails the send operation requested by the protocol, and NDIS would return the packet descriptor and all associated resources to the protocol that originally allocated it.

MiniportCoSendPackets can be called at any IRQL <= DISPATCH_LEVEL. Consequently, MiniportCoSendPackets function is responsible for synchronizing access to its internal queue(s) of packet descriptors with the driver's other MiniportXxx functions that also access the same queue(s).

Requirements

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use MiniportCoSendNetBufferLists instead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP.
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL (see Remarks section)

Partager via