FB_TCPClient/FB_TCPClient2

Overview

Task

Connect to a TCP server to allow data exchange.

Functional Description

The library provides two versions of the FB_TCPClient function block. The FB_TCPClient2 is an enhanced version which supports connections using TLS (Transport Layer Security).

Whether a connection using TLS is supported depends on the controller where the FB_TcpClient2 is used. Refer to the specific manual of your controller to verify if TCP communication using TLS is supported.

The working principle for both function blocks is the same. There are some differences for the provided properties and methods which are described in the respective chapters.

The usual order of command is to call the Connect or ConnectTls method first, specifying the server IP and TCP port to connect. Afterwards, retrieve the value of the State property cyclically until it is different than Connecting. If the state is not Connected, the connection could not be established. Verify the value of the Result property to determine the reason. The method Close has to be called before another connection attempt can be started.

Once the state is Connected, and the value of the property IsWritable is TRUE, data can be exchanged using the Send and Receive methods.

To verify whether there is data ready to be read, the property IsReadable can be used.

The method Peek can be used in the same way as the method Receive. The difference is that a call to Peek leaves the data in the receive buffer of the TCP stack, and the data can be read multiple times. This can be used to determine whether enough data has arrived for processing when the length cannot be determined prior to actually having the data available. If enough data has arrived to be properly processed, use the Receive method to remove the data from the receive buffer so that there is space available for more incoming data.

To detect disconnection of the remote site, read the value of the PeerHasDisconnected property. The value of State automatically changes to Shutdown if the connection has been closed by the server. If that case occurs, remaining unprocessed data can still be read but data can no longer be sent.

To close a connection properly, call the Shutdown method. The state of the connection changes to Shutdown which allows incoming data to be read but no further data can be sent. When the incoming data has been read, processed, or is not of interest, the Close method can be called, terminating the connection.

If processing in a method is unsuccessful, it is indicated in the value of the Result property. The value of Result must be verified after every method call. The result can be reset to Ok using the ResetResult method.

Interface

The function block does not have inputs and outputs. The functionality is available via methods and properties. You do not need to call the function block directly in your application.

Implementation Example for FB_Client2

PROGRAM LibDocu_TcpClient2
VAR
    xConnect : BOOL;
    xConnectTls : BOOL;
    xClose : BOOL;
    etResult : TCPUDP.ET_Result;
    etState : TCPUDP.ET_State;
    iState : INT;
    fbTcpClient : TCPUDP.FB_TCPClient2;
    stTlsSettings : TCPUDP.ST_TlsSettingsClient;
    sIp : STRING(15) := '192.168.1.2';
    uiPort : UINT := 12345;
END_VAR

CASE iState OF
    0: // idle
        IF xConnect OR xConnectTls THEN
            IF xConnect AND_THEN fbtcpclient.Connect(sIp, uiPort) THEN
                iState := 10;
            ELSIF xConnectTls AND_THEN fbtcpclient.ConnectTls(sIp, uiPort, stTlsSettings) THEN
                iState := 10;
            ELSE
                iState := 100; // error state
        END_IF
        xConnect := xConnectTls := FALSE;
    END_IF
    10: // connecting
        CASE fbtcpclient.State OF
            TCPUDP.ET_State.Connecting:
                iState := 10; // stay in connecting
            TCPUDP.ET_State.Connected:
                iState := 20; // connected
            ELSE
                iState := 100; // unexpected state
        END_CASE
    20: // connected
        IF xClose OR fbTcpClient.State = TCPUDP.ET_State.Shutdown THEN
            xClose := FALSE;
            fbTcpClient.Close();
        END_IF
        IF fbTcpClient.State = TCPUDP.ET_State.Closing THEN
                ;
        ELSIF fbTcpClient.State = TCPUDP.ET_State.Idle THEN
            iState := 0;	
        ELSIF fbTcpClient.State <> TCPUDP.ET_State.Connected THEN
            iState := 100;
        END_IF
        (* your code comes here, e.g send data to the connected server *)

    100: // error state
        (* your code comes here*)
END_CASE
etResult := fbTcpClient.Result;
etState := fbTcpClient.State;