MacTransferData

MacTransferData

NDIS_STATUS
MacTransferData(
IN NDIS_HANDLE MacBindingHandle,
IN NDIS_HANDLE MacReceiveContext,
IN UINT ByteOffset,
IN UINT BytesToTransfer,
OUT PNDIS_PACKET Packet,
OUT PUINT BytesTransferred
);

MacTransferData is called when a protocol driver calls NdisTransferData.

Parameters

MacBindingHandle

Specifies the handle that the NIC driver associates with the binding.

MacReceiveContext

Specifies the context value that the NIC driver associates with a packet received from the network. The driver uses this value to determine which packet to transfer on which NIC.

ByteOffset

Specifies the offset within the packet at which this function begins the transfer data operation. If the function is to copy the entire packet, ByteOffset must be zero.

BytesToTransfer

Specifies the number of bytes to transfer. The sum of the ByteOffset and BytesToTransfer values must be less than or equal to the value of the packet size (specified by NdisIndicateReceive, EthIndicateReceive, FddiFilterIndicateReceive, or TrFilterIndicateReceive). The NIC driver does not modify the trailing portion of the packet. This parameter can be zero.

Packet

Points to a protocol-supplied memory location in which MacTransferData returns the packet descriptor for the transferred data.

BytesTransferred

Points to a protocol-supplied variable in which this function returns the number of bytes transferred. This value is invalid if MacTransferData returns NDIS_STATUS_PENDING, so it should be set to zero when MacTransferData handles these requests asynchronously.

Return Value

MacTransferData can return the following status codes:

NDIS_STATUS_FAILURE
NDIS_STATUS_NOT_ACCEPTED
NDIS_STATUS_NOT_INDICATING
NDIS_STATUS_PENDING
NDIS_STATUS_REQUEST_ABORTED
NDIS_STATUS_RESET_IN_PROGRESS
NDIS_STATUS_SUCCESS

Comments

NdisTransferData instructs a NIC driver to access a packet it has received from its NIC. MacTransferData copies packet data into the given packet buffers, but it does not copy the packet header. The values at ByteOffset and BytesToTransfer, which are provided by the protocol driver, do not include the packet header.

A protocol driver can call NdisTransferData from its ProtocolReceive function only once per receive indication. Because several protocol drivers can have a single network interface card open and each such protocol driver can receive transferred data, MacTransferData must be capable of transferring a packet more than once. If the NIC driver services a network interface card from which it can read a packet only once, the driver must copy receive packets into a staging buffer when several protocol drivers are bound to its NIC.

If it finishes the transfer-data operation before it returns control, MacTransferData returns a status code other than NDIS_STATUS_PENDING.

For asynchronous transfers, MacTransferData returns NDIS_STATUS_PENDING, and the NIC driver cannot deliver any more receive indications to the protocol driver designated by the MacBindingHandle while the transfer-data operation is pending. The NIC driver eventually calls NdisCompleteTransferData, which, in turn, calls the ProtocolTransferDataComplete function of the driver that initiated the data transfer. This asynchronous completion allows protocol postprocessing of the transfer-data request.

A MacTransferData function that handles requests asynchronously makes NIC DMA operations more efficient. Drivers for PIO NICs usually support NdisTransferData synchronously.

MacTransferData runs at IRQL DISPATCH_LEVEL.