ProtocolTransferDataComplete (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function is a required driver function if the protocol might bind itself to an underlying connectionless network adapter 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.

Syntax

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

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-allocated packet descriptor the driver originally passed to NdisTransferData.
  • Status
    [in] Specifies the final status of the transfer-data operation.
  • BytesTransferred
    [in] Specifies the number of bytes of data that the network adapter 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 supplied all the requested data for the originally indicated network packet.

Return Value

None.

Remarks

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 network adapter driver calls NdisMTransferDataComplete, NDIS forwards the miniport-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 post-process the miniport-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.

Requirements

Header ndis.h
Library Ndislib.lib
Windows Embedded CE Windows CE .NET 4.0 and later

See Also

Reference

NDIS Lower-Edge Functions
NdisAllocateBuffer
NdisAllocatePacket
NdisMIndicateReceivePacket
NdisOpenAdapter
NdisReinitializePacket
NdisTransferData
NdisZeroMemory
ProtocolReceive