Versão: 20 R5 BETA

WebSocketServer

A classe WebSocketServer permite-lhe criar e configurar um servidor WebSocket em 4D. Quando o servidor 4D WebSocket estiver ativo, você poderá abrir e usar conexões WebSocket entre o 4D e os clientes usando a classe [WebSocketConnection] (WebSocketConnectionClass.md).

História

Release	Mudanças
20	Adicionado

Sobre os servidores WebSocket

O protocolo WebSocket proporciona um canal de comunicação full-duplex entre um servidor WebSocket e um cliente (por exemplo, um navegador Web). Para obter mais informações sobre servidores WebSocket, leia [esta página na Wikipedia] (https://en.wikipedia.org/wiki/WebSocket).

Veja também

Consulte também [esta postagem no blog] (https://blog.4d.com/new-built-in-websocket-server/) sobre o servidor 4D WebSocket.

Requisitos

Para criar e manipular seu servidor WebSocket em 4D, é preciso usar duas classes embutidas em 4D:

essa classe (4D.WebSocketServer) para gerenciar o próprio servidor,
a classe 4D.WebSocketConnection para gerir as ligações e as mensagens.

Além disso, terá de criar duas classes de utilizador que conterão funções de retorno de chamada:

uma classe de usuário para tratar as ligações ao servidor,
uma classe de usuário para tratar as mensagens.

Você deve [criar o servidor WebSocket] (#4dwebsocketservernew) em um worker para manter a conexão ativa.

O [4D Web Server] (WebServerClass.md) deve ser iniciado.

Exemplo

Neste exemplo básico, o nosso servidor WebSocket devolverá mensagens em maiúsculas.

Crie o servidor WebSocket utilizando um trabalhador (obrigatório) e passe a sua classe de ligação ao servidor como parâmetro:

    //criar uma instância da classe de usuário
    //que manipulará as conexões com o servidor
var $handler:cs.myServerHandler
$handler:=cs.myServerHandler.new()

CALL WORKER("WebSocketServer"; Formula(wss:=4D.WebSocketServer.new($handler)))  
    //atribuir uma variável (wss) ao WebSocket permite que você  
    //chame wss.terminate() posteriormente

Defina a classe de usuário myServerHandler que contém a(s) função(ões) de retorno de chamada usada(s) para tratar as conexões com o servidor:

//classe myServerHandler

Function onConnection($wss : Object; $event : Object) : Object
    //retorna uma instância da classe de usuário
    //que tratará as mensagens
    return cs.myConnectionHandler.new() 

Defina a classe de usuário myConnectionHandler que contém a(s) função(ões) de retorno de chamada usada(s) para tratar mensagens:

// minhaConnectionHandler classe

Function onMessage($ws : 4D.WebSocketConnecation; $message : Object)
    ├//reenvia a mensagem em maiúsculas 
    $ws.send(Uppercase($message.data))

JS do lado do cliente

Consulte [esta publicação no blog] (https://blog.4d.com/websocket-server/) para ver um exemplo de código Javascript do lado do cliente que manipula uma conexão WebSocket.

Objecto WebSocketServer

Os objectos de servidor WebSocket fornecem as seguintes propriedades e funções:


.connections : Collection todas as conexões atuais tratadas pelo servidor WebSocket
.dataType : Text o tipo de dados recebidos ou enviados
.handler : Object o acessório que obtém o objeto `WSSHandler` usado para iniciar o servidor WebSocket
.path : Text o padrão do caminho para acessar o servidor de WebSocket
.terminate() fecha o servidor de WebSocket
.terminated : Boolean True se o servidor de WebSocket estiver fechado

4D.WebSocketServer.new()

4D.WebSocketServer.new( WSSHandler : Object { ; options : Object } ) : 4D.WebSocketServer

Parâmetro	Tipo		Descrição
WSSHandler	Object	->	Objecto da classe de utilizador que declara as chamadas de retorno do servidor WebSocket
options	Object	->	Parâmetros de configuração do WebSocket
Resultados	4D.WebSocketServer	<-	Novo objeto WebSocketServer

A função 4D.WebSocketServer.new() cria e inicia um servidor WebSocket que usará os retornos de chamada especificados WSSHandler e (opcionalmente) opções e retorna um objeto 4D.WebSocketServer.

A chamada dessa função requer que o [4D Web Server] (WebServerClass.md) seja iniciado. O host e a port do servidor WebSocket são os mesmos que o host e a porta do 4D Web Server.

Parâmetro WSSHandler

No parâmetro WSSHandler, passe uma instância de uma classe de usuário que será chamada sempre que ocorrer um evento no servidor WebSocket - essencialmente, eventos de conexão. A classe deve definir as seguintes funções de retorno de chamada (somente onConnection é obrigatório):

Propriedade	Tipo	Descrição	Por padrão
onConnection	Function	(obrigatório) Chamada de retorno quando é iniciada uma nova ligação de cliente (ver abaixo)	indefinido
onOpen	Function	Callback quando o servidor WebSocket é iniciado (ver abaixo)	indefinido
onTerminate	Function	Callback quando o servidor WebSocket é terminado (ver abaixo)	indefinido
onError	Function	Callback quando ocorre um erro (ver abaixo)	indefinido

WSHandler.onConnection(WSServer : Object ; event : Object) : Object | null

Parâmetro		Tipo		Descrição
WSServer		4D.WebSocketServer	<-	Objecto actual do servidor WebSocket
"event"		Object	<-	Parâmetros
	type	Text		"connection"
	request	Object		objeto `request`. Contém informações sobre o pedido de ligação (ver abaixo)
Resultado		Object	->	`connectionHandler` object (veja abaixo). Se essa função retornar um objeto `connectionHandler`, um objeto `4D.WebSocketConnection` é criado automaticamente e adicionado à coleção de conexões. Esse objeto é então recebido como parâmetro em cada função do objeto `connectionHandler`. Se o valor devolvido for nulo ou indefinido, a ligação é cancelada.

Esta chamada de retorno é feita quando o handshake estiver concluído. Ele deve ser chamado com um objeto [connectionHandler] válido (#connectionhandler-object) para criar a conexão WebSocket; caso contrário, a conexão será cancelada.

WSHandler.onOpen(WSServer : Object ; event : Object)

Parâmetro		Tipo		Descrição
WSServer		4D.WebSocketServer	<-	Objecto actual do servidor WebSocket
"event"		Object	<-	Parâmetros
	type	Text		"open"

Evento emitido quando o servidor websocket é iniciado.

WSHandler.onTerminate(WSServer : Object ; event : Object)

Parâmetro		Tipo		Descrição
WSServer		4D.WebSocketServer	<-	Objecto actual do servidor WebSocket
"event"		Object	<-	Parâmetros
	type	Text		"terminate"

Evento emitido quando o servidor HTTP ou o servidor WebSocket é encerrado.

WSHandler.onError(WSServer : Object ; event : Object)

Parâmetro		Tipo		Descrição
WSServer		4D.WebSocketServer	<-	Objecto actual do servidor WebSocket
"event"		Object	<-	Parâmetros
	type	Text		"error"
	errors	Collection		Coleção da 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

Evento emitido quando ocorre um erro no servidor WebSocket.

Exemplo de classe `WSSHandler`

Este exemplo de um recurso básico de bate-papo ilustra como lidar com conexões de servidor WebSocket em uma classe WSSHandler.

//minhaWSServerHandler classe 

Função onConnection($wss : Objeto; $event : Objeto) : Object

    ├If (VerifyAddress($event.request. emoteAddress))
        ├// O método VerifyAddress valida o endereço do cliente
        ├// O objeto WSConnectionHandler retornado será usado 
        ├// por 4D para instanciar o 4D. Objeto ebSocketConnection
        ^\\// relacionado a esta conexão
        ├return cs.myConnectionHandler. ew()   
        ™️// Ver connectionHandler objeto
    ëElse 
        ├// A conexão é cancelada➲      
        ½ return Null 
    ├End se 

Function onOpen($wss : Object; $event : Objeto)
LogFile("*** Servidor iniciado")

Função onTerminate($wss : Objeto; $event : Objeto)
LogFile("*** Servidor fechado")

Função onError($wss : Objeto; $event : Objeto)
LogFile("! ! Erro no servidor: "+$event. rrors.first().message)

objeto `request`

Um objeto request contém as seguintes propriedades:

Parâmetro	Tipo	Descrição
headers	Object	O pedido HTTP GET do cliente. `headers.key=value` (o valor pode ser uma coleção se a mesma chave aparecer várias vezes)
query	Object	Objecto que contém os parâmetros URL. Por exemplo, se os parâmetros são: `?key1=value1&key2=value2` -> `query.key1=value1`, `query.key2=value2`
url	Text	contém apenas o URL que está presente no pedido HTTP efectivo. Ex: `GET /status?name=ryan HTTP/1.1` -> url="/status?name=ryan"
remoteAddress	Text	Endereço IP do cliente

objeto `connectionHandler`

Como resultado do WSHandler. callback nConnection, passe um objeto connectionHandler, que é uma instância de uma classe de usuário que será chamada toda vez que um evento ocorrer na conexão de WebSocket --essencialmente, mensagens recebidas. A classe deve definir as seguintes funções de retorno de chamada (somente onConnection é obrigatório):

Parâmetro	Tipo	Descrição
onMessage	Function	(obrigatório) Função chamada quando é recebida uma nova mensagem desta ligação
onOpen	Function	Função chamada quando o `4D.WebSocketConnection` é criado
onTerminate	Function	Função chamada quando esta ligação é terminada
onError	Function	Função chamada quando ocorre um erro

connectionHandler.onMessage(ws : 4D.WebSocketConnection ; event : Object)

Parâmetro		Tipo		Descrição
ws		`4D.WebSocketConnection`	<-	Objecto de ligação WebSocket actual
"event"		Object	<-	Parâmetros
	type	Text		"message"
	data	Text / Blob / Object		dados enviados pelo cliente

Este Callback para dados WebSocket. Chamado sempre que o WebSocket recebe dados.

connectionHandler.onOpen(ws : 4D.WebSocketConnection ; event : Object)

Parâmetro		Tipo		Descrição
ws		`4D.WebSocketConnection`	<-	Objecto de ligação WebSocket actual
"event"		Object	<-	Parâmetros
	type	Text		"open"

Chamado quando o objeto connectionHandler for criado (após o evento WSS.onConnection).

connectionHandler.onTerminate(ws : 4D.WebSocketConnection ; event : Object)

Parâmetro		Tipo		Descrição
ws		`4D.WebSocketConnection`	<-	Objecto de ligação WebSocket actual
"event"		Object	<-	Parâmetros
	type	Text		"terminate"
	code	Number		Código de estado que indica o motivo pelo qual a ligação foi encerrada. Se o WebSocket não retorna um código de erro, `code` está definido para 1005 se nenhum erro ocorreu ou para 1006 se houve um erro.
	reason	Text		Cadeia de caracteres que explica porque é que a ligação foi encerrada. Se o websocket não devolver um motivo, o código é indefinido

Função chamada quando o WebSocket é fechado.

connectionHandler.onError(ws : 4D.WebSocketConnection ; event : Object)

Parâmetro			Tipo		Descrição
ws			`4D.WebSocketConnection`	<-	Objecto de ligação WebSocket actual
"event"			Object	<-	Parâmetros
	type		Text		"error"
	errors	Collection		Coleção de erros 4D stack em caso de erro de execução [].errCode (number) - código de erro 4D []. essagem (texto) - Descrição do erro 4D [].componentSignature (texto) - Assinatura do componente interno que retornou o erro

Função chamada quando ocorre um erro.

Exemplo de classe `connectionHandler`

Este exemplo de um recurso básico de bate-papo ilustra como tratar mensagens em uma classe connectionHandler.

// myConnectionHandler Class

Function onMessage($ws : 4D.WebSocketConnection; $message : Object)
    // Reenvia a mensagem a todos os clientes de chat   
    This.broadcast($ws;$message.data)

Function onOpen($ws : 4D.WebSocketConnection; $message : Object)
    // Envia uma mensagem aos novos usuários conectados
    $ws.send("Welcome on the chat!")    
    // Envia a mensagem "Novo cliente conectado" a todos os outros clientes de chat
    This.broadcast($ws; "New client connected")

Function onTerminate($ws : 4D.WebSocketConnection; $message : Object)
    // Envia a mensagem "Client disconnected" a todos os outros clientes de bate-papo
    This.broadcast($ws; "Client disconnected")

Function broadcast($ws : 4D.WebSocketConnection; $message:text)
    var $client:4D.WebSocketConnection
    // Reenviar a mensagem a todos os clientes de bate-papo
    For each ($client; $ws.wss.connections)
        // Verificar se o id não é a conexão atual
        If ($client.id#$ws.id)
            $client.send($message)
        End if 
    End for each 

Parâmetro options

No parâmetro opcional options, passe um objeto que contenha as seguintes propriedades:

Propriedade	Tipo	Descrição	Por padrão
path	Text	Representa o caminho para aceder ao servidor WebSocket. Se não for definido um caminho, o servidor WebSocket gere todas as ligações	indefinido
dataType	Text	Tipo dos dados recebidos através da função `connectionHandler.onMessage` e os dados enviados por `WebSocketConnection.send()`. Values: "text", "blob","object"). Se "object": (enviar) transforma o objecto num formato json e envia-o; (recepção): recebe o formato json e transforma-o em objecto	text

.connections

.connections : Collection

Descrição

A propriedade .connections contém todas as conexões atuais tratadas pelo servidor WebSocket. Cada elemento da coleção é um objeto [WebSocketConnection] (WebSocketConnectionClass.md).

Quando uma conexão é encerrada, seu status muda para "Fechado" e ele é removido desta coleção.

.dataType

.dataType : Text

Descrição

A propriedade .dataType contém o tipo de dados recebidos ou enviados.

Esta propriedade é só de leitura.

.handler

.handler : Object

Descrição

A propriedade .handler contém o acessório que obtém o objeto WSSHandler usado para iniciar o servidor WebSocket.

.path

.path : Text

Descrição

A propriedade .path contém o padrão do caminho para acessar o servidor de WebSocket . Se não for definido um caminho, o servidor WebSocket gere todas as ligações.

Esta propriedade é só de leitura.

.terminate()

.terminate()

Parâmetro	Tipo		Descrição
			Não exige nenhum parâmetro

Descrição

A função .terminate() fecha o servidor de WebSocket.

.terminated

.terminated : Boolean

Descrição

A propriedade .terminated contém True se o servidor de WebSocket estiver fechado.

Esta propriedade é só de leitura.

Requisitos​

Exemplo​

Objecto WebSocketServer​

4D.WebSocketServer.new()​

Parâmetro WSSHandler​

Exemplo de classe WSSHandler​

objeto request​

objeto connectionHandler​

Exemplo de classe connectionHandler​

Parâmetro options​

.connections​

Descrição​

.dataType​

Descrição​

.handler​

Descrição​

.path​

Descrição​

.terminate()​

Descrição​

.terminated​

Descrição​

Requisitos

Exemplo

Objecto WebSocketServer

4D.WebSocketServer.new()

Parâmetro WSSHandler

Exemplo de classe `WSSHandler`

objeto `request`

objeto `connectionHandler`

Exemplo de classe `connectionHandler`

Parâmetro options

.connections

Descrição

.dataType

Descrição

.handler

Descrição

.path

Descrição

.terminate()

Descrição

.terminated

Descrição