libwebsockets
Lightweight C library for HTML5 websockets
Protocols and Plugins

Modules

 plugin: generic-sessions
 
 plugin: lws-ssh-base
 

Data Structures

struct  lws_protocols
 

Functions

LWS_VISIBLE LWS_EXTERN const struct lws_protocolslws_vhost_name_to_protocol (struct lws_vhost *vh, const char *name)
 
LWS_VISIBLE LWS_EXTERN const struct lws_protocolslws_get_protocol (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN const struct lws_protocolslws_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_adjust_protocol_psds (struct lws *wsi, size_t new_size)
 
LWS_VISIBLE LWS_EXTERN int lws_finalize_startup (struct lws_context *context)
 
LWS_VISIBLE LWS_EXTERN const struct lws_protocol_vhost_optionslws_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 int lws_protocol_init (struct lws_context *context)
 

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.

Function Documentation

◆ 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
wsia connection with the protocol to change
new_sizethe 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.

◆ lws_finalize_startup()

LWS_VISIBLE LWS_EXTERN int lws_finalize_startup ( struct lws_context *  context)

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

lws_finalize_startup() - drop initial process privileges

Parameters
contextlws context

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

◆ 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
wsipointer 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.

◆ 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

◆ 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
vhostvhost the instance is related to
protprotocol 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

◆ 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
vhostvhost the instance is related to
protprotocol the instance is related to
sizebytes 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

◆ 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
pvothe first pvo in the linked-list
namethe name of the pvo to return if found
resultpointer to a const char * to get the result if any

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

◆ 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
pvothe first pvo in the linked-list
namethe name of the pvo to return if found

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

◆ 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
vhvhost to search
nameprotocol name

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