API

Before using the WebSockets plugin you must require it in your code file:

local WebSockets = require("plugin.websockets")

Methods

new

Creates a new WebSocket client.

WebSockets.new()

Arguments

This method takes no arguments.

Returns

A new WebSocket client.

Example

local ws = WebSockets.new()

---

addEventListener

Add the WebSocket event handler.

ws:addEventListener(event, handler)

Arguments

Name	Description	Type	Required
event	The event to start listening for. Must be WSEVENT.	Constant	Y
handler	The function that will be called on a WebSocket event.	Function	Y

Example

...

local function WsHandler(event)
  if event.type == ws.ONOPEN then
    print('connected')
  elseif event.type == ws.ONMESSAGE then
    print('message')
  elseif event.type == ws.ONCLOSE then
    print('disconnected')
  elseif event.type == ws.ONERROR then
    print('error')
  end
end

ws:addEventListener(ws.WSEVENT, WsHandler)

...

See Event Constants for more details about each event type.

---

removeEventListener

Remove the WebSocket event handler.

ws:removeEventListener(event, handler)

Arguments

Name	Description	Type	Required
event	The event to stop listening for. Must be WSEVENT.	Constant	Y
handler	The function that is being called on a WebSocket event.	Function	Y

Example

Assuming the event handler in the addEventListener example.

ws:removeEventListener(ws.WSEVENT, WsHandler)

---

connect

Connect the WebSocket object to a WebSocket endpoint.

ws:connect(uri[, options])

Arguments

Name	Description	Type	Required
uri	The WebSocket endpoint to connect to. Supports ws:// and wss:// protocols.	String	Y
options	An optional table of options for the connection (see below).	Table	N

Options Table

Name	Description	Type	Required
port	The port for the WebSocket endpoint. Defaults to 80 for ws:// and 443 for wss:// protocols.	Number	N
tls	The TLS protocol version to use for a secure socket (wss://). Defaults to TLS_1_2.	Constant	N

Example

ws:connect('ws://demos.kaazing.com/echo')

Make sure your WebSocket event handler is set up before calling this method. See addEventListener.

---

disconnect

Disconnect the WebSocket object from the endpoint.

ws:disconnect()

Arguments

This method takes no arguments.

---

send

Send a message over the WebSocket connection.

ws:send(data)

Arguments

Name	Description	Type	Required
data	The message data to send over the connection.	String	Y

Example

ws:send("Hello WebSocket server")

---

Event Constants

The following event constants are used in the WebSocket event listener. Some events will include addtional data that can be accessed from the event object. See also: addEventListener.

ONOPEN

The WebSocket connection is open and ready.

ws.ONOPEN

Event Keys

This event contains no event keys.

Example

...

local function WsHandler(event)
  if event.type == ws.ONOPEN then
    print('connected')
  end
end

...

---

ONMESSAGE

A WebSocket message has been received.

ws.ONMESSAGE

Event Keys

• data

Example

...

local function WsHandler(event)
  if event.type == ws.ONMESSAGE then
    print(event.data) --> message data
  end
end

...

---

ONCLOSE

The WebSocket connection has closed and is no longer available.

ws.ONCLOSE

Event Keys

• code
• reason

Example

...

local function WsHandler(event)
  if event.type == ws.ONCLOSE then
    print(event.code, event.reason) --> closure code and reason
  end
end

...

---

ONERROR

A WebSocket error has occurred. This will generally close the connection.

ws.ONERROR

Event Keys

• code
• reason

Example

...

local function WsHandler(event)
  if event.type == ws.ONERROR then
    print(event.code, event.reason) --> error code and reason
  end
end

...

---

TLS Constants

By default a secure (wss://) client connection uses TLS 1.2.

The following constants are available for backward compatibility or older systems, and are passed in through the options table (see connect).

TLS_1_0

Use TLS version 1.0 as the secure protocol.

ws.TLS_1_0

---

TLS_1_1

Use TLS version 1.1 as the secure protocol.

ws.TLS_1_1

---

Setup Example

Simple Connect

local WebSockets = require("plugin.websockets")

local ws = WebSockets.new()

local function WsHandler(event)
  if event.type == ws.ONOPEN then
    print('connected')
  elseif event.type == ws.ONMESSAGE then
    print('message', event.data)
  elseif event.type == ws.ONCLOSE then
    print('disconnected', event.code, event.reason)
  elseif event.type == ws.ONERROR then
    print('error', event.code, event.reason)
  end
end

ws:addEventListener(ws.WSEVENT, WsHandler)
ws:connect('ws://demos.kaazing.com/echo')

Using Options

....

ws:connect('wss://demos.kaazing.com/echo', {
  tls = ws.TLS_1_0
})

Download the demo project from the Demo section for an even more detailed example.