WebSocket Protocol

The WebSocket Protocol enables two-way communication between a client running code in a controlled environment to a remote host that has opted-in to communications from that code. The security model used for this is the origin based security model commonly used by web browsers. The protocol consists of an opening handshake followed by basic message framing, layered over TCP. The goal of this technology is to provide a mechanism for browser-based applications that need two-way communication with servers that does not rely on opening multiple HTTP connections.

To use WebSocket, add the following line to your script: 

ws = WebSocket.New

Example

Copy 
ws = WebSocket.New()
print(ws)

Debug Output

2023-03-28T14:37:45.288	Starting Script
2023-03-28T14:37:45.288 websocket

Connect to host with given protocol (ws or wss) to URL and port with optional sub-protocol.

Syntax

ws:Connect(protocol, host, url, port, <sub-protocol>, <headers> )

Arguments

protocol: Connects to client with given protocol.

  • ws:Connect - insecure, equivalent to http

  • wss:Connect - secure, equivalent to https

host: Connects to client using client host.

url: Connects to client using client URL.

port: Connects to client with given port.

sub-protocol: (Optional) Connects to client with given sub-protocol.

<headers>: Connects to client using HTTP headers for client authentication.

Example

Copy 
ws:Connect("wss", "192.168.0.201", "/qrc", 443)

Sends message to server.

Syntax

ws:Write(message, <isBinary>)

Arguments

message: Write the message you wish to send to the server.

<isBinary>: If true is used as argument, write will be binary. If false is used write will be ascii.

Closes the connection to the server.

Syntax

ws:Close()

Callback called when WebSocket is connected.

Syntax

ws:Connected = function(ws)

Arguments

ws: Connected WebSocket.

Examples

Copy 
ws.Connected = function()
  print("Connected")
  ws:Write("Hey!")
end

Callback called when a new message is received by the WebSocket.

Syntax

ws:Data = function(ws, data)

Arguments

ws: Connected WebSocket.

data: Data received in the WebSocket message.

Examples

Copy 
ws.Data = function( ws, data)
  print("Data", data)
end

Callback called when an error occurs on the WebSocket.

Syntax

ws:Error = function(ws, err)

Arguments

ws: Connected WebSocket.

err: Callback error received.

Examples

Copy 
ws.Error = function( ws, err)
  print("Error", err)
end 

Callback called when the WebSocket is closed.

Syntax

ws:Closed = function(ws)

Arguments

ws: Connected WebSocket.

Examples

Copy 
ws.Closed = function()
  print("closed")
end 

Ping is used to keep a WebSocket connection alive.

Syntax

ws:Ping = function(ws)

Arguments

ws: Connected WebSocket.

Events

ws.Pong = function(ws)

Examples

Copy 
ws = WebSocket.New()
pingTimer = Timer.New()

pingTimer.EventHandler = function()
  ws:Ping()
end

ws.Connected = function(ws)
  print("Connected")
  
  -- send ping every 10 seconds
  pingTimer:Start(10)
  
  ws:Write("Hey!")
end

ws.Error = function( ws, err)
  pingTimer:Stop()
  print("Error", err)
end 

ws.Closed = function(ws)
  pingTimer:Stop()
  print("closed")
end 

ws.Data = function( ws, data)
  print("Data", data)
end

ws:Connect("wss", "192.168.0.201", "/qrc", 443)

Portions of this topic are reprinted under permission of the Lua WebSocket Protocol license.