signed short fnReportTCPWindow(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. When this routine is called on a connected socket the new free buffer size will be reported to the TCP partner by sending a TCP ACK.

If the transmission of the TCP ACK was not possible, return values of <= 0 are :

• SOCKET_NOT_FOUND - invalid socket used
• NO_ARP_ENTRY - the destination address is not present in the local ARP table and must be resolved before the transmission can be repeated
• SOCKET_STATE_INVALID - the socket is not connected and so the ACK was not sent. The new buffer length was however set to the socket
• 0 - no data could be transmitted by the Ethernet driver. This is not expected to occur in normal situations when the Ethernet HW is operational

In the case of a return value SOCKET_STATE_INVALID, the caller doesn't need to react since the TCP layer will automatically repeat the TCP ACK once the destination address has been resolved.

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, and announced when the socket is connected, 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.

fnReportTCPWindow() is generally only used when an active reporting is required since it sends an ACK to the TCP partner. When the buffer size is updated from within a call back function the TCP layer will usually send an ACK and so automatically report changes to the window size. In these cases the routine fnModifyTCPWindow() should be used instead

Example

This example shows how the TX_FREE interrupt event, send when the UART buffer becomes empty, is used to update the TCP socket's receiver space on a socket performing Ethernet to RS232 routing. Since the RS232 buffer now has space to accept further transmissions the TCP socket can also be opened to accept more data for it.

        ....
        case INTERRUPT_EVENT:
            if (TX_FREE == ucInputMessage[MSG_INTERRUPT_EVENT]) {
                fnReportTCPWindow(LAN_RS232_socket, TX_BUFFER_SIZE);
            }
            break;
        ....

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

Related functions

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




Please use the µTasker forum to ask specific questions.