diff --git a/doc/html/annotated.html b/doc/html/annotated.html deleted file mode 100644 index 875a43da..00000000 --- a/doc/html/annotated.html +++ /dev/null @@ -1,108 +0,0 @@ - - -
- - - - -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
Clws_cgi_args | |
Clws_client_connect_info | |
Clws_context_creation_info | |
Clws_email | |
Clws_ext_option_arg | |
Clws_ext_options | |
Clws_extension | |
Clws_gs_event_args | |
Clws_http_mount | |
Clws_plat_file_ops | |
Clws_plugin | |
Clws_plugin_capability | |
Clws_polarssl_context | |
Clws_pollargs | |
Clws_pollfd | |
Clws_process_html_args | |
Clws_process_html_state | |
Clws_protocol_vhost_options | |
Clws_protocols | |
Clws_session_info | |
Clws_token_limits | |
Clws_tokens | |
Clwsgw_hash | |
Clwsgw_hash_bin | |
Cpollfd | |
Ctimer_mapping |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Public Member Functions | |
-void | set_wsi (struct lws *_wsi) |
-int | actual_onRX (Socket *s) |
-void | onRX (Socket *s) |
-void | onError (Socket *s, socket_error_t err) |
-void | onDisconnect (TCPStream *s) |
-void | onSent (Socket *s, uint16_t len) |
-void | serialized_writeable (struct lws *wsi) |
-Data Fields | |
-TCPStream * | ts |
-struct lws * | wsi |
-char | writeable |
-char | awaiting_on_writeable |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Public Member Functions | |
void | start (const uint16_t port) |
-Data Fields | |
-TCPListener | srv |
-Protected Member Functions | |
void | onRX (Socket *s) |
void | onError (Socket *s, socket_error_t err) |
void | onIncoming (TCPListener *s, void *impl) |
void | onDisconnect (TCPStream *s) |
-
|
- -protected | -
disconnection
- -
-
|
- -protected | -
if error occurs
- -
-
|
- -protected | -
new connection
- -
-
|
- -protected | -
incoming data ready
- -void lws_conn_listener::start | -( | -const uint16_t | -port | ) | -- |
start listening
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Files | |
file | libwebsockets.h [code] |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
▼ lib | |
libwebsockets.h |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_add_http_header_status (struct lws *wsi, unsigned int code, unsigned char **p, unsigned char *end) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_add_http_header_by_name (struct lws *wsi, const unsigned char *name, const unsigned char *value, int length, unsigned char **p, unsigned char *end) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_add_http_header_by_token (struct lws *wsi, enum lws_token_indexes token, const unsigned char *value, int length, unsigned char **p, unsigned char *end) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_add_http_header_content_length (struct lws *wsi, unsigned long content_length, unsigned char **p, unsigned char *end) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_finalize_http_header (struct lws *wsi, unsigned char **p, unsigned char *end) |
These apis allow you to create HTTP response headers in a way compatible with both HTTP/1.x and HTTP/2.
-They each append to a buffer taking care about the buffer end, which is passed in as a pointer. When data is written to the buffer, the current position p is updated accordingly.
-All of these apis are LWS_WARN_UNUSED_RESULT as they can run out of space and fail with nonzero return.
-LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_header_by_name | -( | -struct lws * | -wsi, | -
- | - | const unsigned char * | -name, | -
- | - | const unsigned char * | -value, | -
- | - | int | -length, | -
- | - | unsigned char ** | -p, | -
- | - | unsigned char * | -end | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_add_http_header_by_name() - append named header and value
-wsi | the connection to check |
name | the hdr name, like "my-header" |
value | the value after the = for this header |
length | the length of the value |
p | pointer to current position in buffer pointer |
end | pointer to end of buffer |
Appends name: value to the headers
- -LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_header_by_token | -( | -struct lws * | -wsi, | -
- | - | enum lws_token_indexes | -token, | -
- | - | const unsigned char * | -value, | -
- | - | int | -length, | -
- | - | unsigned char ** | -p, | -
- | - | unsigned char * | -end | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_add_http_header_by_token() - append given header and value
-wsi | the connection to check |
token | the token index for the hdr |
value | the value after the = for this header |
length | the length of the value |
p | pointer to current position in buffer pointer |
end | pointer to end of buffer |
Appends name=value to the headers, but is able to take advantage of better HTTP/2 coding mechanisms where possible.
- -LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_header_content_length | -( | -struct lws * | -wsi, | -
- | - | unsigned long | -content_length, | -
- | - | unsigned char ** | -p, | -
- | - | unsigned char * | -end | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_add_http_header_by_name() - append content-length helper
-wsi | the connection to check |
content_length | the content length to use |
p | pointer to current position in buffer pointer |
end | pointer to end of buffer |
Appends content-length: content_length to the headers
- -LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_header_status | -( | -struct lws * | -wsi, | -
- | - | unsigned int | -code, | -
- | - | unsigned char ** | -p, | -
- | - | unsigned char * | -end | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_add_http_header_status() - add the HTTP response status code
-wsi | the connection to check |
code | an HTTP code like 200, 404 etc (see enum http_status) |
p | pointer to current position in buffer pointer |
end | pointer to end of buffer |
Adds the initial response code, so should be called first
- -LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_finalize_http_header | -( | -struct lws * | -wsi, | -
- | - | unsigned char ** | -p, | -
- | - | unsigned char * | -end | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_finalize_http_header() - terminate header block
-wsi | the connection to check |
p | pointer to current position in buffer pointer |
end | pointer to end of buffer |
Indicates no more headers will be added
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Data Structures | |
struct | lws_tokens |
struct | lws_token_limits |
-Enumerations | |
enum | lws_token_indexes { - WSI_TOKEN_GET_URI = 0, -WSI_TOKEN_POST_URI = 1, -WSI_TOKEN_OPTIONS_URI = 2, -WSI_TOKEN_HOST = 3, - - WSI_TOKEN_CONNECTION = 4, -WSI_TOKEN_UPGRADE = 5, -WSI_TOKEN_ORIGIN = 6, -WSI_TOKEN_DRAFT = 7, - - WSI_TOKEN_CHALLENGE = 8, -WSI_TOKEN_EXTENSIONS = 9, -WSI_TOKEN_KEY1 = 10, -WSI_TOKEN_KEY2 = 11, - - WSI_TOKEN_PROTOCOL = 12, -WSI_TOKEN_ACCEPT = 13, -WSI_TOKEN_NONCE = 14, -WSI_TOKEN_HTTP = 15, - - WSI_TOKEN_HTTP2_SETTINGS = 16, -WSI_TOKEN_HTTP_ACCEPT = 17, -WSI_TOKEN_HTTP_AC_REQUEST_HEADERS = 18, -WSI_TOKEN_HTTP_IF_MODIFIED_SINCE = 19, - - WSI_TOKEN_HTTP_IF_NONE_MATCH = 20, -WSI_TOKEN_HTTP_ACCEPT_ENCODING = 21, -WSI_TOKEN_HTTP_ACCEPT_LANGUAGE = 22, -WSI_TOKEN_HTTP_PRAGMA = 23, - - WSI_TOKEN_HTTP_CACHE_CONTROL = 24, -WSI_TOKEN_HTTP_AUTHORIZATION = 25, -WSI_TOKEN_HTTP_COOKIE = 26, -WSI_TOKEN_HTTP_CONTENT_LENGTH = 27, - - WSI_TOKEN_HTTP_CONTENT_TYPE = 28, -WSI_TOKEN_HTTP_DATE = 29, -WSI_TOKEN_HTTP_RANGE = 30, -WSI_TOKEN_HTTP_REFERER = 31, - - WSI_TOKEN_KEY = 32, -WSI_TOKEN_VERSION = 33, -WSI_TOKEN_SWORIGIN = 34, -WSI_TOKEN_HTTP_COLON_AUTHORITY = 35, - - WSI_TOKEN_HTTP_COLON_METHOD = 36, -WSI_TOKEN_HTTP_COLON_PATH = 37, -WSI_TOKEN_HTTP_COLON_SCHEME = 38, -WSI_TOKEN_HTTP_COLON_STATUS = 39, - - WSI_TOKEN_HTTP_ACCEPT_CHARSET = 40, -WSI_TOKEN_HTTP_ACCEPT_RANGES = 41, -WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN = 42, -WSI_TOKEN_HTTP_AGE = 43, - - WSI_TOKEN_HTTP_ALLOW = 44, -WSI_TOKEN_HTTP_CONTENT_DISPOSITION = 45, -WSI_TOKEN_HTTP_CONTENT_ENCODING = 46, -WSI_TOKEN_HTTP_CONTENT_LANGUAGE = 47, - - WSI_TOKEN_HTTP_CONTENT_LOCATION = 48, -WSI_TOKEN_HTTP_CONTENT_RANGE = 49, -WSI_TOKEN_HTTP_ETAG = 50, -WSI_TOKEN_HTTP_EXPECT = 51, - - WSI_TOKEN_HTTP_EXPIRES = 52, -WSI_TOKEN_HTTP_FROM = 53, -WSI_TOKEN_HTTP_IF_MATCH = 54, -WSI_TOKEN_HTTP_IF_RANGE = 55, - - WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE = 56, -WSI_TOKEN_HTTP_LAST_MODIFIED = 57, -WSI_TOKEN_HTTP_LINK = 58, -WSI_TOKEN_HTTP_LOCATION = 59, - - WSI_TOKEN_HTTP_MAX_FORWARDS = 60, -WSI_TOKEN_HTTP_PROXY_AUTHENTICATE = 61, -WSI_TOKEN_HTTP_PROXY_AUTHORIZATION = 62, -WSI_TOKEN_HTTP_REFRESH = 63, - - WSI_TOKEN_HTTP_RETRY_AFTER = 64, -WSI_TOKEN_HTTP_SERVER = 65, -WSI_TOKEN_HTTP_SET_COOKIE = 66, -WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY = 67, - - WSI_TOKEN_HTTP_TRANSFER_ENCODING = 68, -WSI_TOKEN_HTTP_USER_AGENT = 69, -WSI_TOKEN_HTTP_VARY = 70, -WSI_TOKEN_HTTP_VIA = 71, - - WSI_TOKEN_HTTP_WWW_AUTHENTICATE = 72, -WSI_TOKEN_PATCH_URI = 73, -WSI_TOKEN_PUT_URI = 74, -WSI_TOKEN_DELETE_URI = 75, - - WSI_TOKEN_HTTP_URI_ARGS = 76, -WSI_TOKEN_PROXY = 77, -WSI_TOKEN_HTTP_X_REAL_IP = 78, -WSI_TOKEN_HTTP1_0 = 79, - - WSI_TOKEN_X_FORWARDED_FOR = 80, -WSI_TOKEN_CONNECT = 81, -_WSI_TOKEN_CLIENT_SENT_PROTOCOLS, -_WSI_TOKEN_CLIENT_PEER_ADDRESS, - - _WSI_TOKEN_CLIENT_URI, -_WSI_TOKEN_CLIENT_HOST, -_WSI_TOKEN_CLIENT_ORIGIN, -_WSI_TOKEN_CLIENT_METHOD, - - WSI_TOKEN_COUNT, -WSI_TOKEN_NAME_PART, -WSI_TOKEN_SKIPPING, -WSI_TOKEN_SKIPPING_SAW_CR, - - WSI_PARSING_COMPLETE, -WSI_INIT_TOKEN_MUXURL - - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN const unsigned char * | lws_token_to_string (enum lws_token_indexes token) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_hdr_total_length (struct lws *wsi, enum lws_token_indexes h) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_hdr_fragment_length (struct lws *wsi, enum lws_token_indexes h, int frag_idx) |
LWS_VISIBLE LWS_EXTERN int | lws_hdr_copy (struct lws *wsi, char *dest, int len, enum lws_token_indexes h) |
LWS_VISIBLE LWS_EXTERN int | lws_hdr_copy_fragment (struct lws *wsi, char *dest, int len, enum lws_token_indexes h, int frag_idx) |
LWS_VISIBLE LWS_EXTERN const char * | lws_get_urlarg_by_name (struct lws *wsi, const char *name, char *buf, int len) |
In lws the client http headers are temporarily stored in a pool, only for the duration of the http part of the handshake. It's because in most cases, the header content is ignored for the whole rest of the connection lifetime and would then just be taking up space needlessly.
-During LWS_CALLBACK_HTTP when the URI path is delivered is the last time the http headers are still allocated, you can use these apis then to look at and copy out interesting header content (cookies, etc)
-Notice that the header total length reported does not include a terminating '\0', however you must allocate for it when using the _copy apis. So the length reported for a header containing "123" is 3, but you must provide a buffer of length 4 so that "123\0" may be copied into it, or the copy will fail with a nonzero return code.
-In the special case of URL arguments, like ?x=1&y=2, the arguments are stored in a token named for the method, eg, WSI_TOKEN_GET_URI if it was a GET or WSI_TOKEN_POST_URI if POST. You can check the total length to confirm the method.
-For URL arguments, each argument is stored urldecoded in a "fragment", so you can use the fragment-aware api lws_hdr_copy_fragment() to access each argument in turn: the fragments contain urldecoded strings like x=1 or y=2.
-As a convenience, lws has an api that will find the fragment with a given name= part, lws_get_urlarg_by_name().
-LWS_VISIBLE LWS_EXTERN const char* lws_get_urlarg_by_name | -( | -struct lws * | -wsi, | -
- | - | const char * | -name, | -
- | - | char * | -buf, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_get_urlarg_by_name() - return pointer to arg value if present
wsi | the connection to check |
name | the arg name, like "token=" |
buf | the buffer to receive the urlarg (including the name= part) |
len | the length of the buffer to receive the urlarg Returns NULL if not found or a pointer inside buf to just after the -name= part. |
LWS_VISIBLE LWS_EXTERN int lws_hdr_copy | -( | -struct lws * | -wsi, | -
- | - | char * | -dest, | -
- | - | int | -len, | -
- | - | enum lws_token_indexes | -h | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_hdr_copy() - copy a single fragment of the given header to a buffer The buffer length len must include space for an additional terminating '\0', or it will fail returning -1.
-wsi | websocket connection |
dest | destination buffer |
len | length of destination buffer |
h | which header index we are interested in |
copies the whole, aggregated header, even if it was delivered in several actual headers piece by piece
- -LWS_VISIBLE LWS_EXTERN int lws_hdr_copy_fragment | -( | -struct lws * | -wsi, | -
- | - | char * | -dest, | -
- | - | int | -len, | -
- | - | enum lws_token_indexes | -h, | -
- | - | int | -frag_idx | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_hdr_copy_fragment() - copy a single fragment of the given header to a buffer The buffer length len must include space for an additional terminating '\0', or it will fail returning -1. If the requested fragment index is not present, it fails returning -1.
-wsi | websocket connection |
dest | destination buffer |
len | length of destination buffer |
h | which header index we are interested in |
frag_idx | which fragment of h we want to copy |
Normally this is only useful to parse URI arguments like ?x=1&y=2, token index WSI_TOKEN_HTTP_URI_ARGS fragment 0 will contain "x=1" and fragment 1 "y=2"
- -LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_hdr_fragment_length | -( | -struct lws * | -wsi, | -
- | - | enum lws_token_indexes | -h, | -
- | - | int | -frag_idx | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_hdr_fragment_length: report length of a single fragment of a header The returned length does not include the space for a terminating '\0'
-wsi | websocket connection |
h | which header index we are interested in |
frag_idx | which fragment of h we want to get the length of |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_hdr_total_length | -( | -struct lws * | -wsi, | -
- | - | enum lws_token_indexes | -h | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_hdr_total_length: report length of all fragments of a header totalled up The returned length does not include the space for a terminating '\0'
-wsi | websocket connection |
h | which header index we are interested in |
LWS_VISIBLE LWS_EXTERN const unsigned char* lws_token_to_string | -( | -enum lws_token_indexes | -token | ) | -- |
#include <lib/libwebsockets.h>
lws_token_to_string() - returns a textual representation of a hdr token index
-![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Modules | |
plugin: generic-sessions | |
-Data Structures | |
struct | lws_protocols |
struct | lws_plugin_capability |
struct | lws_plugin |
-Typedefs | |
-typedef int(* | lws_plugin_init_func) (struct lws_context *, struct lws_plugin_capability *) |
-typedef int(* | lws_plugin_destroy_func) (struct lws_context *) |
-Functions | |
LWS_VISIBLE LWS_EXTERN const struct lws_protocols * | lws_vhost_name_to_protocol (struct lws_vhost *vh, const char *name) |
LWS_VISIBLE LWS_EXTERN const struct lws_protocols * | lws_get_protocol (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN const struct lws_protocols * | lws_protocol_get (struct lws *wsi) LWS_WARN_DEPRECATED |
LWS_VISIBLE LWS_EXTERN void * | lws_protocol_vh_priv_zalloc (struct lws_vhost *vhost, const struct lws_protocols *prot, int size) |
LWS_VISIBLE LWS_EXTERN void * | lws_protocol_vh_priv_get (struct lws_vhost *vhost, const struct lws_protocols *prot) |
LWS_VISIBLE LWS_EXTERN int | lws_finalize_startup (struct lws_context *context) |
-LWS_VISIBLE LWS_EXTERN int | lws_protocol_init (struct lws_context *context) |
Protocols bind ws protocol names to a custom callback specific to that protocol implementaion.
-A list of protocols can be passed in at context creation time, but it is also legal to leave that NULL and add the protocols and their callback code using plugins.
-Plugins are much preferable compared to cut and pasting code into an application each time, since they can be used standalone.
-LWS_VISIBLE LWS_EXTERN int lws_finalize_startup | -( | -struct lws_context * | -context | ) | -- |
#include <lib/libwebsockets.h>
lws_finalize_startup() - drop initial process privileges
-context | lws context |
This is called after the end of the vhost protocol initializations, but you may choose to call it earlier
- -LWS_VISIBLE LWS_EXTERN const struct lws_protocols* lws_get_protocol | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_protocol() - Returns a protocol pointer from a websocket connection.
wsi | pointer to struct websocket you want to know the protocol of |
Some apis can act on all live connections of a given protocol, - this is how you can get a pointer to the active protocol if needed.-
LWS_VISIBLE LWS_EXTERN const struct lws_protocols* lws_protocol_get | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_protocol_get() - deprecated: use lws_get_protocol
- -LWS_VISIBLE LWS_EXTERN void* lws_protocol_vh_priv_get | -( | -struct lws_vhost * | -vhost, | -
- | - | const struct lws_protocols * | -prot | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_protocol_vh_priv_get() - retreive a protocol's per-vhost storage
-vhost | vhost the instance is related to |
prot | protocol the instance is related to |
Recover a pointer to the allocated per-vhost storage for the protocol created by lws_protocol_vh_priv_zalloc() earlier
- -LWS_VISIBLE LWS_EXTERN void* lws_protocol_vh_priv_zalloc | -( | -struct lws_vhost * | -vhost, | -
- | - | const struct lws_protocols * | -prot, | -
- | - | int | -size | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_protocol_vh_priv_zalloc() - Allocate and zero down a protocol's per-vhost storage
vhost | vhost the instance is related to |
prot | protocol the instance is related to |
size | bytes to allocate |
Protocols often find it useful to allocate a per-vhost struct, this is a helper to be called in the per-vhost init LWS_CALLBACK_PROTOCOL_INIT
- -LWS_VISIBLE LWS_EXTERN const struct lws_protocols* lws_vhost_name_to_protocol | -( | -struct lws_vhost * | -vh, | -
- | - | const char * | -name | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_vhost_name_to_protocol() - get vhost's protocol object from its name
-vh | vhost to search |
name | protocol name |
Returns NULL or a pointer to the vhost's protocol of the requested name
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN int | lws_callback_on_writable (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int | lws_callback_on_writable_all_protocol (const struct lws_context *context, const struct lws_protocols *protocol) |
LWS_VISIBLE LWS_EXTERN int | lws_callback_on_writable_all_protocol_vhost (const struct lws_vhost *vhost, const struct lws_protocols *protocol) |
LWS_VISIBLE LWS_EXTERN int | lws_callback_all_protocol (struct lws_context *context, const struct lws_protocols *protocol, int reason) |
LWS_VISIBLE LWS_EXTERN int | lws_callback_all_protocol_vhost (struct lws_vhost *vh, const struct lws_protocols *protocol, int reason) |
LWS_VISIBLE LWS_EXTERN int | lws_callback_vhost_protocols (struct lws *wsi, int reason, void *in, int len) |
-LWS_VISIBLE LWS_EXTERN int | lws_callback_http_dummy (struct lws *wsi, enum lws_callback_reasons reason, void *user, void *in, size_t len) |
LWS_VISIBLE LWS_EXTERN int | lws_get_socket_fd (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN size_t | lws_get_peer_write_allowance (struct lws *wsi) |
lws can only write data on a connection when it is able to accept more data without blocking.
-So a basic requirement is we should only use the lws_write() apis when the connection we want to write on says that he can accept more data.
-When lws cannot complete your send at the time, it will buffer the data and send it in the background, suppressing any further WRITEABLE callbacks on that connection until it completes. So it is important to write new things in a new writeable callback.
-These apis reflect the various ways we can indicate we would like to be called back when one or more connections is writeable.
-LWS_VISIBLE LWS_EXTERN int lws_callback_all_protocol | -( | -struct lws_context * | -context, | -
- | - | const struct lws_protocols * | -protocol, | -
- | - | int | -reason | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_callback_all_protocol() - Callback all connections using the given protocol with the given reason
-context | lws_context |
protocol | Protocol whose connections will get callbacks |
reason | Callback reason index |
LWS_VISIBLE LWS_EXTERN int lws_callback_all_protocol_vhost | -( | -struct lws_vhost * | -vh, | -
- | - | const struct lws_protocols * | -protocol, | -
- | - | int | -reason | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_callback_all_protocol_vhost() - Callback all connections using the given protocol with the given reason
-vh | Vhost whose connections will get callbacks |
protocol | Which protocol to match |
reason | Callback reason index |
LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_callback_on_writable() - Request a callback when this socket becomes able to be written to without blocking
-wsi | Websocket connection instance to get callback for |
LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable_all_protocol | -( | -const struct lws_context * | -context, | -
- | - | const struct lws_protocols * | -protocol | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_callback_on_writable_all_protocol() - Request a callback for all connections on same vhost using the given protocol when it becomes possible to write to each socket without blocking in turn.
-context | lws_context |
protocol | Protocol whose connections will get callbacks |
LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable_all_protocol_vhost | -( | -const struct lws_vhost * | -vhost, | -
- | - | const struct lws_protocols * | -protocol | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_callback_on_writable_all_protocol_vhost() - Request a callback for all connections using the given protocol when it becomes possible to write to each socket without blocking in turn.
-vhost | Only consider connections on this lws_vhost |
protocol | Protocol whose connections will get callbacks |
LWS_VISIBLE LWS_EXTERN int lws_callback_vhost_protocols | -( | -struct lws * | -wsi, | -
- | - | int | -reason, | -
- | - | void * | -in, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_callback_vhost_protocols() - Callback all protocols enabled on a vhost with the given reason
-wsi | wsi whose vhost will get callbacks |
reason | Callback reason index |
in | in argument to callback |
len | len argument to callback |
LWS_VISIBLE LWS_EXTERN size_t lws_get_peer_write_allowance | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_peer_write_allowance() - get the amount of data writeable to peer if known
-wsi | Websocket connection instance |
if the protocol does not have any guidance, returns -1. Currently only http2 connections get send window information from this API. But your code should use it so it can work properly with any protocol.
-If nonzero return is the amount of payload data the peer or intermediary has reported it has buffer space for. That has NO relationship with the amount of buffer space your OS can accept on this connection for a write action.
-This number represents the maximum you could send to the peer or intermediary on this connection right now without the protocol complaining.
-lws manages accounting for send window updates and payload writes automatically, so this number reflects the situation at the peer or intermediary dynamically.
- -LWS_VISIBLE LWS_EXTERN int lws_get_socket_fd | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_socket_fd() - returns the socket file descriptor
-You will not need this unless you are doing something special
-wsi | Websocket connection instance |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
These functions allow low-level control over stdin/out/err of the cgi.
-However for most cases, binding the cgi to http in and out, the default lws implementation already does the right thing.
-![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Data Structures | |
struct | lws_client_connect_info |
-Enumerations | |
enum | lws_client_connect_ssl_connection_flags { LCCSCF_USE_SSL = (1 << 0), -LCCSCF_ALLOW_SELFSIGNED = (1 << 1), -LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK = (1 << 2), -LCCSCF_ALLOW_EXPIRED = (1 << 3) - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN struct lws * | lws_client_connect_via_info (struct lws_client_connect_info *ccinfo) |
LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT | lws_client_connect (struct lws_context *clients, const char *address, int port, int ssl_connection, const char *path, const char *host, const char *origin, const char *protocol, int ietf_version_or_minus_one) LWS_WARN_DEPRECATED |
LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT | lws_client_connect_extended (struct lws_context *clients, const char *address, int port, int ssl_connection, const char *path, const char *host, const char *origin, const char *protocol, int ietf_version_or_minus_one, void *userdata) LWS_WARN_DEPRECATED |
LWS_VISIBLE LWS_EXTERN int | lws_init_vhost_client_ssl (const struct lws_context_creation_info *info, struct lws_vhost *vhost) |
LWS_VISIBLE LWS_EXTERN int | lws_http_client_read (struct lws *wsi, char **buf, int *len) |
LWS_VISIBLE LWS_EXTERN unsigned int | lws_http_client_http_response (struct lws *wsi) |
-LWS_VISIBLE LWS_EXTERN void | lws_client_http_body_pending (struct lws *wsi, int something_left_to_send) |
enum lws_client_connect_ssl_connection_flags | -
#include <lib/libwebsockets.h>
enum lws_client_connect_ssl_connection_flags - flags that may be used with struct lws_client_connect_info ssl_connection member to control if and how SSL checks apply to the client connection being created
- -LWS_VISIBLE LWS_EXTERN struct lws* LWS_WARN_UNUSED_RESULT lws_client_connect | -( | -struct lws_context * | -clients, | -
- | - | const char * | -address, | -
- | - | int | -port, | -
- | - | int | -ssl_connection, | -
- | - | const char * | -path, | -
- | - | const char * | -host, | -
- | - | const char * | -origin, | -
- | - | const char * | -protocol, | -
- | - | int | -ietf_version_or_minus_one | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_client_connect() - Connect to another websocket server
clients | Websocket context |
address | Remote server address, eg, "myserver.com" |
port | Port to connect to on the remote server, eg, 80 |
ssl_connection | 0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self signed certs |
path | Websocket path on server |
host | Hostname on server |
origin | Socket origin name |
protocol | Comma-separated list of protocols being asked for from the server, or just one. The server will pick the one it likes best. If you don't want to specify a protocol, which is legal, use NULL here. |
ietf_version_or_minus_one | -1 to ask to connect using the default, latest protocol supported, or the specific protocol ordinal |
This function creates a connection to a remote server
- -LWS_VISIBLE LWS_EXTERN struct lws* LWS_WARN_UNUSED_RESULT lws_client_connect_extended | -( | -struct lws_context * | -clients, | -
- | - | const char * | -address, | -
- | - | int | -port, | -
- | - | int | -ssl_connection, | -
- | - | const char * | -path, | -
- | - | const char * | -host, | -
- | - | const char * | -origin, | -
- | - | const char * | -protocol, | -
- | - | int | -ietf_version_or_minus_one, | -
- | - | void * | -userdata | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_client_connect_extended() - Connect to another websocket server
clients | Websocket context |
address | Remote server address, eg, "myserver.com" |
port | Port to connect to on the remote server, eg, 80 |
ssl_connection | 0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self signed certs |
path | Websocket path on server |
host | Hostname on server |
origin | Socket origin name |
protocol | Comma-separated list of protocols being asked for from the server, or just one. The server will pick the one it likes best. |
ietf_version_or_minus_one | -1 to ask to connect using the default, latest protocol supported, or the specific protocol ordinal |
userdata | Pre-allocated user data This function creates a connection to a remote server |
LWS_VISIBLE LWS_EXTERN struct lws* lws_client_connect_via_info | -( | -struct lws_client_connect_info * | -ccinfo | ) | -- |
#include <lib/libwebsockets.h>
lws_client_connect_via_info() - Connect to another websocket server
ccinfo | pointer to lws_client_connect_info struct This function creates a connection to a remote server using the - information provided in ccinfo. |
LWS_VISIBLE LWS_EXTERN unsigned int lws_http_client_http_response | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_http_client_http_response() - get last HTTP response code
-wsi | client connection |
Returns the last server response code, eg, 200 for client http connections.
- -LWS_VISIBLE LWS_EXTERN int lws_http_client_read | -( | -struct lws * | -wsi, | -
- | - | char ** | -buf, | -
- | - | int * | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_http_client_read() - consume waiting received http client data
-wsi | client connection |
buf | pointer to buffer pointer - fill with pointer to your buffer |
len | pointer to chunk length - fill with max length of buffer |
This is called when the user code is notified client http data has arrived. The user code may choose to delay calling it to consume the data, for example waiting until an onward connection is writeable.
-For non-chunked connections, up to len bytes of buf are filled with the received content. len is set to the actual amount filled before return.
-For chunked connections, the linear buffer content contains the chunking headers and it cannot be passed in one lump. Instead, this function will call back LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ with in pointing to the chunk start and len set to the chunk length. There will be as many calls as there are chunks or partial chunks in the buffer.
- -LWS_VISIBLE LWS_EXTERN int lws_init_vhost_client_ssl | -( | -const struct lws_context_creation_info * | -info, | -
- | - | struct lws_vhost * | -vhost | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_init_vhost_client_ssl() - also enable client SSL on an existing vhost
-info | client ssl related info |
vhost | which vhost to initialize client ssl operations on |
You only need to call this if you plan on using SSL client connections on the vhost. For non-SSL client connections, it's not necessary to call this.
-The following members of info are used during the call
- options must have LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT set, - otherwise the call does nothing - - provided_client_ssl_ctx must be NULL to get a generated client - ssl context, otherwise you can pass a prepared one in by setting it - - ssl_cipher_list may be NULL or set to the client valid cipher list - - ssl_ca_filepath may be NULL or client cert filepath - - ssl_cert_filepath may be NULL or client cert filepath - - ssl_private_key_filepath may be NULL or client cert private key -
You must create your vhost explicitly if you want to use this, so you have a pointer to the vhost. Create the context first with the option flag LWS_SERVER_OPTION_EXPLICIT_VHOSTS and then call lws_create_vhost() with the same info struct.
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Modules | |
Vhost mounts and options | |
-Data Structures | |
struct | lws_context_creation_info |
struct | lws_protocol_vhost_options |
-Typedefs | |
-typedef int(* | lws_reload_func) (void) |
-Enumerations | |
enum | lws_context_options { - LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, -LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME = (1 << 2), -LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT, -LWS_SERVER_OPTION_LIBEV = (1 << 4), - - LWS_SERVER_OPTION_DISABLE_IPV6 = (1 << 5), -LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS = (1 << 6), -LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED = (1 << 7), -LWS_SERVER_OPTION_VALIDATE_UTF8 = (1 << 8), - - LWS_SERVER_OPTION_SSL_ECDH, -LWS_SERVER_OPTION_LIBUV = (1 << 10), -LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS, -LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT = (1 << 12), - - LWS_SERVER_OPTION_EXPLICIT_VHOSTS = (1 << 13), -LWS_SERVER_OPTION_UNIX_SOCK = (1 << 14), -LWS_SERVER_OPTION_STS = (1 << 15), -LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY = (1 << 16), - - LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE = (1 << 17), -LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN = (1 << 18), -LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN = (1 << 19) - - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN struct lws_context * | lws_create_context (struct lws_context_creation_info *info) |
LWS_VISIBLE LWS_EXTERN void | lws_context_destroy (struct lws_context *context) |
-LWS_VISIBLE LWS_EXTERN void | lws_context_destroy2 (struct lws_context *context) |
LWS_VISIBLE LWS_EXTERN void | lws_context_deprecate (struct lws_context *context, lws_reload_func cb) |
-LWS_VISIBLE LWS_EXTERN int | lws_context_is_deprecated (struct lws_context *context) |
LWS_VISIBLE LWS_EXTERN int | lws_set_proxy (struct lws_vhost *vhost, const char *proxy) |
LWS_EXTERN LWS_VISIBLE struct lws_vhost * | lws_create_vhost (struct lws_context *context, struct lws_context_creation_info *info) |
LWS_VISIBLE LWS_EXTERN int | lwsws_get_config_globals (struct lws_context_creation_info *info, const char *d, char **config_strings, int *len) |
LWS_VISIBLE LWS_EXTERN int | lwsws_get_config_vhosts (struct lws_context *context, struct lws_context_creation_info *info, const char *d, char **config_strings, int *len) |
LWS_VISIBLE LWS_EXTERN struct lws_vhost * | lws_vhost_get (struct lws *wsi) LWS_WARN_DEPRECATED |
LWS_VISIBLE LWS_EXTERN struct lws_vhost * | lws_get_vhost (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int | lws_json_dump_vhost (const struct lws_vhost *vh, char *buf, int len) |
LWS_VISIBLE LWS_EXTERN int | lws_json_dump_context (const struct lws_context *context, char *buf, int len, int hide_vhosts) |
LWS_VISIBLE LWS_EXTERN void * | lws_context_user (struct lws_context *context) |
LWS requires that there is one context, in which you may define multiple vhosts. Each vhost is a virtual host, with either its own listen port or sharing an existing one. Each vhost has its own SSL context that can be set up individually or left disabled.
-If you don't care about multiple "site" support, you can ignore it and lws will create a single default vhost at context creation time.
-enum lws_context_options | -
#include <lib/libwebsockets.h>
enum lws_context_options - context and vhost options
-Enumerator | |
---|---|
LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT | (VH) Don't allow the connection unless the client has a client cert that we recognize; provides LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT - |
LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME | (CTX) Don't try to get the server's hostname - |
LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT | (VH) Allow non-SSL (plaintext) connections on the same port as SSL is listening... undermines the security of SSL; provides LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT - |
LWS_SERVER_OPTION_LIBEV | (CTX) Use libev event loop - |
LWS_SERVER_OPTION_DISABLE_IPV6 | (VH) Disable IPV6 support - |
LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS | (VH) Don't load OS CA certs, you will need to load your own CA cert(s) - |
LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED | (VH) Accept connections with no valid Cert (eg, selfsigned) - |
LWS_SERVER_OPTION_VALIDATE_UTF8 | (VH) Check UT-8 correctness - |
LWS_SERVER_OPTION_SSL_ECDH | (VH) initialize ECDH ciphers - |
LWS_SERVER_OPTION_LIBUV | (CTX) Use libuv event loop - |
LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS | (VH) Use http redirect to force http to https (deprecated: use mount redirection) - |
LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT | (CTX) Initialize the SSL library at all - |
LWS_SERVER_OPTION_EXPLICIT_VHOSTS | (CTX) Only create the context when calling context create api, implies user code will create its own vhosts - |
LWS_SERVER_OPTION_UNIX_SOCK | (VH) Use Unix socket - |
LWS_SERVER_OPTION_STS | (VH) Send Strict Transport Security header, making clients subsequently go to https even if user asked for http - |
LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY | (VH) Enable LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE to take effect - |
LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE | (VH) if set, only ipv6 allowed on the vhost - |
LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN | (CTX) Libuv only: Do not spin on SIGSEGV / SIGFPE. A segfault normally makes the lib spin so you can attach a debugger to it even if it happened without a debugger in place. You can disable that by giving this option. - |
LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN | For backwards-compatibility reasons, by default lws prepends "http://" to the origin you give in the client connection info struct. If you give this flag when you create the context, only the string you give in the client connect info for .origin (if any) will be used directly. - |
LWS_VISIBLE LWS_EXTERN void lws_context_deprecate | -( | -struct lws_context * | -context, | -
- | - | lws_reload_func | -cb | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_context_deprecate() - Deprecate the websocket context
context | Websocket context This function is used on an existing context before superceding it - with a new context. - - It closes any listen sockets in the context, so new connections are - not possible. - - And it marks the context to be deleted when the number of active - connections into it falls to zero. - - Otherwise if you attach the deprecated context to the replacement - context when it has been created using lws_context_attach_deprecated() - both any deprecated and the new context will service their connections. - - This is aimed at allowing seamless configuration reloads. - - The callback cb will be called after the listen sockets are actually - closed and may be reopened. In the callback the new context should be - configured and created. (With libuv, socket close happens async after - more loop events). |
LWS_VISIBLE LWS_EXTERN void lws_context_destroy | -( | -struct lws_context * | -context | ) | -- |
#include <lib/libwebsockets.h>
lws_context_destroy() - Destroy the websocket context
context | Websocket context This function closes any active connections and then frees the - context. After calling this, any further use of the context is - undefined. |
LWS_VISIBLE LWS_EXTERN void* lws_context_user | -( | -struct lws_context * | -context | ) | -- |
#include <lib/libwebsockets.h>
lws_context_user() - get the user data associated with the context
context | Websocket context |
This returns the optional user allocation that can be attached to the context the sockets live in at context_create time. It's a way to let all sockets serviced in the same context share data without using globals statics in the user code.
- -LWS_VISIBLE LWS_EXTERN struct lws_context* lws_create_context | -( | -struct lws_context_creation_info * | -info | ) | -- |
#include <lib/libwebsockets.h>
lws_create_context() - Create the websocket handler
info | pointer to struct with parameters This function creates the listening socket (if serving) and takes care - of all initialization in one step. - - If option LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, no vhost is - created; you're expected to create your own vhosts afterwards using - lws_create_vhost(). Otherwise a vhost named "default" is also created - using the information in the vhost-related members, for compatibility. - - After initialization, it returns a struct lws_context * that - represents this server. After calling, user code needs to take care - of calling lws_service() with the context pointer to get the - server's sockets serviced. This must be done in the same process - context as the initialization call. - - The protocol callback functions are called for a handful of events - including http requests coming in, websocket connections becoming - established, and data arriving; it's also called periodically to allow - async transmission. - - HTTP requests are sent always to the FIRST protocol in protocol, since - at that time websocket protocol has not been negotiated. Other - protocols after the first one never see any HTTP callback activity. - - The server created is a simple http server by default; part of the - websocket standard is upgrading this http connection to a websocket one. - - This allows the same server to provide files like scripts and favicon / - images or whatever over http and dynamic data over websockets all in - one place; they're all handled in the user callback. |
LWS_EXTERN LWS_VISIBLE struct lws_vhost* lws_create_vhost | -( | -struct lws_context * | -context, | -
- | - | struct lws_context_creation_info * | -info | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_create_vhost() - Create a vhost (virtual server context)
context | pointer to result of lws_create_context() |
info | pointer to struct with parameters |
This function creates a virtual server (vhost) using the vhost-related members of the info struct. You can create many vhosts inside one context if you created the context with the option LWS_SERVER_OPTION_EXPLICIT_VHOSTS
- -LWS_VISIBLE LWS_EXTERN struct lws_vhost* lws_get_vhost | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_vhost() - return the vhost a wsi belongs to
-wsi | which connection |
LWS_VISIBLE LWS_EXTERN int lws_json_dump_context | -( | -const struct lws_context * | -context, | -
- | - | char * | -buf, | -
- | - | int | -len, | -
- | - | int | -hide_vhosts | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_json_dump_context() - describe context state and stats in JSON
-context | the context |
buf | buffer to fill with JSON |
len | max length of buf |
LWS_VISIBLE LWS_EXTERN int lws_json_dump_vhost | -( | -const struct lws_vhost * | -vh, | -
- | - | char * | -buf, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_json_dump_vhost() - describe vhost state and stats in JSON
-vh | the vhost |
buf | buffer to fill with JSON |
len | max length of buf |
LWS_VISIBLE LWS_EXTERN int lws_set_proxy | -( | -struct lws_vhost * | -vhost, | -
- | - | const char * | -proxy | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_set_proxy() - Setups proxy to lws_context.
vhost | pointer to struct lws_vhost you want set proxy for |
proxy | pointer to c string containing proxy in format address:port |
Returns 0 if proxy string was parsed and proxy was setup. Returns -1 if proxy is NULL or has incorrect format.
-This is only required if your OS does not provide the http_proxy environment variable (eg, OSX)
-IMPORTANT! You should call this function right after creation of the lws_context and before call to connect. If you call this function after connect behavior is undefined. This function will override proxy settings made on lws_context creation with genenv() call.
- -LWS_VISIBLE LWS_EXTERN struct lws_vhost* lws_vhost_get | -( | -struct lws * | -wsi | ) | -- |
LWS_VISIBLE LWS_EXTERN int lwsws_get_config_globals | -( | -struct lws_context_creation_info * | -info, | -
- | - | const char * | -d, | -
- | - | char ** | -config_strings, | -
- | - | int * | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lwsws_get_config_globals() - Parse a JSON server config file
info | pointer to struct with parameters |
d | filepath of the config file |
config_strings | storage for the config strings extracted from JSON, the pointer is incremented as strings are stored |
len | pointer to the remaining length left in config_strings the value is decremented as strings are stored |
This function prepares a n lws_context_creation_info struct with global settings from a file d.
-Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
- -LWS_VISIBLE LWS_EXTERN int lwsws_get_config_vhosts | -( | -struct lws_context * | -context, | -
- | - | struct lws_context_creation_info * | -info, | -
- | - | const char * | -d, | -
- | - | char ** | -config_strings, | -
- | - | int * | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lwsws_get_config_vhosts() - Create vhosts from a JSON server config file
context | pointer to result of lws_create_context() |
info | pointer to struct with parameters |
d | filepath of the config file |
config_strings | storage for the config strings extracted from JSON, the pointer is incremented as strings are stored |
len | pointer to the remaining length left in config_strings the value is decremented as strings are stored |
This function creates vhosts into a context according to the settings in JSON files found in directory d.
-Requires CMake option LWS_WITH_LEJP_CONF to have been enabled
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Typedefs | |
-typedef void( | lws_ev_signal_cb_t) (EV_P_ struct ev_signal *w, int revents) |
-Functions | |
-LWS_VISIBLE LWS_EXTERN int | lws_ev_sigint_cfg (struct lws_context *context, int use_ev_sigint, lws_ev_signal_cb_t *cb) |
-LWS_VISIBLE LWS_EXTERN int | lws_ev_initloop (struct lws_context *context, struct ev_loop *loop, int tsi) |
-LWS_VISIBLE LWS_EXTERN void | lws_ev_sigint_cb (struct ev_loop *loop, struct ev_signal *watcher, int revents) |
APIs specific to libev event loop itegration
-![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Data Structures | |
struct | lws_ext_options |
struct | lws_ext_option_arg |
struct | lws_extension |
-Typedefs | |
typedef int | lws_extension_callback_function(struct lws_context *context, const struct lws_extension *ext, struct lws *wsi, enum lws_extension_callback_reasons reason, void *user, void *in, size_t len) |
-Enumerations | |
enum | lws_extension_callback_reasons { - LWS_EXT_CB_SERVER_CONTEXT_CONSTRUCT = 0, -LWS_EXT_CB_CLIENT_CONTEXT_CONSTRUCT = 1, -LWS_EXT_CB_SERVER_CONTEXT_DESTRUCT = 2, -LWS_EXT_CB_CLIENT_CONTEXT_DESTRUCT = 3, - - LWS_EXT_CB_CONSTRUCT = 4, -LWS_EXT_CB_CLIENT_CONSTRUCT = 5, -LWS_EXT_CB_CHECK_OK_TO_REALLY_CLOSE = 6, -LWS_EXT_CB_CHECK_OK_TO_PROPOSE_EXTENSION = 7, - - LWS_EXT_CB_DESTROY = 8, -LWS_EXT_CB_DESTROY_ANY_WSI_CLOSING = 9, -LWS_EXT_CB_ANY_WSI_ESTABLISHED = 10, -LWS_EXT_CB_PACKET_RX_PREPARSE = 11, - - LWS_EXT_CB_PACKET_TX_PRESEND = 12, -LWS_EXT_CB_PACKET_TX_DO_SEND = 13, -LWS_EXT_CB_HANDSHAKE_REPLY_TX = 14, -LWS_EXT_CB_FLUSH_PENDING_TX = 15, - - LWS_EXT_CB_EXTENDED_PAYLOAD_RX = 16, -LWS_EXT_CB_CAN_PROXY_CLIENT_CONNECTION = 17, -LWS_EXT_CB_1HZ = 18, -LWS_EXT_CB_REQUEST_ON_WRITEABLE = 19, - - LWS_EXT_CB_IS_WRITEABLE = 20, -LWS_EXT_CB_PAYLOAD_TX = 21, -LWS_EXT_CB_PAYLOAD_RX = 22, -LWS_EXT_CB_OPTION_DEFAULT = 23, - - LWS_EXT_CB_OPTION_SET = 24, -LWS_EXT_CB_OPTION_CONFIRM = 25, -LWS_EXT_CB_NAMED_OPTION_SET = 26 - - } |
enum | lws_ext_options_types { EXTARG_NONE, -EXTARG_DEC, -EXTARG_OPT_DEC - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN int | lws_set_extension_option (struct lws *wsi, const char *ext_name, const char *opt_name, const char *opt_val) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_ext_parse_options (const struct lws_extension *ext, struct lws *wsi, void *ext_user, const struct lws_ext_options *opts, const char *o, int len) |
LWS_EXTERN int | lws_extension_callback_pm_deflate (struct lws_context *context, const struct lws_extension *ext, struct lws *wsi, enum lws_extension_callback_reasons reason, void *user, void *in, size_t len) |
Ws defines optional extensions, lws provides the ability to implement these in user code if so desired.
-We provide one extensions permessage-deflate.
-typedef int lws_extension_callback_function(struct lws_context *context, const struct lws_extension *ext, struct lws *wsi, enum lws_extension_callback_reasons reason, void *user, void *in, size_t len) | -
#include <lib/libwebsockets.h>
typedef lws_extension_callback_function() - Hooks to allow extensions to operate
context | Websockets context |
ext | This extension |
wsi | Opaque websocket instance pointer |
reason | The reason for the call |
user | Pointer to ptr to per-session user data allocated by library |
in | Pointer used for some callback reasons |
len | Length set for some callback reasons Each extension that is active on a particular connection receives - callbacks during the connection lifetime to allow the extension to - operate on websocket data and manage itself. - - Libwebsockets takes care of allocating and freeing "user" memory for - each active extension on each connection. That is what is pointed to - by the user parameter. - - LWS_EXT_CB_CONSTRUCT: called when the server has decided to - select this extension from the list provided by the client, - just before the server will send back the handshake accepting - the connection with this extension active. This gives the - extension a chance to initialize its connection context found - in user. - - LWS_EXT_CB_CLIENT_CONSTRUCT: same as LWS_EXT_CB_CONSTRUCT - but called when client is instantiating this extension. Some - extensions will work the same on client and server side and then - you can just merge handlers for both CONSTRUCTS. - - LWS_EXT_CB_DESTROY: called when the connection the extension was - being used on is about to be closed and deallocated. It's the - last chance for the extension to deallocate anything it has - allocated in the user data (pointed to by user) before the - user data is deleted. This same callback is used whether you - are in client or server instantiation context. - - LWS_EXT_CB_PACKET_RX_PREPARSE: when this extension was active on - a connection, and a packet of data arrived at the connection, - it is passed to this callback to give the extension a chance to - change the data, eg, decompress it. user is pointing to the - extension's private connection context data, in is pointing - to an lws_tokens struct, it consists of a char * pointer called - token, and an int called token_len. At entry, these are - set to point to the received buffer and set to the content - length. If the extension will grow the content, it should use - a new buffer allocated in its private user context data and - set the pointed-to lws_tokens members to point to its buffer. - - LWS_EXT_CB_PACKET_TX_PRESEND: this works the same way as - LWS_EXT_CB_PACKET_RX_PREPARSE above, except it gives the - extension a chance to change websocket data just before it will - be sent out. Using the same lws_token pointer scheme in in, - the extension can change the buffer and the length to be - transmitted how it likes. Again if it wants to grow the - buffer safely, it should copy the data into its own buffer and - set the lws_tokens token pointer to it. - - LWS_EXT_CB_ARGS_VALIDATE: |
enum lws_ext_options_types | -
#include <lib/libwebsockets.h>
enum lws_ext_options_types
-Enumerator | |
---|---|
EXTARG_NONE | does not take an argument - |
EXTARG_DEC | requires a decimal argument - |
EXTARG_OPT_DEC | may have an optional decimal argument - |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_ext_parse_options | -( | -const struct lws_extension * | -ext, | -
- | - | struct lws * | -wsi, | -
- | - | void * | -ext_user, | -
- | - | const struct lws_ext_options * | -opts, | -
- | - | const char * | -o, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_ext_parse_options() - deal with parsing negotiated extension options
-ext | related extension struct |
wsi | websocket connection |
ext_user | per-connection extension private data |
opts | list of supported options |
o | option string to parse |
len | length |
LWS_EXTERN int lws_extension_callback_pm_deflate | -( | -struct lws_context * | -context, | -
- | - | const struct lws_extension * | -ext, | -
- | - | struct lws * | -wsi, | -
- | - | enum lws_extension_callback_reasons | -reason, | -
- | - | void * | -user, | -
- | - | void * | -in, | -
- | - | size_t | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_extension_callback_pm_deflate() - extension for RFC7692
-context | lws context |
ext | related lws_extension struct |
wsi | websocket connection |
reason | incoming callback reason |
user | per-connection extension private data |
in | pointer parameter |
len | length parameter |
Built-in callback implementing RFC7692 permessage-deflate
- -LWS_VISIBLE LWS_EXTERN int lws_set_extension_option | -( | -struct lws * | -wsi, | -
- | - | const char * | -ext_name, | -
- | - | const char * | -opt_name, | -
- | - | const char * | -opt_val | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_set_extension_option(): set extension option if possible
-wsi | websocket connection |
ext_name | name of ext, like "permessage-deflate" |
opt_name | name of option, like "rx_buf_size" |
opt_val | value to set option to |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Data Structures | |
struct | lws_plat_file_ops |
-Functions | |
LWS_VISIBLE LWS_EXTERN struct lws_plat_file_ops *LWS_WARN_UNUSED_RESULT | lws_get_fops (struct lws_context *context) |
-LWS_VISIBLE LWS_EXTERN void | lws_set_fops (struct lws_context *context, struct lws_plat_file_ops *fops) |
Use these helper functions if you want to access a file from the perspective of a specific wsi, which is usually the case. If you just want contextless file access, use the fops callbacks directly with NULL wsi instead of these helpers.
-If so, then it calls the platform handler or user overrides where present (as defined in info->fops)
-The advantage from all this is user code can be portable for file operations without having to deal with differences between platforms.
-LWS_VISIBLE LWS_EXTERN struct lws_plat_file_ops* LWS_WARN_UNUSED_RESULT lws_get_fops | -( | -struct lws_context * | -context | ) | -- |
#include <lib/libwebsockets.h>
lws_get_fops() - get current file ops
-context | context |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Typedefs | |
typedef int(* | lws_spa_fileupload_cb) (void *data, const char *name, const char *filename, char *buf, int len, enum lws_spa_fileupload_states state) |
-Enumerations | |
enum | lws_spa_fileupload_states { LWS_UFS_CONTENT, -LWS_UFS_FINAL_CONTENT, -LWS_UFS_OPEN - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN struct lws_spa * | lws_spa_create (struct lws *wsi, const char *const *param_names, int count_params, int max_storage, lws_spa_fileupload_cb opt_cb, void *opt_data) |
LWS_VISIBLE LWS_EXTERN int | lws_spa_process (struct lws_spa *spa, const char *in, int len) |
LWS_VISIBLE LWS_EXTERN int | lws_spa_finalize (struct lws_spa *spa) |
LWS_VISIBLE LWS_EXTERN int | lws_spa_get_length (struct lws_spa *spa, int n) |
LWS_VISIBLE LWS_EXTERN const char * | lws_spa_get_string (struct lws_spa *spa, int n) |
LWS_VISIBLE LWS_EXTERN int | lws_spa_destroy (struct lws_spa *spa) |
These lws_spa (stateful post arguments) apis let you parse and urldecode POSTed form arguments, both using simple urlencoded and multipart transfer encoding.
-It's capable of handling file uploads as well a named input parsing, and the apis are the same for both form upload styles.
-You feed it a list of parameter names and it creates pointers to the urldecoded arguments: file upload parameters pass the file data in chunks to a user-supplied callback as they come.
-Since it's stateful, it handles the incoming data needing more than one POST_BODY callback and has no limit on uploaded file size.
-typedef int(* lws_spa_fileupload_cb) (void *data, const char *name, const char *filename, char *buf, int len, enum lws_spa_fileupload_states state) | -
#include <lib/libwebsockets.h>
lws_spa_fileupload_cb() - callback to receive file upload data
-data | opt_data pointer set in lws_spa_create |
name | name of the form field being uploaded |
filename | original filename from client |
buf | start of data to receive |
len | length of data to receive |
state | information about how this call relates to file |
Notice name and filename shouldn't be trusted, as they are passed from HTTP provided by the client.
- -enum lws_spa_fileupload_states | -
#include <lib/libwebsockets.h>
enum lws_spa_fileupload_states
-Enumerator | |
---|---|
LWS_UFS_CONTENT | a chunk of file content has arrived - |
LWS_UFS_FINAL_CONTENT | the last chunk (possibly zero length) of file content has arrived - |
LWS_UFS_OPEN | a new file is starting to arrive - |
LWS_VISIBLE LWS_EXTERN struct lws_spa* lws_spa_create | -( | -struct lws * | -wsi, | -
- | - | const char *const * | -param_names, | -
- | - | int | -count_params, | -
- | - | int | -max_storage, | -
- | - | lws_spa_fileupload_cb | -opt_cb, | -
- | - | void * | -opt_data | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_spa_create() - create urldecode parser
-wsi | lws connection (used to find Content Type) |
param_names | array of form parameter names, like "username" |
count_params | count of param_names |
max_storage | total amount of form parameter values we can store |
opt_cb | NULL, or callback to receive file upload data. |
opt_data | NULL, or user pointer provided to opt_cb. |
Creates a urldecode parser and initializes it.
-opt_cb can be NULL if you just want normal name=value parsing, however if one or more entries in your form are bulk data (file transfer), you can provide this callback and filter on the name callback parameter to treat that urldecoded data separately. The callback should return -1 in case of fatal error, and 0 if OK.
- -LWS_VISIBLE LWS_EXTERN int lws_spa_destroy | -( | -struct lws_spa * | -spa | ) | -- |
#include <lib/libwebsockets.h>
lws_spa_destroy() - destroy parser object
-spa | the parser object previously created |
LWS_VISIBLE LWS_EXTERN int lws_spa_finalize | -( | -struct lws_spa * | -spa | ) | -- |
#include <lib/libwebsockets.h>
lws_spa_finalize() - indicate incoming data completed
-spa | the parser object previously created |
LWS_VISIBLE LWS_EXTERN int lws_spa_get_length | -( | -struct lws_spa * | -spa, | -
- | - | int | -n | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_spa_get_length() - return length of parameter value
-spa | the parser object previously created |
n | parameter ordinal to return length of value for |
LWS_VISIBLE LWS_EXTERN const char* lws_spa_get_string | -( | -struct lws_spa * | -spa, | -
- | - | int | -n | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_spa_get_string() - return pointer to parameter value
spa | the parser object previously created |
n | parameter ordinal to return pointer to value for |
LWS_VISIBLE LWS_EXTERN int lws_spa_process | -( | -struct lws_spa * | -spa, | -
- | - | const char * | -in, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_spa_process() - parses a chunk of input data
-spa | the parser object previously created |
in | incoming, urlencoded data |
len | count of bytes valid at |
in |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Data Structures | |
struct | lwsgw_hash_bin |
struct | lwsgw_hash |
struct | lws_session_info |
struct | lws_gs_event_args |
-Enumerations | |
enum | lwsgs_auth_bits { LWSGS_AUTH_LOGGED_IN = 1, -LWSGS_AUTH_ADMIN = 2, -LWSGS_AUTH_VERIFIED = 4, -LWSGS_AUTH_FORGOT_FLOW = 8 - } |
enum | lws_gs_event { LWSGSE_CREATED, -LWSGSE_DELETED - } |
generic-sessions plugin provides a reusable, generic session and login / register / forgot password framework including email verification.
-enum lws_gs_event | -
#include <lib/libwebsockets.h>
enum lws_gs_event
-Enumerator | |
---|---|
LWSGSE_CREATED | a new user was created - |
LWSGSE_DELETED | an existing user was deleted - |
enum lwsgs_auth_bits | -
#include <lib/libwebsockets.h>
enum lwsgs_auth_bits
-Enumerator | |
---|---|
LWSGS_AUTH_LOGGED_IN | user is logged in as somebody - |
LWSGS_AUTH_ADMIN | logged in as the admin user - |
LWSGS_AUTH_VERIFIED | user has verified his email - |
LWSGS_AUTH_FORGOT_FLOW | he just completed "forgot password" flow - |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Data Structures | |
struct | lws_process_html_args |
struct | lws_process_html_state |
-Typedefs | |
-typedef const char *(* | lws_process_html_state_cb) (void *data, int index) |
-Enumerations | |
enum | http_status { - HTTP_STATUS_OK = 200, -HTTP_STATUS_NO_CONTENT = 204, -HTTP_STATUS_PARTIAL_CONTENT = 206, -HTTP_STATUS_MOVED_PERMANENTLY = 301, - - HTTP_STATUS_FOUND = 302, -HTTP_STATUS_SEE_OTHER = 303, -HTTP_STATUS_BAD_REQUEST = 400, -HTTP_STATUS_UNAUTHORIZED, - - HTTP_STATUS_PAYMENT_REQUIRED, -HTTP_STATUS_FORBIDDEN, -HTTP_STATUS_NOT_FOUND, -HTTP_STATUS_METHOD_NOT_ALLOWED, - - HTTP_STATUS_NOT_ACCEPTABLE, -HTTP_STATUS_PROXY_AUTH_REQUIRED, -HTTP_STATUS_REQUEST_TIMEOUT, -HTTP_STATUS_CONFLICT, - - HTTP_STATUS_GONE, -HTTP_STATUS_LENGTH_REQUIRED, -HTTP_STATUS_PRECONDITION_FAILED, -HTTP_STATUS_REQ_ENTITY_TOO_LARGE, - - HTTP_STATUS_REQ_URI_TOO_LONG, -HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE, -HTTP_STATUS_REQ_RANGE_NOT_SATISFIABLE, -HTTP_STATUS_EXPECTATION_FAILED, - - HTTP_STATUS_INTERNAL_SERVER_ERROR = 500, -HTTP_STATUS_NOT_IMPLEMENTED, -HTTP_STATUS_BAD_GATEWAY, -HTTP_STATUS_SERVICE_UNAVAILABLE, - - HTTP_STATUS_GATEWAY_TIMEOUT, -HTTP_STATUS_HTTP_VERSION_NOT_SUPPORTED - - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN int | lws_chunked_html_process (struct lws_process_html_args *args, struct lws_process_html_state *s) |
APIs for receiving chunks of text, replacing a set of variable names via a callback, and then prepending and appending HTML chunked encoding headers.
-LWS_VISIBLE LWS_EXTERN int lws_chunked_html_process | -( | -struct lws_process_html_args * | -args, | -
- | - | struct lws_process_html_state * | -s | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_chunked_html_process() - generic chunked substitution
args | buffer to process using chunked encoding |
s | current processing state |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Modules | |
Form Parsing | |
HTML Chunked Substitution | |
HTTP File transfer | |
HTTP headers: create | |
HTTP headers: read | |
Urlencode and Urldecode | |
-Data Structures | |
struct | lws_tokens |
-Functions | |
LWS_VISIBLE LWS_EXTERN int | lws_return_http_status (struct lws *wsi, unsigned int code, const char *html_body) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_http_redirect (struct lws *wsi, int code, const unsigned char *loc, int len, unsigned char **p, unsigned char *end) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_http_transaction_completed (struct lws *wsi) |
Modules related to handling HTTP
-LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_http_redirect | -( | -struct lws * | -wsi, | -
- | - | int | -code, | -
- | - | const unsigned char * | -loc, | -
- | - | int | -len, | -
- | - | unsigned char ** | -p, | -
- | - | unsigned char * | -end | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_http_redirect() - write http redirect into buffer
-wsi | websocket connection |
code | HTTP response code (eg, 301) |
loc | where to redirect to |
len | length of loc |
p | pointer current position in buffer (updated as we write) |
end | pointer to end of buffer |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_http_transaction_completed | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_http_transaction_completed() - wait for new http transaction or close
wsi | websocket connection Returns 1 if the HTTP connection must close now - Returns 0 and resets connection to wait for new HTTP header / - transaction if possible |
LWS_VISIBLE LWS_EXTERN int lws_return_http_status | -( | -struct lws * | -wsi, | -
- | - | unsigned int | -code, | -
- | - | const char * | -html_body | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_return_http_status() - Return simple http status
wsi | Websocket instance (available from user callback) |
code | Status index, eg, 404 |
html_body | User-readable HTML description < 1KB, or NULL Helper to report HTTP errors back to the client cleanly and - consistently |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN const char * | lws_get_mimetype (const char *file, const struct lws_http_mount *m) |
LWS_VISIBLE LWS_EXTERN int | lws_serve_http_file (struct lws *wsi, const char *file, const char *content_type, const char *other_headers, int other_headers_len) |
-LWS_VISIBLE LWS_EXTERN int | lws_serve_http_file_fragment (struct lws *wsi) |
APIs for sending local files in response to HTTP requests
-LWS_VISIBLE LWS_EXTERN const char* lws_get_mimetype | -( | -const char * | -file, | -
- | - | const struct lws_http_mount * | -m | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_get_mimetype() - Determine mimetype to use from filename
-file | filename |
m | NULL, or mount context |
This uses a canned list of known filetypes first, if no match and m is non-NULL, then tries a list of per-mount file suffix to mimtype mappings.
-Returns either NULL or a pointer to the mimetype matching the file.
- -LWS_VISIBLE LWS_EXTERN int lws_serve_http_file | -( | -struct lws * | -wsi, | -
- | - | const char * | -file, | -
- | - | const char * | -content_type, | -
- | - | const char * | -other_headers, | -
- | - | int | -other_headers_len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_serve_http_file() - Send a file back to the client using http
wsi | Websocket instance (available from user callback) |
file | The file to issue over http |
content_type | The http content type, eg, text/html |
other_headers | NULL or pointer to header string |
other_headers_len | length of the other headers if non-NULL This function is intended to be called from the callback in response - to http requests from the client. It allows the callback to issue - local files down the http link in a single step. - - Returning <0 indicates error and the wsi should be closed. Returning - >0 indicates the file was completely sent and - lws_http_transaction_completed() called on the wsi (and close if != 0) - ==0 indicates the file transfer is started and needs more service later, - the wsi should be left alone. |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Enumerations | |
enum | lws_log_levels { - LLL_ERR = 1 << 0, -LLL_WARN = 1 << 1, -LLL_NOTICE = 1 << 2, -LLL_INFO = 1 << 3, - - LLL_DEBUG = 1 << 4, -LLL_PARSER = 1 << 5, -LLL_HEADER = 1 << 6, -LLL_EXT = 1 << 7, - - LLL_CLIENT = 1 << 8, -LLL_LATENCY = 1 << 9, -LLL_USER = 1 << 10, -LLL_COUNT = 11 - - } |
-Functions | |
-LWS_VISIBLE LWS_EXTERN void | _lws_log (int filter, const char *format,...) LWS_FORMAT(2) |
-LWS_VISIBLE LWS_EXTERN void | _lws_logv (int filter, const char *format, va_list vl) |
LWS_VISIBLE LWS_EXTERN int | lwsl_timestamp (int level, char *p, int len) |
LWS_VISIBLE LWS_EXTERN void | lwsl_hexdump (void *buf, size_t len) |
LWS_VISIBLE LWS_EXTERN void | lws_set_log_level (int level, void(*log_emit_function)(int level, const char *line)) |
LWS_VISIBLE LWS_EXTERN void | lwsl_emit_syslog (int level, const char *line) |
LWS_VISIBLE LWS_EXTERN int | lwsl_visible (int level) |
Lws provides flexible and filterable logging facilities, which can be used inside lws and in user code.
-Log categories may be individually filtered bitwise, and directed to built-in sinks for syslog-compatible logging, or a user-defined function.
-LWS_VISIBLE LWS_EXTERN void lws_set_log_level | -( | -int | -level, | -
- | - | void(*)(int level, const char *line) | -log_emit_function | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_set_log_level() - Set the logging bitfield
level | OR together the LLL_ debug contexts you want output from |
log_emit_function | NULL to leave it as it is, or a user-supplied function to perform log string emission instead of the default stderr one. |
log level defaults to "err", "warn" and "notice" contexts enabled and emission on stderr.
- -LWS_VISIBLE LWS_EXTERN void lwsl_emit_syslog | -( | -int | -level, | -
- | - | const char * | -line | -
- | ) | -- |
#include <lib/libwebsockets.h>
lwsl_emit_syslog() - helper log emit function writes to system log
-level | one of LLL_ log level indexes |
line | log string |
You use this by passing the function pointer to lws_set_log_level(), to set it as the log emit function, it is not called directly.
- -LWS_VISIBLE LWS_EXTERN void lwsl_hexdump | -( | -void * | -buf, | -
- | - | size_t | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lwsl_hexdump() - helper to hexdump a buffer (DEBUG builds only)
-buf | buffer start to dump |
len | length of buffer to dump |
LWS_VISIBLE LWS_EXTERN int lwsl_timestamp | -( | -int | -level, | -
- | - | char * | -p, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lwsl_timestamp: generate logging timestamp string
-level | logging level |
p | char * buffer to take timestamp |
len | length of p |
returns length written in p
- -LWS_VISIBLE LWS_EXTERN int lwsl_visible | -( | -int | -level | ) | -- |
#include <lib/libwebsockets.h>
lwsl_visible() - returns true if the log level should be printed
-level | one of LLL_ log level indexes |
This is useful if you have to do work to generate the log content, you can skip the work if the log level used to print it is not actually enabled at runtime.
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN int | lws_snprintf (char *str, size_t size, const char *format,...) LWS_FORMAT(3) |
LWS_VISIBLE LWS_EXTERN int | lws_get_random (struct lws_context *context, void *buf, int len) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_daemonize (const char *_lock_path) |
LWS_VISIBLE LWS_EXTERN const char *LWS_WARN_UNUSED_RESULT | lws_get_library_version (void) |
LWS_VISIBLE LWS_EXTERN void * | lws_wsi_user (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_parse_uri (char *p, const char **prot, const char **ads, int *port, const char **path) |
LWS_VISIBLE LWS_EXTERN unsigned long | lws_now_secs (void) |
LWS_VISIBLE LWS_EXTERN struct lws_context *LWS_WARN_UNUSED_RESULT | lws_get_context (const struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_get_count_threads (struct lws_context *context) |
LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT | lws_get_parent (const struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT | lws_get_child (const struct lws *wsi) |
-LWS_VISIBLE LWS_EXTERN int | lws_read (struct lws *wsi, unsigned char *buf, size_t len) |
LWS_VISIBLE LWS_EXTERN void | lws_set_allocator (void *(*realloc)(void *ptr, size_t size)) |
Various APIs outside of other categories
-LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_daemonize | -( | -const char * | -_lock_path | ) | -- |
#include <lib/libwebsockets.h>
lws_daemonize(): make current process run in the background
-_lock_path | the filepath to write the lock file |
Spawn lws as a background process, taking care of various things
- -LWS_VISIBLE LWS_EXTERN struct lws* LWS_WARN_UNUSED_RESULT lws_get_child | -( | -const struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_child() - get child wsi or NULL
wsi | lws connection |
Allows you to find a related wsi from the parent wsi.
- -LWS_VISIBLE LWS_EXTERN struct lws_context* LWS_WARN_UNUSED_RESULT lws_get_context | -( | -const struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_context - Allow geting lws_context from a Websocket connection instance
-With this function, users can access context in the callback function. Otherwise users may have to declare context as a global variable.
-wsi | Websocket connection instance |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_get_count_threads | -( | -struct lws_context * | -context | ) | -- |
#include <lib/libwebsockets.h>
lws_get_count_threads(): how many service threads the context uses
-context | the lws context |
By default this is always 1, if you asked for more than lws can handle it will clip the number of threads. So you can use this to find out how many threads are actually in use.
- -LWS_VISIBLE LWS_EXTERN const char* LWS_WARN_UNUSED_RESULT lws_get_library_version | -( | -void | -) | -- |
#include <lib/libwebsockets.h>
lws_get_library_version(): return string describing the version of lws
-On unix, also includes the git describe
- -LWS_VISIBLE LWS_EXTERN struct lws* LWS_WARN_UNUSED_RESULT lws_get_parent | -( | -const struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_parent() - get parent wsi or NULL
wsi | lws connection |
Specialized wsi like cgi stdin/out/err are associated to a parent wsi, this allows you to get their parent.
- -LWS_VISIBLE LWS_EXTERN int lws_get_random | -( | -struct lws_context * | -context, | -
- | - | void * | -buf, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_get_random(): fill a buffer with platform random data
-context | the lws context |
buf | buffer to fill |
len | how much to fill |
This is intended to be called from the LWS_CALLBACK_RECEIVE callback if it's interested to see if the frame it's dealing with was sent in binary mode.
- -LWS_VISIBLE LWS_EXTERN unsigned long lws_now_secs | -( | -void | -) | -- |
#include <lib/libwebsockets.h>
lws_now_secs(): return seconds since 1970-1-1
- -LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_parse_uri | -( | -char * | -p, | -
- | - | const char ** | -prot, | -
- | - | const char ** | -ads, | -
- | - | int * | -port, | -
- | - | const char ** | -path | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_parse_uri: cut up prot:/ads:port/path into pieces Notice it does so by dropping '\0' into input string and the leading / on the path is consequently lost
-p | incoming uri string.. will get written to |
prot | result pointer for protocol part (https://) |
ads | result pointer for address part |
port | result pointer for port part |
path | result pointer for path part |
LWS_VISIBLE LWS_EXTERN void lws_set_allocator | -( | -void *(*)(void *ptr, size_t size) | -realloc | ) | -- |
#include <lib/libwebsockets.h>
lws_set_allocator() - custom allocator support
-realloc | Allows you to replace the allocator (and deallocator) used by lws |
LWS_VISIBLE LWS_EXTERN int lws_snprintf | -( | -char * | -str, | -
- | - | size_t | -size, | -
- | - | const char * | -format, | -
- | - | - | ... | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_snprintf(): snprintf that truncates the returned length too
-str | destination buffer |
size | bytes left in destination buffer |
format | format string |
... | args for format |
This lets you correctly truncate buffers by concatenating lengths, if you reach the limit the reported length doesn't exceed the limit.
- -LWS_VISIBLE LWS_EXTERN void* lws_wsi_user | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_wsi_user() - get the user data associated with the connection
wsi | lws connection |
Not normally needed since it's passed into the callback
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN const char *LWS_WARN_UNUSED_RESULT | lws_canonical_hostname (struct lws_context *context) |
LWS_VISIBLE LWS_EXTERN void | lws_get_peer_addresses (struct lws *wsi, lws_sockfd_type fd, char *name, int name_len, char *rip, int rip_len) |
LWS_VISIBLE LWS_EXTERN const char * | lws_get_peer_simple (struct lws *wsi, char *name, int namelen) |
LWS_VISIBLE LWS_EXTERN int | lws_interface_to_sa (int ipv6, const char *ifname, struct sockaddr_in *addr, size_t addrlen) |
These wrap miscellaneous useful network-related functions
-LWS_VISIBLE LWS_EXTERN const char* LWS_WARN_UNUSED_RESULT lws_canonical_hostname | -( | -struct lws_context * | -context | ) | -- |
#include <lib/libwebsockets.h>
lws_canonical_hostname() - returns this host's hostname
-This is typically used by client code to fill in the host parameter when making a client connection. You can only call it after the context has been created.
-context | Websocket context |
LWS_VISIBLE LWS_EXTERN void lws_get_peer_addresses | -( | -struct lws * | -wsi, | -
- | - | lws_sockfd_type | -fd, | -
- | - | char * | -name, | -
- | - | int | -name_len, | -
- | - | char * | -rip, | -
- | - | int | -rip_len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_get_peer_addresses() - Get client address information
wsi | Local struct lws associated with |
fd | Connection socket descriptor |
name | Buffer to take client address name |
name_len | Length of client address name buffer |
rip | Buffer to take client address IP dotted quad |
rip_len | Length of client address IP buffer This function fills in name and rip with the name and IP of - the client connected with socket descriptor fd. Names may be - truncated if there is not enough room. If either cannot be - determined, they will be returned as valid zero-length strings. |
LWS_VISIBLE LWS_EXTERN const char* lws_get_peer_simple | -( | -struct lws * | -wsi, | -
- | - | char * | -name, | -
- | - | int | -namelen | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_get_peer_simple() - Get client address information without RDNS
-wsi | Local struct lws associated with |
name | Buffer to take client address name |
namelen | Length of client address name buffer |
This provides a 123.123.123.123 type IP address in name from the peer that has connected to wsi
- -LWS_VISIBLE LWS_EXTERN int lws_interface_to_sa | -( | -int | -ipv6, | -
- | - | const char * | -ifname, | -
- | - | struct sockaddr_in * | -addr, | -
- | - | size_t | -addrlen | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_interface_to_sa() - Convert interface name or IP to sockaddr struct
-ipv6 | Allow IPV6 addresses |
ifname | Interface name or IP |
addr | struct sockaddr_in * to be written |
addrlen | Length of addr |
This converts a textual network interface name to a sockaddr usable by other network functions
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN const char * | lws_sql_purify (char *escaped, const char *string, int len) |
LWS_VISIBLE LWS_EXTERN const char * | lws_json_purify (char *escaped, const char *string, int len) |
APIs for escaping untrusted JSON and SQL safely before use
-LWS_VISIBLE LWS_EXTERN const char* lws_json_purify | -( | -char * | -escaped, | -
- | - | const char * | -string, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_json_purify() - like strncpy but with escaping for json chars
-escaped | output buffer |
string | input buffer ('/0' terminated) |
len | output buffer max length |
Because escaping expands the output string, it's not possible to do it in-place, ie, with escaped == string
- -LWS_VISIBLE LWS_EXTERN const char* lws_sql_purify | -( | -char * | -escaped, | -
- | - | const char * | -string, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_sql_purify() - like strncpy but with escaping for sql quotes
-escaped | output buffer |
string | input buffer ('/0' terminated) |
len | output buffer max length |
Because escaping expands the output string, it's not possible to do it in-place, ie, with escaped == string
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Enumerations | |
enum | lws_write_protocol { - LWS_WRITE_TEXT = 0, -LWS_WRITE_BINARY = 1, -LWS_WRITE_CONTINUATION = 2, -LWS_WRITE_HTTP = 3, - - LWS_WRITE_PING = 5, -LWS_WRITE_PONG = 6, -LWS_WRITE_HTTP_FINAL = 7, -LWS_WRITE_HTTP_HEADERS = 8, - - LWS_WRITE_NO_FIN = 0x40, -LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80 - - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN int | lws_write (struct lws *wsi, unsigned char *buf, size_t len, enum lws_write_protocol protocol) |
APIs related to writing data on a connection
-enum lws_write_protocol | -
#include <lib/libwebsockets.h>
Enumerator | |
---|---|
LWS_WRITE_TEXT | Send a ws TEXT message,the pointer must have LWS_PRE valid memory behind it. The receiver expects only valid utf-8 in the payload - |
LWS_WRITE_BINARY | Send a ws BINARY message, the pointer must have LWS_PRE valid memory behind it. Any sequence of bytes is valid - |
LWS_WRITE_CONTINUATION | Continue a previous ws message, the pointer must have LWS_PRE valid memory behind it - |
LWS_WRITE_HTTP | Send HTTP content - |
LWS_WRITE_HTTP_HEADERS | Send http headers (http2 encodes this payload and LWS_WRITE_HTTP payload differently, http 1.x links also handle this correctly. so to be compatible with both in the future,header response part should be sent using this regardless of http version expected) - |
LWS_WRITE_NO_FIN | This part of the message is not the end of the message - |
LWS_WRITE_CLIENT_IGNORE_XOR_MASK | client packet payload goes out on wire unmunged only useful for security tests since normal servers cannot decode the content if used - |
LWS_VISIBLE LWS_EXTERN int lws_write | -( | -struct lws * | -wsi, | -
- | - | unsigned char * | -buf, | -
- | - | size_t | -len, | -
- | - | enum lws_write_protocol | -protocol | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_write() - Apply protocol then write data to client
wsi | Websocket instance (available from user callback) |
buf | The data to send. For data being sent on a websocket connection (ie, not default http), this buffer MUST have LWS_PRE bytes valid BEFORE the pointer. This is so the protocol header data can be added in-situ. |
len | Count of the data bytes in the payload starting from buf |
protocol | Use LWS_WRITE_HTTP to reply to an http connection, and one of LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate data on a websockets connection. Remember to allow the extra bytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT are used. |
This function provides the way to issue data back to the client for both http and websocket protocols.
-IMPORTANT NOTICE!
-When sending with websocket protocol
-LWS_WRITE_TEXT, LWS_WRITE_BINARY, LWS_WRITE_CONTINUATION, LWS_WRITE_PING, LWS_WRITE_PONG
-the send buffer has to have LWS_PRE bytes valid BEFORE the buffer pointer you pass to lws_write().
-This allows us to add protocol info before and after the data, and send as one packet on the network without payload copying, for maximum efficiency.
-So for example you need this kind of code to use lws_write with a 128-byte payload
-char buf[LWS_PRE + 128];
-// fill your part of the buffer... for example here it's all zeros memset(&buf[LWS_PRE], 0, 128);
-lws_write(wsi, &buf[LWS_PRE], 128, LWS_WRITE_TEXT);
-When sending HTTP, with
-LWS_WRITE_HTTP, LWS_WRITE_HTTP_HEADERS LWS_WRITE_HTTP_FINAL
-there is no protocol data prepended, and don't need to take care about the LWS_PRE bytes valid before the buffer pointer.
-LWS_PRE is at least the frame nonce + 2 header + 8 length LWS_SEND_BUFFER_POST_PADDING is deprecated, it's now 0 and can be left off. The example apps no longer use it.
-Pad LWS_PRE to the CPU word size, so that word references to the address immediately after the padding won't cause an unaligned access error. Sometimes for performance reasons the recommended padding is even larger than sizeof(void *).
In the case of sending using websocket protocol, be sure to allocate - valid storage before and after buf as explained above. This scheme - allows maximum efficiency of sending data and protocol in a single - packet while not burdening the user code with any protocol knowledge. - - Return may be -1 for a fatal error needing connection close, or the - number of bytes sent. -
The OS may not accept everything you asked to write on the connection.
-Posix defines POLLOUT indication from poll() to show that the connection will accept more write data, but it doesn't specifiy how much. It may just accept one byte of whatever you wanted to send.
-LWS will buffer the remainder automatically, and send it out autonomously.
-During that time, WRITABLE callbacks will be suppressed.
-This is to handle corner cases where unexpectedly the OS refuses what we usually expect it to accept. You should try to send in chunks that are almost always accepted in order to avoid the inefficiency of the buffering.
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN int | lws_service (struct lws_context *context, int timeout_ms) |
LWS_VISIBLE LWS_EXTERN int | lws_service_tsi (struct lws_context *context, int timeout_ms, int tsi) |
LWS_VISIBLE LWS_EXTERN void | lws_cancel_service_pt (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN void | lws_cancel_service (struct lws_context *context) |
LWS_VISIBLE LWS_EXTERN int | lws_service_fd (struct lws_context *context, struct lws_pollfd *pollfd) |
LWS_VISIBLE LWS_EXTERN int | lws_service_fd_tsi (struct lws_context *context, struct lws_pollfd *pollfd, int tsi) |
LWS_VISIBLE LWS_EXTERN int | lws_service_adjust_timeout (struct lws_context *context, int timeout_ms, int tsi) |
lws_client_http_body_pending() - control if client connection neeeds to send body
-wsi | client connection |
something_left_to_send | nonzero if need to send more body, 0 (default) if nothing more to send |
If you will send payload data with your HTTP client connection, eg, for POST, when you set the related http headers in LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER callback you should also call this API with something_left_to_send nonzero, and call lws_callback_on_writable(wsi);
-After sending the headers, lws will call your callback with LWS_CALLBACK_CLIENT_HTTP_WRITEABLE reason when writable. You can send the next part of the http body payload, calling lws_callback_on_writable(wsi); if there is more to come, or lws_client_http_body_pending(wsi, 0); to let lws know the last part is sent and the connection can move on.
-If you're not using libev / libuv, these apis are needed to enter the poll() wait in lws and service any connections with pending events.
-LWS_VISIBLE LWS_EXTERN void lws_cancel_service | -( | -struct lws_context * | -context | ) | -- |
#include <lib/libwebsockets.h>
lws_cancel_service() - Cancel wait for new pending socket activity
context | Websocket context This function let a call to lws_service() waiting for a timeout - immediately return. - - What it basically does is provide a fake event that will be swallowed, - so the wait in poll() is ended. That's useful because poll() doesn't - attend to changes in POLLIN/OUT/ERR until it re-enters the wait. |
LWS_VISIBLE LWS_EXTERN void lws_cancel_service_pt | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_cancel_service_pt() - Cancel servicing of pending socket activity on one thread
wsi | Cancel service on the thread this wsi is serviced by This function lets a call to lws_service() waiting for a timeout - immediately return. - - It works by creating a phony event and then swallowing it silently. - - The reason it may be needed is when waiting in poll(), changes to - the event masks are ignored by the OS until poll() is reentered. This - lets you halt the poll() wait and make the reentry happen immediately - instead of having the wait out the rest of the poll timeout. |
LWS_VISIBLE LWS_EXTERN int lws_service | -( | -struct lws_context * | -context, | -
- | - | int | -timeout_ms | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_service() - Service any pending websocket activity
context | Websocket context |
timeout_ms | Timeout for poll; 0 means return immediately if nothing needed service otherwise block and service immediately, returning after the timeout if nothing needed service. |
This function deals with any pending websocket traffic, for three kinds of event. It handles these events on both server and client types of connection the same.
-1) Accept new connections to our context's server
-2) Call the receive callback for incoming frame data received by server or client connections.
-You need to call this service function periodically to all the above functions to happen; if your application is single-threaded you can just call it in your main event loop.
-Alternatively you can fork a new process that asynchronously handles calling this service in a loop. In that case you are happy if this call blocks your thread until it needs to take care of something and would call it with a large nonzero timeout. Your loop then takes no CPU while there is nothing happening.
-If you are calling it in a single-threaded app, you don't want it to wait around blocking other things in your loop from happening, so you would call it with a timeout_ms of 0, so it returns immediately if nothing is pending, or as soon as it services whatever was pending.
- -LWS_VISIBLE LWS_EXTERN int lws_service_adjust_timeout | -( | -struct lws_context * | -context, | -
- | - | int | -timeout_ms, | -
- | - | int | -tsi | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_service_adjust_timeout() - Check for any connection needing forced service
context | Websocket context |
timeout_ms | The original poll timeout value. You can just set this to 1 if you don't really have a poll timeout. |
tsi | thread service index |
Under some conditions connections may need service even though there is no pending network action on them, this is "forced service". For default poll() and libuv / libev, the library takes care of calling this and dealing with it for you. But for external poll() integration, you need access to the apis.
-If anybody needs "forced service", returned timeout is zero. In that case, you can call lws_service_tsi() with a timeout of -1 to only service guys who need forced service.
- -LWS_VISIBLE LWS_EXTERN int lws_service_fd | -( | -struct lws_context * | -context, | -
- | - | struct lws_pollfd * | -pollfd | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_service_fd() - Service polled socket with something waiting
context | Websocket context |
pollfd | The pollfd entry describing the socket fd and which events happened, or NULL to tell lws to do only timeout servicing. |
This function takes a pollfd that has POLLIN or POLLOUT activity and services it according to the state of the associated struct lws.
-The one call deals with all "service" that might happen on a socket including listen accepts, http files as well as websocket protocol.
-If a pollfd says it has something, you can just pass it to lws_service_fd() whether it is a socket handled by lws or not. If it sees it is a lws socket, the traffic will be handled and pollfd->revents will be zeroed now.
-If the socket is foreign to lws, it leaves revents alone. So you can see if you should service yourself by checking the pollfd revents after letting lws try to service it.
-You should also call this with pollfd = NULL to just allow the once-per-second global timeout checks; if less than a second since the last check it returns immediately then.
- -LWS_VISIBLE LWS_EXTERN int lws_service_fd_tsi | -( | -struct lws_context * | -context, | -
- | - | struct lws_pollfd * | -pollfd, | -
- | - | int | -tsi | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_service_fd_tsi() - Service polled socket in specific service thread
context | Websocket context |
pollfd | The pollfd entry describing the socket fd and which events happened. |
tsi | thread service index |
Same as lws_service_fd() but used with multiple service threads
- -LWS_VISIBLE LWS_EXTERN int lws_service_tsi | -( | -struct lws_context * | -context, | -
- | - | int | -timeout_ms, | -
- | - | int | -tsi | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_service() - Service any pending websocket activity
-context | Websocket context |
timeout_ms | Timeout for poll; 0 means return immediately if nothing needed service otherwise block and service immediately, returning after the timeout if nothing needed service. |
Same as lws_service(), but for a specific thread service index. Only needed if you are spawning multiple service threads.
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN unsigned char * | lws_SHA1 (const unsigned char *d, size_t n, unsigned char *md) |
LWS_VISIBLE LWS_EXTERN int | lws_b64_encode_string (const char *in, int in_len, char *out, int out_size) |
LWS_VISIBLE LWS_EXTERN int | lws_b64_decode_string (const char *in, char *out, int out_size) |
These provide SHA-1 and B64 helper apis
-LWS_VISIBLE LWS_EXTERN int lws_b64_decode_string | -( | -const char * | -in, | -
- | - | char * | -out, | -
- | - | int | -out_size | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_b64_decode_string(): decode a string from base 64
-in | incoming buffer |
out | result buffer |
out_size | length of result buffer |
Decodes a string using b64
- -LWS_VISIBLE LWS_EXTERN int lws_b64_encode_string | -( | -const char * | -in, | -
- | - | int | -in_len, | -
- | - | char * | -out, | -
- | - | int | -out_size | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_b64_encode_string(): encode a string into base 64
-in | incoming buffer |
in_len | length of incoming buffer |
out | result buffer |
out_size | length of result buffer |
Encodes a string using b64
- -LWS_VISIBLE LWS_EXTERN unsigned char* lws_SHA1 | -( | -const unsigned char * | -d, | -
- | - | size_t | -n, | -
- | - | unsigned char * | -md | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_SHA1(): make a SHA-1 digest of a buffer
-d | incoming buffer |
n | length of incoming buffer |
md | buffer for message digest (must be >= 20 bytes) |
Reduces any size buffer into a 20-byte SHA-1 hash.
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Data Structures | |
struct | lws_email |
-Enumerations | |
enum | lwsgs_smtp_states { - LGSSMTP_IDLE, -LGSSMTP_CONNECTING, -LGSSMTP_CONNECTED, -LGSSMTP_SENT_HELO, - - LGSSMTP_SENT_FROM, -LGSSMTP_SENT_TO, -LGSSMTP_SENT_DATA, -LGSSMTP_SENT_BODY, - - LGSSMTP_SENT_QUIT - - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN int | lws_email_init (struct lws_email *email, uv_loop_t *loop, int max_content) |
LWS_VISIBLE LWS_EXTERN void | lws_email_check (struct lws_email *email) |
LWS_VISIBLE LWS_EXTERN void | lws_email_destroy (struct lws_email *email) |
These apis let you communicate with a local SMTP server to send email from lws. It handles all the SMTP sequencing and protocol actions.
-Your system should have postfix, sendmail or another MTA listening on port 25 and able to send email using the "mail" commandline app. Usually distro MTAs are configured for this by default.
-It runs via its own libuv events if initialized (which requires giving it a libuv loop to attach to).
-It operates using three callbacks, on_next() queries if there is a new email to send, on_get_body() asks for the body of the email, and on_sent() is called after the email is successfully sent.
-To use it
-When you have at least one email to send, call lws_email_check() to schedule starting to send it.
-enum lwsgs_smtp_states | -
#include <lib/libwebsockets.h>
enum lwsgs_smtp_states - where we are in SMTP protocol sequence
-Enumerator | |
---|---|
LGSSMTP_IDLE | awaiting new email - |
LGSSMTP_CONNECTING | opening tcp connection to MTA - |
LGSSMTP_CONNECTED | tcp connection to MTA is connected - |
LGSSMTP_SENT_HELO | sent the HELO - |
LGSSMTP_SENT_FROM | sent FROM - |
LGSSMTP_SENT_TO | sent TO - |
LGSSMTP_SENT_DATA | sent DATA request - |
LGSSMTP_SENT_BODY | sent the email body - |
LGSSMTP_SENT_QUIT | sent the session quit - |
LWS_VISIBLE LWS_EXTERN void lws_email_check | -( | -struct lws_email * | -) | -- |
#include <lib/libwebsockets.h>
lws_email_check() - Request check for new email
-struct lws_email context to check |
Schedules a check for new emails in 1s... call this when you have queued an email for send.
- -LWS_VISIBLE LWS_EXTERN void lws_email_destroy | -( | -struct lws_email * | -) | -- |
#include <lib/libwebsockets.h>
lws_email_destroy() - stop using the struct lws_email
-the struct lws_email context |
Stop sending email using email and free allocations
- -LWS_VISIBLE LWS_EXTERN int lws_email_init | -( | -struct lws_email * | -email, | -
- | - | uv_loop_t * | -loop, | -
- | - | int | -max_content | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_email_init() - Initialize a struct lws_email
-struct lws_email to init | |
loop | libuv loop to use |
max_content | max email content size |
Prepares a struct lws_email for use ending SMTP
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN struct lws * | lws_adopt_socket (struct lws_context *context, lws_sockfd_type accept_fd) |
LWS_VISIBLE LWS_EXTERN struct lws * | lws_adopt_socket_vhost (struct lws_vhost *vh, lws_sockfd_type accept_fd) |
-LWS_VISIBLE struct lws * | lws_adopt_socket_vhost2 (struct lws_vhost *vh, lws_sockfd_type accept_fd, int allow_ssl, int raw) |
LWS_VISIBLE LWS_EXTERN struct lws * | lws_adopt_socket_readbuf (struct lws_context *context, lws_sockfd_type accept_fd, const char *readbuf, size_t len) |
LWS_VISIBLE LWS_EXTERN struct lws * | lws_adopt_socket_vhost_readbuf (struct lws_vhost *vhost, lws_sockfd_type accept_fd, const char *readbuf, size_t len) |
When integrating with an external app with its own event loop, these can be used to accept connections from someone else's listening socket.
-When using lws own event loop, these are not needed.
-LWS_VISIBLE LWS_EXTERN struct lws* lws_adopt_socket | -( | -struct lws_context * | -context, | -
- | - | lws_sockfd_type | -accept_fd | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_adopt_socket() - adopt foreign socket as if listen socket accepted it for the default vhost of context.
context | lws context |
accept_fd | fd of already-accepted socket to adopt |
Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces.
-LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.
- -LWS_VISIBLE LWS_EXTERN struct lws* lws_adopt_socket_readbuf | -( | -struct lws_context * | -context, | -
- | - | lws_sockfd_type | -accept_fd, | -
- | - | const char * | -readbuf, | -
- | - | size_t | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_adopt_socket_readbuf() - adopt foreign socket and first rx as if listen socket accepted it for the default vhost of context.
context | lws context |
accept_fd | fd of already-accepted socket to adopt |
readbuf | NULL or pointer to data that must be drained before reading from accept_fd |
len | The length of the data held at |
readbuf | Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces. |
LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.
-If your external code did not already read from the socket, you can use lws_adopt_socket() instead.
-This api is guaranteed to use the data at
readbuf | first, before reading from the socket. |
readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
- -LWS_VISIBLE LWS_EXTERN struct lws* lws_adopt_socket_vhost | -( | -struct lws_vhost * | -vh, | -
- | - | lws_sockfd_type | -accept_fd | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_adopt_socket_vhost() - adopt foreign socket as if listen socket accepted it for vhost
vhost | lws vhost |
accept_fd | fd of already-accepted socket to adopt |
Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces.
-LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.
- -LWS_VISIBLE LWS_EXTERN struct lws* lws_adopt_socket_vhost_readbuf | -( | -struct lws_vhost * | -vhost, | -
- | - | lws_sockfd_type | -accept_fd, | -
- | - | const char * | -readbuf, | -
- | - | size_t | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_adopt_socket_vhost_readbuf() - adopt foreign socket and first rx as if listen socket accepted it for vhost.
vhost | lws vhost |
accept_fd | fd of already-accepted socket to adopt |
readbuf | NULL or pointer to data that must be drained before reading from accept_fd |
len | The length of the data held at |
readbuf | Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces. |
LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.
-If your external code did not already read from the socket, you can use lws_adopt_socket() instead.
-This api is guaranteed to use the data at
readbuf | first, before reading from the socket. |
readbuf is limited to the size of the ah rx buf, currently 2048 bytes.
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Enumerations | |
enum | pending_timeout { - NO_PENDING_TIMEOUT = 0, -PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE = 1, -PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE = 2, -PENDING_TIMEOUT_ESTABLISH_WITH_SERVER = 3, - - PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE = 4, -PENDING_TIMEOUT_AWAITING_PING = 5, -PENDING_TIMEOUT_CLOSE_ACK = 6, -PENDING_TIMEOUT_AWAITING_EXTENSION_CONNECT_RESPONSE = 7, - - PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE = 8, -PENDING_TIMEOUT_SSL_ACCEPT = 9, -PENDING_TIMEOUT_HTTP_CONTENT = 10, -PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND = 11, - - PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE = 12, -PENDING_TIMEOUT_SHUTDOWN_FLUSH = 13, -PENDING_TIMEOUT_CGI = 14, -PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE = 15, - - PENDING_TIMEOUT_WS_PONG_CHECK_SEND_PING = 16, -PENDING_TIMEOUT_WS_PONG_CHECK_GET_PONG = 17, -PENDING_TIMEOUT_CLIENT_ISSUE_PAYLOAD = 18 - - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN void | lws_set_timeout (struct lws *wsi, enum pending_timeout reason, int secs) |
APIs related to setting connection timeouts
-LWS_VISIBLE LWS_EXTERN void lws_set_timeout | -( | -struct lws * | -wsi, | -
- | - | enum pending_timeout | -reason, | -
- | - | int | -secs | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_set_timeout() - marks the wsi as subject to a timeout
-You will not need this unless you are doing something special
-wsi | Websocket connection instance |
reason | timeout reason |
secs | how many seconds |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN const char * | lws_urlencode (char *escaped, const char *string, int len) |
LWS_VISIBLE LWS_EXTERN int | lws_urldecode (char *string, const char *escaped, int len) |
APIs for receiving chunks of text, replacing a set of variable names via a callback, and then prepending and appending HTML chunked encoding headers.
-LWS_VISIBLE LWS_EXTERN int lws_urldecode | -( | -char * | -string, | -
- | - | const char * | -escaped, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_urldecode() - like strncpy but with urldecoding
-string | output buffer |
escaped | input buffer ('\0' terminated) |
len | output buffer max length |
This is only useful for '\0' terminated strings
-Since urldecoding only shrinks the output string, it is possible to do it in-place, ie, string == escaped
- -LWS_VISIBLE LWS_EXTERN const char* lws_urlencode | -( | -char * | -escaped, | -
- | - | const char * | -string, | -
- | - | int | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_urlencode() - like strncpy but with urlencoding
-escaped | output buffer |
string | input buffer ('/0' terminated) |
len | output buffer max length |
Because urlencoding expands the output string, it's not possible to do it in-place, ie, with escaped == string
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Typedefs | |
typedef int | lws_callback_function(struct lws *wsi, enum lws_callback_reasons reason, void *user, void *in, size_t len) |
-Enumerations | |
enum | lws_callback_reasons { - LWS_CALLBACK_ESTABLISHED = 0, -LWS_CALLBACK_CLIENT_CONNECTION_ERROR = 1, -LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH = 2, -LWS_CALLBACK_CLIENT_ESTABLISHED = 3, - - LWS_CALLBACK_CLOSED = 4, -LWS_CALLBACK_CLOSED_HTTP = 5, -LWS_CALLBACK_RECEIVE = 6, -LWS_CALLBACK_RECEIVE_PONG = 7, - - LWS_CALLBACK_CLIENT_RECEIVE = 8, -LWS_CALLBACK_CLIENT_RECEIVE_PONG = 9, -LWS_CALLBACK_CLIENT_WRITEABLE = 10, -LWS_CALLBACK_SERVER_WRITEABLE = 11, - - LWS_CALLBACK_HTTP = 12, -LWS_CALLBACK_HTTP_BODY = 13, -LWS_CALLBACK_HTTP_BODY_COMPLETION = 14, -LWS_CALLBACK_HTTP_FILE_COMPLETION = 15, - - LWS_CALLBACK_HTTP_WRITEABLE = 16, -LWS_CALLBACK_FILTER_NETWORK_CONNECTION = 17, -LWS_CALLBACK_FILTER_HTTP_CONNECTION = 18, -LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED = 19, - - LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION = 20, -LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS = 21, -LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS = 22, -LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION = 23, - - LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER = 24, -LWS_CALLBACK_CONFIRM_EXTENSION_OKAY = 25, -LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED = 26, -LWS_CALLBACK_PROTOCOL_INIT = 27, - - LWS_CALLBACK_PROTOCOL_DESTROY = 28, -LWS_CALLBACK_WSI_CREATE = 29, -LWS_CALLBACK_WSI_DESTROY = 30, -LWS_CALLBACK_GET_THREAD_ID = 31, - - LWS_CALLBACK_ADD_POLL_FD = 32, -LWS_CALLBACK_DEL_POLL_FD = 33, -LWS_CALLBACK_CHANGE_MODE_POLL_FD = 34, -LWS_CALLBACK_LOCK_POLL = 35, - - LWS_CALLBACK_UNLOCK_POLL = 36, -LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY = 37, -LWS_CALLBACK_WS_PEER_INITIATED_CLOSE = 38, -LWS_CALLBACK_WS_EXT_DEFAULTS = 39, - - LWS_CALLBACK_CGI = 40, -LWS_CALLBACK_CGI_TERMINATED = 41, -LWS_CALLBACK_CGI_STDIN_DATA = 42, -LWS_CALLBACK_CGI_STDIN_COMPLETED = 43, - - LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP = 44, -LWS_CALLBACK_CLOSED_CLIENT_HTTP = 45, -LWS_CALLBACK_RECEIVE_CLIENT_HTTP = 46, -LWS_CALLBACK_COMPLETED_CLIENT_HTTP = 47, - - LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ = 48, -LWS_CALLBACK_HTTP_BIND_PROTOCOL = 49, -LWS_CALLBACK_HTTP_DROP_PROTOCOL = 50, -LWS_CALLBACK_CHECK_ACCESS_RIGHTS = 51, - - LWS_CALLBACK_PROCESS_HTML = 52, -LWS_CALLBACK_ADD_HEADERS = 53, -LWS_CALLBACK_SESSION_INFO = 54, -LWS_CALLBACK_GS_EVENT = 55, - - LWS_CALLBACK_HTTP_PMO = 56, -LWS_CALLBACK_CLIENT_HTTP_WRITEABLE = 57, -LWS_CALLBACK_OPENSSL_PERFORM_SERVER_CERT_VERIFICATION = 58, -LWS_CALLBACK_RAW_RX = 59, - - LWS_CALLBACK_RAW_CLOSE = 60, -LWS_CALLBACK_RAW_WRITEABLE = 61, -LWS_CALLBACK_RAW_ADOPT = 62, -LWS_CALLBACK_USER = 1000 - - } |
The protocol callback is the primary way lws interacts with user code. For one of a list of a few dozen reasons the callback gets called at some event to be handled.
-All of the events can be ignored, returning 0 is taken as "OK" and returning nonzero in most cases indicates that the connection should be closed.
-typedef int lws_callback_function(struct lws *wsi, enum lws_callback_reasons reason, void *user, void *in, size_t len) | -
#include <lib/libwebsockets.h>
typedef lws_callback_function() - User server actions
wsi | Opaque websocket instance pointer |
reason | The reason for the call |
user | Pointer to per-session user data allocated by library |
in | Pointer used for some callback reasons |
len | Length set for some callback reasons This callback is the way the user controls what is served. All the - protocol detail is hidden and handled by the library. - - For each connection / session there is user data allocated that is - pointed to by "user". You set the size of this user data area when - the library is initialized with lws_create_server. |
enum lws_callback_reasons | -
#include <lib/libwebsockets.h>
enum lws_callback_reasons - reason you're getting a protocol callback
-Enumerator | |
---|---|
LWS_CALLBACK_ESTABLISHED | (VH) after the server completes a handshake with an incoming client. If you built the library with ssl support, in is a pointer to the ssl struct associated with the connection or NULL. - |
LWS_CALLBACK_CLIENT_CONNECTION_ERROR | the request client connection has been unable to complete a handshake with the remote server. If in is non-NULL, you can find an error string of length len where it points to -Diagnostic strings that may be returned include "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" |
LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH | this is the last chance for the client user code to examine the http headers and decide to reject the connection. If the content in the headers is interesting to the client (url, etc) it needs to copy it out at this point since it will be destroyed before the CLIENT_ESTABLISHED call - |
LWS_CALLBACK_CLIENT_ESTABLISHED | after your client connection completed a handshake with the remote server - |
LWS_CALLBACK_CLOSED | when the websocket session ends - |
LWS_CALLBACK_CLOSED_HTTP | when a HTTP (non-websocket) session ends - |
LWS_CALLBACK_RECEIVE | data has appeared for this server endpoint from a remote client, it can be found at *in and is len bytes long - |
LWS_CALLBACK_RECEIVE_PONG | servers receive PONG packets with this callback reason - |
LWS_CALLBACK_CLIENT_RECEIVE | data has appeared from the server for the client connection, it can be found at *in and is len bytes long - |
LWS_CALLBACK_CLIENT_RECEIVE_PONG | clients receive PONG packets with this callback reason - |
LWS_CALLBACK_CLIENT_WRITEABLE | If you call lws_callback_on_writable() on a connection, you will get one of these callbacks coming when the connection socket is able to accept another write packet without blocking. If it already was able to take another packet without blocking, you'll get this callback at the next call to the service loop function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE and servers get LWS_CALLBACK_SERVER_WRITEABLE. - |
LWS_CALLBACK_SERVER_WRITEABLE | See LWS_CALLBACK_CLIENT_WRITEABLE - |
LWS_CALLBACK_HTTP | an http request has come from a client that is not asking to upgrade the connection to a websocket one. This is a chance to serve http content, for example, to send a script to the client which will then open the websockets connection. in points to the URI path requested and lws_serve_http_file() makes it very simple to send back a file to the client. Normally after sending the file you are done with the http connection, since the rest of the activity will come by websockets from the script that was delivered by http, so you will want to return 1; to close and free up the connection. - |
LWS_CALLBACK_HTTP_BODY | the next len bytes data from the http request body HTTP connection is now available in in. - |
LWS_CALLBACK_HTTP_BODY_COMPLETION | the expected amount of http request body has been delivered - |
LWS_CALLBACK_HTTP_FILE_COMPLETION | a file requested to be sent down http link has completed. - |
LWS_CALLBACK_HTTP_WRITEABLE | you can write more down the http protocol link now. - |
LWS_CALLBACK_FILTER_NETWORK_CONNECTION | called when a client connects to the server at network level; the connection is accepted but then passed to this callback to decide whether to hang up immediately or not, based on the client IP. in contains the connection socket's descriptor. Since the client connection information is not available yet, wsi still pointing to the main server socket. Return non-zero to terminate the connection before sending or receiving anything. Because this happens immediately after the network connection from the client, there's no websocket protocol selected yet so this callback is issued only to protocol 0. - |
LWS_CALLBACK_FILTER_HTTP_CONNECTION | called when the request has been received and parsed from the client, but the response is not sent yet. Return non-zero to disallow the connection. user is a pointer to the connection user space allocation, in is the URI, eg, "/" In your handler you can use the public APIs lws_hdr_total_length() / lws_hdr_copy() to access all of the headers using the header enums lws_token_indexes from libwebsockets.h to check for and read the supported header presence and content before deciding to allow the http connection to proceed or to kill the connection. - |
LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED | A new client just had been connected, accepted, and instantiated into the pool. This callback allows setting any relevant property to it. Because this happens immediately after the instantiation of a new client, there's no websocket protocol selected yet so this callback is issued only to protocol 0. Only wsi is defined, pointing to the new client, and the return value is ignored. - |
LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION | called when the handshake has been received and parsed from the client, but the response is not sent yet. Return non-zero to disallow the connection. user is a pointer to the connection user space allocation, in is the requested protocol name In your handler you can use the public APIs lws_hdr_total_length() / lws_hdr_copy() to access all of the headers using the header enums lws_token_indexes from libwebsockets.h to check for and read the supported header presence and content before deciding to allow the handshake to proceed or to kill the connection. - |
LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS | if configured for including OpenSSL support, this callback allows your user code to perform extra SSL_CTX_load_verify_locations() or similar calls to direct OpenSSL where to find certificates the client can use to confirm the remote server identity. user is the OpenSSL SSL_CTX* - |
LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS | if configured for including OpenSSL support, this callback allows your user code to load extra certifcates into the server which allow it to verify the validity of certificates returned by clients. user is the server's OpenSSL SSL_CTX* - |
LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION | if the libwebsockets vhost was created with the option LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this callback is generated during OpenSSL verification of the cert sent from the client. It is sent to protocol[0] callback as no protocol has been negotiated on the connection yet. Notice that the libwebsockets context and wsi are both NULL during this callback. See http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html to understand more detail about the OpenSSL callback that generates this libwebsockets callback and the meanings of the arguments passed. In this callback, user is the x509_ctx, in is the ssl pointer and len is preverify_ok Notice that this callback maintains libwebsocket return conventions, return 0 to mean the cert is OK or 1 to fail it. This also means that if you don't handle this callback then the default callback action of returning 0 allows the client certificates. - |
LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER | this callback happens when a client handshake is being compiled. user is NULL, in is a char **, it's pointing to a char * which holds the next location in the header buffer where you can add headers, and len is the remaining space in the header buffer, which is typically some hundreds of bytes. So, to add a canned cookie, your handler code might look similar to: char **p = (char **)in; - - if (len < 100) - return 1; - - *p += sprintf(*p, "Cookie: a=b\x0d\x0a"); - - return 0; - Notice if you add anything, you just have to take care about the CRLF on the line you added. Obviously this callback is optional, if you don't handle it everything is fine. -Notice the callback is coming to protocols[0] all the time, because there is no specific protocol negotiated yet. - |
LWS_CALLBACK_CONFIRM_EXTENSION_OKAY | When the server handshake code sees that it does support a requested extension, before accepting the extension by additing to the list sent back to the client it gives this callback just to check that it's okay to use that extension. It calls back to the requested protocol and with in being the extension name, len is 0 and user is valid. Note though at this time the ESTABLISHED callback hasn't happened yet so if you initialize user content there, user content during this callback might not be useful for anything. Notice this callback comes to protocols[0]. - |
LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED | When a client connection is being prepared to start a handshake to a server, each supported extension is checked with protocols[0] callback with this reason, giving the user code a chance to suppress the claim to support that extension by returning non-zero. If unhandled, by default 0 will be returned and the extension support included in the header to the server. Notice this callback comes to protocols[0]. - |
LWS_CALLBACK_PROTOCOL_INIT | One-time call per protocol, per-vhost using it, so it can do initial setup / allocations etc - |
LWS_CALLBACK_PROTOCOL_DESTROY | One-time call per protocol, per-vhost using it, indicating this protocol won't get used at all after this callback, the vhost is getting destroyed. Take the opportunity to deallocate everything that was allocated by the protocol. - |
LWS_CALLBACK_WSI_CREATE | outermost (earliest) wsi create notification to protocols[0] - |
LWS_CALLBACK_WSI_DESTROY | outermost (latest) wsi destroy notification to protocols[0] - |
LWS_CALLBACK_GET_THREAD_ID | lws can accept callback when writable requests from other threads, if you implement this callback and return an opaque current thread ID integer. - |
LWS_CALLBACK_ADD_POLL_FD | lws normally deals with its poll() or other event loop internally, but in the case you are integrating with another server you will need to have lws sockets share a polling array with the other server. This and the other POLL_FD related callbacks let you put your specialized poll array interface code in the callback for protocol 0, the first protocol you support, usually the HTTP protocol in the serving case. This callback happens when a socket needs to be added to the polling loop: in points to a struct lws_pollargs; the fd member of the struct is the file descriptor, and events contains the active events -If you are using the internal lws polling / event loop you can just ignore these callbacks. - |
LWS_CALLBACK_DEL_POLL_FD | This callback happens when a socket descriptor needs to be removed from an external polling array. in is again the struct lws_pollargs containing the fd member to be removed. If you are using the internal polling loop, you can just ignore it. - |
LWS_CALLBACK_CHANGE_MODE_POLL_FD | This callback happens when lws wants to modify the events for a connection. in is the struct lws_pollargs with the fd to change. The new event mask is in events member and the old mask is in the prev_events member. If you are using the internal polling loop, you can just ignore it. - |
LWS_CALLBACK_LOCK_POLL | These allow the external poll changes driven by lws to participate in an external thread locking scheme around the changes, so the whole thing is threadsafe. These are called around three activities in the library,
|
LWS_CALLBACK_UNLOCK_POLL | See LWS_CALLBACK_LOCK_POLL, ignore if using lws internal poll - |
LWS_CALLBACK_OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY | if configured for including OpenSSL support but no private key file has been specified (ssl_private_key_filepath is NULL), this is called to allow the user to set the private key directly via libopenssl and perform further operations if required; this might be useful in situations where the private key is not directly accessible by the OS, for example if it is stored on a smartcard. user is the server's OpenSSL SSL_CTX* - |
LWS_CALLBACK_WS_PEER_INITIATED_CLOSE | The peer has sent an unsolicited Close WS packet. in and len are the optional close code (first 2 bytes, network order) and the optional additional information which is not defined in the standard, and may be a string or non-human- readable data. If you return 0 lws will echo the close and then close the connection. If you return nonzero lws will just close the connection. - |
LWS_CALLBACK_HTTP_PMO | per-mount options for this connection, called before the normal LWS_CALLBACK_HTTP when the mount has per-mount options - |
LWS_CALLBACK_CLIENT_HTTP_WRITEABLE | when doing an HTTP type client connection, you can call lws_client_http_body_pending(wsi, 1) from LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER to get these callbacks sending the HTTP headers. -From this callback, when you have sent everything, you should let lws know by calling lws_client_http_body_pending(wsi, 0) - |
LWS_CALLBACK_OPENSSL_PERFORM_SERVER_CERT_VERIFICATION | Similar to LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION this callback is called during OpenSSL verification of the cert sent from the server to the client. It is sent to protocol[0] callback as no protocol has been negotiated on the connection yet. Notice that the wsi is set because lws_client_connect_via_info was successful. -See http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html to understand more detail about the OpenSSL callback that generates this libwebsockets callback and the meanings of the arguments passed. In this callback, user is the x509_ctx, in is the ssl pointer and len is preverify_ok. -THIS IS NOT RECOMMENDED BUT if a cert validation error shall be overruled and cert shall be accepted as ok, X509_STORE_CTX_set_error((X509_STORE_CTX*)user, X509_V_OK); must be called and return value must be 0 to mean the cert is OK; returning 1 will fail the cert in any case. -This also means that if you don't handle this callback then the default callback action of returning 0 will not accept the certificate in case of a validation error decided by the SSL lib. -This is expected and secure behaviour when validating certificates. -Note: LCCSCF_ALLOW_SELFSIGNED and LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK still work without this callback being implemented. - |
LWS_CALLBACK_RAW_RX | RAW mode connection RX - |
LWS_CALLBACK_RAW_CLOSE | RAW mode connection is closing - |
LWS_CALLBACK_RAW_WRITEABLE | RAW mode connection may be written - |
LWS_CALLBACK_RAW_ADOPT | RAW mode connection was adopted (equivalent to 'created') - |
LWS_CALLBACK_USER | user code can use any including / above without fear of clashes - |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
-LWS_VISIBLE LWS_EXTERN int | lws_uv_sigint_cfg (struct lws_context *context, int use_uv_sigint, uv_signal_cb cb) |
-LWS_VISIBLE LWS_EXTERN void | lws_libuv_run (const struct lws_context *context, int tsi) |
-LWS_VISIBLE LWS_EXTERN void | lws_libuv_stop (struct lws_context *context) |
-LWS_VISIBLE LWS_EXTERN void | lws_libuv_stop_without_kill (const struct lws_context *context, int tsi) |
-LWS_VISIBLE LWS_EXTERN int | lws_uv_initloop (struct lws_context *context, uv_loop_t *loop, int tsi) |
-LWS_VISIBLE LWS_EXTERN uv_loop_t * | lws_uv_getloop (struct lws_context *context, int tsi) |
-LWS_VISIBLE LWS_EXTERN void | lws_uv_sigint_cb (uv_signal_t *watcher, int signum) |
APIs specific to libuv event loop itegration
-![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Data Structures | |
struct | lws_protocol_vhost_options |
struct | lws_http_mount |
-Enumerations | |
enum | lws_mount_protocols { - LWSMPRO_HTTP = 0, -LWSMPRO_HTTPS = 1, -LWSMPRO_FILE = 2, -LWSMPRO_CGI = 3, - - LWSMPRO_REDIR_HTTP = 4, -LWSMPRO_REDIR_HTTPS = 5, -LWSMPRO_CALLBACK = 6 - - } |
enum lws_mount_protocols | -
#include <lib/libwebsockets.h>
enum lws_mount_protocols This specifies the mount protocol for a mountpoint, whether it is to be served from a filesystem, or it is a cgi etc.
-Enumerator | |
---|---|
LWSMPRO_HTTP | not supported yet - |
LWSMPRO_HTTPS | not supported yet - |
LWSMPRO_FILE | serve from filesystem directory - |
LWSMPRO_CGI | pass to CGI to handle - |
LWSMPRO_REDIR_HTTP | redirect to http:// url - |
LWSMPRO_REDIR_HTTPS | redirect to https:// url - |
LWSMPRO_CALLBACK | hand by named protocol's callback - |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Enumerations | |
enum | lws_close_status { - LWS_CLOSE_STATUS_NOSTATUS = 0, -LWS_CLOSE_STATUS_NORMAL = 1000, -LWS_CLOSE_STATUS_GOINGAWAY = 1001, -LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002, - - LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003, -LWS_CLOSE_STATUS_RESERVED = 1004, -LWS_CLOSE_STATUS_NO_STATUS = 1005, -LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006, - - LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007, -LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008, -LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009, -LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010, - - LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011, -LWS_CLOSE_STATUS_TLS_FAILURE = 1015, -LWS_CLOSE_STATUS_NOSTATUS_CONTEXT_DESTROY = 9999 - - } |
-Functions | |
LWS_VISIBLE LWS_EXTERN void | lws_close_reason (struct lws *wsi, enum lws_close_status status, unsigned char *buf, size_t len) |
When we close a ws connection, we can send a reason code and a short UTF-8 description back with the close packet.
-enum lws_close_status | -
#include <lib/libwebsockets.h>
enum lws_close_status - RFC6455 close status codes
-Enumerator | |
---|---|
LWS_CLOSE_STATUS_NORMAL | 1000 indicates a normal closure, meaning that the purpose for which the connection was established has been fulfilled. - |
LWS_CLOSE_STATUS_GOINGAWAY | 1001 indicates that an endpoint is "going away", such as a server going down or a browser having navigated away from a page. - |
LWS_CLOSE_STATUS_PROTOCOL_ERR | 1002 indicates that an endpoint is terminating the connection due to a protocol error. - |
LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE | 1003 indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands only text data MAY send this if it receives a binary message). - |
LWS_CLOSE_STATUS_RESERVED | Reserved. The specific meaning might be defined in the future. - |
LWS_CLOSE_STATUS_NO_STATUS | 1005 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that no status code was actually present. - |
LWS_CLOSE_STATUS_ABNORMAL_CLOSE | 1006 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed abnormally, e.g., without sending or receiving a Close control frame. - |
LWS_CLOSE_STATUS_INVALID_PAYLOAD | 1007 indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 [RFC3629] data within a text message). - |
LWS_CLOSE_STATUS_POLICY_VIOLATION | 1008 indicates that an endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code that can be returned when there is no other more suitable status code (e.g., 1003 or 1009) or if there is a need to hide specific details about the policy. - |
LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE | 1009 indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process. - |
LWS_CLOSE_STATUS_EXTENSION_REQUIRED | 1010 indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn't return them in the response message of the WebSocket handshake. The list of extensions that are needed SHOULD appear in the /reason/ part of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead - |
LWS_CLOSE_STATUS_UNEXPECTED_CONDITION | 1011 indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request. - |
LWS_CLOSE_STATUS_TLS_FAILURE | 1015 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed due to a failure to perform a TLS handshake (e.g., the server certificate can't be verified). - |
LWS_VISIBLE LWS_EXTERN void lws_close_reason | -( | -struct lws * | -wsi, | -
- | - | enum lws_close_status | -status, | -
- | - | unsigned char * | -buf, | -
- | - | size_t | -len | -
- | ) | -- |
#include <lib/libwebsockets.h>
lws_close_reason - Set reason and aux data to send with Close packet If you are going to return nonzero from the callback requesting the connection to close, you can optionally call this to set the reason the peer will be told if possible.
-wsi | The websocket connection to set the close reason on |
status | A valid close status from websocket standard |
buf | NULL or buffer containing up to 124 bytes of auxiliary data |
len | Length of data in |
buf | to send |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
-Functions | |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_send_pipe_choked (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int | lws_is_final_fragment (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN unsigned char | lws_get_reserved_bits (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_partial_buffered (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT | lws_frame_is_binary (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int | lws_is_ssl (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN int | lws_is_cgi (struct lws *wsi) |
LWS_VISIBLE LWS_EXTERN SSL * | lws_get_ssl (struct lws *wsi) |
These provide information about ws connection or message status
-LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_frame_is_binary | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_frame_is_binary(): true if the current frame was sent in binary mode
-wsi | the connection we are inquiring about |
This is intended to be called from the LWS_CALLBACK_RECEIVE callback if it's interested to see if the frame it's dealing with was sent in binary mode.
- -LWS_VISIBLE LWS_EXTERN unsigned char lws_get_reserved_bits | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_reserved_bits() - access reserved bits of ws frame
wsi | lws connection |
LWS_VISIBLE LWS_EXTERN SSL* lws_get_ssl | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_get_ssl() - Return wsi's SSL context structure
wsi | websocket connection |
Returns pointer to the SSL library's context structure
- -LWS_VISIBLE LWS_EXTERN int lws_is_cgi | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_is_cgi() - find out if this wsi is running a cgi process
wsi | lws connection |
LWS_VISIBLE LWS_EXTERN int lws_is_final_fragment | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_is_final_fragment() - tests if last part of ws message
wsi | lws connection |
LWS_VISIBLE LWS_EXTERN int lws_is_ssl | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_is_ssl() - Find out if connection is using SSL
wsi | websocket connection to check Returns 0 if the connection is not using SSL, 1 if using SSL and - using verified cert, and 2 if using SSL but the cert was not - checked (appears for client wsi told to skip check on connection) |
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_partial_buffered | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_partial_buffered() - find out if lws buffered the last write
wsi | websocket connection to check |
Returns 1 if you cannot use lws_write because the last write on this connection is still buffered, and can't be cleared without returning to the service loop and waiting for the connection to be writeable again.
-If you will try to do >1 lws_write call inside a single WRITEABLE callback, you must check this after every write and bail if set, ask for a new writeable callback and continue writing from there.
-This is never set at the start of a writeable callback, but any write may set it.
- -LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_send_pipe_choked | -( | -struct lws * | -wsi | ) | -- |
#include <lib/libwebsockets.h>
lws_send_pipe_choked() - tests if socket is writable or not
wsi | lws connection |
Allows you to check if you can write more on the socket
- -![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
Clws_cgi_args | |
Clws_client_connect_info | |
▼Clws_conn | |
Clws_conn_listener | |
Clws_context_creation_info | |
Clws_email | |
Clws_ext_option_arg | |
Clws_ext_options | |
Clws_extension | |
Clws_gs_event_args | |
Clws_http_mount | |
Clws_plat_file_ops | |
Clws_plugin | |
Clws_plugin_capability | |
Clws_polarssl_context | |
Clws_pollargs | |
Clws_pollfd | |
Clws_process_html_args | |
Clws_process_html_state | |
Clws_protocol_vhost_options | |
Clws_protocols | |
Clws_session_info | |
Clws_token_limits | |
Clws_tokens | |
Clwsgw_hash | |
Clwsgw_hash_bin | |
Cpollfd |
![]() |
-
- libwebsockets
-
- Lightweight C library for HTML5 websockets
- |
-
Libwebsockets covers a lot of interesting features for people making embedded servers or clients
-You can browse by api category here
-A collection of READMEs for build, coding, lwsws etc are here
-t |