libwebsockets
Lightweight C library for HTML5 websockets
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_CONSTRUCT = 4 , LWS_EXT_CB_CLIENT_CONSTRUCT = 5 , LWS_EXT_CB_DESTROY = 8 , LWS_EXT_CB_PACKET_TX_PRESEND = 12 ,
  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 <include/libwebsockets/lws-ws-ext.h>

typedef lws_extension_callback_function() - Hooks to allow extensions to operate

Parameters
contextWebsockets context
extThis extension
wsiOpaque websocket instance pointer
reasonThe reason for the call
userPointer to ptr to per-session user data allocated by library
inPointer used for some callback reasons
lenLength 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_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

#include <include/libwebsockets/lws-ws-ext.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

55  {
56  EXTARG_NONE,
57  EXTARG_DEC,
60  /* Add new things just above here ---^
61  * This is part of the ABI, don't needlessly break compatibility */
62 };
@ EXTARG_DEC
Definition: lws-ws-ext.h:57
@ EXTARG_OPT_DEC
Definition: lws-ws-ext.h:58
@ EXTARG_NONE
Definition: lws-ws-ext.h:56

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 <include/libwebsockets/lws-ws-ext.h>

lws_ext_parse_options() - deal with parsing negotiated extension options

Parameters
extrelated extension struct
wsiwebsocket connection
ext_userper-connection extension private data
optslist of supported options
ooption string to parse
lenlength

◆ 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 <include/libwebsockets/lws-ws-ext.h>

lws_extension_callback_pm_deflate() - extension for RFC7692

Parameters
contextlws context
extrelated lws_extension struct
wsiwebsocket connection
reasonincoming callback reason
userper-connection extension private data
inpointer parameter
lenlength 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 <include/libwebsockets/lws-ws-ext.h>

lws_set_extension_option(): set extension option if possible

Parameters
wsiwebsocket connection
ext_namename of ext, like "permessage-deflate"
opt_namename of option, like "rx_buf_size"
opt_valvalue to set option to