Modules
	Vhost mounts and options

Data Structures
struct	lws_context_creation_info

struct	lws_protocol_vhost_options

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) }

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 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)

LWS_VISIBLE LWS_EXTERN void *	lws_context_user (struct lws_context *context)

Detailed Description

Context and Vhost releated functions

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.

Enumeration Type Documentation

◆ lws_context_options

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_REQUIRE_VALID_OPENSSL_CLIENT_CERT     = (1 << 1) |
                                                                   (1 << 12),
         LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME            = (1 << 2),
         LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT             = (1 << 3) |
                                                                   (1 << 12),
         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                              = (1 << 9) |
                                                                   (1 << 12),
         LWS_SERVER_OPTION_LIBUV                                 = (1 << 10),
         LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS                = (1 << 11) |
                                                                   (1 << 12),
         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),
         /****** add new things just above ---^ ******/
 };

Function Documentation

◆ lws_context_destroy()

LWS_VISIBLE LWS_EXTERN void lws_context_destroy ( struct lws_context * context )

#include <lib/libwebsockets.h>

lws_context_destroy() - Destroy the websocket context

Parameters

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_context_user()

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

Parameters

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_create_context()

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

Parameters

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_create_vhost()

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)

Parameters

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_get_vhost()

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

Parameters

wsi	which connection

◆ lws_json_dump_context()

LWS_VISIBLE LWS_EXTERN int lws_json_dump_context	(	const struct lws_context *	context,
		char *	buf,
		int	len
	)

#include <lib/libwebsockets.h>

lws_json_dump_context() - describe context state and stats in JSON

Parameters

context	the context
buf	buffer to fill with JSON
len	max length of buf

◆ lws_json_dump_vhost()

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

Parameters

vh	the vhost
buf	buffer to fill with JSON
len	max length of buf

◆ lws_set_proxy()

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.

Parameters

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_vhost_get()

LWS_VISIBLE LWS_EXTERN struct lws_vhost* lws_vhost_get ( struct lws * wsi )

#include <lib/libwebsockets.h>

lws_vhost_get() -

Deprecated:: deprecated: use lws_get_vhost()

◆ lwsws_get_config_globals()

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

Parameters

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

◆ lwsws_get_config_vhosts()

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

Parameters

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

Modules

Data Structures

Enumerations

Functions

Detailed Description

Context and Vhost releated functions

Enumeration Type Documentation

◆ lws_context_options

Function Documentation

◆ lws_context_destroy()

◆ lws_context_user()

◆ lws_create_context()

◆ lws_create_vhost()

◆ lws_get_vhost()

◆ lws_json_dump_context()

◆ lws_json_dump_vhost()

◆ lws_set_proxy()

◆ lws_vhost_get()

◆ lwsws_get_config_globals()

◆ lwsws_get_config_vhosts()