ClientEventChainedReceiveDatagram routine
The ClientEventChainedReceiveDatagram routine is an event handler that the underlying TDI transport calls in response to an incoming receive from a remote node that was directed to a local-node transport address opened by the client.
The transport calls this handler, rather than ClientEventReceiveDatagram, when it is forwarding a full TSDU indicated to the transport by an NDIS miniport driver and the client can be given direct read-only access to the buffered TSDU until the client has consumed the data.
Syntax
NTSTATUS ClientEventChainedReceiveDatagram(
_In_ PVOID TdiEventContext,
_In_ LONG SourceAddressLength,
_In_ PVOID SourceAddress,
_In_ LONG OptionsLength,
_In_ PVOID Options,
_In_ ULONG ReceiveDatagramFlags,
_In_ ULONG ReceiveDatagramLength,
_In_ ULONG StartingOffset,
_In_ PMDL Tsdu,
_In_ PVOID TsduDescriptor
);
Parameters
TdiEventContext [in]
Pointer to the client-supplied context provided in the IRP that was set up with TdiBuildSetEventHandler when ClientEventChainedReceiveDatagram was registered with the underlying transport.SourceAddressLength [in]
Specifies the size in bytes of the buffer at SourceAddress.SourceAddress [in]
Pointer to a buffer specifying the remote-node transport address from which the datagram was sent.OptionsLength [in]
Specifies the size in bytes of the buffer at Options. Zero implies no option string is available. Options is NULL if this parameter is zero.Options [in]
Pointer to a buffer specifying a string of transport-specific options sent with the datagram. This pointer is NULL if OptionsLength is zero.ReceiveDatagramFlags [in]
Specifies the nature of the receive-datagram indication as a combination (ORed) of the following flags:TDI_RECEIVE_ENTIRE_MESSAGE
The buffer mapped at Tsdu contains a full TSDU, and the client retains read-only access to this buffer until the client consumes the indicated data if ClientEventChainedReceiveDatagram returns STATUS_PENDING. This flag is always set when ClientEventChainedReceiveDatagram is called.TDI_RECEIVE_BROADCAST
The receive was broadcast.TDI_RECEIVE_MULTICAST
The receive was multicast.
ReceiveDatagramLength [in]
Specifies the number of bytes of client data in the buffer mapped at Tsdu.StartingOffset [in]
Specifies the byte offset at which the client data starts within the buffer mapped at Tsdu.Tsdu [in]
Pointer to an MDL, possibly the initial MDL in a chain, mapping the buffer containing the received TSDU.TsduDescriptor [in]
Pointer to a descriptor for the received TSDU. The client must call TdiReturnChainedReceives with this pointer subsequently if ClientEventChainedReceiveDatagram returns STATUS_PENDING for this receive indication. This pointer should be treated as a handle to an opaque variable, to be used by the client only as a parameter to TdiReturnChainedReceives if ClientEventChainedReceiveDatagram returns STATUS_PENDING.
Return value
ClientEventChainedReceiveDatagram can return one of the following:
| Return code | Description |
|---|---|
| STATUS_SUCCESS | Indicates the client consumed all the data in the given TSDU and is returning ownership of the buffer to the underlying driver immediately. |
| STATUS_PENDING | Indicates the client is retaining ownership of the buffer containing the given TSDU until it calls TdiReturnChainedReceives with the given TsduDescriptor. |
| STATUS_DATA_NOT_ACCEPTED | Indicates the client is not interested in the TSDU. |
Remarks
When a datagram arrives from a remote node, the transport calls the registered ClientEvent(Chained)ReceiveDatagram handlers for each client with an open file object representing an address that matches the destination address of the datagram. Because a datagram is not associated with an established connection, the TDI driver passes the transport address of the remote-node sender at SourceAddress to the receiving client along with the datagram.
A call to ClientEventChainedReceiveDatagram gives the client read-only access to the indicated TSDU for the range within the buffer specified by the input StartingOffset and ReceiveLength. If the indicated data is of interest to the client, ClientEventChainedReceiveDatagram either copies the indicated range of TSDU data into a client-allocated internal buffer and returns STATUS_SUCCESS immediately or retains control of the buffer by returning STATUS_PENDING. If it returns STATUS_PENDING, the client must call TdiReturnChainedReceives subsequently with the input TsduDescriptor to relinquish control of the buffer after the client has consumed the data.
In general, such a call to TdiReturnChainedReceives should occur as quickly as possible. Holding on to a buffer passed to ClientEventChainedReceiveDatagram for any extended period constrains I/O throughput in underlying driver(s), because the NDIS miniport driver that allocated the buffer cannot reuse this resource for subsequent receive indications until TdiReturnChainedReceives is called.
Because calls to ClientEventChainedReceiveDatagram always indicate the availability of a full TSDU, the client never has to set up TDI_RECEIVE_DATAGRAM requests for such an indication, as the corresponding ClientEventReceiveDatagram handler sometimes must to obtain a full TSDU. Consequently, receive indications made to ClientEventChainedReceiveDatagram increase network I/O throughput and performance by decreasing call overhead for the client, for its underlying transport, and for the system overall. A transport never calls the corresponding ClientEventReceiveDatagram handler with the same indication it makes to ClientEventChainedReceiveDatagram.
When ClientEventChainedReceiveDatagram returns control with either STATUS_SUCCESS or STATUS_DATA_NOT_ACCEPTED, the underlying transport assumes the client is done with this receive indication. If the client returns STATUS_PENDING, the transport assumes it has no way of tracking completion of this receive indication because the client is responsible for calling TdiReturnChainedReceives when it has consumed the indicated TSDU.
The underlying TDI transport does not call ClientEventChainedReceiveDatagram if the client has an outstanding receive or receive-datagram request on the local transport address that is the target of an incoming datagram.
To receive indications for broadcast datagrams that the TDI driver receives on the network, the client must open the broadcast address of its underlying transport and register its ClientEvent(Chained)ReceiveDatagram handler(s).
ClientEventChainedReceiveDatagram must be capable of carrying out its operations at IRQL = DISPATCH_LEVEL.
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 |
Desktop |
Header |
Tdikrnl.h (include TdiKrnl.h) |
IRQL |
DISPATCH_LEVEL (see Remarks section) |
See also