192 lines
5.2 KiB
Markdown
192 lines
5.2 KiB
Markdown
# Websocket Module
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2016-08-02 | [Luís Fonseca](https://github.com/luismfonseca) | [Luís Fonseca](https://github.com/luismfonseca) | [websocket.c](../../app/modules/websocket.c)|
|
|
|
|
A websocket *client* module that implements [RFC6455](https://tools.ietf.org/html/rfc6455) (version 13) and provides a simple interface to send and receive messages.
|
|
|
|
The implementation supports fragmented messages, automatically responds to ping requests and periodically pings if the server isn't communicating.
|
|
|
|
**SSL/TLS support**
|
|
|
|
Take note of constraints documented in the [net module](net.md).
|
|
|
|
|
|
## websocket.createClient()
|
|
|
|
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()`.
|
|
|
|
#### Syntax
|
|
`websocket.createClient()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`websocketclient`
|
|
|
|
#### Example
|
|
```lua
|
|
local ws = websocket.createClient()
|
|
-- ...
|
|
ws:close()
|
|
ws = nil
|
|
```
|
|
|
|
|
|
## websocket.client:close()
|
|
|
|
Closes a websocket connection. The client issues a close frame and attempts 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.
|
|
|
|
#### Syntax
|
|
`websocket:close()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
ws = websocket.createClient()
|
|
ws:close()
|
|
ws:close() -- nothing will happen
|
|
|
|
ws = nil -- fully dispose the client as Lua will now gc it
|
|
```
|
|
|
|
|
|
## websocket.client:config(params)
|
|
|
|
Configures websocket client instance.
|
|
|
|
#### Syntax
|
|
`websocket:config(params)`
|
|
|
|
#### Parameters
|
|
- `params` table with configuration parameters. Following keys are recognized:
|
|
- `headers` table of extra request headers affecting every request
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
ws = websocket.createClient()
|
|
ws:config({headers={['User-Agent']='NodeMCU'}})
|
|
```
|
|
|
|
|
|
## websocket.client:connect()
|
|
|
|
Attempts to establish a websocket connection to the given URL.
|
|
|
|
#### Syntax
|
|
`websocket:connect(url)`
|
|
|
|
#### Parameters
|
|
- `url` the URL for the websocket.
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
ws = websocket.createClient()
|
|
ws:connect('ws://echo.websocket.org')
|
|
```
|
|
|
|
If it fails, an error will be delivered via `websocket:on("close", handler)`.
|
|
|
|
|
|
## websocket.client:on()
|
|
|
|
Registers the callback function to handle websockets events (there can be only one handler function registered per event type).
|
|
|
|
#### Syntax
|
|
`websocket:on(eventName, function(ws, ...))`
|
|
|
|
#### Parameters
|
|
- `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.
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
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 happened |
|
|
|
|
|
|
## websocket.client:send()
|
|
|
|
Sends a message through the websocket connection.
|
|
|
|
#### Syntax
|
|
`websocket:send(message, opcode)`
|
|
|
|
#### Parameters
|
|
- `message` the data to send.
|
|
- `opcode` optionally set the opcode (default: 1, text message)
|
|
|
|
#### Returns
|
|
`nil` or an error if socket is not connected
|
|
|
|
#### Example
|
|
```lua
|
|
ws = websocket.createClient()
|
|
ws:on("connection", function()
|
|
ws:send('hello!')
|
|
end)
|
|
ws:connect('ws://echo.websocket.org')
|
|
```
|