Saltar para o conteúdo principal
Versão: v20 R4 BETA

WebSocket

Histórico
VersãoMudanças
v20 R2Adicionado

A classe WebSocket permite-lhe abrir uma ligação de cliente WebSocket com um servidor, enviar e receber dados e fechar a ligação.

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.

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")
  1. 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())
  1. 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 de conteúdo do corpo da resposta
.handler : Objecto    o acessor que obtém o objecto connectionHandler utilizado para iniciar a ligação
.id : Longint    o identificador único da ligação
.send( message : Text )
.send( message : Blob )
.send( message : Object )
    envia message para o servidor WebSocket no tipo de dados definido (Text, Blob ou Object)
.status : Text    o estado atual da ligação (pode ser "Connecting", "Closing", "Closed" ou "Connected")
.terminate( { code : Integer { ; reason : Text } } )    fecha a ligação WebSocket, juntamente com os parâmetros opcionais code e reason
.url : Text    o URL ao qual o WebSocket se ligou

4D.WebSocket.new()

Histórico
VersãoMudanças
v20 R3Suporte da propriedade headers em connectionHandler

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

ParâmetroTipoDescrição
urlText->URL a que se deve ligar
connectionHandlerObject->Objeto que declara as chamadas de retorno WebSocket
Resultados4D.WebSocket<-Novo objeto WebSocket

|

A função 4D.WebSocket.new() cria e devolve um novo objeto 4D.WebSocket ligado ao servidor WebSocket no endereço que passou em url. O objeto 4D.WebSocket fornece uma API para criar e gerir uma ligação WebSocket a um servidor, bem como para enviar e receber dados de e para o servidor.

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 ligações protegidas por TLS

Se a ligação não for possível, é devolvido um objeto null sendo gerado um erro (que pode ser intersetado através de um método instalado com 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.
  • The WebSocket will be valid as long as the form or worker is not closed.
PropriedadeTipoDescrição
onMessageFunctionFunção de retorno de chamada para dados WebSocket. Chamado sempre que o WebSocket tiver recebido dados. A chamada de retorno recebe os seguintes parâmetros:
  • $1: Objeto WebSocket
  • $2: Object
    • $2.type (text): sempre "message"
    • $2.data (texto, blob, ou objeto, ver dataType): Dados recebidos
    onErrorFunctionFunção de retorno de chamada para erros de execução. A chamada de retorno recebe os seguintes parâmetros:
  • $1: Objeto WebSocket
  • $2: Object
    • $2.type (text): sempre "error"
    • $2.errors: coleção de pilha de erros 4D em caso de erro de execução.
      • [].errCode (number): Código de erro 4D
      • [].message (text): Descrição do erro 4D
      • [].componentSignature (text): Assinatura do componente interno que retornou o erro
    onTerminateFunctionFunção de retorno de chamada quando o WebSocket é terminado. A chamada de retorno recebe os seguintes parâmetros:
  • $1: Objeto WebSocket
  • $2: Object
    • $2.code (number, só de leitura): curto sem sinal que contém o código de fecho enviado pelo servidor.
    • $2.reason (text, só de leitura): Motivo pelo qual o servidor fechou a conexão. Isto é específico do servidor e do subprotocolo em causa.
    • $2.wasClean (boolean, somente leitura): indica se a conexão foi ou não fechada de forma limpa.
    onOpenFunctionFunção de retorno de chamada quando o websocket está aberto. A chamada de retorno recebe os seguintes parâmetros:
  • $1: Objeto WebSocket
  • $2: Object
    • $2.type (texto): sempre "open"
    dataTypeTextTipo de dados recebidos ou enviados. Valores disponíveis: "text" (padrão), "blob", "object". "text" = utf-8
    headersObjectCabeçalhos do 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 é sempre executado

    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 de conteúdo do corpo da resposta. Pode ser "text", "blob" ou "object".

    Esta propriedade é só de leitura.

    .handler

    .handler : Objecto

    Descrição

    The .handler property contains o acessor que obtém o objecto connectionHandler utilizado para iniciar a ligação.

    Esta propriedade é só de leitura.

    .id

    .id : Longint

    Descrição

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

    Esta propriedade é só de leitura.

    .send()

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

    ParâmetroTipoDescrição
    messageText, Blob, Object->Mensagem a enviar

    Descrição

    A função .send() envia message para o servidor WebSocket no tipo de dados definido (Text, Blob ou Object).

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

    TipoConteúdo
    TextTexto em UTF-8
    BlobDados binários
    ObjectTexto em JSON UTF-8 (mesmo resultado de JSON Stringify)

    .status

    .status : Text

    Descrição

    A propriedade .status contém o estado atual da ligação (pode ser "Connecting", "Closing", "Closed" ou "Connected").

    Esta propriedade é só de leitura.

    .terminate()

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

    ParâmetroTipoDescrição
    codeInteger->Código de estado que explica porque é que a ligação está a ser encerrada
    reasonText->O motivo pelo qual a ligação está a fechar

    |

    Descrição

    A função .terminate() fecha a ligação WebSocket, juntamente com os 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. If you specify a code value, you should also specify a reason value.

    In reason, you can pass a string describing why the connection is being closed.

    .url

    .url : Text

    Descrição

    A propriedade .url contém o URL ao qual o WebSocket se ligou. É o URL que passou para a função new().

    Esta propriedade é só de leitura.