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