Since | Origin / Contributor | Maintainer | Source |
---|---|---|---|
2016-08-02 | Luís Fonseca | Luís Fonseca | websocket.c |
A websocket client module that implements RFC6455 (version 13) and provides a simple interface to send and receive messages.
The implementation supports fragmented messages, automatically respondes to ping requests and periodically pings if the server isn’t communicating.
SSL/TLS support
Take note of constraints documented in the net module.
Creates a new websocket client. This client should be stored in a variable and will provide all the functions to handle a connection.
When the connection becomes closed, the same client can still be reused - the callback functions are kept - and you can connect again to any server.
Before disposing the client, make sure to call ws:close()
.
websocket.createClient()
none
websocketclient
local ws = websocket.createClient()
-- ...
ws:close()
ws = nil
Closes a websocket connection. The client issues a close frame and attemtps to gracefully close the websocket. If server doesn’t reply, the connection is terminated after a small timeout.
This function can be called even if the websocket isn’t connected.
This function must always be called before disposing the reference to the websocket client.
websocket:close()
none
nil
ws = websocket.createClient()
ws:close()
ws:close() -- nothing will happen
ws = nil -- fully dispose the client as lua will now gc it
Configures websocket client instance.
websocket:config(params)
params
table with configuration parameters. Following keys are recognized:
headers
table of extra request headers affecting every requestnil
ws = websocket.createClient()
ws:config({headers={['User-Agent']='NodeMCU'}})
Attempts to estabilish a websocket connection to the given URL.
websocket:connect(url)
url
the URL for the websocket.nil
ws = websocket.createClient()
ws:connect('ws://echo.websocket.org')
If it fails, an error will be delivered via websocket:on("close", handler)
.
Registers the callback function to handle websockets events (there can be only one handler function registered per event type).
websocket:on(eventName, function(ws, ...))
eventName
the type of websocket event to register the callback function. Those events are: connection
, receive
and close
.function(ws, ...)
callback function.
The function first parameter is always the websocketclient.
Other arguments are required depending on the event type. See example for more details.
If nil
, any previously configured callback is unregistered.nil
local ws = websocket.createClient()
ws:on("connection", function(ws)
print('got ws connection')
end)
ws:on("receive", function(_, msg, opcode)
print('got message:', msg, opcode) -- opcode is 1 for text message, 2 for binary
end)
ws:on("close", function(_, status)
print('connection closed', status)
ws = nil -- required to lua gc the websocket client
end)
ws:connect('ws://echo.websocket.org')
Note that the close callback is also triggered if any error occurs.
The status code for the close, if not 0 then it represents an error, as described in the following table.
Status Code | Explanation |
---|---|
0 | User requested close or the connection was terminated gracefully |
-1 | Failed to extract protocol from URL |
-2 | Hostname is too large (>256 chars) |
-3 | Invalid port number (must be >0 and <= 65535) |
-4 | Failed to extract hostname |
-5 | DNS failed to lookup hostname |
-6 | Server requested termination |
-7 | Server sent invalid handshake HTTP response (i.e. server sent a bad key) |
-8 to -14 | Failed to allocate memory to receive message |
-15 | Server not following FIN bit protocol correctly |
-16 | Failed to allocate memory to send message |
-17 | Server is not switching protocols |
-18 | Connect timeout |
-19 | Server is not responding to health checks nor communicating |
-99 to -999 | Well, something bad has happenned |
Sends a message through the websocket connection.
websocket:send(message, opcode)
message
the data to send.opcode
optionally set the opcode (default: 1, text message)nil
or an error if socket is not connected
ws = websocket.createClient()
ws:on("connection", function()
ws:send('hello!')
end)
ws:connect('ws://echo.websocket.org')