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

Lanzamiento	Modificaciones
20 R2	Añadidos

Programación asíncrona

Esta clase soporta programación asíncrona en 4D como se describe en la página Ejecución Asíncrona.

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")

2. Conécte al servidor WebSocket desde un formulario 4D instanciando un 4D.WebSocket:

Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())

3. 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

Lanzamiento	Modificaciones
20 R3	Soporte de la propiedad headers en connectionHandler

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

Parámetros	Tipo		Descripción
url	Text	->	URL a la que conectarse
connectionHandler	Object	->	Objeto que declara las retrollamadas WebSocket
Resultado	4D.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.

Propiedad	Tipo	Descripción
onMessage	Function	Funció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
onError	Function	Funció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 errores 4D apilados 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
onTerminate	Function	Funció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): unsigned short 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 al servidor y al subprotocolo particular.
onOpen	Function	Funció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"
dataType	Text	Tipo de datos recibidos o enviados. Valores disponibles: "text" (por defecto), "blob", "object". "text" = utf-8
headers	Object	Encabezados del WebSocket. Sintaxis para la asignación de llave estándar: headers.*key*:=*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 : 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ámetros	Tipo		Descripción
message	Text, 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:

Tipo	Contenido
Text	Texto en UTF-8
Blob	Datos binarios
Object	Texto 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ámetros	Tipo		Descripción
code	Integer	->	Código de estado que explica por qué se cierra la conexión
reason	Text	->	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.