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.