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.
Historique
| Release | Modifications |
|---|---|
| 20 R9 | Nouveaux attributs listener, address et port |
| 20 R8 | Classe ajoutée |
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.
Pour le débogage et la surveillance, vous pouvez utiliser le fichier journal 4DTCPUDPLog.txt qui enregistre les événements liés aux connexions TCP. Ces événements comprennent la transmission de données, les erreurs et les informations sur le cycle de vie de la connexion.
Programmation asynchrone
Cette classe prend en charge la programmation asynchrone dans 4D, comme décrit dans la page Exécution asynchrone.
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 :
| address : Text l'adresse IP ou le nom de domaine de la machine distante |
| closed : Boolean si la connexion est fermée |
| errors : Collection une collection d'objets erreur associés à la connexion |
| listener : Object l'objet TCPListener qui a créé la TCPConnection, s'il y en a un |
| noDelay : Boolean si l'algorithme de Nagle est désactivé ( true) ou activé (false) |
| port : Number le numéro de port de la machine distante |
| .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ètres | Type | Description | |
|---|---|---|---|
| serverAddress | Text | -> | Nom de domaine ou adresse IP du serveur |
| serverPort | Integer | -> | Numéro de port du serveur |
| options | Object | -> | options de configuration de la connexion |
| Résultat | 4D.TCPConnection | <- | 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.TCPConnection.
Paramètre options
Dans le paramètre options, passez un objet qui peut contenir les propriétés suivantes :
| Propriété | Type | Description | Par défaut |
|---|---|---|---|
| onConnection | Formula | Callback déclenchée lorsque la connexion est établie. | Undefined |
| onData | Formula | Callback déclenchée lors de la réception de données | Undefined |
| onShutdown | Formula | Callback déclenchée lorsque la connexion est correctement fermée | Undefined |
| onError | Formula | Callback déclenchée en cas d'erreur | Undefined |
| onTerminate | Formula | Callback déclenchée juste avant que la TCPConnection ne soit libérée | Undefined |
| noDelay | Boolean | Lecture seulement Désactive l'algorithme de Nagle si true | False |
| connectionTimeout | Real | Temps maximum (en secondes) pour établir la connexion. En cas de dépassement, la tentative de connexion est interrompue | Défini par le système, généralement ≥ 30 |
| TLS | Boolean | Active le chiffrement TLS pour les connexions | False |
Fonctions de callback
Toutes les fonctions de callback reçoivent deux paramètres :
| Paramètres | Type | Description |
|---|---|---|
| $connection | objet TCPConnection | L'instance de connexion TCP courante. |
| $event | objet TCPEvent | Contient des informations sur l'événement. |
Séquence des appels de callbacks :
onConnectionest déclenchée lorsque la connexion est établie.onDataest déclenchée à chaque fois que des données sont reçues.onShutdownouonErrorest déclenchée :onShutdownest déclenchée lorsque la connexion est correctement fermée.onErrorest déclenchée en cas d'erreur.
onTerminateest 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.
.address
address : Text
Description
La propriété .address contient l'adresse IP ou le nom de domaine de la machine distante.
.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é | Type | Description | |
|---|---|---|---|
| errors | Collection | Pile d'erreurs 4D en cas d'erreur | |
| [].errCode | Number | Code d'erreur 4D | |
| [].message | Text | Description de l'erreur 4D | |
| [].componentSignature | Text | Signature du composant interne qui a retourné l'erreur |
.listener
listener : Object
Description
La propriété .listener contient l'objet TCPListener qui a créé la TCPConnection, s'il y en a un. Cette propriété est en lecture seule.
.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.
.port
port : Number
Description
La propriété .port contient le numéro de port de la machine distante. Cette propriété est en lecture seule.
.send()
.send( data : Blob )
| Paramètres | Type | Description | |
|---|---|---|---|
| data | Blob | -> | 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ètres | Type | Description | |
|---|---|---|---|
| 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ètres | Type | Description | |
|---|---|---|---|
| timeout | Real | -> | 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
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.