TLS_RECEIVE_2

Type	Function block
Description	The function block is used to receive data via TCP (Transmission Control Protocol) or (TLS (Transmission Layer Security) from a TCP/TLS-capable Ethernet device. This is done using a TCP/TLS socket. The socket must first be opened using the TLS_SOCKET_2 function block before data can be received. Once the socket is opened and a connection is established, the function block receives data from the communication partner either via a pure TCP connection or a TLS-secured connection. The type of connection used depends on the value of the START_TLS input of the TLS_SOCKET_2 function block: With START_TLS = FALSE, the function block uses a pure TCP connection to receive data. With START_TLS = TRUE, the function block receives data via a TLS-secured connection. The function block provides a security check for identifying whether the IEC application expects the data to be received unsecure (via a TCP connection) or secure (via TLS-secured connection). The security check is done by comparing the values of the RECEIVE_SECURE input of the function block and the START_TLS input of the TLS_SOCKET_2 FB. If an inconsistency of the input values is detected, for example, RECEIVE_SECURE = TRUE (IEC application requires secure reception of data) and START_TLS = FALSE (TLS protocol not yet initialized), the ERROR output is set to TRUE and the error code 16#C150 is indicated at the STATUS output. If the EN_R input (EN_R - ENable_Receive) is TRUE, the function block receives data. If data has been successfully received, the NDR output (NDR = New Data Received) is set to TRUE for each cycle in which the specified amount of data has been copied to the DATA buffer. If EN_R is still set to TRUE and new data is received in the next cycle, NDR remains TRUE and the new data is copied to the variable connected to the DATA parameter. If no new data is received, NDR is set to FALSE. The device from which data are received is indicated at the outputs SOURCE_IP (IP address of the sending device) and SOURCE_PORT (port number of the sending device). WARNING Unintended machine operation Verify that the influence of the output data cannot result in an unintended or hazardous behavior of the entire system.
Notes	The socket opened by the TLS_SOCKET_2 function block can only be used for subsequent calls of the TLS_RECEIVE_2 function block as long as the ACTIVE output of the TLS_SOCKET_2 function block is TRUE. Calling the TLS_RECEIVE_2 function block while ACTIVE = FALSE causes an error at the TLS_RECEIVE_2 function block (ERROR = TRUE and STATUS code = 0xC210 issued). The socket handle created by the TLS_SOCKET_2 function block is not compatible with the socket handle created by the TCP_SOCKET or TLS_SOCKET function block. The socket handle can only be used with the TLS_SEND_2/TLS_RECEIVE_2 function blocks. For controllers with integrated firewall, make sure that the firewall does not block the ports involved in the communication. Otherwise, the connection cannot be established. Function blocks have to be instantiated. The instance name of the function block has to be declared in the 'Variables' table of the POU where the FB is going to be used. The instance name must be unique within the POU.
Parameters	Inputs Note The input specifically relevant for the TLS communication on top of the TCP communication is RECEIVE_SECURE. The other inputs specify TCP functionality. EN_R Data type: BOOL Description: With a rising edge at the EN_R input (EN_R = ENable_Receive), the data reception is started. As long as EN_R = TRUE, receiving data is possible. HANDLE Data type: DWORD Description: Socket handle that has been opened with the TLS_SOCKET_2 function block (see also the notes above). Note Do not use a handle created with an instance of the older function block implementation TCP_SOCKET or TLS_SOCKET with the TLS_RECEIVE_2 function block. Only use handles within the same "FB generation". The parameter is only evaluated in the cycle in which the EN_R parameter switches to TRUE. EXP_DATA_CNT Data type: UDINT Description: Number of bytes of the data to be received (EXP_DATA_CNT = EXPected DATA CouNT). The number of bytes is less or equal to the number of bytes provided with the variable connected to the DATA buffer. The following applies: If the value is greater than 0, only the specified number of bytes is copied to the variable connected to the DATA buffer. If less than the specified number of bytes have been received, these bytes are appended to the already received bytes in the variable connected to the DATA buffer. The output DATA_CNT is incremented accordingly. If the EXP_DATA_CNT bytes have been received, the output NDR is set to TRUE. Otherwise further calls of this instance are necessary to receive all expected data. If more than the specified number of bytes have been received, only EXP_DATA_CNT bytes are copied to the variable connected to the DATA buffer. The output DATA_CNT is incremented accordingly and NDR is set to TRUE. The remaining bytes (received but not yet copied) can be read by the next calls of the instance. If the value is 0, all data that have been received since the last call are copied to the variable connected to the DATA buffer (with the number of copied bytes being restricted to the size of the connected variable). The output DATA_CNT is incremented accordingly. If one or more bytes have been received (DATA_CNT > 0), the output NDR is set to TRUE. The parameter is only evaluated in the cycle in which the EN_R parameter switches to TRUE. Tip: You can use the SIZEOF function to determine the size of a variable (number of bytes reserved for the variable in the controller memory). RECEIVE_SECURE Data type: BOOL Description: Determines whether the IEC application expects the data to be received unsecure (via TCP connection) or secure (via TLS-secured connection). TRUE: application expects secure data reception (via TLS-secured connection). FALSE: application expects unsecure data reception (via TCP connection). The input value is compared with the value of the START_TLS input of the TLS_SOCKET_2 FB. If an inconsistency of the input values is detected, for example, RECEIVE_SECURE = TRUE (IEC application requires secure reception of data) and START_TLS = FALSE (TLS protocol not yet initialized), the ERROR output is set to TRUE and the error code 16#C150 is indicated at the STATUS output. Input/Output DATA Data type: ANY Description: Data buffer which contains the received data. Data is transmitted as byte stream. There is no Little-/Big-Endian conversion. If the data type of the connected variable is a STRUCT (or ARRAY OF STRUCT), the variable in the controller memory may contain padding bytes which have to be considered in the incoming data stream. Outputs NDR Data type: BOOL Description: NDR (New Data Received) is set to TRUE for one cycle once the data has been received successfully. You can only evaluate the success of the transmission during the cycle while NDR = TRUE. If NDR is TRUE, the next call (if some bytes were received) will overwrite DATA (NDR may be TRUE again) If NDR is FALSE, the next call (if some bytes were received) will append the received bytes to DATA. DATA_CNT will be incremented accordingly. If the expected number of bytes is reached, NDR will be TRUE ERROR Data type: BOOL Description: If an error occurs, the ERROR output is set to TRUE. The corresponding error code is indicated at the STATUS output. See Error Codes / Status Codes for TLS_* Function Blocks. STATUS Data type: WORD Description: Provides the error code in the event of an error (ERROR = TRUE) or the current status of the function block (ERROR = FALSE). Error codes start with 16#Cxxx and status codes with 16#8xxx. See Error Codes / Status Codes for TLS_* Function Blocks. SOURCE_IP Data type: STRING Description: IP address of the device from which data have been received. In case of an error, the last valid IP address is kept. Note The string contains an IPv4 address that consists of four numbers (0 to 255) separated by dot. SOURCE_PORT Data type: UINT Description: Port number of the device from which data have been received. In case of an error, the last valid port number is kept. DATA_CNT Data type: UDINT Description: Number of successfully received bytes. The number of bytes is less or equal to the number of bytes provided with the variable connected to the DATA buffer. The parameter has to be evaluated in the cycle in which NDR = TRUE. Tip: You can use the SIZEOF function to determine the size of a variable (number of bytes reserved for the variable in the controller memory).