Aller au contenu principal
Version: 20 R8

TCPConnection

La classe TCPConnection vous permet de gérer des connexions TCP (Transmission Control Protocol) clientes à un serveur pour l'envoi et la réception des données ainsi que la gestion des événements du cycle de vie de la connexion via des rétroappels.

La classe TCPConnection est disponible dans le class store 4D. Vous pouvez créer une connexion TCP à l'aide de la fonction 4D.TCPConnection.new(), qui renvoie un objet TCPConnection.

Toutes les fonctions de la classe TCPConnection sont thread-safe.

Grâce au refcounting d'objet standard de 4D, une TCPConnection est automatiquement libérée lorsqu'elle n'est plus référencée. Par conséquent, les ressources associées sont correctement refermées sans qu'il soit nécessaire de procéder à une clôture explicite.

Les objets TCPConnection sont libérés lorsqu'il n'existe plus de références à ces objets dans la mémoire. Cela se produit généralement, par exemple, à la fin de l'exécution d'une méthode pour les variables locales. Si vous souhaitez "forcer" la fermeture d'une connexion à tout moment, nullifiez ses références en leur attribuant la valeur Null.

Historique
ReleaseModifications
20 R8Classe ajoutée

Exemples

Les exemples suivants montrent comment utiliser les classes 4D.TCPConnection et 4D.TCPEvent pour gérer une connexion client TCP, traiter les événements, envoyer des données et fermer correctement la connexion. Des exemples synchrones et asynchrones sont fournis.

Exemple synchrone

Cet exemple montre comment établir une connexion, envoyer des données et la fermer en utilisant un objet simple pour la configuration :

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

// Ouvrir une connexion
$tcpClient := 4D.TCPConnection.new($domain; $port; $options)

// Envoyer des données
var $blobData : Blob
TEXT TO BLOB($message; $blobData; UTF8 text without length)
$tcpClient.send($blobData)

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

Exemple asynchrone

Cet exemple définit une classe qui gère le cycle de vie de la connexion et les événements, et montre comment travailler de manière asynchrone :

// classe : cs.MyAsyncTCPConnection

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

// Se connecter à l'un des serveurs lancés à l'intérieur de workers
Function connect()
This.connection := 4D.TCPConnection.new(This.url ; This.port ; This)

// Se déconnecter du serveur
Function disconnect()
This.connection.shutdown()
This.connection := Null

// Envoyer des données au serveur
Function getInfo()
var $blob : Blob
TEXT TO BLOB("Information" ; $blob)
This.connection.send($blob)

// Callback appelée lorsque la connexion est établie avec succès
Function onConnection($connection : 4D.TCPConnection ; $event : 4D.TCPEvent)
ALERT("Connection established")

// Callback appelée lorsque la connexion est correctement fermée
Function onShutdown($connection : 4D.TCPConnection ; $event : 4D.TCPEvent)
ALERT("Connection closed")

// Callback appelée lors de la réception de données du serveur
Function onData($connection : 4D.TCPConnection ; $event : 4D.TCPEvent)
ALERT(BLOB to text($event.data ; UTF8 text without length))

//Attention: Il n'y a aucune garantie que vous recevrez toutes les données dont vous avez besoin dans un seul paquet réseau.

// Callback appelée lorsque la connexion est fermée de manière inattendue
Function onError($connection : 4D.TCPConnection ; $event : 4D.TCPEvent)
ALERT("Connection error")

// Callback appelé après onShutdown/onError juste avant que l'objet TCPConnection ne soit libéré
Function onTerminate($connection : 4D.TCPConnection ; $event : 4D.TCPEvent)
ALERT("Connection terminated")


Exemple d'utilisation

Créer une nouvelle méthode nommée AsyncTCP, pour initialiser et gérer la connexion TCP :

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

Appeler la méthode AsyncTCP dans un worker :

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

Objet TCPConnection

Un objet TCPConnection est un objet non partageable.

Les objets TCPConnection offrent les propriétés et fonctions suivantes :

closed : Boolean
si la connexion est fermée
errors : Collection
une collection d'objets erreur associés à la connexion
noDelay : Boolean
si l'algorithme de Nagle est désactivé (true) ou activé (false)
.send( data : Blob )
envoie les données au serveur
.shutdown()
ferme le canal écriture de la connexion (flux client vers serveur)
.wait( { timeout : Real } )
attend que la connexion TCP soit fermée ou que le timeout spécifié soit atteint

4D.TCPConnection.new()

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

ParamètresTypeDescription
serverAddressText->Nom de domaine ou adresse IP du serveur
serverPortInteger->Numéro de port du serveur
optionsObject->options de configuration de la connexion
RésultatTCPConnection<-Nouvel objet TCPConnection

Description

La fonction 4D.TCPConnection.new() crée une nouvelle connexion TCP vers les serverAddress et serverPort spécifiés, en utilisant les options définies, et renvoie un objet 4D.HTTPRequest.

Paramètre options

Dans le paramètre options, passez un objet qui peut contenir les propriétés suivantes :

PropriétéTypeDescriptionPar défaut
onConnectionFormulaCallback déclenchée lorsque la connexion est établie.Undefined
onDataFormulaCallback déclenchée lors de la réception de donnéesUndefined
onShutdownFormulaCallback déclenchée lorsque la connexion est correctement ferméeUndefined
onErrorFormulaCallback déclenchée en cas d'erreurUndefined
onTerminateFormulaCallback déclenchée juste avant que la TCPConnection ne soit libéréeUndefined
noDelayBooleanLecture seulement Désactive l'algorithme de Nagle si trueFalse

Fonctions de callback

Toutes les fonctions de callback reçoivent deux paramètres :

ParamètresTypeDescription
$connectionobjet TCPConnectionL'instance de connexion TCP courante.
$eventobjet TCPEventContient des informations sur l'événement.

Séquence des appels de callbacks :

  1. onConnection est déclenchée lorsque la connexion est établie.
  2. onData est déclenchée à chaque fois que des données sont reçues.
  3. onShutdown ou onError est déclenchée :
    • onShutdown est déclenchée lorsque la connexion est correctement fermée.
    • onError est déclenchée en cas d'erreur.
  4. onTerminate est toujours déclenchée juste avant que la TCPConnection soit libérée (la connexion est fermée ou une erreur s'est produite).

Objet TCPEvent

Un objet TCPEvent est renvoyé lorsqu'une fonction de callback est appelée.

.closed

closed : Boolean

Description

La propriété .closed indique si la connexion est fermée. Retourne true si la connexion est fermée en raison d'une erreur, d'un appel à shutdown(), ou de la fermeture par le serveur.

.errors

errors : Collection

Description

La propriété .errors contient une collection d'objets erreur associés à la connexion. Chaque objet erreur comprend le code d'erreur, une description et la signature du composant qui a provoqué l'erreur.

PropriétéTypeDescription
errorsCollectionPile d'erreurs 4D en cas d'erreur
[].errCodeNumberCode d'erreur 4D
[].messageTextDescription de l'erreur 4D
[].componentSignatureTextSignature du composant interne qui a retourné l'erreur

.noDelay

noDelay : Boolean

Description

La propriété .noDelay indiquesi l'algorithme de Nagle est désactivé (true) ou activé (false). Cette propriété est en lecture seule.

.send()

.send( data : Blob )

ParamètresTypeDescription
dataBlob->Données à envoyer

Description

La fonction send() envoie les données au serveur. Si la connexion n'est pas encore établie, les données sont envoyées une fois la connexion établie.

.shutdown()

.shutdown()

ParamètresTypeDescription
Ne requiert aucun paramètre

Description

La fonction shutdown() ferme le canal écriture de la connexion (flux client vers serveur) tout en gardant le canal lecture (flux serveur vers client) ouvert, ce qui vous permet de continuer à recevoir des données jusqu'à ce que la connexion soit complètement fermée par le serveur ou qu'une erreur se produise.

.wait()

.wait( { timeout : Real } )

ParamètresTypeDescription
timeoutReal->Délai d'attente maximum en secondes pour la réponse

Description

La fonction wait() attend que la connexion TCP soit fermée ou que le timeout spécifié soit atteint

note

Pendant une exécution .wait(), les fonctions de callback sont exécutées, en particulier les callbacks provenant d'autres événements ou d'autres instances de SystemWorker. Vous pouvez sortir d'un .wait() en appelant shutdown() depuis un callback.