CO_SEND_COMPLETE_HANDLER callback 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.
The ProtocolCoSendComplete function is a required driver function in connection-oriented protocol drivers. ProtocolCoSendComplete completes the processing of a protocol-initiated send previously passed to NdisCoSendPackets.
Syntax
CO_SEND_COMPLETE_HANDLER ProtocolCoSendComplete;
VOID ProtocolCoSendComplete(
_In_ NDIS_STATUS Status,
_In_ NDIS_HANDLE ProtocolVcContext,
_In_ PNDIS_PACKET Packet
)
{ ... }
Parameters
Status [in]
Specifies the final status of the send operation, either NDIS_STATUS_SUCCESS or an error status propagated from the underlying driver.ProtocolVcContext [in]
Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-VC run-time state. The driver originally supplied this handle either when it called NdisCoCreateVc or from its ProtocolCoCreateVc function. This context area contains the NdisVcHandle that the driver previously passed to NdisCoSendPackets.Packet [in]
Pointer to the protocol-supplied packet descriptor for the completed send.
Return value
None
Remarks
ProtocolCoSendComplete performs whatever postprocessing is necessary for a completed transmit operation, such as notifying the client that originally requested the protocol to send data over the network on the VC.
Completion of a send operation usually implies that the underlying NIC driver actually has transmitted the given packet over the network. However, the driver of a so-called intelligent NIC can consider a send complete as soon as it downloads the net packet to its NIC. The underlying driver's call to NdisMCoSendComplete causes NDIS to call the ProtocolCoSendComplete function.
When ProtocolCoSendComplete is called, the driver regains ownership of the following protocol-allocated resources:
The packet descriptor at Packet
All buffer descriptors chained to the packet descriptor that map buffers containing the net packet data and any protocol-allocated buffers mapped by these descriptors
Any out-of-band block associated with the packet descriptor
Any protocol-allocated buffer specified in the out-of-band block at MediaSpecificInformation
Consequently, ProtocolCoSendComplete can either release these resources or prepare them for reuse in a subsequent call to NdisCoSendPackets. As a general rule, reusing such resources yields better performance than releasing them except, possibly, in periods of low network traffic if the protocol previously allocated a surplus of these resources to handle a period of heavy I/O demand.
To prepare the buffer and packet descriptors for reuse, ProtocolCoSendComplete should follow these guidelines:
Always call an NdisUnchainBufferAtXxx function as many times as necessary to save the buffer descriptor pointers before ProtocolCoSendComplete calls NdisReinitializePacket with the descriptor at Packet.
Otherwise, NdisReinitializePacket sets the head of the buffer chain to NULL so the protocol cannot recover pointers to the buffer descriptors chained to the packet descriptor. Either the protocol loses MDL(s) mapping client-supplied buffer(s) or it loses a set of buffer descriptors the protocol allocated with NdisAllocateBuffer.
Always pass the pointer returned by NDIS_OOB_DATA_FROM_PACKET to NdisZeroMemory to clear an associated out-of-band data block, never the Packet pointer.
Otherwise, NdisZeroMemory destroys the packet descriptor the protocol allocated with NdisAllocatePacket, rendering it unusable for specifying subsequent sends.
As an alternative to clearing the out-of-band block, the protocol can reinitialize only those members that the protocol normally sets up for sends with the appropriate NDIS_SET_PACKET_XXX macros.
Until ProtocolCoSendComplete is called, the current status of a protocol-initiated send is volatile. A protocol temporarily releases ownership of all resources it allocated for a send when it calls NdisCoSendPackets, even if the protocol supplies out-of-band information with the packet descriptors it allocates for sends. In particular, a protocol should never attempt to examine the Status member of the associated out-of-band data block when NdisCoSendPackets returns control.
Although NDIS always submits protocol-supplied packet arrays to the underlying miniport driver in the protocol-determined order passed in calls to NdisCoSendPackets, the underlying driver can complete the given packets in random order. That is, every bound protocol can rely on NDIS to submit the packets the protocol passes to NdisCoSendPackets in FIFO order to the underlying driver, but no protocol can rely on that underlying driver to call NdisMCoSendComplete with those packets in the same order.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolCoSendNetBufferListsCompleteinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP |
Header |
Ndis.h (include Ndis.h) |
IRQL |
<= DISPATCH_LEVEL |
See also
NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO