ProtocolTransferDataComplete

The ProtocolTransferDataComplete function is a required driver function if the protocol might bind itself to an underlying connectionless NIC driver that does not indicate full-packet receives with NdisMIndicateReceivePacket. ProtocolTransferDataComplete completes the processing of a protocol-initiated transfer-data request for which NdisTransferData returned NDIS_STATUS_PENDING.

Exclusively connection-oriented protocols need no ProtocolTransferDataComplete function.

VOID
  ProtocolTransferDataComplete(
    IN NDIS_HANDLE  ProtocolBindingContext,
    IN PNDIS_PACKET  Packet,
    IN NDIS_STATUS  Status,
    IN UINT  BytesTransferred
    );

Parameters

ProtocolBindingContext

Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding run-time state. The driver supplied this handle when it called NdisOpenAdapter.

Packet

Pointer to the protocol-allocated packet descriptor the driver originally passed to NdisTransferData.

Status

Specifies the final status of the transfer-data operation.

BytesTransferred

Specifies the number of bytes of data that the NIC driver transferred into the buffers mapped by buffer descriptors chained to the packet descriptor at Packet. The protocol uses this value to determine whether the miniport driver supplied all the requested data for the originally indicated network packet.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

ProtocolTransferDataComplete can be called before NdisTransferData returns control. If this occurs, the protocol driver has no opportunity to inspect the status code that NdisTransferData returns at Status. The protocol must assume that the given packet descriptor at Packet was pending until ProtocolTransferDataComplete was called.

When the underlying NIC driver calls NdisMTransferDataComplete, NDIS forwards the miniport driver-supplied Packet pointer and Status value to ProtocolTransferDataComplete. When this occurs, the protocol regains ownership of the resources it allocated for a preceding call to NdisTransferData. ProtocolTransferDataComplete can postprocess the miniport driver-supplied data in the buffers the protocol chained to the packet descriptor at Packet, along with the data ProtocolReceive copied in the corresponding indication. Then, ProtocolTransferDataComplete can notify interested clients of the received network data.

ProtocolTransferDataComplete also can either release the resources that the protocol allocated for its call to NdisTransferData or prepare the returned buffer and packet descriptors for reuse in a subsequent call to NdisTransferData. 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, ProtocolTransferDataComplete should follow these guidelines:

• Always call an NdisUnchainBufferAtXxx function as many times as necessary to save the buffer descriptor pointers before ProtocolTransferDataComplete 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. In effect, the protocol loses a set of buffer descriptors that the protocol allocated with NdisAllocateBuffer, and possibly loses access to the protocol-allocated buffers mapped by these descriptors as well.

• Never call NdisZeroMemory with a pointer to a packet descriptor. Use NdisReinitializePacket instead.

  Otherwise, NdisZeroMemory destroys the packet descriptor the protocol allocated with NdisAllocatePacket, rendering it unusable for specifying subsequent data transfers and sends.

ProtocolTransferDataComplete runs at IRQL = DISPATCH_LEVEL.

See Also

MiniportTransferData, NdisAllocateBuffer, NdisFreeBuffer, NdisFreeMemory, NdisFreePacket, NdisMIndicateReceivePacket, NdisMTransferDataComplete, NdisReinitializePacket, NdisTransferData, NdisUnchainBufferAtBack, NdisUnchainBufferAtFront, NdisZeroMemory, ProtocolReceive, ProtocolReceivePacket