Saltar al contenido principal
Versión: 20 R10 BETA

WebSocket

La clase WebSocket permite abrir una conexión de cliente WebSocket con un servidor, enviar y recibir datos y cerrar la conexión.

Las conexiones cliente WebSocket son útiles, por ejemplo, para recibir datos financieros en tiempo real o enviar y recibir mensajes de un chat.

Historia
LanzamientoModificaciones
20 R2Añadidos

Ejemplo

En este ejemplo, creamos un cliente WebSocket muy básico.

  1. Cree la clase usuario WSConnectionHandler que contiene la(s) función(es) de retrollamada utilizada(s) para gestionar las retrollamadas evento 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. Conécte al servidor WebSocket desde un formulario 4D instanciando un 4D.WebSocket:
Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())
  1. Para enviar mensajes al servidor WebSocket desde el formulario 4D, puede escribir:
Form.webSocket.send("Hello world")

Objeto WebSocket

Los objetos WebSocket ofrecen las siguientes propiedades y funciones:

.dataType : Text
el tipo de contenido del cuerpo de la respuesta
.handler : Object
el accessor que obtiene el objeto connectionHandler utilizado para iniciar la conexión
.id : Integer
el identificador único de la conexión
.send( message : Text )
.send( message : Blob )
.send( message : Object )

envía message al servidor WebSocket en el tipo de datos definido (Texto, Blob u Objeto)
.status : Text
el estado actual de la conexión (puede ser "Connecting", "Closing", "Closed", o "Connected")
.terminate( { code : Integer { ; reason : Text } } )
cierra la conexión WebSocket, junto con los parámetros opcionales code y reason
.url : Text
la URL a la que se ha conectado el WebSocket

4D.WebSocket.new()

Historia
LanzamientoModificaciones
20 R3Soporte de la propiedad headers en connectionHandler

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

ParámetrosTipoDescripción
urlText->URL a la que conectarse
connectionHandlerObject->Objeto que declara las retrollamadas WebSocket
Resultado4D.WebSocket<-Nuevo objeto WebSocket

La función 4D.WebSocket.new() crea y devuelve un nuevo objeto 4D.WebSocket conectado al servidor WebSocket en la dirección especificada en url. El objeto 4D.WebSocket ofrece una API para crear y gestionar una conexión WebSocket a un servidor, así como para enviar y recibir datos hacia y desde el servidor.

En url, pase la URL a la que responderá el servidor WebSocket. Se pueden utilizar los siguientes patrones de URL:

  • ws://host[:port]path[?query] para conexiones estándar
  • wss://host[:port]path[?query] para conexiones seguras TLS

Si la conexión no es posible, se devuelve un objeto null y se genera un error (que puede interceptar utilizando un método instalado con ON ERR CALL).

Parámetro connectionHandler

En connectionHandler, puede pasar un objeto que contenga funciones de retrollamada a ser llamadas según los eventos de conexión, así como el tipo de datos y encabezados a manejar.

  • Las retrollamadas se llaman automáticamente en el contexto del formulario o worker que inicia la conexión.
  • El WebSocket será válido siempre y cuando el formulario o trabajador no esté cerrado.
PropiedadTipoDescripción
onMessageFunctionFunción de retrollamada para datos WebSocket. Llamada cada vez que el WebSocket ha recibido datos. La retrollamada recibe los siguientes parámetros
  • :$1: objeto WebSocket$2
  • : objeto
    • $2.type (texto): siempre "message"
    • $2.data (texto, blob u objeto, ver dataType): datos recibidos
    onErrorFunctionFunción de retrollamada para errores de ejecución. The callback receives the following parameters:
  • $1: WebSocket object
  • $2: Object
    • $2.type (text): always "error"
    • $2.errors: collection 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
    onTerminateFunctionFunción de retrollamada cuando el WebSocket se termina. The callback receives the following parameters:
  • $1: WebSocket object
  • $2: Object
    • $2.code (number, read-only): unsigned short containing the close code sent by the server.
    • $2.reason (text, read-only): Reason why the server closed the connection. Esto es específico al servidor y al subprotocolo particular.
    onOpenFunctionFunción de retrollamada cuando el webSocket está abierto. La retrollamada recibe los siguientes parámetros
  • :$1: objeto WebSocket
  • :$2 objeto
    • $2.type (texto): siempre "open"
    dataTypeTextTipo de datos recibidos o enviados. Valores disponibles: "text" (por defecto), "blob", "object". "text" = utf-8
    headersObjectEncabezados del WebSocket.
  • Syntax for standard key assignment: headers.*key*:=*value* (value can be a Collection if the same key appears multiple times)
  • Syntax for Cookie assignment (particular case): headers.Cookie:="*name*=*value* {; *name2*=*value2*{; ... } }"
  • Esta es la secuencia de llamadas de retorno:

    1. onOpen se ejecuta una vez
    2. Cero o varios onMessage son ejecutados
    3. Cero o un onError es ejecutado (detiene el procesamiento)
    4. onTerminate se ejecuta siempre una vez

    Ejemplo

    Quiere definir los encabezados en la clase usuario WSConnectionHandler:

    // Clase WSConnectionHandler

    Class constructor($myToken:Text)

    // Creación de los encabezados enviados al servidor
    This.headers:=New object("x-authorization";$myToken)
    // Definimos dos cookies
    This.headers.Cookie:="yummy_cookie=choco; tasty_cookie=fresa"
    ...

    .dataType

    .dataType : Text

    Descripción

    La propiedad .dataType contiene el tipo de contenido del cuerpo de la respuesta. Puede ser "text", "blob" u "object".

    Esta propiedad es de sólo lectura.

    .handler

    .handler : Object

    Descripción

    La propiedad .handler contiene el accessor que obtiene el objeto connectionHandler utilizado para iniciar la conexión.

    Esta propiedad es de sólo lectura.

    .id

    .id : Integer

    Descripción

    La propiedad .id contiene el identificador único de la conexión.

    Esta propiedad es de sólo lectura.

    .send()

    .send( message : Text )
    .send( message : Blob )
    .send( message : Object )

    ParámetrosTipoDescripción
    messageText, Blob, Object->Mensaje a enviar

    Descripción

    La función .send() envía message al servidor WebSocket en el tipo de datos definido (Texto, Blob u Objeto).

    Los siguientes contenidos se envían en función del tipo de message:

    TipoContenido
    TextTexto en UTF-8
    BlobDatos binarios
    ObjectTexto en JSON UTF-8 (mismo resultado que con JSON Stringify)

    .status

    .status : Text

    Descripción

    La propiedad .status contiene el estado actual de la conexión (puede ser "Connecting", "Closing", "Closed", o "Connected").

    Esta propiedad es de sólo lectura.

    .terminate()

    .terminate( { code : Integer { ; reason : Text } } )

    ParámetrosTipoDescripción
    codeInteger->Código de estado que explica por qué se cierra la conexión
    reasonText->La razón por la que se cierra la conexión

    Descripción

    La función .terminate() cierra la conexión WebSocket, junto con los parámetros opcionales code y reason.

    En code, puede pasar un código de estado que explique por qué se está cerrando la conexión (ver también WebSocket Connection Close Code in the RFC6455):

    • Si no se especifica, el código de cierre de la conexión se establece automáticamente en 1000 para un cierre normal o, en caso contrario, en otro valor estándar del rango 1001-1015 que indique la razón real por la que se cerró la conexión.
    • Si se especifica, el valor de este parámetro de código anula el ajuste automático. El valor debe ser un número entero. O 1000, o un código personalizado en el rango 3000-4999. Si especifica un valor code, también debe especificar un valor reason.

    En reason, puede pasar una cadena que describa por qué se está cerrando la conexión.

    .url

    .url : Text

    Descripción

    La propiedad .url contiene la URL a la que se ha conectado el WebSocket. Es la URL que ha pasado a la función new().

    Esta propiedad es de sólo lectura.