ProtocolSendComplete (Windows Embedded CE 6.0)

1/6/2010

This function is a required driver function that completes the processing of a protocol-initiated send previously passed to NdisSendPackets or NdisSend, which returned NDIS_STATUS_PENDING.

Syntax

VOID ProtocolSendComplete(
  NDIS_HANDLE ProtocolBindingContext,
  PNDIS_PACKET Packet,
  NDIS_STATUS Status
);

Parameters

• ProtocolBindingContext
  [in] Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding runtime state. The driver supplied this handle when it called NdisOpenAdapter.

• Packet
  [in] Points to the protocol-supplied packet descriptor for the completed send.

• Status
  [in] Specifies the final status of the send operation.

Return Value

None.

Remarks

ProtocolSendComplete performs whatever post-processing is necessary for a completed transmit operation, such as notifying the client that originally requested the protocol to send data over the network.

Completion of a send operation usually implies that the underlying network adapter driver actually has transmitted the given packet over the network. However, the driver of a so-called intelligent network adapter can consider a send complete as soon as it downloads the net packet to its network adapter. The underlying driver's call to NdisMSendComplete or NdisMWanSendComplete causes NDIS to call the ProtocolSendComplete function.

When ProtocolSendComplete 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, ProtocolSendComplete can either release these resources or prepare them for reuse in a subsequent call to NdisSend. 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, ProtocolSendComplete should follow these guidelines:

• Always call an NdisUnchainBufferAtXXX function as many times as necessary to save the buffer descriptor pointers before ProtocolSendComplete 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 MDLs mapping client-supplied buffers 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 ProtocolSendComplete 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 NdisSend, 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 NdisSend returns control.

Requirements

See Also

Reference

NDIS Lower-Edge Functions
NdisAllocateBuffer
NdisAllocatePacket
NdisOpenAdapter
NdisMSendComplete
NdisMWanSendComplete
NdisReinitializePacket
NdisZeroMemory
NdisSend
NdisSendPackets
ProtocolStatus
ProtocolStatusComplete