Saltar al contenido principal
Versión: v20

WebSocketServer

Histórico
VersiónModificaciones
v20Añadidos

La clase WebSocketServer permite crear y configurar un servidor WebSocket en 4D. Una vez que el servidor 4D WebSocket está activo, puede abrir y utilizar conexiones WebSocket entre 4D y los clientes utilizando la clase WebSocketConnection.

Sobre los servidores WebSocket

El protocolo WebSocket ofrece un canal de comunicación full-duplex entre un servidor WebSocket y un cliente (por ejemplo, un navegador web). Para más información sobre servidores WebSocket, consulte esta página en Wikipedia.

Ver también

Ver también esta entrada del blog sobre el servidor 4D WebSocket.

Requisitos

Para crear y manejar su Servidor WebSocket en 4D, tendrá que utilizar dos clases 4D integradas:

  • esta clase (4D.WebSocketServer) para gestionar el propio servidor,
  • la clase 4D.WebSocketConnection para gestionar conexiones y mensajes.

Además, tendrá que crear dos clases de usuario que contendrán funciones de retrollamada:

  • una clase usuario para gestionar las conexiones al servidor,
  • una clase usuario para gestionar mensajes.

Debe crear el servidor WebSocket dentro de un worker para mantener viva la conexión.

El 4D Web Server debe ser iniciado.

Ejemplo

En este ejemplo básico, nuestro servidor WebSocket devolverá los mensajes en mayúsculas.

  1. Crea el servidor WebSocket utilizando un worker (obligatorio) y pasa su clase de conexión al servidor como parámetro:
    //crea una instancia de la clase usuario
//que manejará las conexiones al servidor
var $handler:cs.myServerHandler
$handler:=cs.myServerHandler.new()

CALL WORKER("WebSocketServer"; Formula(wss:=4D.WebSocketServer.new($handler)))
//asignar una variable (wss) al WebSocket permite
//llamar después a wss.terminate()
  1. Define la clase usuario myServerHandler que contiene la(s) función(es) de retrollamada utilizada(s) para manejar las conexiones al servidor:
//clase myServerHandler

Function onConnection($wss : Object; $event : Object) : Object
//devuelve una instancia de la clase usuario
//que gestionará los mensajes
return cs.myConnectionHandler.new()
  1. Defina la clase usuario myConnectionHandler que contiene la(s) función(es) de retrollamada utilizada(s) para manejar los mensajes:
//clase myConnectionHandler

Function onMessage($ws : 4D.WebSocketConnection; $message : Object)
//envía el mensaje en mayúsculas
$ws.send(Uppercase($message.data))

JS del lado del cliente

Consulte esta entrada de blog para ver un ejemplo de código Javascript del lado del cliente que gestiona una conexión WebSocket.

Objeto WebSocketServer

Los objetos de servidor WebSocket ofrecen las siguientes propiedades y funciones:

.connections : Collection    todas las conexiones actuales gestionadas por el servidor WebSocket
.dataType : Text    el tipo de datos recibidos o enviados
.handler : Object    el accesor que recupera el objeto WSHandler utilizado para iniciar el servidor WebSocket
.path : Text    el modelo de la ruta de acceso al servidor WebSocket
.terminate()    cierra el servidor WebSocket
.terminated : Boolean    True si el servidor WebSocket está cerrado

4D.WebSocketServer.new()

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

ParámetrosTipoDescripción
WSSHandlerObject->Objeto de la clase usuario que declara las retrollamadas del servidor WebSocket
optionsObject->Parámetros de configuración de WebSocket
Result4D.WebSocketServer<-Nuevo objeto WebSocketServer

|

La función 4D.WebSocketServer.new() crea e inicia un servidor WebSocket que utilizará las retrollamadas WSSHandler especificados y (opcionalmente) options y devuelve un objeto 4D.WebSocketServer.

La llamada a esta función requiere que el Server Web 4D esté iniciado. El host y el puerto del servidor WebSocket son los mismos que el host y el puerto del servidor Web 4D.

Parámetro WSSHandler

En el parámetro WSSHandler, pase una instancia de una clase usuario que será llamada cada vez que ocurra un evento en el servidor WebSocket --esencialmente, eventos de conexión. La clase debe definir las siguientes funciones de retrollamada (sólo onConnection es obligatoria):

PropiedadTipoDescripciónPor defecto
onConnectionFunction(obligatorio) Retro llamada cuando se inicia una nueva conexión cliente (ver más abajo)indefinido
onOpenFunctionRetrollamada cuando se inicia el servidor WebSocket (ver más abajo)indefinido
onTerminateFunctionRetrollamada cuando se termina el servidor WebSocket (ver abajo)indefinido
onErrorFunctionRetrollamada cuando se ha producido un error (ver abajo)indefinido

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

ParámetrosTipoDescripción
WSServer4D.WebSocketServer<-Objeto servidor WebSocket actual
eventoObject<-Parámetros
typeText"connection"
requestObjectobjeto request. Contiene información sobre la solicitud de conexión (ver abajo)
ResultadoObject->objeto connectionHandler (ver abajo). Si esta función devuelve un objeto connectionHandler, se crea automáticamente un objeto 4D.WebSocketConnection y se añade a la colección de conexiones . Este objeto se recibe entonces como parámetro en cada función del objeto connectionHandler. Si el valor devuelto es nulo o indefinido, se cancela la conexión.

Esta retrollamada se llama cuando el establecimiento de la comunicación se ha completado. Debe ser llamada con un objeto connectionHandler válido para crear la conexión WebSocket, de lo contrario la conexión se cancela.

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

ParámetrosTipoDescripción
WSServer4D.WebSocketServer<-Objeto servidor WebSocket actual
eventoObject<-Parámetros
typeText"open"

Evento emitido cuando se inicia el servidor websocket.

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

ParámetrosTipoDescripción
WSServer4D.WebSocketServer<-Objeto servidor WebSocket actual
eventoObject<-Parámetros
typeText"terminate"

Evento emitido cuando se cierra el servidor HTTP o el servidor WebSocket.

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

ParámetrosTipoDescripción
WSServer4D.WebSocketServer<-Objeto servidor WebSocket actual
eventoObject<-Parámetros
typeText"error"
errorsCollectionColección de la pila de errores 4D en caso de error de ejecución
  • [].errCode (number) - Código de error 4D
  • [].message (text) - Descripción del error 4D
  • [].componentSignature (text) - Firma del componente interno que ha devuelto el error
  • Evento emitido cuando se produce un error en el servidor WebSocket.

    Ejemplo de clase WSSHandler

    Este ejemplo de una función básica de chat ilustra cómo manejar conexiones de servidor WebSocket en una clase WSSHandler.

    //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("!!! Error del servidor: "+$event.errors.first().message)

    request objeto

    Un objeto request contiene las siguientes propiedades:

    ParámetrosTipoDescripción
    headersObjectLa petición HTTP GET del cliente. headers.key=value (el valor puede ser una colección si la misma llave aparece varias veces)
    queryObjectObjeto que contiene los parámetros de la URL. Por ejemplo, si los parámetros son ?key1=valor1&key2=valor2 -> query.key1=valor1, query.key2=valor2
    urlTextcontiene sólo la URL que está presente en la petición HTTP real. Ejemplo: GET /status?name=ryan HTTP/1.1 -> url="/status?name=ryan"
    remoteAddressTextDirección IP del cliente

    Objeto connectionHandler

    Como resultado de la retrollamada WSHandler.onConnection, pasa un objeto connectionHandler, que es una instancia de una clase de usuario que será llamada cada vez que ocurra un evento en la conexión WebSocket --esencialmente, mensajes recibidos. La clase debe definir las siguientes funciones de retrollamada (sólo onMessage es obligatoria):

    ParámetrosTipoDescripción
    onMessageFunction(obligatorio) Función llamada cuando se recibe un nuevo mensaje de esta conexión
    onOpenFunctionFunción llamada cuando se crea 4D.WebSocketConnection
    onTerminateFunctionFunción a la que se llama cuando finaliza esta conexión
    onErrorFunctionFunción llamada cuando se produce un error

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

    ParámetrosTipoDescripción
    ws4D.WebSocketConnection<-Objeto de conexión WebSocket actual
    eventoObject<-Parámetros
    typeText"message"
    dataText / Blob / Objectdatos enviados por el cliente

    Esta retrollamada para datos WebSocket. Llamada cada vez que el WebSocket recibe datos.

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

    ParámetrosTipoDescripción
    ws4D.WebSocketConnection<-Objeto de conexión WebSocket actual
    eventoObject<-Parámetros
    typeText"open"

    Llamada cuando se crea el objeto connectionHandler (después del evento WSS.onConnection).

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

    ParámetrosTipoDescripción
    ws4D.WebSocketConnection<-Objeto de conexión WebSocket actual
    eventoObject<-Parámetros
    typeText"terminate"
    codeNumberCódigo de estado que indica por qué se ha cerrado la conexión. Si el WebSocket no devuelve un código de error, code toma el valor 1005 si no se ha producido ningún error o 1006 si se ha producido un error.
    reasonTextCadena que explica porque se ha cerrado la conexión. Si el websocket no devuelve una razón, el código es indefinido

    Función llamada cuando se cierra el WebSocket.

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

    ParámetrosTipoDescripción
    ws4D.WebSocketConnection<-Objeto de conexión WebSocket actual
    eventoObject<-Parámetros
    typeText"error"
    errorsCollectionColección de la pila de errores 4D en caso de error de ejecución
  • [].errCode (number) - Código de error 4D
  • [].message (text) - Descripción del error 4D
  • [].componentSignature (text) - Firma del componente interno que ha devuelto el error
  • Función llamada cuando se ha producido un error.

    Ejemplo de class connectionHandler

    Este ejemplo de una función básica de chat ilustra cómo gestionar mensajes en una clase connectionHandler.

    // Clase myConnectionHandler

    Function onMessage($ws : 4D.WebSocketConnection; $message : Object)
    // Reenviar el mensaje a todos los clientes del chat
    This.broadcast($ws;$message.data)

    Function onOpen($ws : 4D.WebSocketConnection; $message : Object)
    // Enviar un mensaje a los nuevos usuarios conectados
    $ws.send("¡Bienvenidos al chat!")
    // Enviar el mensaje "Nuevo cliente conectado" a todos los demás clientes de chat
    This.broadcast($ws; "Nuevo cliente conectado")

    Function onTerminate($ws : 4D.WebSocketConnection; $message : Object)
    // Enviar el mensaje "Cliente desconectado" a todos los demás clientes de chat
    This.broadcast($ws; "Cliente desconectado")

    Function broadcast($ws : 4D.WebSocketConnection; $message:text)
    var $client:4D.WebSocketConnection
    // Reenviar el mensaje a todos los clientes de chat
    For each ($client; $ws.wss.connections)
    // Comprobar que el id no es la conexión actual
    If ($client.id#$ws.id)
    $client.send($message)
    End if
    End for each

    Parámetro options

    En el parámetro opcional options, pase un objeto que contenga las siguientes propiedades:

    PropiedadTipoDescripciónPor defecto
    pathTextRepresenta la ruta de acceso al servidor WebSocket. Si no se define ninguna ruta, el servidor WebSocket gestiona todas las conexionesindefinido
    dataTypeTextTipo de los datos recibidos a través de la función connectionHandler.onMessage y de los datos enviados por WebSocketConnection.send(). Valores: "text", "blob","object"). Si "object": (send) transforma object en formato json y lo envía; (reception): recibe formato json y lo transforma en objecttext

    .connections

    .connections : Collection

    Descripción

    La propiedad .connections contiene todas las conexiones actuales gestionadas por el servidor WebSocket. Cada elemento de la colección es un objeto WebSocketConnection.

    Cuando se finaliza una conexión, su estado `` cambia a "Closed" y se elimina de esta colección.

    .dataType

    .dataType : Text

    Descripción

    La propiedad .dataType contiene el tipo de datos recibidos o enviados.

    Esta propiedad es de sólo lectura.

    .handler

    .handler : Object

    Descripción

    La propiedad .handler contiene el accesor que recupera el objeto WSHandler utilizado para iniciar el servidor WebSocket.

    .path

    .path : Text

    Descripción

    La propiedad .path contiene el modelo de la ruta de acceso al servidor WebSocket. Si no se ha definido ninguna ruta, el servidor WebSocket gestiona todas las conexiones.

    Esta propiedad es de sólo lectura.

    .terminate()

    .terminate()

    ParámetrosTipoDescripción
    No requiere ningún parámetro

    |

    Descripción

    La función .terminate() cierra el servidor WebSocket.

    .terminated

    .terminated : Boolean

    Descripción

    La propiedad .terminated contiene True si el servidor WebSocket está cerrado.

    Esta propiedad es de sólo lectura.