Verawebsockets
(→loop) |
(→loop) |
||
| Line 29: | Line 29: | ||
=== loop === | === loop === | ||
This function must be called if the [[#create|''create'']] function was called with the ''standalone'' parameter set to ''true''. | This function must be called if the [[#create|''create'']] function was called with the ''standalone'' parameter set to ''true''. | ||
| − | + | It blocks the main thread, waiting for the service thread to finish execution. | |
Parameters: | Parameters: | ||
Revision as of 08:18, 9 March 2018
Contents |
What is verawebsockets?
verawebsockets is a Lua library based on the libwebsockets v2.4 library (https://libwebsockets.org).
The intention is to provide websockets support for the Luup plugins, which means that verawebsockets can be used from LuaUPnP as well as from standalone Lua scripts.
Functions
create
Creates a websocket oject, which must be passed to other functions which require it.
Parameters:
- url (string): The URL to connect to.
- event_handlers (table): A table where the index is the event ID, and the value is the callback function name.
- ssl_settings (table): A table where the index is the SSL setting name, and the value is the SSL setting value.
- standalone (boolean): Set this to true if using the library from a standalone Lua script, or to false if using the library from LuaUPnP. If not set, the default value is false. If standalone is true, you must call the loop function after you call the connect function.
Returns:
- wso (websocket): The websocket object.
connect
Connects to the URL from the websocket object.
Parameters:
- wso (websocket): This is the websocket object returned by the create function.
Returns:
- nothing
loop
This function must be called if the create function was called with the standalone parameter set to true. It blocks the main thread, waiting for the service thread to finish execution.
Parameters:
- none
Returns:
- nothing
set_log_level
Set how verbose the logs should be.
The default log level is 0, meaning nothing is logged.
If the library is used from LuaUPnP, the logs can be seen in /tmp/log.Init-LuaUPnP
Parameters:
- log_levels (int or string): log_levels can be either a number, representing a bit mask where each bit is a log level, or the string "all", which means all log levels enabled, and it's the equivalent of setting all the bits in the mask (log_levels = 2047). The available log levels are listed here.
Reference
Event IDs
Since verawebsockets is based on the libwebsockets library, the verawebsockets event IDs are the same as the libwebsockets callback reasons, which are documented here:
https://libwebsockets.org/lws-api-doc-v2.4-stable/html/group__usercb.html
These are the event IDs which are currently supported:
| Event ID | libwebsockets callback reason | Description |
|---|---|---|
| 1 | LWS_CALLBACK_CLIENT_CONNECTION_ERROR | Failed to connect to the server. The reason for the failure is passed as parameter to the callback function. Some possible values are:
|
| 3 | LWS_CALLBACK_CLIENT_ESTABLISHED | Called after the connection with the server has been established. No parameter is passed to the callback function. |
| 4 | LWS_CALLBACK_CLOSED | Called after the websocket connection closed. No parameter is passed to the callback function. |
| 8 | LWS_CALLBACK_CLIENT_RECEIVE | Called when we receive data from the server. The received data is passed as parameter to the callback function. |
SSL settings
These are the SSL settings which are currently supported:
| SSL setting | Description |
|---|---|
| client_ssl_cert_filepath | The certificate the client should present to the server on connection. |
| client_ssl_private_key_filepath | Filepath to the client private key. |
Log levels
| Log level | Description |
|---|---|
| 1 | Error |
| 2 | Warning |
| 4 | Notice |
| 8 | Info |
| 16 | Debug |
| 32 | Parser |
| 64 | Header |
| 128 | Extensions |
| 256 | Client |
| 512 | Latency |
| 1024 | User |
Further documentation
- The WebSocket protocol:
https://tools.ietf.org/html/rfc6455
- The libwebsockets library:
- libwebsockets v2.4 documentation:
https://libwebsockets.org/lws-api-doc-v2.4-stable/html/index.html
