New class to perform TCP connections

With the release of 4D 20 R8, a game-changing feature has arrived:: the TCPConnection class. This modern class leverages object-oriented syntax and supports asynchronous network connection handling, providing a fresh and powerful alternative to the 4D Internet Commands. Using TCPConnection, you can connect to virtually anything—whether it’s servers, printers, cash registers, or industrial devices—making it a versatile tool for handling unique networking requirements.

In this release, the TCP client functionality is available, allowing you to connect to external servers and seamlessly exchange data.

HDI TCPConnections

To demonstrate the potential of TCPConnection, this post will walk you through a simple implementation using a singleton class that simplifies TCP communication.

Tutorial with a simple singleton class

Let’s use a shared singleton class called “ConnectionToTheServer”, which is a simplification of the class used in the HDI:

Shared Singleton Class constructor()

//Connect to a server
Function connect($address : Text; $port : Integer)

    This.connection:=4D.TCPConnection.new($address; $port; This)

//Disconnect from the server
Function disconnect()

    This.connection.shutdown()
    This.connection:=Null

//Send a text to the server
Function sendText($text : Text)

    var $blob : Blob
    TEXT TO BLOB($text; $blob; UTF8 text without length)
    This.sendBlob($blob)

//Send a blob to the server
Function sendBlob($blob : Blob)

    This.connection.send($blob)

//Callback called when the connection is successfully established
Function onConnection($connection : 4D.TCPConnection; $event : 4D.TCPEvent)

    ALERT("Connection established")

//Callback called when the connection is properly closed
Function onShutdown($connection : 4D.TCPConnection; $event : 4D.TCPEvent)

    ALERT("Connection closed")

//Callback called when receiving data. The simple servers always send a sentence to show to the user
Function onData($connection : 4D.TCPConnection; $event : 4D.TCPEvent)

    ALERT(BLOB to text($event.data; UTF8 text without length))

//Callback called when the connection is closed unexpectedly
Function onError($connection : 4D.TCPConnection; $event : 4D.TCPEvent)

    ALERT("Connection error")

Using this class is very simple. First, the connect function connects to a server:

cs.ConnectionToTheServer.me.connect("server IP address or domain name";1234/*server port*/)

The connect function instantiates the TCPConnection object and also connects to the server. It also takes a third parameter which is an option object. This object is important as it has to implement all the callbacks. In this example, and for the sake of simplicity, the singleton is used directly as it implements all the callbacks.

Once connect has been called, data can be sent to the server either by calling sendText or sendBlob:

cs.ConnectionToTheServer.me.sendText("The text to send to the server")

TCPConnection only sends blobs of data. To send a text, it first needs to be converted to a blob like in the sendText function.

To retrieve data from the server, callbacks have to be used. The first callback called is onConnection. onConnection is called when the connection is actually established to the server. It is possible to send data before onConnection is called, in that case the data is kept and sent when the connection is established. It’s even possible to connect, send data and shutdown without waiting: In that case, the connection will be established, the data will be sent and once all the data is sent the connection will be closed.

Another important callback is onData: It is called everytime the TCPConnection receives data from the server. The data received is accessible in the $event.data blob, that can be used as is or turned into text with the BLOB to text command like in the example.

Last but not least: After connecting, sending and receiving, the last important part of a connection is closing. There are 3 ways for a connection to be closed: Either the server closes the connection, the client closes the connection or a connection error occurs and you get disconnected.

When the server closes the connection, the onShutdown callback is called.

To shutdown the connection on the client side, you can call:

cs.ConnectionToTheServer.me.disconnect()

A call to disconnect will also call the onShutdown callback (as the connection is being closed).

And finally, if a connection error occurs forcing the connection to close, the onError callback is called. The onError callback is also called if the connection to the server fails.

Conclusion

As you can see, the TCPConnection class is incredibly easy to use while providing robust functionality. Whether you’re sending or receiving data, it ensures reliable communication with external devices or servers.

If you have questions or need additional support, feel free to reach out on the 4D forum.