TDI_STATUS
ClientEventReceiveDatagram (
IN PVOID TdiEventContext,
IN INT SourceAddressLength,
IN PVOID SourceAddress,
IN INT OptionsLength,
IN PVOID Options,
IN ULONG ReceiveDatagramFlags,
IN ULONG BytesIndicated,
IN ULONG BytesAvailable,
OUT ULONG * BytesTaken,
IN PVOID Tsdu,
OUT PIRP * IoRequestPacket
);
ClientEventReceiveDatagram is a routine the TDI driver calls in response to a TDI_EVENT_RECEIVE_DATAGRAM event. ClientEventReceiveDatagram copies data from a connectionless TSDU, called a “datagram,” that the TDI driver has received. The driver does not call ClientEventReceiveDatagram if the client has an outstanding receive datagram request.
Note To receive indications for broadcast datagrams that the TDI driver receives, the client must open the broadcast address object of the driver and register a ClientEventReceiveDatagram handler (see the comment in the description of TDI_RECEIVE_DATAGRAM).
The driver calls ClientEventReceiveDatagram for each client with an address matching 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 client (source address) to the receiving client along with the datagram. All datagram data is available to the TDI driver, although the driver may not pass all of it. It uses separate indications to pass datagrams that arrive after it begins an event.
When ClientEventReceiveDatagram receives the datagram, it can copy some or all of the data, issue a receive datagram request, or do both. When it has finished processing, it writes the number of bytes copied. If it wants to accept the data after making a receive datagram request, it writes a pointer to an appropriate IRP in which it issues the TDI_RECEIVE_DATAGRAM request message.
A driver that supports internal buffering should retain a datagram during the client receive datagram operation. It should keep the data to satisfy future receive datagram requests. The TDI driver specifies the total amount of buffered data in the TDI_DATAGRAM_INFO structure. A default of 4K is recommended.
Parameters
TdiEventContext
Points to the context the client specifies in an IRP when it issues the TDI_SET_EVENT_HANDLER request message to register ClientEventReceiveDatagram.
SourceAddressLength
Specifies the length, in bytes, of the buffer that SourceAddress indicates.
SourceAddress
Points to a buffer specifying the remote node client transport address for the datagram.
OptionsLength
Indicates the length, in bytes, of the buffer that Options indicates. A value of 0 implies no options.
Options
Points to a buffer specifying a string of driver-specific options sent with the datagram.
ReceiveDatagramFlags
Specifies bit flags that provide additional information about the datagram. The following bit flag is currently available:
| Bit Flag | Meaning |
| TDI_RECEIVE_COPY_LOOKAHEAD | Specifies that the driver can copy lookahead data using fast copy functions. |
BytesIndicated
Specifies the total number of datagram bytes the driver indicates. This value is always less than or equal to BytesAvailable.
BytesAvailable
Specifies the total number of bytes currently available to the driver. The driver must provide a minimum of 128 bytes of data in the indication, unless the received datagram is less than 128 bytes in length. If BytesAvailable is greater than BytesIndicated, the driver has data that it does not present when it calls ClientEventReceiveDatagram.
BytesTaken
Points to the caller–defined memory location to which ClientEventReceiveDatagram writes the number of bytes of data it copies from the datagram.
Tsdu
Points to the datagram.
IoRequestPacket
Points to the caller–defined memory location to which ClientEventReceiveDatagram writes a pointer to an IRP for a receive datagram request. If this parameter is NULL, the client will not be making such a request.
Return Value
ClientEventReceiveDatagram can return the following status codes:
STATUS_DATA_NOT_ACCEPTED
STATUS_MORE_PROCESSING_REQUIRED
STATUS_SUCCESS
For more information about status codes, see Part II, Chapter 10.
Comments
If the client decides to receive further data in a receive datagram request, the new request retrieves the data that ClientEventReceiveDatagram does not receive, along with any new data the TDI driver has available. If the client does not make a receive datagram request, it loses this data.
See Also