Saltar al contenido principal
Versión: v20 R4 BETA

WebSocket

Histórico
VersiónModificaciones
v20 R2Añadidos

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.

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 accesor que obtiene el objeto connectionHandler utilizado para iniciar la conexión
.id : Longint    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 (Text, Blob u Object)
.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()

Histórico
VersiónModificaciones
v20 R3Soporte de la propiedad encabezados 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
Result4D.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 que pasó en url. El objeto 4D.WebSocket ofrece una API para crear y gestionar una conexión WebSocket con 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 (text): siempre "message"
    • $2.data (texto, blob u objeto, ver dataType): Datos recibidos
    onErrorFunctionFunción de retrollamada para errores de ejecución. La retrollamada recibe los siguientes parámetros:
  • $1: Objeto WebSocket
  • $2: Objeto
    • $2.type (text): siempre "error"
    • $2.errors: colecció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
    onTerminateFunctionFunción de retrollamada cuando el WebSocket se termina. La retrollamada recibe los siguientes parámetros:
  • $1: Objeto WebSocket
  • $2: Objeto
    • $2.code (number, solo lectura): corto sin firmar que contiene el código de cierre enviado por el servidor.
    • $2.reason (text, sólo lectura): razón por la que el servidor cerró la conexión. Esto es específico de cada servidor y subprotocolo.
    • $2.wasClean (boolean, sólo lectura): indica si la conexión se cerró limpiamente o no.
    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.
  • Sintaxis para la asignación estándar de las llaves: headers.*key*:=*value* (value puede ser una colección si la misma llave aparece varias veces)
  • Sintaxis para asignación de cookies (caso particular): headers.Cookie:="*name*=*value* {; *name2*=*value2*{; ... } }"
  • Esta es la secuencia de llamadas de retorno:

    1. onOpen se ejecuta una vez
    2. Se ejecutan cero o varios onMessage
    3. Se ejecuta cero o un onError (detiene el procesamiento)
    4. onTerminate se ejecuta siempre

    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 accesor que obtiene el objeto connectionHandler utilizado para iniciar la conexión.

    Esta propiedad es de sólo lectura.

    .id

    .id : Longint

    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 (Text, Blob u Object).

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

    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 en el 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 de code, también debe especificar un valor de 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.