include/libwebsockets/lws-protocols-plugins.h

   1 /*
   2  * libwebsockets - small server side websockets and web server implementation
   3  *
   4  * Copyright (C) 2010-2018 Andy Green <andy@warmcat.com>
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public
   8  *  License as published by the Free Software Foundation:
   9  *  version 2.1 of the License.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19  *  MA  02110-1301  USA
  20  *
  21  * included from libwebsockets.h
  22  */
  23
  24 /*! \defgroup Protocols-and-Plugins Protocols and Plugins
  25  * \ingroup lwsapi
  26  *
  27  * ##Protocol and protocol plugin -related apis
  28  *
  29  * Protocols bind ws protocol names to a custom callback specific to that
  30  * protocol implementaion.
  31  *
  32  * A list of protocols can be passed in at context creation time, but it is
  33  * also legal to leave that NULL and add the protocols and their callback code
  34  * using plugins.
  35  *
  36  * Plugins are much preferable compared to cut and pasting code into an
  37  * application each time, since they can be used standalone.
  38  */
  39 ///@{
  40 /** struct lws_protocols -      List of protocols and handlers client or server
  41  *                                      supports. */
  42
  43 struct lws_protocols {
  44         const char *name;
  45         /**< Protocol name that must match the one given in the client
  46          * Javascript new WebSocket(url, 'protocol') name. */
  47         lws_callback_function *callback;
  48         /**< The service callback used for this protocol.  It allows the
  49          * service action for an entire protocol to be encapsulated in
  50          * the protocol-specific callback */
  51         size_t per_session_data_size;
  52         /**< Each new connection using this protocol gets
  53          * this much memory allocated on connection establishment and
  54          * freed on connection takedown.  A pointer to this per-connection
  55          * allocation is passed into the callback in the 'user' parameter */
  56         size_t rx_buffer_size;
  57         /**< lws allocates this much space for rx data and informs callback
  58          * when something came.  Due to rx flow control, the callback may not
  59          * be able to consume it all without having to return to the event
  60          * loop.  That is supported in lws.
  61          *
  62          * If .tx_packet_size is 0, this also controls how much may be sent at
  63          * once for backwards compatibility.
  64          */
  65         unsigned int id;
  66         /**< ignored by lws, but useful to contain user information bound
  67          * to the selected protocol.  For example if this protocol was
  68          * called "myprotocol-v2", you might set id to 2, and the user
  69          * code that acts differently according to the version can do so by
  70          * switch (wsi->protocol->id), user code might use some bits as
  71          * capability flags based on selected protocol version, etc. */
  72         void *user; /**< ignored by lws, but user code can pass a pointer
  73                         here it can later access from the protocol callback */
  74         size_t tx_packet_size;
  75         /**< 0 indicates restrict send() size to .rx_buffer_size for backwards-
  76          * compatibility.
  77          * If greater than zero, a single send() is restricted to this amount
  78          * and any remainder is buffered by lws and sent afterwards also in
  79          * these size chunks.  Since that is expensive, it's preferable
  80          * to restrict one fragment you are trying to send to match this
  81          * size.
  82          */
  83
  84         /* Add new things just above here ---^
  85          * This is part of the ABI, don't needlessly break compatibility */
  86 };
  87
  88 /**
  89  * lws_vhost_name_to_protocol() - get vhost's protocol object from its name
  90  *
  91  * \param vh: vhost to search
  92  * \param name: protocol name
  93  *
  94  * Returns NULL or a pointer to the vhost's protocol of the requested name
  95  */
  96 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
  97 lws_vhost_name_to_protocol(struct lws_vhost *vh, const char *name);
  98
  99 /**
 100  * lws_get_protocol() - Returns a protocol pointer from a websocket
 101  *                                connection.
 102  * \param wsi:  pointer to struct websocket you want to know the protocol of
 103  *
 104  *
 105  *      Some apis can act on all live connections of a given protocol,
 106  *      this is how you can get a pointer to the active protocol if needed.
 107  */
 108 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
 109 lws_get_protocol(struct lws *wsi);
 110
 111 /** lws_protocol_get() -  deprecated: use lws_get_protocol */
 112 LWS_VISIBLE LWS_EXTERN const struct lws_protocols *
 113 lws_protocol_get(struct lws *wsi) LWS_WARN_DEPRECATED;
 114
 115 /**
 116  * lws_protocol_vh_priv_zalloc() - Allocate and zero down a protocol's per-vhost
 117  *                                 storage
 118  * \param vhost:        vhost the instance is related to
 119  * \param prot:         protocol the instance is related to
 120  * \param size:         bytes to allocate
 121  *
 122  * Protocols often find it useful to allocate a per-vhost struct, this is a
 123  * helper to be called in the per-vhost init LWS_CALLBACK_PROTOCOL_INIT
 124  */
 125 LWS_VISIBLE LWS_EXTERN void *
 126 lws_protocol_vh_priv_zalloc(struct lws_vhost *vhost,
 127                             const struct lws_protocols *prot, int size);
 128
 129 /**
 130  * lws_protocol_vh_priv_get() - retreive a protocol's per-vhost storage
 131  *
 132  * \param vhost:        vhost the instance is related to
 133  * \param prot:         protocol the instance is related to
 134  *
 135  * Recover a pointer to the allocated per-vhost storage for the protocol created
 136  * by lws_protocol_vh_priv_zalloc() earlier
 137  */
 138 LWS_VISIBLE LWS_EXTERN void *
 139 lws_protocol_vh_priv_get(struct lws_vhost *vhost,
 140                          const struct lws_protocols *prot);
 141
 142 /**
 143  * lws_adjust_protocol_psds - change a vhost protocol's per session data size
 144  *
 145  * \param wsi: a connection with the protocol to change
 146  * \param new_size: the new size of the per session data size for the protocol
 147  *
 148  * Returns user_space for the wsi, after allocating
 149  *
 150  * This should not be used except to initalize a vhost protocol's per session
 151  * data size one time, before any connections are accepted.
 152  *
 153  * Sometimes the protocol wraps another protocol and needs to discover and set
 154  * its per session data size at runtime.
 155  */
 156 LWS_VISIBLE LWS_EXTERN void *
 157 lws_adjust_protocol_psds(struct lws *wsi, size_t new_size);
 158
 159 /**
 160  * lws_finalize_startup() - drop initial process privileges
 161  *
 162  * \param context:      lws context
 163  *
 164  * This is called after the end of the vhost protocol initializations, but
 165  * you may choose to call it earlier
 166  */
 167 LWS_VISIBLE LWS_EXTERN int
 168 lws_finalize_startup(struct lws_context *context);
 169
 170 /**
 171  * lws_pvo_search() - helper to find a named pvo in a linked-list
 172  *
 173  * \param pvo:  the first pvo in the linked-list
 174  * \param name: the name of the pvo to return if found
 175  *
 176  * Returns NULL, or a pointer to the name pvo in the linked-list
 177  */
 178 LWS_VISIBLE LWS_EXTERN const struct lws_protocol_vhost_options *
 179 lws_pvo_search(const struct lws_protocol_vhost_options *pvo, const char *name);
 180
 181 /**
 182  * lws_pvo_get_str() - retreive a string pvo value
 183  *
 184  * \param pvo:  the first pvo in the linked-list
 185  * \param name: the name of the pvo to return if found
 186  * \param result: pointer to a const char * to get the result if any
 187  *
 188  * Returns 0 if found and *result set, or nonzero if not found
 189  */
 190 LWS_VISIBLE LWS_EXTERN int
 191 lws_pvo_get_str(void *in, const char *name, const char **result);
 192
 193 LWS_VISIBLE LWS_EXTERN int
 194 lws_protocol_init(struct lws_context *context);
 195
 196 #ifdef LWS_WITH_PLUGINS
 197
 198 /* PLUGINS implies LIBUV */
 199
 200 #define LWS_PLUGIN_API_MAGIC 180
 201
 202 /** struct lws_plugin_capability - how a plugin introduces itself to lws */
 203 struct lws_plugin_capability {
 204         unsigned int api_magic; /**< caller fills this in, plugin fills rest */
 205         const struct lws_protocols *protocols; /**< array of supported protocols provided by plugin */
 206         int count_protocols; /**< how many protocols */
 207         const struct lws_extension *extensions; /**< array of extensions provided by plugin */
 208         int count_extensions; /**< how many extensions */
 209 };
 210
 211 typedef int (*lws_plugin_init_func)(struct lws_context *,
 212                                     struct lws_plugin_capability *);
 213 typedef int (*lws_plugin_destroy_func)(struct lws_context *);
 214
 215 /** struct lws_plugin */
 216 struct lws_plugin {
 217         struct lws_plugin *list; /**< linked list */
 218 #if (UV_VERSION_MAJOR > 0)
 219         uv_lib_t lib; /**< shared library pointer */
 220 #endif
 221         void *l; /**< so we can compile on ancient libuv */
 222         char name[64]; /**< name of the plugin */
 223         struct lws_plugin_capability caps; /**< plugin capabilities */
 224 };
 225
 226 #endif
 227
 228 ///@}