NTSTATUS
ClientEventReceiveDatagram (
IN PVOID TdiEventContext,
IN LONG SourceAddressLength,
IN PVOID SourceAddress,
IN LONG OptionsLength,
IN PVOID Options,
IN ULONG ReceiveDatagramFlags,
IN ULONG BytesIndicated,
IN ULONG BytesAvailable,
OUT ULONG * BytesTaken,
IN PVOID Tsdu,
OUT PIRP * IoRequestPacket
);
ClientEventReceiveDatagram 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 that the client has opened.
If this flag is clear (or if TDI_RECEIVE_PARTIAL is set by a legacy
transport), ClientEventReceiveDatagram must check the BytesAvailable
and BytesIndicated parameters to determine how much of the TSDU has
been provided. Although legacy transports continue to set the
TDI_RECEIVE_PARTIAL flag, newer transports leave clear the
TDI_RECEIVE_ENTIRE_MESSAGE flag to indicate partial TSDUs to their clients.
ClientEventReceiveDatagram can return one of the following:
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.
ClientEventReceiveDatagram accepts or rejects a TSDU that the TDI driver has received on a particular transport address that the client opened with a preceding call to ZwCreateFile. A datagram TSDU is discrete. Unlike a normal or expedited TSDU, it cannot be transmitted as a sequence of records. In other words, a full datagram is available to the TDI transport, although the driver might not pass all of it in a single call to ClientEventReceiveDatagram.
The transport has removed the transport-layer header from the TSDU before it calls ClientEventReceiveDatagram.
The driver does not call ClientEventReceiveDatagram if the client has an outstanding receive or receive-datagram request on the local transport address that is the target of an incoming datagram.
When ClientEventReceiveDatagram is called, it can do one of the following:
When it has finished copying receive data, ClientEventReceiveDatagram sets the variable at BytesTaken to the number of bytes of data accepted before it returns control.
If the ClientEventReceiveDatagram issues a receive-datagram request, the transport retrieves any data that ClientEventReceiveDatagram did not receive, along with any new data the TDI transport has available. If the client does not make such a receive-datagram request, it loses this data.
Any TDI transport driver that supports internal buffering should retain a datagram during its clients' receive-datagram operations to satisfy any subsequent receive-datagram requests. The client of such a TDI driver can determine the total amount of buffer space it allocates for received datagrams by submitting a request, set up with TdiBuildQueryInformation for the QType TDI_QUERY_DATAGRAM_INFO or TDI_QUERY_MAX_DATAGRAM_INFO. Usually, such a transport's buffer space for datagrams is around four kilobytes.
To receive indications for broadcast datagrams that the TDI driver receives on the network, the client must open the local-node broadcast address of its underlying transport and register a ClientEvent(Chained)ReceiveDatagram handler on the address.
By default, ClientEventReceiveDatagram runs at IRQL DISPATCH_LEVEL.
ClientEventChainedReceiveDatagram, ClientEventReceive, TdiBuildInternalDeviceControlIrp, TdiBuildReceiveDatagram, TdiBuildSetEventHandler, TA_ADDRESS