fnModifyTCPWindow()

USOCKET fnModifyTCPWindow(USOCKET TCPSocket, unsigned short usBufferSpace);

TCPSocket is the number of the TCP socket whose receive windows size is to be updated.

usBufferSpace is the new free receive buffer space available to the socket.


This routine is only available when the project define CONTROL_WINDOW_SIZE is active.

The routine can be used to update the size of the free buffer space available to the TCP sockets receiver. Only the local socket's information is updated and no announcement is made across an open TCP connection on this socket. See fnReportTCPWindow() when active reporting is required.

The function returns the TCP socket's number if the update was successful or the error SOCKET_NOT_FOUND if the socket could not be found.

If the project define ANNOUNCE_MAX_SEGMENT_SIZE is not active the maximum buffer size that will be announced is limited to the size of the Ethernet buffer space TCP_MAX_WINDOW_SIZE.

The receive TCP buffer size set to the socket is referenced to the memory available for receive frames to be stored to. This could also be theoretical space since the user is responsible for copying received data from the Etherent buffer to this storage area. The window size announced to the remote TCP partner allows its transmitter to optimise the transmission of bulk data. It will generally attempt to send as much data as possible to fill the receiver's window. If the receiver's window reduces in size it means that the available space for storage is decreasing and so the transmitter can also be quelched (flow control) by announcing smaller values.

A good example of the use of the receiver window size is when the received TCP data is being relayed to a serial output which has its own transmitter buffer space. By reporting the size of the serial buffer to the TCP socket the remote TCP partner knows how much data can be sent and still be accepted for transfer to the serial interface. If the serial interface operation is stalled, due to flow control for example, its output buffer can still be filled with data arriving from the TCP connection. As long as the TCP socket's receiver window reflects the available space in the serial output, the flow control will then operate along the complete length of the transmission patch, back to the transmitter at the remote TCP partner. After a stall has been removed and there is adequate space in the serial buffer, the new window size can be reported by calling fnReportTCPWindow() with the new free buffer size.

fnModifyTCPWindow() is generally called from within a call back function to set the new receive window size that will then be reported when the socket sends an ACK, which could also be piggy-backed with an immediate transmission.

Example

This example shows how a TCP call back function relays received data to a serial interface and also updates the TCP receive window size accordingly.

static int fnRS232Listener(USOCKET Socket, unsigned char ucEvent, unsigned char *ucIp_Data, unsigned short usPortLen)
        ....
        case TCP_EVENT_DATA:
        {
            unsigned short usBufferSpace = fnWrite(RS232_handle, 0, usPortLen); // check the buffer space after copying the received data
            fnModifyTCPWindow(Socket, usBufferSpace);       // set the new receive window size
            fnWrite(RS232_handle, ucIp_Data, usPortLen);    // transfer the received data to the RS232 connection
            break;
        }
        ....


See the following forum thread for additional details about working with TCP sockets: µTasker forum TCP discussion.

Related functions

fnGetTCP_Socket();
fnReleaseTCP_Socket();
fnReportTCPWindow(); fnGetTCP_state();
fnTCP_Activity();
fnTCP_Connect();
fnTCP_close();




Please use the µTasker forum to ask specific questions.