Aller au contenu principal
Version: v20 R4 BETA

WebSocketServer

Historique
VersionModifications
v20Ajout

La classe WebSocketServer vous permet de créer et configurer un serveur WebSocket en 4D. Une fois le serveur WebSocket 4D actif, vous pouvez ouvrir et utiliser les connexions WebSocket entre 4D et les clients en utilisant la classe WebSocketConnection.

À propos des serveurs WebSocket

Le protocole WebSocket fournit un canal de communication full-duplex entre un serveur WebSocket et un client (par exemple un navigateur Web). Pour plus d'informations sur les serveurs WebSocket, lisez cette page sur Wikipedia.

Voir aussi

Voir également cet article de blog sur le serveur WebSocket 4D.

Conditions requises

Pour créer et gérer votre serveur WebSocket dans 4D, vous devrez utiliser deux classes intégrées à 4D :

  • cette classe (4D.WebSocketServer) pour gérer le serveur lui-même,
  • la classe 4D.WebSocketConnection pour gérer les connexions et les messages.

De plus, vous devrez créer deux classes utilisateurs qui contiendront les fonctions de callback :

  • une classe utilisateur pour gérer les connexions serveur,
  • une classe utilisateur pour gérer les messages.

Vous devez créer le serveur WebSocket au sein d'un worker pour maintenir la connexion active.

The 4D Web Server must be started.

Exemple

Dans cet exemple de base, notre serveur WebSocket renverra les messages en majuscules.

  1. Créez le serveur WebSocket en utilisant un worker (obligatoire) et passez votre classe de connexion serveur en tant que paramètre :
    // Créer une instance de la classe utilisateur
// qui gérera les connexions vers le serveur
var $handler: cs.myServerHandler
$handler := cs.myServerHandler.new()

CALL WORKER("WebSocketServer"; Formula(wss := 4D.WebSocketServer.new($handler)))
// attribuer une variable (wss) au WebSocket vous permet
// d'appeler wss.terminate() par la suite
  1. Définissez la classe utilisateur myServerHandler contenant la ou les fonction(s) de callback utilisée(s) pour gérer les connexions au serveur :
// Classe myServerHandler

Function onConnection($wss: Object; $event: Object): Object
// retourne une instance de la classe utilisateur
// qui traitera les messages
return cs.myConnectionHandler.new()
  1. Définissez la classe utilisateur myConnectionHandler contenant la ou les fonction(s) de callback utilisée(s) pour gérer les messages :
// Classe myConnectionHandler

Function onMessage($ws : 4D.WebSocketConnection; $message : Object)
// renvoie le message en majuscules
$ws.send(Uppercase($message.data))

Client-Side JS

Voir cet article de blog pour un exemple de code Javascript côté client gérant une connexion WebSocket.

Objet WebSocketServer

Les objets WebSocketServer offrent les propriétés et fonctions suivantes :

.connections : Collection    toutes les connexions courantes gérées par le serveur WebSocket
.dataType : Text    le type de données reçues ou envoyées
.handler : Object    l'accesseur qui récupère l'objet WSSHandler utilisé pour initier le serveur WebSocket
.path : Text    le modèle du chemin d'accès au serveur WebSocket
.terminate()    closes the WebSocket server
.terminated : Boolean    True si le serveur WebSocket est fermé

4D.WebSocketServer.new()

4D.WebSocketServer.new( WSSHandler : Object { ; options : Object } ) : 4D.WebSocketServer

ParamètresTypeDescription
WSSHandlerObject->Objet de la classe utilisateur déclarant les callbacks du serveur WebSocket
optionsObject->Paramètres de configuration du WebSocket
Résultat4D.WebSocketServer<-Nouvel objet WebSocketServer

|

The 4D.WebSocketServer.new() function creates and starts a WebSocket server that will use the specified WSSHandler callbacks and (optionally) options, and returns a 4D.WebSocketServer object.

Calling this function requires that the 4D Web Server is started. The host and port of the WebSocket server are the same as the host and port of the 4D Web Server.

WSSHandler parameter

In the WSSHandler parameter, pass an instance of a user class that will be called every time an event occurs on the WebSocket server --essentially, connection events. The class should define the following callback functions (only onConnection is mandatory):

PropriétéTypeDescriptionPar défaut
onConnectionFunction(obligatoire) Callback quand une nouvelle connexion cliente est démarrée (voir ci-dessous)undefined
onOpenFunctionCallback quand le serveur WebSocket est démarré (voir ci-dessous)undefined
onTerminateFunctionCallback quand le serveur WebSocket est stoppé (voir ci-dessous)undefined
onErrorFunctionCallback quand une erreur est survenue (voir ci-dessous)undefined

WSHandler.onConnection(WSServer : Object ; event : Object) : Object | null

ParamètresTypeDescription
WSServer4D.WebSocketServer<-Objet serveur WebSocket courant
eventObject<-Paramètres
typeText"connection"
requestObjectrequest object. Contient les informations de la requête de connexion (voir ci-dessous)
RésultatObject->connectionHandler object (see below). If this function returns a connectionHandler object, a 4D.WebSocketConnection object is automatically created and added to the collection of connections. This object is then received as parameter in each function of the connectionHandler object. Si la valeur renvoyée est null ou undefined, la connexion est annulée.

Cette callback est appelée lorsque le handshake est terminé. It must be called with a valid connectionHandler object to create the WebSocket connection, otherwise the connection is cancelled.

WSHandler.onOpen(WSServer : Object ; event : Object)

ParamètresTypeDescription
WSServer4D.WebSocketServer<-Objet serveur WebSocket courant
eventObject<-Paramètres
typeText"open"

Événement émis lorsque le serveur websocket est démarré.

WSHandler.onTerminate(WSServer : Object ; event : Object)

ParamètresTypeDescription
WSServer4D.WebSocketServer<-Objet serveur WebSocket courant
eventObject<-Paramètres
typeText"terminate"

Événement émis lors de la fermeture du serveur HTTP ou du serveur WebSocket.

WSHandler.onError(WSServer : Object ; event : Object)

ParamètresTypeDescription
WSServer4D.WebSocketServer<-Objet serveur WebSocket courant
eventObject<-Paramètres
typeText"error"
errorsCollectionCollection of 4D error stack in case of execution error
  • [].errCode (number) - 4D error code
  • [].message (text) - Description of the 4D error
  • [].componentSignature (text) - Signature of the internal component which returned the error
  • Événement émis lorsqu'une erreur se produit sur le serveur WebSocket.

    Example of WSSHandler class

    This example of a basic chat feature illustrates how to handle WebSocket server connections in a WSSHandler class.

    //myWSServerHandler class 

    Function onConnection($wss : Object; $event : Object) : Object

    If (VerifyAddress($event.request.remoteAddress))
    // The VerifyAddress method validates the client address
    // The returned WSConnectionHandler object will be used
    // by 4D to instantiate the 4D.WebSocketConnection object
    // related to this connection
    return cs.myConnectionHandler.new()
    // See connectionHandler object
    Else
    // The connection is cancelled
    return Null
    End if

    Function onOpen($wss : Object; $event : Object)
    LogFile("*** Server started")

    Function onTerminate($wss : Object; $event : Object)
    LogFile("*** Server closed")

    Function onError($wss : Object; $event : Object)
    LogFile("!!! Server error: "+$event.errors.first().message)

    request object

    A request object contains the following properties:

    ParamètresTypeDescription
    headersObjectLa requête HTTP GET du client. headers.key=value (value can be a collection if the same key appears multiple times)
    queryObjectObjet qui contient les paramètres de l'URL. For example, if parameters are: ?key1=value1&key2=value2 -> query.key1=value1, query.key2=value2
    urlTextcontient uniquement l'URL qui est présente dans la requête HTTP réelle. Ex: GET /status?name=ryan HTTP/1.1 -> url="/status?name=ryan"
    remoteAddressTextAdresse IP du client

    connectionHandler object

    As a result of the WSHandler.onConnection callback, pass a connectionHandler object, which is an instance of a user class that will be called every time an event occurs in the WebSocket connection --essentially, messages received. The class should define the following callback functions (only onMessage is mandatory):

    ParamètresTypeDescription
    onMessageFunction(obligatoire) Fonction appelée lorsqu'un nouveau message est reçu de cette connexion
    onOpenFunctionFunction called when the 4D.WebSocketConnection is created
    onTerminateFunctionFonction appelée lorsque cette connexion est terminée
    onErrorFunctionFonction appelée en cas d'erreur

    connectionHandler.onMessage(ws : 4D.WebSocketConnection ; event : Object)

    ParamètresTypeDescription
    ws4D.WebSocketConnection<-Objet connexion WebSocket courant
    eventObject<-Paramètres
    typeText"message"
    dataText / Blob / Objectdonnées envoyées par le client

    Callback pour les données WebSocket. Appelée à chaque fois que le WebSocket reçoit des données.

    connectionHandler.onOpen(ws : 4D.WebSocketConnection ; event : Object)

    ParamètresTypeDescription
    ws4D.WebSocketConnection<-Objet connexion WebSocket courant
    eventObject<-Paramètres
    typeText"open"

    Called when the connectionHandler object is created (after WSS.onConnection event).

    connectionHandler.onTerminate(ws : 4D.WebSocketConnection ; event : Object)

    ParamètresTypeDescription
    ws4D.WebSocketConnection<-Objet connexion WebSocket courant
    eventObject<-Paramètres
    typeText"terminate"
    codeNumberCode de statut indiquant la cause de la fermeture de la connexion. If the WebSocket does not return an error code, code is set to 1005 if no error occurred or to 1006 if there was an error.
    reasonTextChaîne expliquant pourquoi la connexion a été fermée. Si le websocket ne renvoie pas de raison, le code est undefined

    Fonction appelée lorsque la WebSocket est fermée.

    connectionHandler.onError(ws : 4D.WebSocketConnection ; event : Object)

    ParamètresTypeDescription
    ws4D.WebSocketConnection<-Objet connexion WebSocket courant
    eventObject<-Paramètres
    typeText"error"
    errorsCollectionCollection of 4D errors stack in case of execution error
  • [].errCode (number) - 4D error code
  • [].message (text) - Description of the 4D error
  • [].componentSignature (text) - Signature of the internal component which returned the error
  • Fonction appelée en cas d'erreur.

    Example of connectionHandler class

    This example of a basic chat feature illustrates how to handle messages in a connectionHandler class.

    // myConnectionHandler Class

    Function onMessage($ws : 4D.WebSocketConnection; $message : Object)
    // Resend the message to all chat clients
    This.broadcast($ws;$message.data)

    Function onOpen($ws : 4D.WebSocketConnection; $message : Object)
    // Send a message to new connected users
    $ws.send("Welcome on the chat!")
    // Send "New client connected" message to all other chat clients
    This.broadcast($ws;"New client connected")

    Function onTerminate($ws : 4D.WebSocketConnection; $message : Object)
    // Send "Client disconnected" message to all other chat clients
    This.broadcast($ws;"Client disconnected")

    Function broadcast($ws : 4D.WebSocketConnection; $message:text)
    var $client:4D.WebSocketConnection
    // Resend the message to all chat clients
    For each ($client; $ws.wss.connections)
    // Check that the id is not the current connection
    If ($client.id#$ws.id)
    $client.send($message)
    End if
    End for each

    options parameter

    In the optional options parameter, pass an object that contains the following properties:

    PropriétéTypeDescriptionPar défaut
    pathTextReprésente le chemin d'accès au serveur WebSocket. Si aucun chemin n'est défini, le serveur WebSocket gère toutes les connexionsundefined
    dataTypeTextType of the data received through the connectionHandler.onMessage and the data send by WebSocketConnection.send() function. Valeurs : "text", "blob", "object"). Si "objet" : (envoi) transforme l'objet au format json et l'envoie ; (réception) : reçoit le format json et le transforme en objettext

    .connections

    .connections : Collection

    Description

    La propriété .connections contient toutes les connexions courantes gérées par le serveur WebSocket. Chaque élément de la collection est un objet WebSocketConnection.

    When a connection is terminated, its status changes to "Closed" and it is removed from this collection.

    .dataType

    .dataType : Text

    Description

    La propriété .dataType contient le type de données reçues ou envoyées.

    Cette propriété est en lecture seule.

    .handler

    .handler : Object

    Description

    La propriété .handler contient l'accesseur qui récupère l'objet WSSHandler utilisé pour initier le serveur WebSocket.

    .path

    .path : Text

    Description

    La propriété .path contient le modèle du chemin d'accès au serveur WebSocket. Si aucun chemin n'a été défini, le serveur WebSocket gère toutes les connexions.

    Cette propriété est en lecture seule.

    .terminate()

    .terminate()

    ParamètresTypeDescription
    Ne requiert aucun paramètre

    |

    Description

    La fonction .terminate() closes the WebSocket server.

    .terminated

    .terminated : Boolean

    Description

    La propriété .terminated contient True si le serveur WebSocket est fermé.

    Cette propriété est en lecture seule.