Share via


W_TRANSFER_DATA_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 MiniportTransferData function is required in NIC drivers that do not indicate multipacket receives and/or media-specific information with NdisMIndicateReceivePacket and in those that do not support WAN media.

Syntax

W_TRANSFER_DATA_HANDLER MiniportTransferData;

NDIS_STATUS MiniportTransferData(
  _Out_ PNDIS_PACKET Packet,
  _Out_ PUINT        BytesTransferred,
  _In_  NDIS_HANDLE  MiniportAdapterContext,
  _In_  NDIS_HANDLE  MiniportReceiveContext,
  _In_  UINT         ByteOffset,
  _In_  UINT         BytesToTransfer
)
{ ... }

Parameters

  • Packet [out]
    Pointer to a packet descriptor with chained buffers into which MiniportTransferData should copy the received data.

  • BytesTransferred [out]
    Pointer to a variable that MiniportTransferData sets to the number of bytes it copied into the packet. This value is meaningless if MiniportTransferData returns NDIS_STATUS_PENDING.

  • MiniportAdapterContext [in]
    Specifies the handle to a miniport driver-allocated context area in which the driver maintains per-NIC state, set up by MiniportInitialize.

  • MiniportReceiveContext [in]
    Specifies the context handle previously passed to NdisMXxxIndicateReceive. The miniport driver can examine this value to determine which receive to copy.

  • ByteOffset [in]
    Specifies the offset within the received packet at which MiniportTransferData should begin the copy. If the entire packet is copied, ByteOffset is zero.

  • BytesToTransfer [in]
    Specifies how many bytes to copy. The sum of ByteOffset and BytesToTransfer should be less than or equal to the packet size that was specified in the miniport's receive indication. This value can be zero.

Return value

MiniportTransferData can return one of the following:

Return code Description
NDIS_STATUS_SUCCESS

MiniportTransferData copied the requested data into the protocol-supplied packet, and it set BytesTransferred to the number of bytes copied.

NDIS_STATUS_PENDING

The driver will complete the transfer asynchronously with a call to NdisMTransferDataComplete.

NDIS_STATUS_FAILURE

Either the data could not be copied or the input transfer range was invalid.

 

Remarks

MiniportTransferData copies the contents of the received packet to a given protocol-allocated packet.

NDIS calls MiniportTransferData when a ProtocolReceive function calls NdisTransferData. The media header associated with a packet cannot be copied; only the data portion of a packet can be copied. The range passed to NdisTransferData never includes the media header. Usually, the ByteOffset input to MiniportTransferData excludes data that the miniport driver already indicated in the lookahead buffer.

A miniport driver must be prepared to copy a given packet more than once. If its NIC supports reading a given packet only once, the miniport driver must copy each received network packet to a staging buffer.

MiniportTransferData can call NdisQueryPacket to determine how many buffer descriptors the allocating protocol has provided. The protocol is responsible for supplying a packet descriptor that accommodates the transfer it requested. MiniportTransferData can call NdisQueryBuffer or NdisQueryBufferSafe to determine how much data to copy into each protocol-supplied buffer.

MiniportTransferData can fail a request if the given ByteOffset and BytesToTransfer exceed the packet size originally indicated. Alternatively, MiniportTransferData can simply transfer all available data starting at any valid ByteOffset.

Because MiniportTransferData is asynchronous, a miniport driver that has this function cannot deliver receive indications while a transfer is pending. If MiniportTransferData returns NDIS_STATUS_PENDING, the miniport driver must call NdisMTransferDataComplete when the transfer is complete.

A driver that indicates packets with NdisMIndicateReceivePacket does not need a MiniportTransferData function because such a driver always indicates full packets to bound protocols.

Interrupts are still disabled when MiniportTransferData is called.

Requirements

Target platform

Desktop

Version

Not supported for NDIS 6.0 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

See also

MiniportInitialize

NdisGetFirstBufferFromPacket

NdisGetFirstBufferFromPacketSafe

NdisGetNextBuffer

NdisMArcIndicateReceive

NdisMEthIndicateReceive

NdisMFddiIndicateReceive

NdisMIndicateReceivePacket

NdisMoveMemory

NdisMTransferDataComplete

NdisMTrIndicateReceive

NdisQueryBuffer

NdisQueryBufferSafe

NdisQueryPacket

NdisTransferData

ProtocolReceive

 

 

Send comments about this topic to Microsoft