Verawebsockets

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 can be passed to the connect function.

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): In standalone mode the service thread won't be detached, which means that the main thread should wait for the service thread to exit, before exiting itself.

This is done by calling the loop function from Lua.
This mode should be used when the library is loaded from a standalone Lua script, which can afford to block for an undefined amount of time.
If the library is loaded from LuaUPnP, standalone should be false, because LuaUPnP functions can't block for much time, otherwise the watchdog will restart the Luup engine.

Returns:

• wso (websocket)

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: getaddrinfo (ipv6) failed unknown address family getaddrinfo (ipv4) failed set socket opts failed insert wsi failed lws_ssl_client_connect1 failed lws_ssl_client_connect2 failed Peer hung up read failed HS: URI missing HS: Redirect code but no Location HS: URI did not parse HS: Redirect failed HS: Server did not return 200 HS: OOM HS: disallowed by client filter HS: disallowed at ESTABLISHED HS: ACCEPT missing HS: ws upgrade response not 101 HS: UPGRADE missing HS: Upgrade to something other than websocket HS: CONNECTION missing HS: UPGRADE malformed HS: PROTOCOL malformed HS: Cannot match protocol HS: EXT: list too big HS: EXT: failed setting defaults HS: EXT: failed parsing defaults HS: EXT: failed parsing options HS: EXT: Rejects server options HS: EXT: unknown ext HS: Accept hash wrong HS: Rejected by filter cb HS: OOM HS: SO_SNDBUF failed HS: Rejected at CLIENT_ESTABLISHED
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:

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.

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

Parameters:

• none

Returns:

• nothing

set_log_level

Parameters:

• log_levels (int or string)

Further documentation

• The WebSocket protocol:

https://tools.ietf.org/html/rfc6455

• The libwebsockets library:

https://libwebsockets.org

• libwebsockets v2.4 documentation:

https://libwebsockets.org/lws-api-doc-v2.4-stable/html/index.html