WebSocket

Historique

Version	Modifications
v20 R2	Ajout

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.

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 body content de la réponse
.handler : Object    l'accesseur qui obtient 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 avec le type de données défini (Text, Blob ou Object)
.status : Text    le statut actuel de la connexion (peut être "Connecting", "Closing", "Closed", ou "Connected")
.terminate( { code : Integer { ; reason : Text } } )    ferme la connexion WebSocket, avec les paramètres optionnels code et reason
.url : Text    l'URL à laquelle la WebSocket s'est connectée

4D.WebSocket.new()

Historique

Version	Modifications
v20 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 indiqué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 (numérique) : 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 (numérique, en lecture seule) : unsigned short contenant le code de fermeture envoyé par le serveur. $2.reason (texte, en lecture seule) : Raison pour laquelle le serveur a fermé la connexion. Elle est spécifique au serveur et au sous-protocole. $2.wasClean (booléen, en lecture seule) : Indique si la connexion a été fermée proprement ou non.
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 de la WebSocket. Syntaxe pour l'affectation standard des clés : headers.*key*:=*value* (value peut être une collection si la même clé apparaît plusieurs fois) Syntaxe pour l'affectation des cookies (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 body content 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 obtient 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 avec 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 actuel 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() ferme 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 à laquelle la WebSocket s'est connectée. Il s'agit de l'URL que vous avez passée à la fonction new() .

Cette propriété est en lecture seule.