Receive Method

Overview

Task

Read data stored in the receive buffer and remove it.

Functional Description

Reads data stored in the receive buffer and removes it from there if it has been read without detecting an error.

The UDINT return value indicates the number of bytes written to the application-provided buffer.

For additional information about the receive methods, refer to section Receive Method.

Considerations for Connections Using TLS

The behavior of the methods Peek and Receive might be different for the connections with TLS and without TLS. Especially when large data packets are exchanged. When executing the methods on a connection using TLS, it might be required that several method calls must be executed until all data are copied or moved to the application buffer. In every case before processing the data, verify the amount of data which was copied or moved and whether the data are complete.

Interface

Used by

• FB_TCPClient/FB_TCPClient2

Receive Methods

The methods for receiving of data, provided by the function blocks FB_TCPClient/FB_TCPClient2 and FB_TCPServer/FB_TCPServer2 in this library provide the input/output parameter iq_udiFillLevel. This parameter determines the offset in the buffer, and therefore where the data is written. On each execution of the function the value is updated by adding the number of the written bytes to the original value.

In cases where data are received in several packets, but have to be stored in one buffer and are processed later as a whole, the respective receive function can be called several times without modifying the parameter iq_udiFillLevel from the last function call.

The difference of the receive-buffer size (i_udiReceiveBufferSize) and the fill level is used to determine the maximum number of bytes to be read.

Function Call Example

The following graphics illustrate the content of the buffer and the modification of parameter iq_udiFillLevel for two function calls, whereby the function was executed successfully each time.

Stage	Description	Illustration
1	Before the first call of the function, the pointer is set to the first index of the buffer. The fill level is set to 0. The parameter i_udiReceiveBufferSize indicates the absolute size of the buffer in bytes.
2	On each function call, the buffer is erased from the start of the fill level. During the first function call in this example, the available data was moved from the TCP stack into the buffer. The fill level is updated by the function and indicates the number of read bytes in the buffer. When the TCP stack has memory space available, the remote client or server is informed about the available space, as a result, it sends the subsequent data packet. The second function call is executed without any modification of the input parameters.
3	During the second function call, the available data is moved again from the TCP stack into the buffer. The fill level is updated by the function and then, the value is equal to the value of i_udiReceiveBufferSize. This means that the receive-buffer is full. A further function call would be aborted with the result FillLevelOutOfRange. Finally, if the receive-buffer is full, you need to process the data and to update the value of the fill level for the buffer accordingly.

Data Limits per Function Call

Depending on the controller, the amount of data to be moved in one function call of one of the Receive, Send or Peek methods is limited.