TDI_EVENT_RECEIVE

The TDI_EVENT_RECEIVE event handler is called when incoming data arrives for a connection. The called client may take all, some, or none of the indicated data during the call to the handler, and may also optionally pass back a pointer to a buffer to receive remaining or newly arrived data. There are some intricacies relating to when a receive event handler will be called if it has recently been called or there is a receive buffer outstanding. For more information, refer to the Windows NT/Windows 2000 TDI documentation.

Since TCP is a stream-oriented protocol, there is no restriction on the minimum number of bytes that will be indicated in a receive event call.

TDI_STATUS
  RcvEvent(
    PVOID  EventContext, 
    PVOID  ConnectionContext,  
    ulong  Flags, 
    uint  Indicated, 
    uint  Available, 
    uint  *Taken, 
    uchar  *Data, 
    EventRcvBuffer  *Buffer
    );

Parameters

EventContext

Context value supplied on the TdiSetEvent call.

ConnectionContext

Context for the connection object receiving the data. This context was supplied by the client as a parameter to the TdiOpenConnection call that opened the connection.

Flags

Supplies information about the receive indication. The most interesting flag is TDI_RECEIVE_ENTIRE_MESSAGE. If this flag is set, the PUSH bit was set on the segment containing the data being delivered. See the Windows NT/Windows 2000 TDI documentation for more details on the flags.

Indicated

Count 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 may be supplied either by returning a pointer in the EventRcvBuffer structure or by calling TdiReceive.

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 Available. Note that this may be greater than indicated, which allows the client to skip data that has arrived but not been indicated if it needs. Taken is only examined if TDI_MORE_PROCESSING or TDI_SUCCESS is returned. In these cases, 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

Pointer to a buffer of received data. The length of the buffer is given by Indicated.

Buffer

Pointer to an EventRcvBuffer structure. The client may fill in this structure to give the transport a buffer into which to place data. This structure is only examined if the status TDI_MORE_PROCESSING is returned. The buffer returned by the client may be larger than the size indicated by Available. In this case, the buffer will be retained for more arriving data.

Comments

There are three relevant status codes that the client can return from the call to the event handler.

Note  If TDI_MORE_PROCESSING or TDI_SUCCESS is returned, the client must set Taken to be the count of the number of bytes consumed. If there is data that the client does not consume and there is no receive buffer provided, the VxD transport will make a best effort attempt to buffer the data for later consumption. However, if the transport is unable to allocate memory, the data is dropped and will need to be retransmitted.