TdiReturnChainedReceives

TdiReturnChainedReceives

VOID
TdiReturnChainedReceives(
IN PVOID *TsduDescriptors,
IN ULONG NumberOfTsdus
);

TdiReturnChainedReceives returns an array of TSDU descriptors for one or more chained receive indications previously forwarded to a transport's client, which returned STATUS_PENDING for each such chained receive indication.

Parameters

TsduDescriptors

Points to an array of descriptors of type NDIS_PACKET.

NumberOfTsdus

Specifies the number of elements in the array at TsduDescriptors.

Comments

For faster network throughput, a TDI transport can pass to its clients direct (but read-only) access to a chain of buffers containing a full received network packet, subject to the following conditions:

·The transport registered an NDIS ProtocolReceivePacket function with NdisRegisterProtocol, so it can receive indications that permit direct, read-only access to the contents of the underlying NIC driver's receive buffer(s). If the transport is bound directly to the driver of a physical NIC, rather than to an NDIS intermediate driver, its ProtocolReceivePacket function is given access to the NIC's receive buffer(s).

·The transport is bound to a underlying NIC driver that calls NdisMIndicateReceivePacket to make receive indications, thereby allowing any bound protocol that supplies a ProtocolReceivePacket function to hold on to received data in the NIC driver's receive buffer(s) until the protocol no longer needs the indicated packet. Such a receive indication is always a full network packet, mapped by the buffer descriptors (MDLs) chained to each indicated NDIS_PACKET-type TSDU descriptor.

·The client has registered its handler for TDI_EVENT_CHAINED_RECEIVE or TDI_EVENT_RECEIVE_DATAGRAM events with the transport.

When such a transport's ProtocolReceivePacket function is called, it can forward the receive indication to the appropriate ClientEventReceive(Datagram) function, giving the client the opportunity to process the indicated TSDU without the overhead of double buffering such a received packet in the transport. If the ClientEventReceive(Datagram) callback returns STATUS_PENDING, the client retains exclusive read-only access to the indicated packet until that client calls TdiReturnChainedReceives with the TSDU descriptor. Its call to TdiReturnChainedReceives returns the indicated descriptor and all resources that it describes to the underlying NDIS driver that originally allocated the packet descriptor.

Any packets indicated by the underlying NDIS driver to the transport's ProtocolReceive function must be forwarded to such a client's ClientEventReceive, ClientEventReceiveExpedited, or ClientEventReceiveDatagram function. Calls to these client event handlers direct the client to make a copy of the indicated data as quickly as possible, and ClientEventReceive(Expedited/Datagram) relinquishes the client's access to the buffer(s) containing the indicated data when the event handler returns control.

Only kernel-mode clients with registered ClientEventChainedReceive, ClientEventChainedReceiveExpedited, and/or ClientEventChainedReceiveDatagram handlers call TdiReturnChainedReceives.

Callers of TdiReturnChainedReceives run at IRQL <= DISPATCH_LEVEL.