Saltar para o conteúdo principal
Versão: 20 R9 BETA

WebSocket

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.

História
ReleaseMudanças
20 R2Adicionado

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 do conteúdo do corpo de resposta
.handler : Object
o acessório que obtém o objeto connectionHandler usado para iniciar a conexão
.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
o status atual da conexão (pode ser "Connecting", "Closing", "Closed" ou "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
ReleaseMudanças
20 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 retorna um novo objeto 4D.WebSocket conectado ao servidor de WebSocket no endereço que você 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 conexões TLS seguras

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

Em connectionHandler, você pode passar um objeto que contém funções de callback a serem chamadas de acordo com eventos de conexão, bem como o tipo de dados e os cabeçalhos a serem tratados.

  • 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.
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
  • : Objeto
    • $2.type (texto): sempre "message"
    • $2.data (texto, blob ou objeto, consulte 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
  • : Objeto
    • $2.type (texto): sempre "error"
    • $2.errors: coleção de pilha de erros 4D em caso de erro de execução.
      • [].errCode (número): código de erro 4D
      • [].message (texto): descrição do erro 4D
      • [].componentSignature (texto): 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: objeto
    • $2.code (number, read-only): short sem sinal que contém o código de fechamento enviado pelo servidor.
    • $2.reason (text, read-only): motivo pelo qual o servidor fechou a conexão. Isto é específico do servidor e do subprotocolo em causa.
    onOpenFunctionFunção de retorno de chamada quando o websocket está aberto. A chamada de retorno recebe os seguintes parâmetros
  • :$1: objeto WebSocket
  • $2: objeto
    • $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.
  • Sintaxe para atribuição de chave padrão: headers.*key*:=*value* (value pode ser uma coleção se a mesma chave aparecer várias vezes)
  • Sintaxe para atribuição de cookie (caso específico): 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 uma vez

    Exemplo

    Você deseja definir cabeçalhos na classe usuário WSConnectionHandler:

    // Classe WSConnectionHandler

    Class constructor($myToken:Text)

    // Criação dos cabeçalhos enviados ao servidor
    This.headers:=New object("x-authorization";$myToken)
    // Definimos dois 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

    A propriedade .handler contém o acessório que obtém o objeto connectionHandler usado para iniciar a conexão.

    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âmetroTipoDescrição
    messageText, 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:

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

    .status

    .status : Text

    Descrição

    A propriedade .status contém o status atual da conexã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 conexão de WebSocket, juntamente com parâmetros opcionais code e reason.

    Em code, você pode passar um código de estado explicando porque a conexão está sendo fechada (consulte também WebSocket Connection Close Code in the RFC6455):

    • Se não for especificado, um código de fechamento da conexão será automaticamente definido como 1000 para um fechamento normal ou, caso contrário, como outro valor padrão no intervalo 1001-1015 que indique o motivo real pelo qual a conexão foi fechada.
    • 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.