Details of the API for dmc_websockets.

WebSockets Module API

Methods

WebSocket:new( params )

Create a websocket object, used to connect to a websocket server.

Parameter example Notes
uri ws://echo.websocket.org (string) the address of the WebSocket server. can include port or wss. defaults to 80 (ws) or 445 (wss)
port 80 (number) the port of the websocket server, if not in uri
protocols {'JSON'} (string or table of strings) additional protocols for the server
throttle 500 or LOW (number or constant) how long to pause for requests. constants are WebSocket.OFF, WebSocket.LOW, WebSocket.MEDIUM, WebSocket.HIGH
ssl_params ? additional params for an SSL connection

main.lua

local WebSockets = require 'dmc_corona.dmc_websockets'

-- create a websocket object, 'ws'
local ws = WebSockets:new{
    uri='ws.server.com'
}

WebSockets Configuration File

coming soon

WebSocket Object API

Properties

ws.throttle (milliseconds)

This controls how often the module will check for data. There are several constants available for usage: OFF, LOW, MEDIUM, HIGH. Defaults to MEDIUM.

local WebSockets = require 'dmc_corona.dmc_websockets'
local ws = WebSockets:new{
    uri='ws.server.com'
}
ws.throttle = WebSocket.LOW

or

local WebSockets = require 'dmc_corona.dmc_websockets'
local ws = WebSockets:new{
    uri='ws.server.com'
}
ws.throttle = 500

ws.readyState (number)

The readonly attribute readyState represents the state of the connection. It can have the following values.

Value Indication
Value of 0 the connection has not yet been established
Value of 1 the connection is established and communication is possible
Value of 2 the connection is going through the closing handshake
Value of 3 the connection has been closed or could not be opened

Methods

ws:send( data )

The send() method transmits data using the websocket connection.

ws:close()

The close() method would be used to terminate any existing connection.

ws:addEventListener( ws.EVENT, callbackFunction )

Events are fired when there is a change in the socket. Type of event is one of following:

ONOPEN, ONMESSAGE, ONCLOSE, ONERROR

main.lua

local WebSockets = require 'dmc_corona.dmc_websockets'

local function webSocketsEvent_handler( event )

    local evt_type = event.type

    if evt_type == ws.ONOPEN then
        print( 'Received event: ONOPEN' )

    elseif evt_type == ws.ONMESSAGE then
        local msg = event.message
        print( "Received event: ONMESSAGE" )
        print( msg.data, msg.type )

    elseif evt_type == ws.ONCLOSE then
        print( "Received event: ONCLOSE" )

    elseif evt_type == ws.ONERROR then
        print( "Received event: ONERROR" )

    end
end

local ws = WebSockets:new{
    uri='ws.server.com'
}
ws:addEventListener( ws.EVENT, webSocketsEvent_handler )

Events

ws.ONOPEN

This event occurs when socket connection is established.

ws.ONMESSAGE

This event occurs when client receives data from server. Data message has two components, data and type. Type is one of text or bindary.

main.lua

local function webSocketsEvent_handler( event )

    if event.type == ws.ONMESSAGE then
        local msg = event.message
        print( "Received event: ONMESSAGE" )
        print( msg.data, msg.type )
    end
end

ws.ONERROR

This event occurs when there is any error in communication.

ws.ONCLOSE

This event occurs when connection is closed.