 |
libwebsockets
Lightweight C library for HTML5 websockets
|
|
libwebsockets
Lightweight C library for HTML5 websockets
|
Collaboration diagram for context and vhost related functions:Topics | |
| Vhost mounts and options | |
Data Structures | |
| struct | lws_context_creation_info |
| struct | lws_protocol_vhost_options |
Typedefs | |
| typedef int(* | lws_context_ready_cb_t) (struct lws_context *context) |
| typedef int(* | lws_reload_func) (void) |
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.
| struct lws_context_creation_info |
struct lws_context_creation_info - parameters to create context and /or vhost with
This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS is not given, then for backwards compatibility one vhost is created at context-creation time using the info from this struct.
If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created at the same time as the context, they are expected to be created afterwards.
Definition at line 274 of file lws-context-vhost.h.
Collaboration diagram for lws_context_creation_info:| Data Fields | ||
|---|---|---|
| gid_t | gid |
CONTEXT: group id to change to after setting listen socket, or -1. See also .username below. |
| uid_t | uid |
CONTEXT: user id to change to after setting listen socket, or -1. See also .groupname below. |
| uint64_t | options |
VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields |
| void * | user |
VHOST + CONTEXT: optional user pointer that will be associated with the context when creating the context (and can be retrieved by lws_context_user(context), or with the vhost when creating the vhost (and can be retrieved by lws_vhost_user(vhost)). You will need to use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately if you care about giving the context and vhost different user pointer values. |
| unsigned int | count_threads |
CONTEXT: how many contexts to create in an array, 0 = 1 |
| unsigned int | fd_limit_per_thread |
CONTEXT: nonzero means restrict each service thread to this many fds, 0 means the default which is divide the process fd limit by the number of threads. Note if this is nonzero, and fd_limit_per_thread multiplied by the number of service threads is less than the process ulimit, then lws restricts internal lookup table allocation to the smaller size, and switches to a less efficient lookup scheme. You should use this to trade off speed against memory usage if you know the lws context will only use a handful of fds. Bear in mind lws may use some fds internally, for example for the cancel pipe, so you may need to allow for some extras for normal operation. |
| const char * | vhost_name |
VHOST: name of vhost, must match external DNS name used to access the site, like "warmcat.com" as it's used to match Host: header and / or SNI name for SSL. CONTEXT: NULL, or the name to associate with the context for context-specific logging |
| void * | external_baggage_free_on_destroy |
CONTEXT: NULL, or pointer to something externally malloc'd, that should be freed when the context is destroyed. This allows you to automatically sync the freeing action to the context destruction action, so there is no need for an external free() if the context succeeded to create. |
| unsigned int | pt_serv_buf_size |
CONTEXT: 0 = default of 4096. This buffer is used by various service related features including file serving, it defines the max chunk of file that can be sent at once. At the risk of lws having to buffer failed large sends, it can be increased to, eg, 128KiB to improve throughput. |
| void ** | foreign_loops |
CONTEXT: This is ignored if the context is not being started with an event loop, ie, .options has a flag like LWS_SERVER_OPTION_LIBUV. NULL indicates lws should start its own even loop for each service thread, and deal with closing the loops when the context is destroyed. Non-NULL means it points to an array of external ("foreign") event loops that are to be used in turn for each service thread. In the default case of 1 service thread, it can just point to one foreign event loop. |
| void(*)(void *event_lib_handle, int signum) | signal_cb |
CONTEXT: NULL: default signal handling. Otherwise this receives the signal handler callback. event_lib_handle is the native event library signal handle, eg uv_signal_t * for libuv. |
| struct lws_context ** | pcontext |
CONTEXT: if non-NULL, at the end of context destroy processing, the pointer pointed to by pcontext is written with NULL. You can use this to let foreign event loops know that lws context destruction is fully completed. |
| void(*)(struct lws_vhost *vh, void *arg) | finalize |
VHOST: NULL, or pointer to function that will be called back when the vhost is just about to be freed. The arg parameter will be set to whatever finalize_arg is below. |
| void * | finalize_arg |
VHOST: opaque pointer lws ignores but passes to the finalize callback. If you don't care, leave it NULL. |
| const char * | listen_accept_role |
VHOST: NULL for default, or force accepted incoming connections to bind to this role. Uses the role names from their ops struct, eg, "raw-skt". |
| const char * | listen_accept_protocol |
VHOST: NULL for default, or force accepted incoming connections to bind to this vhost protocol name. |
| const struct lws_protocols ** | pprotocols |
VHOST: NULL: use .protocols, otherwise ignore .protocols and use this array of pointers to protocols structs. The end of the array is marked by a NULL pointer. This is preferred over .protocols, because it allows the protocol struct to be opaquely defined elsewhere, with just a pointer to it needed to create the context with it. .protocols requires also the type of the user data to be known so its size can be given. |
| const char * | username |
CONTEXT: string username for post-init permissions. Like .uid but takes a string username. |
| const char * | groupname |
CONTEXT: string groupname for post-init permissions. Like .gid but takes a string groupname. |
| const char * | unix_socket_perms |
VHOST: if your vhost is listening on a unix socket, you can give a "username:groupname" string here to control the owner:group it's created with. It's always created with 0660 mode. |
| const lws_system_ops_t * | system_ops |
CONTEXT: hook up lws_system_ apis to system-specific implementations |
| const lws_retry_bo_t * | retry_and_idle_policy |
VHOST: optional retry and idle policy to apply to this vhost. Currently only the idle parts are applied to the connections. |
| int | rlimit_nofile |
0 = inherit the initial ulimit for files / sockets from the startup environment. Nonzero = try to set the limit for this process. |
| int | fo_listen_queue |
VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the platform supports it, with the given queue length for the listen socket. |
| const struct lws_plugin_evlib * | event_lib_custom |
CONTEXT: If non-NULL, override event library selection so it uses this custom event library implementation, instead of default internal loop. Don't set any other event lib context creation flags in that case. it will be used automatically. This is useful for integration where an existing application is using its own handrolled event loop instead of an event library, it provides a way to allow lws to use the custom event loop natively as if it were an "event library". |
| lws_log_cx_t * | log_cx |
CONTEXT: NULL to use the default, process-scope logging context, else a specific logging context to associate with this context |
| int | default_loglevel |
CONTEXT: 0 for LLL_USER, LLL_ERR, LLL_WARN, LLL_NOTICE enabled by default when using lws_cmdline_option_handle_builtin(), else set to the LLL_ flags you want to be the default before calling lws_cmdline_option_handle_builtin(). Your selected default loglevel can then be cleanly overridden using -d 1039 etc commandline switch |
| lws_sockfd_type | vh_listen_sockfd |
VHOST: 0 for normal vhost listen socket fd creation, if any. Nonzero to force the selection of an already-existing fd for the vhost's listen socket, which is already prepared. This is intended for an external process having chosen the fd, which cannot then be zero. |
| void * | _unused[2] |
dummy |
| struct lws_protocol_vhost_options |
struct lws_protocol_vhost_options - linked list of per-vhost protocol name=value options
This provides a general way to attach a linked-list of name=value pairs, which can also have an optional child link-list using the options member.
Definition at line 1313 of file lws-context-vhost.h.
Collaboration diagram for lws_protocol_vhost_options:| Data Fields | ||
|---|---|---|
| const struct lws_protocol_vhost_options * | next |
linked list |
| const struct lws_protocol_vhost_options * | options |
child linked-list of more options for this node |
| const char * | name |
name of name=value pair |
| const char * | value |
value of name=value pair |
| #define LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Don't allow the connection unless the client has a client cert that we recognize; provides LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT
Definition at line 46 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME (1ll << 2) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Don't try to get the server's hostname
Definition at line 51 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Allow non-SSL (plaintext) connections on the same port as SSL is listening. If combined with LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS it will try to force http connections on an https listener (eg, http://x.com:443) to redirect to an explicit https connection (eg, https://x.com)
Definition at line 53 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_LIBEV (1ll << 4) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Use libev event loop
Definition at line 61 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_DISABLE_IPV6 (1ll << 5) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Disable IPV6 support
Definition at line 63 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_DISABLE_OS_CA_CERTS (1ll << 6) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Don't load OS CA certs, you will need to load your own CA cert(s)
Definition at line 65 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_PEER_CERT_NOT_REQUIRED (1ll << 7) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Accept connections with no valid Cert (eg, selfsigned)
Definition at line 68 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_VALIDATE_UTF8 (1ll << 8) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Check UT-8 correctness
Definition at line 70 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_SSL_ECDH |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) initialize ECDH ciphers
Definition at line 72 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_LIBUV (1ll << 10) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Use libuv event loop
Definition at line 75 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Use an http redirect to force the client to ask for https. Notice if your http server issues the STS header and the client has ever seen that, the client will fail the http connection before it can actually do the redirect.
Combine with LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS to handle, eg, http://x.com:443 -> https://x.com
(deprecated: use mount redirection)
Definition at line 77 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT (1ll << 12) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Initialize the SSL library at all
Definition at line 88 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_EXPLICIT_VHOSTS (1ll << 13) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Only create the context when calling context create api, implies user code will create its own vhosts
Definition at line 90 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_UNIX_SOCK (1ll << 14) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Use Unix socket
Definition at line 93 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_STS (1ll << 15) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Send Strict Transport Security header, making clients subsequently go to https even if user asked for http
Definition at line 95 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_IPV6_V6ONLY_MODIFY (1ll << 16) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Enable LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE to take effect
Definition at line 98 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_IPV6_V6ONLY_VALUE (1ll << 17) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) if set, only ipv6 allowed on the vhost
Definition at line 100 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_UV_NO_SIGSEGV_SIGFPE_SPIN (1ll << 18) |
#include <include/libwebsockets/lws-context-vhost.h>
(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.
Definition at line 102 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_JUST_USE_RAW_ORIGIN (1ll << 19) |
#include <include/libwebsockets/lws-context-vhost.h>
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.
Definition at line 108 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_FALLBACK_TO_RAW /* use below name */ (1ll << 20) |
#include <include/libwebsockets/lws-context-vhost.h>
Definition at line 115 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_FALLBACK_TO_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 20) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) if invalid http is coming in the first line, then abandon trying to treat the connection as http, and belatedly apply the .listen_accept_role / .listen_accept_protocol info struct members to the connection. If they are NULL, for backwards-compatibility the connection is bound to "raw-skt" role, and in order of priority: 1) the vh protocol with a pvo named "raw", 2) the vh protocol with a pvo named "default", or 3) protocols[0].
Must be combined with LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT to work with a socket listening with tls.
Definition at line 116 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_LIBEVENT (1ll << 21) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Use libevent event loop
Definition at line 129 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_ONLY_RAW /* Use below name instead */ (1ll << 22) |
#include <include/libwebsockets/lws-context-vhost.h>
Definition at line 132 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_ADOPT_APPLY_LISTEN_ACCEPT_CONFIG (1ll << 22) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) All connections to this vhost / port are bound to the role and protocol given in .listen_accept_role / .listen_accept_protocol.
If those explicit user-controlled names are NULL, for backwards- compatibility the connection is bound to "raw-skt" role, and in order of priority: 1) the vh protocol with a pvo named "raw", 2) the vh protocol with a pvo named "default", or 3) protocols[0].
It's much preferred to specify the role + protocol using the .listen_accept_role and .listen_accept_protocol in the info struct.
Definition at line 133 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_ALLOW_LISTEN_SHARE (1ll << 23) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Set to allow multiple listen sockets on one interface + address + port. The default is to strictly allow only one listen socket at a time. This is automatically selected if you have multiple service threads. Linux only.
Definition at line 146 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_CREATE_VHOST_SSL_CTX (1ll << 24) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Force setting up the vhost SSL_CTX, even though the user code doesn't explicitly provide a cert in the info struct. It implies the user code is going to provide a cert at the LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS callback, which provides the vhost SSL_CTX * in the user parameter.
Definition at line 152 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_SKIP_PROTOCOL_INIT (1ll << 25) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) You probably don't want this. It forces this vhost to not call LWS_CALLBACK_PROTOCOL_INIT on its protocols. It's used in the special case of a temporary vhost bound to a single protocol.
Definition at line 159 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_IGNORE_MISSING_CERT (1ll << 26) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Don't fail if the vhost TLS cert or key are missing, just continue. The vhost won't be able to serve anything, but if for example the ACME plugin was configured to fetch a cert, this lets you bootstrap your vhost from having no cert to start with.
Definition at line 164 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK (1ll << 27) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) On this vhost, if the connection is being upgraded, insist that there's a Host: header and that the contents match the vhost name + port (443 / 80 are assumed if no :port given based on if the connection is using TLS).
By default, without this flag, on upgrade lws just checks that the Host: header was given without checking the contents... this is to allow lax hostname mappings like localhost / 127.0.0.1, and CNAME mappings like www.mysite.com / mysite.com
Definition at line 170 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE (1ll << 28) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Send lws default HTTP headers recommended by Mozilla Observatory for security. This is a helper option that sends canned headers on each http response enabling a VERY strict Content Security Policy. The policy is so strict, for example it won't let the page run its own inline JS nor show images or take CSS from a different server. In many cases your JS only comes from your server as do the image sources and CSS, so that is what you want... attackers hoping to inject JS into your DOM are completely out of luck since even if they succeed, it will be rejected for execution by the browser according to the strict CSP. In other cases you have to deviate from the complete strictness, in which case don't use this flag: use the .headers member in the vhost init described in struct lws_context_creation_info instead to send the adapted headers yourself.
Definition at line 181 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER (1ll << 29) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) If you really want to allow HTTP connections on a tls listener, you can do it with this combined with LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT. But this is allowing accidental loss of the security assurances provided by tls depending on the client using http when he meant https... it's not recommended.
Definition at line 198 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_FAIL_UPON_UNABLE_TO_BIND (1ll << 30) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) When instantiating a new vhost and the specified port is already in use, a null value shall be return to signal the error.
Definition at line 206 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_H2_JUST_FIX_WINDOW_UPDATE_OVERFLOW (1ll << 31) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Indicates the connections using this vhost should ignore h2 WINDOW_UPDATE from broken peers and fix them up
Definition at line 211 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_VH_H2_HALF_CLOSED_LONG_POLL (1ll << 32) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Tell the vhost to treat half-closed remote clients as entered into an immortal (ie, not subject to normal timeouts) long poll mode.
Definition at line 215 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_GLIB (1ll << 33) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Use glib event loop
Definition at line 221 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_H2_PRIOR_KNOWLEDGE (1ll << 34) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) Tell the vhost to treat plain text http connections as H2 with prior knowledge (no upgrade request involved)
Definition at line 224 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_NO_LWS_SYSTEM_STATES (1ll << 35) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Disable lws_system state, eg, because we are a secure streams proxy client that is not trying to track system state by itself.
Definition at line 229 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_SS_PROXY (1ll << 36) |
#include <include/libwebsockets/lws-context-vhost.h>
(VH) We are being a SS Proxy listen socket for the vhost
Definition at line 233 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_SDEVENT (1ll << 37) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Use sd-event loop
Definition at line 236 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_ULOOP (1ll << 38) |
#include <include/libwebsockets/lws-context-vhost.h>
(CTX) Use libubox / uloop event loop
Definition at line 239 of file lws-context-vhost.h.
| #define LWS_SERVER_OPTION_DISABLE_TLS_SESSION_CACHE (1ll << 39) |
#include <include/libwebsockets/lws-context-vhost.h>
(VHOST) Disallow use of client tls caching (on by default)
Definition at line 242 of file lws-context-vhost.h.
| #define lws_check_opt | ( | c, | |
| f ) |
#include <include/libwebsockets/lws-context-vhost.h>
Definition at line 249 of file lws-context-vhost.h.
| typedef int(* lws_context_ready_cb_t) (struct lws_context *context) |
#include <include/libwebsockets/lws-context-vhost.h>
Definition at line 257 of file lws-context-vhost.h.
| typedef int(* lws_reload_func) (void) |
#include <include/libwebsockets/lws-context-vhost.h>
Definition at line 1035 of file lws-context-vhost.h.
| LWS_VISIBLE LWS_EXTERN struct lws_context * lws_create_context | ( | const struct lws_context_creation_info * | info | ) |
#include <include/libwebsockets/lws-context-vhost.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. |
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN void lws_context_destroy | ( | struct lws_context * | context | ) |
#include <include/libwebsockets/lws-context-vhost.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_deprecate | ( | struct lws_context * | context, |
| lws_reload_func | cb ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_context_deprecate() - Deprecate the websocket context
| context | Websocket context |
| cb | Callback notified when old context listen sockets are closed 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. 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). |
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN int lws_context_is_deprecated | ( | struct lws_context * | context | ) |
#include <include/libwebsockets/lws-context-vhost.h>
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN int lws_set_proxy | ( | struct lws_vhost * | vhost, |
| const char * | proxy ) |
#include <include/libwebsockets/lws-context-vhost.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.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN int lws_set_socks | ( | struct lws_vhost * | vhost, |
| const char * | socks ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_set_socks() - Setup socks to lws_context.
| vhost | pointer to struct lws_vhost you want set socks for |
| socks | pointer to c string containing socks in format address:port |
Returns 0 if socks string was parsed and socks was setup. Returns -1 if socks is NULL or has incorrect format.
This is only required if your OS does not provide the socks_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.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN struct lws_vhost * lws_create_vhost | ( | struct lws_context * | context, |
| const struct lws_context_creation_info * | info ) |
#include <include/libwebsockets/lws-context-vhost.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
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN void lws_vhost_destroy | ( | struct lws_vhost * | vh | ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_vhost_destroy() - Destroy a vhost (virtual server context)
| vh | pointer to result of lws_create_vhost() |
This function destroys a vhost. Normally, if you just want to exit, then lws_destroy_context() will take care of everything. If you want to destroy an individual vhost and all connections and allocations, you can do it with this.
If the vhost has a listen sockets shared by other vhosts, it will be given to one of the vhosts sharing it rather than closed.
The vhost close is staged according to the needs of the event loop, and if there are multiple service threads. At the point the vhost itself if about to be freed, if you provided a finalize callback and optional arg at vhost creation time, it will be called just before the vhost is freed.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN int lwsws_get_config_globals | ( | struct lws_context_creation_info * | info, |
| const char * | d, | ||
| char ** | config_strings, | ||
| int * | len ) |
#include <include/libwebsockets/lws-context-vhost.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
References LWS_EXTERN, and LWS_VISIBLE.
| 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 <include/libwebsockets/lws-context-vhost.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
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN struct lws_vhost * lws_get_vhost | ( | struct lws * | wsi | ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_get_vhost() - return the vhost a wsi belongs to
| wsi | which connection |
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN const char * lws_get_vhost_name | ( | struct lws_vhost * | vhost | ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_get_vhost_name() - returns the name of a vhost
| vhost | which vhost |
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN struct lws_vhost * lws_get_vhost_by_name | ( | struct lws_context * | context, |
| const char * | name ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_get_vhost_by_name() - returns the vhost with the requested name, or NULL
| context | the lws_context to look in |
| name | vhost name we are looking for |
Returns NULL, or the vhost with the name name
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN int lws_get_vhost_port | ( | struct lws_vhost * | vhost | ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_get_vhost_port() - returns the port a vhost listens on, or -1
| vhost | which vhost |
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN void * lws_get_vhost_user | ( | struct lws_vhost * | vhost | ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_get_vhost_user() - returns the user pointer for the vhost
| vhost | which vhost |
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN const char * lws_get_vhost_iface | ( | struct lws_vhost * | vhost | ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_get_vhost_iface() - returns the binding for the vhost listen socket
| vhost | which vhost |
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN void * lws_vhost_user | ( | struct lws_vhost * | vhost | ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_vhost_user() - get the user data associated with the vhost
| vhost | Websocket vhost |
This returns the optional user pointer that can be attached to a vhost when it was created. Lws never dereferences this pointer, it only sets it when the vhost is created, and returns it using this api.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN void * lws_context_user | ( | struct lws_context * | context | ) |
#include <include/libwebsockets/lws-context-vhost.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.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN const char * lws_vh_tag | ( | struct lws_vhost * | vh | ) |
#include <include/libwebsockets/lws-context-vhost.h>
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN void _lws_context_info_defaults | ( | struct lws_context_creation_info * | info, |
| const char * | sspol ) |
#include <include/libwebsockets/lws-context-vhost.h>
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN void lws_default_loop_exit | ( | struct lws_context * | cx | ) |
#include <include/libwebsockets/lws-context-vhost.h>
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN void lws_context_default_loop_run_destroy | ( | struct lws_context * | cx | ) |
#include <include/libwebsockets/lws-context-vhost.h>
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN int lws_cmdline_passfail | ( | int | argc, |
| const char ** | argv, | ||
| int | actual ) |
#include <include/libwebsockets/lws-context-vhost.h>
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN int lws_systemd_inherited_fd | ( | unsigned int | index, |
| struct lws_context_creation_info * | info ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_systemd_inherited_fd() - prepare vhost creation info for systemd exported fd if any
| index | 0+ index of exported fd |
| info | info struct to be prepared with related info, if any |
Returns 0 and points info to the related fd, aligning the other information to the type of fd and port it is bound to, or returns nonzero if no such inherited fd.
References LWS_EXTERN, and LWS_VISIBLE.
| LWS_VISIBLE LWS_EXTERN int lws_context_is_being_destroyed | ( | struct lws_context * | context | ) |
#include <include/libwebsockets/lws-context-vhost.h>
lws_context_is_being_destroyed() - find out if context is being destroyed
| context | the struct lws_context pointer |
Returns nonzero if the context has had lws_context_destroy() called on it... when using event library loops the destroy process can be asynchronous. In the special case of libuv foreign loops, the failure to create the context may have to do work on the foreign loop to reverse the partial creation, meaning a failed context create cannot unpick what it did and return NULL.
In that condition, a valid context that is already started the destroy process is returned, and this test api will return nonzero as a way to find out the create is in the middle of failing.
1.13.2 
