Saltar al contenido principal
Versión: 20 R5

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 : 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 (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
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 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. La retrollamada recibe los siguientes parámetros
  • :$1: objeto WebSocket$2
  • : objeto
    • $2.type (texto): siempre "error"
    • $2.errors: colección de pilas de errores 4D en caso de error de ejecución.
      • [].errCode (número): código de error 4D
      • [].message (texto): descripción del error 4D
      • [].componentSignature (texto): 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 (número, solo lectura): unsigned short contiene el código de cierre enviado por el servidor.
    • $2.reason (texto, solo lectura): razón por la cual el servidor cerró la conexión. 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.
  • Sintaxis para la asignación de llave estándar: headers.*llave*:=*value* (value puede ser una Colección si la misma llave aparece varias veces)
  • Sintaxis para asignación de Cookie (caso particular): 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 : 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 (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.