 |
libwebsockets
Lightweight C library for HTML5 websockets
|
|
libwebsockets
Lightweight C library for HTML5 websockets
|
#include <libwebsockets.h>
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.
| void* lws_context_creation_info::_unused[8] |
dummy
| int lws_context_creation_info::bind_iface |
VHOST: nonzero to strictly bind sockets to the interface name in .iface (eg, "eth2"), using SO_BIND_TO_DEVICE.
Requires SO_BINDTODEVICE support from your OS and CAP_NET_RAW capability.
Notice that common things like access network interface IP from your local machine use your lo / loopback interface and will be disallowed by this.
| cap_value_t lws_context_creation_info::caps[4] |
CONTEXT: array holding Linux capabilities you want to continue to be available to the server after it transitions to a noprivileged user. Usually none are needed but for, eg, .bind_iface, CAP_NET_RAW is required. This gives you a way to still have the capability but drop root.
| const char* lws_context_creation_info::client_ssl_ca_filepath |
VHOST: Client SSL context init: CA certificate filepath or NULL
| const char* lws_context_creation_info::client_ssl_cert_filepath |
VHOST: Client SSL context init:T he certificate the client should present to the peer on connection
| const char* lws_context_creation_info::client_ssl_cipher_list |
VHOST: Client SSL context init: List of valid ciphers to use (eg, "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL" or you can leave it as NULL to get "DEFAULT"
| const char* lws_context_creation_info::client_ssl_private_key_filepath |
VHOST: Client SSL context init: filepath to client private key if this is set to NULL but client_ssl_cert_filepath is set, you can handle the LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS callback of protocols[0] to allow setting of the private key directly via openSSL library calls
| const char* lws_context_creation_info::client_ssl_private_key_password |
VHOST: Client SSL context init: NULL or the passphrase needed for the private key
| char lws_context_creation_info::count_caps |
CONTEXT: count of Linux capabilities in .caps[]. 0 means no capabilities will be inherited from root (the default)
| unsigned int lws_context_creation_info::count_threads |
CONTEXT: how many contexts to create in an array, 0 = 1
| const char* lws_context_creation_info::ecdh_curve |
VHOST: if NULL, defaults to initializing server with "prime256v1"
| const struct lws_extension* lws_context_creation_info::extensions |
VHOST: NULL or array of lws_extension structs listing the extensions this context supports.
| void* lws_context_creation_info::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 lws_context_creation_info::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.
| const struct lws_plat_file_ops* lws_context_creation_info::fops |
CONTEXT: NULL, or pointer to an array of fops structs, terminated by a sentinel with NULL .open.
If NULL, lws provides just the platform file operations struct for backwards compatibility.
| int lws_context_creation_info::gid |
CONTEXT: group id to change to after setting listen socket, or -1.
| const struct lws_protocol_vhost_options* lws_context_creation_info::headers |
VHOST: pointer to optional linked list of per-vhost canned headers that are added to server responses
| uint32_t lws_context_creation_info::http2_settings[7] |
CONTEXT: after context creation http2_settings[1] thru [6] have been set to the lws platform default values. VHOST: if http2_settings[0] is nonzero, the values given in http2_settings[1]..[6] are used instead of the lws platform default values. Just leave all at 0 if you don't care.
| const char* lws_context_creation_info::http_proxy_address |
VHOST: If non-NULL, attempts to proxy via the given address. If proxy auth is required, use format "username:password\@server:port"
| unsigned int lws_context_creation_info::http_proxy_port |
VHOST: If http_proxy_address was non-NULL, uses this port
| const char* lws_context_creation_info::iface |
VHOST: NULL to bind the listen socket to all interfaces, or the interface name, eg, "eth2" If options specifies LWS_SERVER_OPTION_UNIX_SOCK, this member is the pathname of a UNIX domain socket. you can use the UNIX domain sockets in abstract namespace, by prepending an at symbol to the socket name.
| unsigned short lws_context_creation_info::ip_limit_ah |
CONTEXT: max number of ah a single IP may use simultaneously 0 is no limit. This is a soft limit: if the limit is reached, connections from that IP will wait in the ah waiting list and not be able to acquire an ah until a connection belonging to the IP relinquishes one it already has.
| unsigned short lws_context_creation_info::ip_limit_wsi |
CONTEXT: max number of wsi a single IP may use simultaneously. 0 is no limit. This is a hard limit, connections from the same IP will simply be dropped once it acquires the amount of simultaneous wsi / accepted connections given here.
| int lws_context_creation_info::ka_interval |
CONTEXT: if ka_time was nonzero, how long to wait before each ka_probes attempt
| int lws_context_creation_info::ka_probes |
CONTEXT: if ka_time was nonzero, after the timeout expires how many times to try to get a response from the peer before giving up and killing the connection
| int lws_context_creation_info::ka_time |
CONTEXT: 0 for no TCP keepalive, otherwise apply this keepalive timeout to all libwebsocket sockets, client or server
| int lws_context_creation_info::keepalive_timeout |
VHOST: (default = 0 = 60s) seconds to allow remote client to hold on to an idle HTTP/1.1 connection
| const char* lws_context_creation_info::log_filepath |
VHOST: filepath to append logs to... this is opened before any dropping of initial privileges
| short lws_context_creation_info::max_http_header_data |
CONTEXT: The max amount of header payload that can be handled in an http request (unrecognized header payload is dropped)
| unsigned int lws_context_creation_info::max_http_header_data2 |
CONTEXT: if max_http_header_data is 0 and this is nonzero, this will be used in place of the default. It's like this for compatibility with the original short version, this is unsigned int length.
| short lws_context_creation_info::max_http_header_pool |
CONTEXT: The max number of connections with http headers that can be processed simultaneously (the corresponding memory is allocated for the lifetime of the context). If the pool is busy new incoming connections must wait for accept until one becomes free.
| const struct lws_http_mount* lws_context_creation_info::mounts |
VHOST: optional linked list of mounts for this vhost
| unsigned int lws_context_creation_info::options |
VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields
| const char* const* lws_context_creation_info::plugin_dirs |
CONTEXT: NULL, or NULL-terminated array of directories to scan for lws protocol plugins at context creation time
| int lws_context_creation_info::port |
VHOST: Port to listen on. Use CONTEXT_PORT_NO_LISTEN to suppress listening for a client. Use CONTEXT_PORT_NO_LISTEN_SERVER if you are writing a server but you are using Socket adoption helpers instead of the built-in listener
| const struct lws_protocols* lws_context_creation_info::protocols |
VHOST: Array of structures listing supported protocols and a protocol- specific callback for each one. The list is ended with an entry that has a NULL callback pointer.
| SSL_CTX* lws_context_creation_info::provided_client_ssl_ctx |
CONTEXT: If non-null, swap out libwebsockets ssl implementation for the one provided by provided_ssl_ctx. Libwebsockets no longer is responsible for freeing the context if this option is selected.
| void* lws_context_creation_info::provided_client_ssl_ctx |
dummy if ssl disabled
| unsigned int lws_context_creation_info::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.
| const struct lws_protocol_vhost_options* lws_context_creation_info::pvo |
VHOST: pointer to optional linked list of per-vhost options made accessible to protocols
| const struct lws_protocol_vhost_options* lws_context_creation_info::reject_service_keywords |
CONTEXT: Optional list of keywords and rejection codes + text.
The keywords are checked for existing in the user agent string.
Eg, "badrobot" "404 Not Found"
| const char* lws_context_creation_info::server_string |
CONTEXT: string used in HTTP headers to identify server software, if NULL, "libwebsockets".
| int lws_context_creation_info::simultaneous_ssl_restriction |
CONTEXT: 0 (no limit) or limit of simultaneous SSL sessions possible.
| const char* lws_context_creation_info::socks_proxy_address |
VHOST: If non-NULL, attempts to proxy via the given address. If proxy auth is required, use format "username:password\@server:port"
| unsigned int lws_context_creation_info::socks_proxy_port |
VHOST: If socks_proxy_address was non-NULL, uses this port
| const char* lws_context_creation_info::ssl_ca_filepath |
VHOST: CA certificate filepath or NULL. (For backwards compatibility, this can also be used to pass the client CA filepath when setting up a vhost client SSL context, but it is preferred to use .client_ssl_ca_filepath for that.)
| const char* lws_context_creation_info::ssl_cert_filepath |
VHOST: If libwebsockets was compiled to use ssl, and you want to listen using SSL, set to the filepath to fetch the server cert from, otherwise NULL for unencrypted. (For backwards compatibility, this can also be used to pass the client certificate when setting up a vhost client SSL context, but it is preferred to use .client_ssl_cert_filepath for that.)
| const char* lws_context_creation_info::ssl_cipher_list |
VHOST: List of valid ciphers to use (eg, "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL" or you can leave it as NULL to get "DEFAULT" (For backwards compatibility, this can also be used to pass the client cipher list when setting up a vhost client SSL context, but it is preferred to use .client_ssl_cipher_list for that.)
| int lws_context_creation_info::ssl_info_event_mask |
VHOST: mask of ssl events to be reported on LWS_CALLBACK_SSL_INFO callback for connections on this vhost. The mask values are of the form SSL_CB_ALERT, defined in openssl/ssl.h. The default of 0 means no info events will be reported.
| long lws_context_creation_info::ssl_options_clear |
VHOST: Any bits set here will be cleared as SSL options
| long lws_context_creation_info::ssl_options_set |
VHOST: Any bits set here will be set as SSL options
| const char* lws_context_creation_info::ssl_private_key_filepath |
VHOST: filepath to private key if wanting SSL mode; if this is set to NULL but ssl_cert_filepath is set, the OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called to allow setting of the private key directly via openSSL library calls. (For backwards compatibility, this can also be used to pass the client cert private key filepath when setting up a vhost client SSL context, but it is preferred to use .client_ssl_private_key_filepath for that.)
| const char* lws_context_creation_info::ssl_private_key_password |
VHOST: NULL or the passphrase needed for the private key. (For backwards compatibility, this can also be used to pass the client cert passphrase when setting up a vhost client SSL context, but it is preferred to use .client_ssl_private_key_password for that.)
| unsigned int lws_context_creation_info::timeout_secs |
VHOST: various processes involving network roundtrips in the library are protected from hanging forever by timeouts. If nonzero, this member lets you set the timeout used in seconds. Otherwise a default timeout is used.
| unsigned int lws_context_creation_info::timeout_secs_ah_idle |
VHOST: seconds to allow a client to hold an ah without using it. 0 defaults to 10s.
| const struct lws_token_limits* lws_context_creation_info::token_limits |
CONTEXT: NULL or struct lws_token_limits pointer which is initialized with a token length limit for each possible WSI_TOKEN_
| int lws_context_creation_info::uid |
CONTEXT: user id to change to after setting listen socket, or -1.
| void* lws_context_creation_info::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.
| const char* lws_context_creation_info::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.
| unsigned short lws_context_creation_info::ws_ping_pong_interval |
CONTEXT: 0 for none, else interval in seconds between sending PINGs on idle websocket connections. When the PING is sent, the PONG must come within the normal timeout_secs timeout period or the connection will be dropped. Any RX or TX traffic on the connection restarts the interval timer, so a connection which always sends or receives something at intervals less than the interval given here will never send PINGs / expect PONGs. Conversely as soon as the ws connection is established, an idle connection will do the PING / PONG roundtrip as soon as ws_ping_pong_interval seconds has passed without traffic
1.8.14