Collaboration diagram for Protocols and Plugins:

Topics
	plugin: lws-ssh-base

Data Structures
struct	lws_protocols

struct	lws_plugin_header

struct	lws_plugin_protocol

struct	lws_plugin

struct	lws_plugin_evlib

struct	lws_webrtc_ops

union	lws_plugin.u

Macros
#define	LWS_PROTOCOL_LIST_TERM { NULL, NULL, 0, 0, 0, NULL, 0 }

#define	LWS_PLUGIN_API_MAGIC 192

#define	LWS_WEBRTC_OPS_ABI_VERSION 9

Typedefs
typedef struct lws_plugin_header	lws_plugin_header_t

typedef struct lws_plugin_protocol	lws_plugin_protocol_t

typedef struct lws_plugin_evlib	lws_plugin_evlib_t

typedef int(*	each_plugin_cb_t) (struct lws_plugin p, void user)

typedef void(*	lws_webrtc_on_media_cb) (struct lws wsi_ws, int tid, const uint8_t buf, size_t len, int marker, uint32_t timestamp)

typedef int(*	lws_webrtc_session_iter_cb) (struct pss_webrtc pss, void user)

typedef void(*	lws_dht_store_completion_cb_t) (void *closure, int result)

Enumerations
enum	lws_webrtc_codec { LWS_WEBRTC_CODEC_H264 , LWS_WEBRTC_CODEC_AV1 }

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 void *	lws_vhd_find_by_pvo (struct lws_context cx, const char protname, const char pvo_name, const char pvo_value)

LWS_VISIBLE LWS_EXTERN void *	lws_adjust_protocol_psds (struct lws *wsi, size_t new_size)

LWS_VISIBLE LWS_EXTERN int	lws_finalize_startup (struct lws_context context, const char where)

LWS_VISIBLE LWS_EXTERN const struct lws_protocol_vhost_options *	lws_pvo_search (const struct lws_protocol_vhost_options pvo, const char name)

LWS_VISIBLE LWS_EXTERN int	lws_pvo_get_str (void in, const char name, const char **result)

LWS_VISIBLE LWS_EXTERN const struct lws_protocol_vhost_options *	lws_pmo_search (const struct lws_http_mount mount, const char name)

LWS_VISIBLE LWS_EXTERN int	lws_pmo_get_str (const struct lws_http_mount mount, const char name, const char **result)

LWS_VISIBLE LWS_EXTERN int	lws_protocol_init (struct lws_context *context)

LWS_VISIBLE LWS_EXTERN int	lws_plugins_init (struct lws_plugin *pplugin, const char const d, const char _class, const char filter, each_plugin_cb_t each, void each_user)

LWS_VISIBLE LWS_EXTERN int	lws_plugins_destroy (struct lws_plugin *pplugin, each_plugin_cb_t each, void each_user)

Detailed Description

Protocol and protocol plugin -related apis

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.

Data Structure Documentation

◆ lws_protocols

struct lws_protocols

struct lws_protocols - List of protocols and handlers client or server supports.

Definition at line 44 of file lws-protocols-plugins.h.

Collaboration diagram for lws_protocols:

Data Fields
const char *	name	Protocol name that must match the one given in the client Javascript new WebSocket(url, 'protocol') name.
lws_callback_function *	callback	The service callback used for this protocol. It allows the service action for an entire protocol to be encapsulated in the protocol-specific callback
size_t	per_session_data_size	Each new connection using this protocol gets this much memory allocated on connection establishment and freed on connection takedown. A pointer to this per-connection allocation is passed into the callback in the 'user' parameter
size_t	rx_buffer_size	lws allocates this much space for rx data and informs callback when something came. Due to rx flow control, the callback may not be able to consume it all without having to return to the event loop. That is supported in lws. If .tx_packet_size is 0, this also controls how much may be sent at once for backwards compatibility.
unsigned int	id	ignored by lws, but useful to contain user information bound to the selected protocol. For example if this protocol was called "myprotocol-v2", you might set id to 2, and the user code that acts differently according to the version can do so by switch (wsi->a.protocol->id), user code might use some bits as capability flags based on selected protocol version, etc.
void *	user	ignored by lws, but user code can pass a pointer here it can later access from the protocol callback
size_t	tx_packet_size	0 indicates restrict send() size to .rx_buffer_size for backwards- compatibility. If greater than zero, a single send() is restricted to this amount and any remainder is buffered by lws and sent afterwards also in these size chunks. Since that is expensive, it's preferable to restrict one fragment you are trying to send to match this size.

◆ lws_plugin_header

struct lws_plugin_header

Definition at line 273 of file lws-protocols-plugins.h.

Collaboration diagram for lws_plugin_header:

Data Fields
const char *	name
const char *	_class
const char *	lws_build_hash
unsigned int	api_magic
unsigned int	priority	Higher value == initialized earlier. Plugins with API magic < 192 default to 0.

◆ lws_plugin_protocol

struct lws_plugin_protocol

Definition at line 292 of file lws-protocols-plugins.h.

Collaboration diagram for lws_plugin_protocol:

Data Fields
lws_plugin_header_t	hdr
const struct lws_protocols *	protocols	array of supported protocols provided by plugin
const struct lws_extension *	extensions	array of extensions provided by plugin
int	count_protocols	how many protocols
int	count_extensions	how many extensions

◆ lws_plugin

struct lws_plugin

Definition at line 307 of file lws-protocols-plugins.h.

Collaboration diagram for lws_plugin:

Data Fields
struct lws_plugin *	list	linked list
const lws_plugin_header_t *	hdr
union lws_plugin.u	u

◆ lws_plugin_evlib

struct lws_plugin_evlib

Definition at line 327 of file lws-protocols-plugins.h.

Collaboration diagram for lws_plugin_evlib:

Data Fields
lws_plugin_header_t	hdr
const struct lws_event_loop_ops *	ops

◆ lws_webrtc_ops

struct lws_webrtc_ops

Definition at line 393 of file lws-protocols-plugins.h.

Collaboration diagram for lws_webrtc_ops:

Data Fields
uint32_t	abi_version
int()(struct lws_webrtc_peer_media media, const uint8_t *buf, size_t len, int codec, uint32_t pts)	send_video
int()(struct lws_webrtc_peer_media media, const uint8_t *buf, size_t len, uint32_t timestamp)	send_audio
int()(struct pss_webrtc pss, const char *buf, size_t len)	send_text
int()(struct pss_webrtc pss)	send_pli
void()(struct lws_webrtc_peer_media media)	media_ref
void()(struct lws_webrtc_peer_media *pmedia)	media_unref
int()(struct vhd_webrtc vhd, lws_webrtc_session_iter_cb cb, void *user)	foreach_session
struct lws_webrtc_peer_media ()(struct pss_webrtc *pss)	get_media
int()(struct lws wsi, enum lws_callback_reasons reason, void user, void in, size_t len, struct vhd_webrtc *vhd)	shared_callback
void ()(struct pss_webrtc *pss)	get_user_data
void()(struct pss_webrtc pss, void *data)	set_user_data
struct lws_vhost ()(struct vhd_webrtc *vhd)	get_vhost
struct lws_context ()(struct vhd_webrtc *vhd)	get_context
void()(struct vhd_webrtc vhd, lws_webrtc_on_media_cb cb)	set_on_media
uint8_t()(struct pss_webrtc pss)	get_video_pt
uint8_t()(struct pss_webrtc pss)	get_audio_pt
uint8_t()(struct pss_webrtc pss)	get_video_pt_h264
uint8_t()(struct pss_webrtc pss)	get_video_pt_av1
uint16_t()(struct pss_webrtc pss)	get_seq_video
int()(struct pss_webrtc pss)	create_offer

◆ lws_plugin.u

union lws_plugin.u

Definition at line 312 of file lws-protocols-plugins.h.

Collaboration diagram for lws_plugin.u:

Data Fields
void *	l

Macro Definition Documentation

◆ LWS_PROTOCOL_LIST_TERM

#define LWS_PROTOCOL_LIST_TERM { NULL, NULL, 0, 0, 0, NULL, 0 }

#include <include/libwebsockets/lws-protocols-plugins.h>

Definition at line 89 of file lws-protocols-plugins.h.

◆ LWS_PLUGIN_API_MAGIC

#define LWS_PLUGIN_API_MAGIC 192

#include <include/libwebsockets/lws-protocols-plugins.h>

Definition at line 260 of file lws-protocols-plugins.h.

◆ LWS_WEBRTC_OPS_ABI_VERSION

#define LWS_WEBRTC_OPS_ABI_VERSION 9

#include <include/libwebsockets/lws-protocols-plugins.h>

Definition at line 391 of file lws-protocols-plugins.h.

Typedef Documentation

◆ lws_plugin_header_t

typedef struct lws_plugin_header lws_plugin_header_t

#include <include/libwebsockets/lws-protocols-plugins.h>

◆ lws_plugin_protocol_t

typedef struct lws_plugin_protocol lws_plugin_protocol_t

#include <include/libwebsockets/lws-protocols-plugins.h>

◆ lws_plugin_evlib_t

typedef struct lws_plugin_evlib lws_plugin_evlib_t

#include <include/libwebsockets/lws-protocols-plugins.h>

◆ each_plugin_cb_t

typedef int(* each_plugin_cb_t) (struct lws_plugin *p, void *user)

#include <include/libwebsockets/lws-protocols-plugins.h>

Definition at line 332 of file lws-protocols-plugins.h.

◆ lws_webrtc_on_media_cb

typedef void(* lws_webrtc_on_media_cb) (struct lws *wsi_ws, int tid, const uint8_t *buf, size_t len, int marker, uint32_t timestamp)

#include <include/libwebsockets/lws-protocols-plugins.h>

Definition at line 382 of file lws-protocols-plugins.h.

◆ lws_webrtc_session_iter_cb

typedef int(* lws_webrtc_session_iter_cb) (struct pss_webrtc *pss, void *user)

#include <include/libwebsockets/lws-protocols-plugins.h>

Definition at line 384 of file lws-protocols-plugins.h.

◆ lws_dht_store_completion_cb_t

typedef void(* lws_dht_store_completion_cb_t) (void *closure, int result)

#include <include/libwebsockets/lws-protocols-plugins.h>

Definition at line 458 of file lws-protocols-plugins.h.

Enumeration Type Documentation

◆ lws_webrtc_codec

enum lws_webrtc_codec

#include <include/libwebsockets/lws-protocols-plugins.h>

Enumerator
LWS_WEBRTC_CODEC_H264
LWS_WEBRTC_CODEC_AV1

Definition at line 386 of file lws-protocols-plugins.h.

                      {
        LWS_WEBRTC_CODEC_H264,
        LWS_WEBRTC_CODEC_AV1
};

Function Documentation

◆ lws_vhost_name_to_protocol()

LWS_VISIBLE LWS_EXTERN const struct lws_protocols * lws_vhost_name_to_protocol	(	struct lws_vhost *	vh,
		const char *	name )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_vhost_name_to_protocol() - get vhost's protocol object from its name

Parameters

vh	vhost to search
name	protocol name

Returns NULL or a pointer to the vhost's protocol of the requested name

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_get_protocol()

LWS_VISIBLE LWS_EXTERN const struct lws_protocols * lws_get_protocol ( struct lws * wsi )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_get_protocol() - Returns a protocol pointer from a websocket connection.

Parameters

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.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_protocol_get()

LWS_VISIBLE LWS_EXTERN const struct lws_protocols * lws_protocol_get ( struct lws * wsi )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_protocol_get() - deprecated: use lws_get_protocol

References LWS_EXTERN, LWS_VISIBLE, and LWS_WARN_DEPRECATED.

◆ lws_protocol_vh_priv_zalloc()

LWS_VISIBLE LWS_EXTERN void * lws_protocol_vh_priv_zalloc	(	struct lws_vhost *	vhost,
		const struct lws_protocols *	prot,
		int	size )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_protocol_vh_priv_zalloc() - Allocate and zero down a protocol's per-vhost storage

Parameters

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

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_protocol_vh_priv_get()

LWS_VISIBLE LWS_EXTERN void * lws_protocol_vh_priv_get	(	struct lws_vhost *	vhost,
		const struct lws_protocols *	prot )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_protocol_vh_priv_get() - retreive a protocol's per-vhost storage

Parameters

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

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_vhd_find_by_pvo()

LWS_VISIBLE LWS_EXTERN void * lws_vhd_find_by_pvo	(	struct lws_context *	cx,
		const char *	protname,
		const char *	pvo_name,
		const char *	pvo_value )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_vhd_find_by_pvo() - find a partner vhd

Parameters

cx	the lws_context
protname	the name of the lws_protocol the vhd belongs to
pvo_name	the name of a pvo that must exist bound to the vhd
pvo_value	the required value of the named pvo

This allows architectures with multiple protocols bound together to cleanly discover partner protocol instances even on completely different vhosts. For example, a proxy may consist of two protocols listening on different vhosts, and there may be multiple instances of the proxy in the same process. It's desirable that each side of the proxy is an independent protocol that can be freely bound to any vhost, eg, allowing Unix Domain to tls / h2 proxying, or each side bound to different network interfaces for localhost-only visibility on one side, using existing vhost management.

That leaves the problem that the two sides have to find each other and bind at runtime. This api allows each side to specify the protocol name, and a common pvo name and pvo value that indicates the two sides belong together, and search through all the instantiated vhost-protocols looking for a match. If found, the private allocation (aka "vhd" of the match is returned). NULL is returned on no match.

Since this can only succeed when called by the last of the two protocols to be instantiated, both sides should call it and handle NULL gracefully, since it may mean that they were first and their partner vhsot-protocol has not been instantiated yet.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_adjust_protocol_psds()

LWS_VISIBLE LWS_EXTERN void * lws_adjust_protocol_psds	(	struct lws *	wsi,
		size_t	new_size )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_adjust_protocol_psds - change a vhost protocol's per session data size

Parameters

wsi	a connection with the protocol to change
new_size	the new size of the per session data size for the protocol

Returns user_space for the wsi, after allocating

This should not be used except to initalize a vhost protocol's per session data size one time, before any connections are accepted.

Sometimes the protocol wraps another protocol and needs to discover and set its per session data size at runtime.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_finalize_startup()

LWS_VISIBLE LWS_EXTERN int lws_finalize_startup	(	struct lws_context *	context,
		const char *	where )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_finalize_startup() - drop initial process privileges

Parameters

context lws context

This is called after the end of the vhost protocol initializations, but you may choose to call it earlier

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_pvo_search()

LWS_VISIBLE LWS_EXTERN const struct lws_protocol_vhost_options * lws_pvo_search	(	const struct lws_protocol_vhost_options *	pvo,
		const char *	name )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_pvo_search() - helper to find a named pvo in a linked-list

Parameters

pvo	the first pvo in the linked-list
name	the name of the pvo to return if found

Returns NULL, or a pointer to the name pvo in the linked-list

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_pvo_get_str()

LWS_VISIBLE LWS_EXTERN int lws_pvo_get_str	(	void *	in,
		const char *	name,
		const char **	result )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_pvo_get_str() - retreive a string pvo value

Parameters

in	the first pvo in the linked-list
name	the name of the pvo to return if found
result	pointer to a const char * to get the result if any

Returns 0 if found and *result set, or nonzero if not found

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_pmo_search()

LWS_VISIBLE LWS_EXTERN const struct lws_protocol_vhost_options * lws_pmo_search	(	const struct lws_http_mount *	mount,
		const char *	name )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_pmo_search() - helper to find a named pmo in a linked-list

Parameters

mount	the mount it is associated with
name	the name of the pmo to return if found

Returns NULL, or a pointer to the named pmo in the linked-list

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_pmo_get_str()

LWS_VISIBLE LWS_EXTERN int lws_pmo_get_str	(	const struct lws_http_mount *	mount,
		const char *	name,
		const char **	result )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_pmo_get_str() - retreive a string pmo value

Parameters

mount	the mount it is associated with
name	the name of the pmo to return if found
result	pointer to a const char * to get the result if any

Returns 0 if found and *result set, or nonzero if not found

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_protocol_init()

LWS_VISIBLE LWS_EXTERN int lws_protocol_init ( struct lws_context * context )

#include <include/libwebsockets/lws-protocols-plugins.h>

◆ lws_plugins_init()

LWS_VISIBLE LWS_EXTERN int lws_plugins_init	(	struct lws_plugin **	pplugin,
		const char const	d,
		const char *	_class,
		const char *	filter,
		each_plugin_cb_t	each,
		void *	each_user )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_plugins_init() - dynamically load plugins of matching class from dirs

Parameters

pplugin	pointer to linked-list for this kind of plugin
d	array of directory paths to look in
_class	class string that plugin must declare
filter	NULL, or a string that must appear after the third char of the plugin filename
each	NULL, or each_plugin_cb_t callback for each instantiated plugin
each_user	pointer passed to each callback

Allows you to instantiate a class of plugins to a specified linked-list. The each callback allows you to init each inistantiated callback and pass a pointer each_user to it.

To take down the plugins, pass a pointer to the linked-list head to lws_plugins_destroy.

This is used for lws protocol plugins but you can define your own plugin class name like "mypluginclass", declare it in your plugin headers, and load your own plugins to your own list using this api the same way.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_plugins_destroy()

LWS_VISIBLE LWS_EXTERN int lws_plugins_destroy	(	struct lws_plugin **	pplugin,
		each_plugin_cb_t	each,
		void *	each_user )

#include <include/libwebsockets/lws-protocols-plugins.h>

lws_plugins_destroy() - dynamically unload list of plugins

Parameters

pplugin	pointer to linked-list for this kind of plugin
each	NULL, or each_plugin_cb_t callback for each instantiated plugin
each_user	pointer passed to each callback

Allows you to destroy a class of plugins from a specified linked-list created by a call to lws_plugins_init().

The each callback allows you to deinit each inistantiated callback and pass a pointer each_user to it, just before its footprint is destroyed.

Topics

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Protocol and protocol plugin -related apis

Data Structure Documentation

◆ lws_protocols

◆ lws_plugin_header

◆ lws_plugin_protocol

◆ lws_plugin

◆ lws_plugin_evlib

◆ lws_webrtc_ops

◆ lws_plugin.u

Macro Definition Documentation

◆ LWS_PROTOCOL_LIST_TERM

◆ LWS_PLUGIN_API_MAGIC

◆ LWS_WEBRTC_OPS_ABI_VERSION

Typedef Documentation

◆ lws_plugin_header_t

◆ lws_plugin_protocol_t

◆ lws_plugin_evlib_t

◆ each_plugin_cb_t

◆ lws_webrtc_on_media_cb

◆ lws_webrtc_session_iter_cb

◆ lws_dht_store_completion_cb_t

Enumeration Type Documentation

◆ lws_webrtc_codec

Function Documentation

◆ lws_vhost_name_to_protocol()

◆ lws_get_protocol()

◆ lws_protocol_get()

◆ lws_protocol_vh_priv_zalloc()

◆ lws_protocol_vh_priv_get()

◆ lws_vhd_find_by_pvo()

◆ lws_adjust_protocol_psds()

◆ lws_finalize_startup()

◆ lws_pvo_search()

◆ lws_pvo_get_str()

◆ lws_pmo_search()

◆ lws_pmo_get_str()

◆ lws_protocol_init()

◆ lws_plugins_init()

◆ lws_plugins_destroy()