WebSocket
La classe WebSocket
permet d'ouvrir une connexion cliente WebSocket avec un serveur, d'envoyer et de recevoir des données et de fermer la connexion.
Les connexions clientes WebSocket sont utiles, par exemple, pour recevoir des données financières en temps réel ou pour envoyer et recevoir des messages à partir d'une messagerie instantanée.
Historique
Release | Modifications |
---|---|
20 R2 | Ajout |
Exemple
Dans cet exemple, nous créons un client WebSocket très basique.
- Créez la classe utilisateur
WSConnectionHandler
contenant la ou les fonction(s) de callback utilisée(s) pour gérer les callbacks d'événements WebSocket :
// WSConnectionHandler class
Class constructor
Function onMessage($ws : 4D.WebSocket; $event : Object)
ALERT($event.data)
Function onTerminate($ws : 4D.WebSocket; $event : Object)
ALERT("Connection closed")
- Connexion au serveur WebSocket à partir d'un formulaire 4D en instanciant un 4D.WebSocket :
Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())
- Pour envoyer des messages au serveur WebSocket à partir du formulaire 4D, vous pouvez écrire :
Form.webSocket.send("Hello world")
Objet WebSocket
Les objets WebSocket exposent les propriétés et fonctions suivantes :
.dataType : Text le type de contenu du body de la réponse |
.handler : Object l'accesseur qui récupère l'objet connectionHandler utilisé pour initier la connexion |
.id : Longint l'identifiant unique de la connexion |
.send( message : Text ) .send( message : Blob ) .send( message : Object ) envoie message au serveur WebSocket dans le type de données défini (Text, Blob ou Object) |
.status : Text le statut courant de la connexion (peut être "Connecting", "Closing", "Closed" ou "Connected") |
.terminate( { code : Integer { ; reason : Text } } ) referme la connexion WebSocket, avec les paramètres optionnels code et reason |
.url : Text l'URL auquel le WebSocket s'est connecté |
4D.WebSocket.new()
Historique
Release | Modifications |
---|---|
20 R3 | Prise en charge de la propriété headers dans connectionHandler |
4D.WebSocket.new( url : Text { ; connectionHandler : Object } ) : 4D.WebSocket
Paramètres | Type | Description | |
---|---|---|---|
url | Text | -> | URL à laquelle se connecter |
connectionHandler | Object | -> | Objet déclarant les callbacks WebSocket |
Résultat | 4D.WebSocket | <- | Nouvel objet WebSocket |
La fonction 4D.WebSocket.new()
crée et renvoie un nouvel objet 4D.WebSocket
connecté au serveur WebSocket à l'adresse que vous avez spécifiée dans url. L'objet 4D.WebSocket
fournit une API pour la création et la gestion d'une connexion WebSocket à un serveur, ainsi que pour l'envoi et la réception de données vers et depuis le serveur.
Dans url, indiquez l'URL à laquelle le serveur WebSocket répondra. Les modèles d'URL suivants peuvent être utilisés :
ws://host[:port]path[?query]
pour les connexions standardwss://host[:port]path[?query]
pour les connexions TLS sécurisées
Si la connexion n'est pas possible, un objet null
est renvoyé et une erreur est générée (que vous pouvez intercepter à l'aide d'une méthode installée avec ON ERR CALL
).
Paramètre connectionHandler
Dans connectionHandler, vous pouvez transmettre un objet contenant des fonctions de callback à appeler selon les événements de connexion, ainsi que le type de données et les en-têtes à gérer.
- Les callbacks sont automatiquement appelées dans le contexte du formulaire ou du worker qui initie la connexion.
- La WebSocket reste valide tant que le formulaire ou le worker n'est pas fermé.
Propriété | Type | Description |
---|---|---|
onMessage | Function | Fonction de callback pour les données WebSocket. Appelée à chaque fois que le WebSocket a reçu des données. La callback reçoit les paramètres suivants :$1 : objet WebSocket$2 : Objet
|
onError | Function | Fonction de callback pour les erreurs d'exécution. La callback reçoit les paramètres suivants:$1 : objet WebSocket$2 : Objet
|
onTerminate | Function | Fonction de callback lorsque la WebSocket est terminée. La callback reçoit les paramètres suivants : $1 : objet WebSocket$2 : Objet
|
onOpen | Function | Fonction de callback lorsque la WebSocket est ouverte. La callback reçoit les paramètres suivants:$1 : objet WebSocket$2 : Objet
|
dataType | Text | Type de données reçues ou envoyées. Valeurs disponibles : "text" (par défaut), "blob", "object". "text" = utf-8 |
headers | Object | En-têtes du WebSocket.headers.*clé*:=*valeur* (valeur peut être une Collection si la même clé apparaît plusieurs fois)headers.Cookie:="*nom*=*valeur* {; *nom2*=*valeur2*{; ... } }" |
Voici la séquence des appels de callbacks :
onOpen
est exécuté une fois- Zéro ou plusieurs
onMessage
sont exécutés - Zéro ou un
onError
est exécuté (stoppe le traitement) onTerminate
est toujours exécuté
Exemple
Vous souhaitez définir des en-têtes dans la classe utilisateur WSConnectionHandler
:
// Classe WSConnectionHandler
Class constructor($myToken:Text)
// Création des en-têtes envoyés au serveur
This.headers:=New object("x-authorization" ;$myToken)
// Nous définissons deux cookies
This.headers.Cookie:="yummy_cookie=choco ; tasty_cookie=strawberry"
...
.dataType
.dataType : Text
Description
La propriété .dataType
contient le type de contenu du body de la réponse. Peut être "text", "blob" ou "object".
Cette propriété est en lecture seule.
.handler
.handler : Object
Description
La propriété .handler
contient l'accesseur qui récupère l'objet connectionHandler
utilisé pour initier la connexion.
Cette propriété est en lecture seule.
.id
.id : Longint
Description
La propriété .id
contient l'identifiant unique de la connexion.
Cette propriété est en lecture seule.
.send()
.send( message : Text )
.send( message : Blob )
.send( message : Object )
Paramètres | Type | Description | |
---|---|---|---|
message | Text, Blob, Object | -> | Message à envoyer |
Description
La fonction .send()
envoie message au serveur WebSocket dans le type de données défini (Text, Blob ou Object).
Les contenus suivants sont envoyés en fonction du type de message :
Type | Contenu |
---|---|
Text | Texte en UTF-8 |
Blob | Données binaires |
Object | Texte en JSON UTF-8 (même résultat qu'avec JSON Stringify ) |
.status
.status : Text
Description
La propriété .status
contient le statut courant de la connexion (peut être "Connecting", "Closing", "Closed" ou "Connected").
Cette propriété est en lecture seule.
.terminate()
.terminate( { code : Integer { ; reason : Text } } )
Paramètres | Type | Description | |
---|---|---|---|
code | Integer | -> | Code de statut indiquant la cause de la fermeture de la connexion |
reason | Text | -> | Cause de la fermeture de la connexion |
Description
La fonction .terminate()
referme la connexion WebSocket, avec les paramètres optionnels code et reason.
Dans code, vous pouvez passer un code d'état expliquant pourquoi la connexion est fermée (voir aussi WebSocket Connection Close Code in the RFC6455) :
- S'il n'est pas spécifié, le code de fermeture de la connexion est automatiquement fixé à 1000 pour une fermeture normale, ou à une autre valeur standard dans la plage 1001-1015 qui indique la raison réelle de la fermeture de la connexion.
- Si elle est spécifiée, la valeur de ce paramètre de code remplace le réglage automatique. La valeur doit être un nombre entier. Soit 1000, soit un code personnalisé compris entre 3000 et 4999. Si vous spécifiez la valeur du *code * , vous devez également spécifier une reason.
Dans reason, vous pouvez passer une chaîne de caractères décrivant la raison pour laquelle la connexion est fermée.
.url
.url : Text
Description
La propriété .url
contient l'URL auquel le WebSocket s'est connecté. Il s'agit de l'URL que vous avez passé à la fonction new()
.
Cette propriété est en lecture seule.