TCPConnection

The TCPConnection class allows you to manage Transmission Control Protocol (TCP) client connections to a server, enabling you to send and receive data, and handle connection lifecycle events using callbacks.

The TCPConnection class is available from the 4D class store. You can create a TCP connection using the 4D.TCPConnection.new() function, which returns a TCPConnection object.

All TCPConnection class functions are thread-safe.

Thanks to the standard 4D object refcounting, a TCPConnection is automatically released when it is no longer referenced. Consequently, the associated resources, are properly cleaned up without requiring explicit closure.

TCPConnection objects are released when no more references to them exist in memory. This typically occurs, for example, at the end of a method execution for local variables. If you want to "force" the closure of a connection at any moment, nullify its references by setting them to Null.

História

Release	Mudanças
20 R8	Classe adicionada

Exemplos

The following examples demonstrate how to use the 4D.TCPConnection and 4D.TCPEvent classes to manage a TCP client connection, handle events, send data, and properly close the connection. Both synchronous and asynchronous examples are provided.

Synchronous Example

This example shows how to establish a connection, send data, and shut it down using a simple object for configuration:

var $domain : Text := "127.0.0.1"
var $port : Integer := 10000
var $options : Object := New object() // Configuration object
var $tcpClient : 4D.TCPConnection
var $message : Text := "test message"

// Open a connection
$tcpClient := 4D.TCPConnection.new($domain; $port; $options)

// Send data
var $blobData : Blob
TEXT TO BLOB($message; $blobData; UTF8 text without length)
$tcpClient.send($blobData)

// Shutdown
$tcpClient.shutdown()
$tcpClient.wait(0)

Asynchronous Example

This example defines a class that handles the connection lifecycle and events, showcasing how to work asynchronously:

// Class definition: cs.MyAsyncTCPConnection

Class constructor($url : Text; $port : Integer)
    This.connection := Null
    This.url := $url
    This.port := $port

// Connect to one of the servers launched inside workers
Function connect()
    This.connection := 4D.TCPConnection.new(This.url; This.port; This)

// Disconnect from the server
Function disconnect()
    This.connection.shutdown()
    This.connection := Null

// Send data to the server
Function getInfo()
    var $blob : Blob
    TEXT TO BLOB("Information"; $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 from the server
Function onData($connection : 4D.TCPConnection; $event : 4D.TCPEvent)
    ALERT(BLOB to text($event.data; UTF8 text without length))

	//Warning: There's no guarantee you'll receive all the data you need in a single network packet.
	
// Callback called when the connection is closed unexpectedly
Function onError($connection : 4D.TCPConnection; $event : 4D.TCPEvent)
    ALERT("Connection error")

// Callback called after onShutdown/onError just before the TCPConnection object is released
Function onTerminate($connection : 4D.TCPConnection; $event : 4D.TCPEvent)
	ALERT("Connection terminated")

Usage example

Create a new method named AsyncTCP, to initialize and manage the TCP connection:

var $myObject : cs.MyAsyncTCPConnection
$myObject := cs.MyAsyncTCPConnection.new("myURL"; 10000)
$myObject.connect()
$myObject.getInfo()
$myObject.disconnect()

Call the AsyncTCP method in a worker:

CALL WORKER("new process"; "Async_TCP")

TCPConnection Object

A TCPConnection object is a non-sharable object.

TCPConnection objects provide the following properties and functions:

errors : Collection a collection of error objects associated with the connection
noDelay : Boolean whether Nagle's algorithm is disabled (true) or enabled (false)
.send( data : Blob ) envia dados para o servidor
.shutdown() closes the write channel of the connection (client to server stream)
.wait( { timeout : Real } ) waits until the TCP connection is closed or the specified timeout is reached

4D.TCPConnection.new()

4D.TCPConnection.new( serverAddress : Text ; serverPort : Number ; options : Object ) : 4D.TCPConnection

Parâmetro	Tipo		Descrição
serverAddress	Text	->	Domain name or IP address of the server
serverPort	Integer	->	Port number of the server
options	Object	->	Configuração opções para a conexão
Resultados	TCPConnection	<-	New TCPConnection object

Descrição

The 4D.TCPConnection.new() function creates a new TCP connection to the specified serverAddress and serverPort, using the defined options, and returns a 4D.HTTPRequest object.

options parameter

In the options parameter, pass an object that can contain the following properties:

Propriedade	Tipo	Descrição	Por padrão
onConnection	Formula	Callback triggered when the connection is established.	Indefinido
onData	Formula	Callback triggered when data is received	Indefinido
onShutdown	Formula	Callback triggered when the connection is properly closed	Indefinido
onError	Formula	Callback triggered in case of an error	Indefinido
onTerminate	Formula	Callback triggered just before the TCPConnection is released	Indefinido
noDelay	Parâmetros	Read-only Disables Nagle's algorithm if true	False

Funções Callback

All callback functions receive two parameters:

Parâmetro	Tipo	Descrição
$connection	objeto TCPConnection	The current TCP connection instance.
$event	objeto TCPEvent	Contains information about the event.

Sequence of Callback Calls:

1. onConnection is triggered when the connection is established.
2. onData is triggered each time data is received.
3. Either onShutdown or onError is triggered:
   • onShutdown is triggered when the connection is properly closed.
   • onError is triggered if an error occurs.
4. onTerminate is always triggered just before the TCPConnection is released (connection is closed or an error occured).

TCPEvent object

Um objeto TCPEvent é retornado quando uma função de callback é chamada.

.closed

closed : Boolean

Descrição

A propriedade .closed contém se a conexão está fechada. Returns true if the connection is closed, either due to an error, a call to shutdown(), or closure by the server.

.errors

errors : Collection

Descrição

The .errors property contains a collection of error objects associated with the connection. Each error object includes the error code, a description, and the signature of the component that caused the error.

Propriedade		Tipo	Descrição
errors		Collection	pilha de erros 4D em caso de erro
	[].errCode	Number	Código de erro 4D
	[].message	Text	Descrição do erro 4D
	[].componentSignature	Text	Assinatura da componente interna que devolveu o erro

.noDelay

noDelay : Boolean

Descrição

The .noDelay property contains whether Nagle's algorithm is disabled (true) or enabled (false). Essa propriedade é somente leitura.

.send()

.send( data : Blob )

Parâmetro	Tipo		Descrição
data	Blob	->	Data to be sent

Descrição

A função send() envia dados para o servidor. If the connection is not established yet, the data is sent once the connection is established.

.shutdown()

.shutdown()

Parâmetro	Tipo		Descrição
			Não exige nenhum parâmetro

Descrição

The shutdown() function closes the write channel of the connection (client to server stream) while keeping the read channel (server to client stream) open, allowing you to continue receiving data until the connection is fully closed by the server or an error occurs.

.wait()

.wait( { timeout : Real } )

Parâmetro	Tipo		Descrição
timeout	Real	->	Maximum wait time in seconds

Descrição

The wait() function waits until the TCP connection is closed or the specified timeout is reached

nota

During the .wait() execution, callback functions are executed, whether they originate from other SystemWorker instances. Você pode sair de um .wait() chamando shutdown() de um retorno de chamada.