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.

1. 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")

2. Connexion au serveur WebSocket à partir d'un formulaire 4D en instanciant un 4D.WebSocket :

Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())

3. 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 standard
• wss://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 $2.type (texte) : toujours "message" $2.data (texte, blob ou objet, voir dataType) : Données reçues
onError	Function	Fonction de callback pour les erreurs d'exécution. La callback reçoit les paramètres suivants: $1: objet WebSocket $2: Objet $2.type (texte) : toujours "error" $2.errors: collection de piles d'erreurs 4D en cas d'erreur d'exécution. [].errCode (nombre) : Code d'erreur 4D [].message (texte) : Description de l'erreur 4D [].componentSignature (texte) : Signature du composant interne qui a renvoyé l'erreur
onTerminate	Function	Fonction de callback lorsque la WebSocket est terminée. La callback reçoit les paramètres suivants : $1: objet WebSocket $2: Objet $2.code (nombre, lecture seule) : unsigned short contenant le code de fermeture envoyé par le serveur. $2.reason (texte, lecture seule) : Raison pour laquelle le serveur a fermé la connexion. Elle est spécifique au serveur et au sous-protocole particulier.
onOpen	Function	Fonction de callback lorsque la WebSocket est ouverte. La callback reçoit les paramètres suivants: $1: objet WebSocket $2: Objet $2.type (texte): toujours "open"
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. Syntaxe pour l'assignation de clé standard : headers.*clé*:=*valeur* (valeur peut être une Collection si la même clé apparaît plusieurs fois) Syntaxe pour l'assignation de Cookie (cas particulier) : headers.Cookie:="*nom*=*valeur* {; *nom2*=*valeur2*{; ... } }"

Voici la séquence des appels de callbacks :

1. onOpen est exécuté une fois
2. Zéro ou plusieurs onMessage sont exécutés
3. Zéro ou un onError est exécuté (stoppe le traitement)
4. 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.