TDI_EVENT_RECEIVE_DATAGRAM

The TDI_EVENT_RECEIVE_DATAGRAM event handler is called when an incoming datagram is received. As with the TDI_EVENT_RECEIVE event, the called client may take all, some, or none of the data, and may optionally pass back a buffer for unconsumed data. Unlike stream data, datagrams are not buffered, so any data the client does not consume is lost if no buffer is provided on the return. Also, MSTCP will not queue datagram receive buffers for later use if they are returned from an event handler. Thus, if a client consumes all the datagram and passes back a buffer, the buffer will be completed immediately with a length of zero.

TDI_STATUS
  RcvDGEvent(
    PVOID  EventContext, 
    uint  AddressLength,  
    PTRANSPORT_ADDRESS  Address, 
    uint  OptionsLength, 
    PVOID  Options,  
    uint  Flags, 
    uint  Indicated, 
    uint  Available,  
    uint  *Taken, 
    uchar  *Data, 
    EventRcvBuffer  **Buffer    );

Parameters

EventContext: Context value supplied on the TdiSetEvent call.
AddressLength: Length in bytes of the structure pointed to by Address.
Address: Pointer to a TRANSPORT_ADDRESS structure identifying the remote peer that sent the datagram. This structure is valid only for the duration of the call to the event handler.
OptionsLength: Length in bytes of Options.
Options: Pointer to a buffer containing IP options received with the datagram. This buffer is valid only for the duration of the call to the event handler, and may be NULL if there were no options.
Flags: Set of TDI flags providing more information about the event. In the VxD environment, they are largely meaningless and may be ignored. See the Windows NT/Windows 2000 TDI documentation for more details on the flags.
Indicated: Is a cCount of the number of bytes of data being indicated (for example, the number of bytes in the buffer pointed to by Data).
Available: Count of the total number of bytes of data available in the transport. This value will always be greater than or equal to Indicated. If Available is greater than Indicated, then there is data available that is not being passed up in the event handler, and the called client will need to supply a receive buffer to retrieve it. The receive buffer must be supplied either by returning a pointer to an EventRcvBuffer structure. If Available is greater than Indicated and the client does not provide an EventRcvBuffer structure, the additional data will be lost.
Taken: Pointer to a location where the client may fill in the total number of bytes taken on the indication. The client may set Taken to zero if no data was consumed. The maximum value to which Taken may be set is Indicated. This is different from the TDI_EVENT_RECEIVE handler, where the maximum value of Taken is Available. If a client wants to consume the indicated data and discard the rest, it should return TDI_SUCCESS. Taken is only examined if TDI_MORE_PROCESSING is returned. In this case, the transport assumes that the first Taken bytes of data were consumed by the client and will not copy this data into a client buffer.
Data: Is a pointer to a buffer of received data. The length of the buffer is given by Indicated.
Buffer: Pointer to a pointer to an EventRcvBuffer structure If the client wants to return a receive buffer, it should set Buffer to a pointer to a filled in EventRcvBuffer structure describing the buffer chain and providing a callback routine. Note that this is different from the TDI_EVENT_RECEIVE case, where the transport provides the EventRcvBuffer structure and the client merely fills it in. This structure is only examined if the status TDI_MORE_PROCESSING is returned. The client-provided EventRcvBuffer structure must remain valid until the completion routine is called. The completion routine is generally called immediately.

Comments

The status codes that can be returned from a receive datagram event are TDI_MORE_PROCESSING, TDI_NOT_ACCEPTED, and TDI_SUCCESS. They have the same meaning as when they are returned from an ordinary TDI_EVENT_RECEIVE handler.