Verawebsockets
From MiOS
(Difference between revisions)
(Created page with "== What is ''verawebsockets''? == '''verawebsockets''' is a Lua library based on the '''libwebsockets v2.4''' library (https://libwebsockets.org). The intention is to provid...") |
|||
| Line 8: | Line 8: | ||
=== create === | === create === | ||
Creates a websocket oject, which can be passed to the [[#connect|connect]] function. | Creates a websocket oject, which can be passed to the [[#connect|connect]] function. | ||
| + | |||
Parameters: | Parameters: | ||
* url (string): The URL to connect to. | * url (string): The URL to connect to. | ||
| Line 13: | Line 14: | ||
* ssl_settings (table): A table where the index is the SSL setting name, and the value is the SSL setting value. | * 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. | * 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 is done by calling the [[#loop|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. | + | 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. | + | 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: | Returns: | ||
| Line 22: | Line 23: | ||
==== Event IDs ==== | ==== 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: | 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 | https://libwebsockets.org/lws-api-doc-v2.4-stable/html/group__usercb.html | ||
Revision as of 08:52, 8 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 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:
|
| 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:
- libwebsockets v2.4 documentation:
https://libwebsockets.org/lws-api-doc-v2.4-stable/html/index.html
