Extension related functions

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)

Detailed Description

Extension releated functions

Ws defines optional extensions, lws provides the ability to implement these in user code if so desired.

We provide one extensions permessage-deflate.

Typedef Documentation

lws_extension_callback_function

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

Parameters

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:

Enumeration Type Documentation

lws_ext_options_types

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

                           {
        EXTARG_NONE, 
        EXTARG_DEC,  
        EXTARG_OPT_DEC 
        /* Add new things just above here ---^
         * This is part of the ABI, don't needlessly break compatibility */
};

Function Documentation

lws_ext_parse_options()

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

Parameters

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

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

Parameters

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

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

Parameters

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