Aller au contenu principal
Version: 20 R5

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
ReleaseModifications
20 R2Ajout

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")
  1. Connexion au serveur WebSocket à partir d'un formulaire 4D en instanciant un 4D.WebSocket :
Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())
  1. 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
ReleaseModifications
20 R3Prise en charge de la propriété headers dans connectionHandler

4D.WebSocket.new( url : Text { ; connectionHandler : Object } ) : 4D.WebSocket

ParamètresTypeDescription
urlText->URL à laquelle se connecter
connectionHandlerObject->Objet déclarant les callbacks WebSocket
Résultat4D.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éTypeDescription
onMessageFunctionFonction 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
    onErrorFunctionFonction 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
    onTerminateFunctionFonction 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.
    onOpenFunctionFonction 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"
    dataTypeTextType de données reçues ou envoyées. Valeurs disponibles : "text" (par défaut), "blob", "object". "text" = utf-8
    headersObjectEn-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ètresTypeDescription
    messageText, 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 :

    TypeContenu
    TextTexte en UTF-8
    BlobDonnées binaires
    ObjectTexte 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ètresTypeDescription
    codeInteger->Code de statut indiquant la cause de la fermeture de la connexion
    reasonText->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.