TCPConnection

A classe TCPConnection permite gerenciar conexões de cliente TCP (Transmission Control Protocol) com um servidor, possibilitando o envio e o recebimento de dados e a manipulação de eventos do ciclo de vida da conexão usando retornos de chamada.

A classe TCPConnection está disponível no repositório de classes 4D. Você pode criar uma conexão TCP usando a função 4D.TCPConnection.new(), que retorna um objeto TCPConnection.

Todas as funções da classe TCPConnection são thread-seguras.

Graças ao objeto 4D padrão refcounting, um TCPConnection é automaticamente liberado quando não for mais referenciado. Consequentemente, os recursos associados são devidamente limpos sem a necessidade de fechamento explícito.

Os objetos TCPConnection são liberados quando não houver mais referências a eles na memória. Isso geralmente ocorre, por exemplo, no final da execução de um método para variáveis locais. Se quiser "forçar" o fechamento de uma conexão a qualquer momento, nullify suas referências, definindo-as como Null.

4DTCPUDPLog.txt file

For debugging and monitoring, you can use the 4DTCPUDPLog.txt log file that records events related to TCP connections. Events include data transmission, errors, and connection lifecycle information.

História

Release	Mudanças
20 R9	Novos atributos listener, address e port
20 R8	Classe adicionada

Exemplos

Os exemplos a seguir demonstram como usar as classes 4D.TCPConnection e 4D.TCPEvent para gerenciar uma conexão de cliente TCP, manipular eventos, enviar dados e fechar adequadamente a conexão. São fornecidos exemplos síncronos e assíncronos.

Exemplo síncrono

Este exemplo mostra como estabelecer uma conexão, enviar dados e encerrá-la usando um objeto simples para configuração:

var $domain : Text := "127.0.0.1"
var $port : Integer := 10000
var $options : Object := New object() // Objeto de configuração
var $tcpClient : 4D.TCPConnection
var $message : Text := "test message"

// Abra uma conexão
$tcpClient := 4D.TCPConnection.new($domain; $port; $options)

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

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

Exemplo assíncrono

Este exemplo define uma classe que lida com o ciclo de vida e os eventos da conexão, demonstrando como trabalhar de forma assíncrona:

// Definição de classe: cs.MyAsyncTCPConnection

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

// Conectar-se a um dos servidores lançados dentro dos workers
Function connect()
    This.connection := 4D.TCPConnection.new(This.url; This.port; This)

// Desconectar do servidor
Function disconnect()
    This.connection.shutdown()
    This.connection := Null

// Enviar dados para o servidor
Function getInfo()
    var $blob : Blob
    TEXT TO BLOB("Information"; $blob)
    This.connection.send($blob)

// Callback chamado quando a conexão é estabelecida com sucesso
Function onConnection($connection : 4D.TCPConnection; $event : 4D.TCPEvent)
    ALERT("Connection established")

// Callback chamado quando a conexão é fechada corretamente
Function onShutdown($connection : 4D.TCPConnection; $event : 4D.TCPEvent)
    ALERT("Conexão fechada")

// Callback chamado ao receber dados do servidor
Function onData($connection : 4D.TCPConnection; $event : 4D.TCPEvent)
    ALERT(BLOB to text($event.data; UTF8 text without length))

	//Warning: Não há garantia de que você receberá todos os dados de que precisa em um único pacote de rede.
	
// Chamada de retorno quando a conexão é fechada inesperadamente
Function onError($connection : 4D.TCPConnection; $event : 4D.TCPEvent)
    ALERT("Erro de conexão")

// Chamada de retorno após onShutdown/onError, logo antes de o objeto TCPConnection ser liberado
Function onTerminate($connection : 4D.TCPConnection; $event : 4D.TCPEvent)
	ALERT("Conexão encerrada")

Exemplos de uso

Crie um novo método chamado AsyncTCP, para inicializar e gerenciar a conexão TCP:

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

Chamar o método AsyncTCP em um worker:

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

Objeto TCPConnection

Um objeto TCPConnection é um objeto não compartilhável.

Os objetos TCPConnection fornecem as seguintes propriedades e funções:

address : Text o endereço IP ou nome de domínio da máquina remota
closed : Boolean se a conexão está fechada
errors : Collection uma coleção de objetos de erro associados à conexão
listener : Object o objeto TCPListener que criou a TCPConnection, se houver
noDelay : Boolean se o algoritmo de Nagle está desativado (true) ou ativado (false)
port : Number o número da porta da máquina remota
.send( data : Blob ) envia dados para o servidor
.shutdown() fecha o canal de gravação da conexão (fluxo do cliente para o servidor)
.wait( { timeout : Real } ) aguarda até que a conexão TCP seja fechada ou o timeout especificado seja atingido

4D.TCPConnection.new()

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

Parâmetro	Tipo		Descrição
serverAddress	Text	->	Nome de domínio ou endereço IP do servidor
serverPort	Integer	->	Número da porta do servidor
options	Object	->	Configuração opções para a conexão
Resultados	4D.TCPConnection	<-	Novo objeto TCPConnection

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.TCPConnection object.

options parameter

No parâmetro options, passe um objeto que possa conter as seguintes propriedades:

Propriedade	Tipo	Descrição	Por padrão
onConnection	Formula	Callback acionado quando a conexão for estabelecida.	Indefinido
onData	Formula	Callback acionado quando os dados forem recebidos	Indefinido
onShutdown	Formula	Callback acionado quando a conexão for fechada corretamente	Indefinido
onError	Formula	Callback acionado no caso de um erro	Indefinido
onTerminate	Formula	Callback acionada imediatamente antes de a TCPConnection ser liberada	Indefinido
noDelay	Parâmetros	Somente leitura Desabilita o algoritmo do Nagle se true	False
connectionTimeout	Real	Tempo máximo (em segundos) para estabelecer a conexão. Se excedido, a tentativa de conexão será abortada	Definido pelo sistema, geralmente ≥ 30

Funções Callback

Todas as funções de chamada de retorno recebem dois parâmetros de objectos:

Parâmetro	Tipo	Descrição
$connection	objeto TCPConnection	A instância de conexão TCP atual.
$event	objeto TCPEvent	Contém informações sobre o evento.

Sequência de chamadas de retorno:

1. O onConnection é acionado quando a conexão é estabelecida.
2. onData é acionado cada vez que os dados são recebidos.
3. O onShutdown ou o onError estão ativados:
   • O onShutdown é acionado quando a conexão for fechada corretamente.
   • onError é acionado se ocorrer um erro.
4. O onTerminate é sempre acionado logo antes de a TCPConnection ser liberada (a conexão é fechada ou ocorre um erro).

Objeto TCPEvent

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

.address

address : Text

Descrição

A propriedade .address contém o endereço IP ou nome de domínio da máquina remota.

.closed

closed : Boolean

Descrição

A propriedade .closed contém se a conexão está fechada. Retorna true se a conexão for fechada, seja devido a um erro, uma chamada para shutdown(), ou fechamento pelo servidor.

.errors

errors : Collection

Descrição

A propriedade .errors contém uma coleção de objetos de erro associados à conexão. Cada objeto de erro inclui o código de erro, uma descrição e a assinatura do componente que causou o erro.

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

.listener

listener : Object

Descrição

A propriedade .listener contém o objeto TCPListener que criou a TCPConnection, se houver. Essa propriedade é somente leitura.

.noDelay

noDelay : Boolean

Descrição

A propriedade .noDelay contém se o algoritmo de Nagle está desativado (true) ou ativado (false). Essa propriedade é somente leitura.

.port

port : Number

Descrição

A propriedade .port contém o número da porta da máquina remota . Essa propriedade é somente leitura.

.send()

.send( data : Blob )

Parâmetro	Tipo		Descrição
data	Blob	->	Dados a serem enviados

Descrição

A função send() envia dados para o servidor. Se a conexão ainda não foi estabelecida, os dados são enviados assim que a conexão for estabelecida.

.shutdown()

.shutdown()

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

Descrição

A função shutdown() fecha o canal de gravação da conexão (fluxo do cliente para o servidor) e mantém o canal de leitura (fluxo do servidor para o cliente) aberto, permitindo que você continue recebendo dados até que a conexão seja totalmente fechada pelo servidor ou ocorra um erro.

.wait()

.wait( { timeout : Real } )

Parâmetro	Tipo		Descrição
timeout	Real	->	Tempo máximo de espera em segundos

Descrição

A função wait() aguarda até que a conexão TCP seja fechada ou o timeout especificado seja atingido

nota

Durante a execução do .wait(), as funções de retorno de chamada são executadas, sejam elas originadas de outras instâncias do SystemWorker. Você pode sair de um .wait() chamando shutdown() de um retorno de chamada.