WebSocket

Histórico

Versión	Modificaciones
v20 R2	Añ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")

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 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ón	Modificaciones
v20 R3	Soporte de la propiedad encabezados 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
Result	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 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.

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

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

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