WebSocket

The WebSocket class allows you to open a WebSocket client connection with a server, send and receive data, and close the connection.

As ligações cliente WebSocket são úteis, por exemplo, para receber dados financeiros em tempo real ou enviar e receber mensagens de um chat.

História

Release	Mudanças
20 R2	Adicionado

Exemplo

Neste exemplo, criamos um cliente WebSocket muito básico.

1. Criar a classe usuário WSConnectionHandler que contém as funções de retorno de chamada utilizadas para tratar os retornos de chamada de eventos 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. Conecte-se ao servidor WebSocket a partir de um formulário 4D instanciando um 4D.WebSocket:

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

3. Para enviar mensagens para o servidor WebSocket a partir do formulário 4D, pode escrever:

Form.webSocket.send("Hello world")

Objeto WebSocket

Os objetos WebSocket fornecem as seguintes propriedades e funções:

.dataType : Text o tipo do conteúdo do corpo de resposta
.handler : Object the accessor that gets the connectionHandler object used to initiate the connection
.id : Integer o identificador único da conexão
.send( message : Text ) .send( message : Blob ) .send( message : Object ) envia mensagem ao servidor de WebSocket no tipo de dados definido (Texto, Blob, ou Objeto)
.status : Text the current connection status (can be "Connecting", "Closing", "Closed", or "Connected")
.terminate( { code : Integer { ; reason : Text } } ) fecha a conexão de WebSocket, juntamente com parâmetros opcionais code e reason
.url : Text a URL à qual o WebSocket se conectou

4D.WebSocket.new()

História

Release	Mudanças
20 R3	Suporte da propriedade headers em connectionHandler

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

Parâmetro	Tipo		Descrição
url	Text	->	URL a que se deve ligar
connectionHandler	Object	->	Objeto que declara as chamadas de retorno WebSocket
Resultados	4D.WebSocket	<-	Novo objeto WebSocket

The 4D.WebSocket.new() function creates and returns a new 4D.WebSocket object connected to the WebSocket server at the address you passed in url. The 4D.WebSocket object provides an API for creating and managing a WebSocket connection to a server, as well as sending and receiving data to and from the server.

Em url, passe o URL ao qual o servidor WebSocket responderá. Podem ser utilizados os seguintes padrões de URL:

• ws://host[:port]path[?query] para ligações padrão
• wss://host[:port]path[?query] para conexões TLS seguras

If the connection is not possible, a null object is returned and an error is generated (that you can intercept using a method installed with ON ERR CALL).

Parâmetro connectionHandler

In connectionHandler, you can pass an object containing callback functions to be called according to connection events, as well as data type and headers to handle.

• As chamadas de retorno são chamadas automaticamente no contexto do formulário ou do worker que inicia a ligação.
• O WebSocket será válido enquanto o formulário ou o worker não for fechado.

Propriedade	Tipo	Descrição
onMessage	Function	Função de retorno de chamada para dados WebSocket. Chamado sempre que o WebSocket tiver recebido dados. The callback receives the following parameters: $1: WebSocket object $2: Object $2.type (text): always "message" $2.data (text, blob, or object, see dataType): Received data
onError	Function	Função de retorno de chamada para erros de execução. 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
onTerminate	Function	Função de retorno de chamada quando o WebSocket é terminado. 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. Isto é específico do servidor e do subprotocolo em causa.
onOpen	Function	Função de retorno de chamada quando o websocket está aberto. The callback receives the following parameters: $1: WebSocket object $2: Object $2.type (text): always "open"
dataType	Text	Tipo de dados recebidos ou enviados. Valores disponíveis: "text" (padrão), "blob", "object". "text" = utf-8
headers	Object	Headers of the 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*{; ... } }"

Aqui está a sequência de chamadas de retorno:

1. onOpen é executado uma vez
2. São executados zero ou vários onMessage
3. Zero ou um onError é executado (pára o processamento)
4. onTerminate is always executed

Exemplo

You want to set headers in the WSConnectionHandler user class:

// WSConnectionHandler class

Class constructor($myToken:Text)

// Creation of the headers sent to the server
This.headers:=New object("x-authorization";$myToken)
// We define two cookies
This.headers.Cookie:="yummy_cookie=choco; tasty_cookie=strawberry"
...

.dataType

.dataType : Text

Descrição

A propriedade .dataType contém o tipo do conteúdo do corpo de resposta. Pode ser "text", "blob" ou "object".

Esta propriedade é só de leitura.

.handler

.handler : Object

Descrição

The .handler property contains the accessor that gets the connectionHandler object used to initiate the connection.

Esta propriedade é só de leitura.

.id

.id : Integer

Descrição

A propriedade .id contém o identificador único da conexão.

Esta propriedade é só de leitura.

.send()

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

Parâmetro	Tipo		Descrição
message	Text, Blob, Object	->	Mensagem a enviar

Descrição

A função .send() envia mensagem ao servidor de WebSocket no tipo de dados definido (Texto, Blob, ou Objeto).

Os conteúdos seguintes são enviados em função do tipo de message:

Tipo	Conteúdo
Text	Texto em UTF-8
Blob	Dados binários
Object	Texto em JSON UTF-8 (o mesmo resultado que com JSON Stringify)

.status

.status : Text

Descrição

The .status property contains the current connection status (can be "Connecting", "Closing", "Closed", or "Connected").

Esta propriedade é só de leitura.

.terminate()

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

Parâmetro	Tipo		Descrição
code	Integer	->	Código de estado que explica porque é que a ligação está a ser encerrada
reason	Text	->	O motivo pelo qual a ligação está a fechar

Descrição

A função .terminate() fecha a conexão de WebSocket, juntamente com parâmetros opcionais code e reason.

In code, you can pass a status code explaining why the connection is being closed (see also WebSocket Connection Close Code in the RFC6455):

• If unspecified, a close code for the connection is automatically set to 1000 for a normal closure, or otherwise to another standard value in the range 1001-1015 that indicates the actual reason the connection was closed.
• Se especificado, o valor desse parâmetro de código substitui a configuração automática. O valor deve ser um número inteiro. Ou 1000, ou um código personalizado no intervalo 3000-4999. Se você especificar um valor code, também deverá especificar um valor reason.

Em reason, você pode passar uma frase descrevendo porque a conexão está sendo fechada.

.url

.url : Text

Descrição

A propriedade .url contém a URL à qual o WebSocket se conectou. É o URL que você passou para a função new().

Esta propriedade é só de leitura.