TdiReturnChainedReceives function
The TdiReturnChainedReceives function 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.
Syntax
VOID TdiReturnChainedReceives(
_In_ PVOID *TsduDescriptors,
_In_ ULONG NumberOfTsdus
);
Parameters
TsduDescriptors [in]
Pointer to an array of descriptors of type NDIS_PACKET.NumberOfTsdus [in]
Specifies the number of elements in the array at TsduDescriptors.
Return value
None
Remarks
For faster network throughput, a TDI transport can pass to its clients direct (but read-only) access to a chain of NDIS miniport driver-allocated buffers containing a full received network packet, subject to the following conditions:
The NDIS protocol driver at the bottom of the transport stack (or the monolithic transport) registered a ProtocolReceivePacket function with NdisRegisterProtocol, so it can receive indications that permit direct, read-only access to the contents of the underlying NDIS miniport driver's receive buffers. If the transport is bound directly to the driver of a physical NIC, its ProtocolReceivePacket function is given read-only access to the NIC's receive buffers.
The underlying NIC driver calls NdisMIndicateReceivePacket to make receive indications, thereby allowing any bound protocol that supplies a ProtocolReceivePacket function to retain read-only access to the received data in the NIC driver's receive buffers until it is consumed, possibly by one or more clients of the TDI driver at the top of the transport stack. 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 up the transport stack to the TDI driver. The TDI driver indicates the receive to the appropriate ClientEventReceive(Datagram) function, thereby 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 descriptors.
A TDI client's call to TdiReturnChainedReceives returns the indicated packet descriptors and all the associated resources directly to NDIS, bypassing the indicating TDI driver and any lower drivers in its transport stack. This allows NDIS to return the packet descriptors and associated resources more quickly to the underlying NDIS miniport driver (or NDIS intermediate driver, if any) that originally allocated the packet descriptors and chained buffer descriptors, possibly after NDIS indicates this chained receive to any other transports that also bound themselves to the same NDIS miniport driver.
Packets indicated by the underlying NDIS driver to the transport's ProtocolReceive function should be buffered internally in the transport, but they must be indicated 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 buffers containing the indicated data when the event handler returns control.
Only kernel-mode clients with registered ClientEventChainedReceive, ClientEventChainedReceiveExpedited, and/or ClientEventChainedReceiveDatagram handlers call TdiReturnChainedReceives.
Note The TDI feature is deprecated and will be removed in future versions of Microsoft Windows. Depending on how you use TDI, use either the Winsock Kernel (WSK) or Windows Filtering Platform (WFP). For more information about WFP and WSK, see Windows Filtering Platform and Winsock Kernel. For a Windows Core Networking blog entry about WSK and TDI, see Introduction to Winsock Kernel (WSK).
Requirements
Target platform |
Universal |
Header |
Tdikrnl.h (include TdiKrnl.h) |
Library |
Tdi.lib |
IRQL |
<= DISPATCH_LEVEL |
See also
ClientEventChainedReceiveDatagram
ClientEventChainedReceiveExpedited