lws-ws-ext.h (7837B)
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 extensions Extension related functions 26 * ##Extension releated functions 27 * 28 * Ws defines optional extensions, lws provides the ability to implement these 29 * in user code if so desired. 30 * 31 * We provide one extensions permessage-deflate. 32 */ 33///@{ 34 35/* 36 * NOTE: These public enums are part of the abi. If you want to add one, 37 * add it at where specified so existing users are unaffected. 38 */ 39enum lws_extension_callback_reasons { 40 LWS_EXT_CB_CONSTRUCT = 4, 41 LWS_EXT_CB_CLIENT_CONSTRUCT = 5, 42 LWS_EXT_CB_DESTROY = 8, 43 LWS_EXT_CB_PACKET_TX_PRESEND = 12, 44 LWS_EXT_CB_PAYLOAD_TX = 21, 45 LWS_EXT_CB_PAYLOAD_RX = 22, 46 LWS_EXT_CB_OPTION_DEFAULT = 23, 47 LWS_EXT_CB_OPTION_SET = 24, 48 LWS_EXT_CB_OPTION_CONFIRM = 25, 49 LWS_EXT_CB_NAMED_OPTION_SET = 26, 50 51 /****** add new things just above ---^ ******/ 52}; 53 54/** enum lws_ext_options_types */ 55enum lws_ext_options_types { 56 EXTARG_NONE, /**< does not take an argument */ 57 EXTARG_DEC, /**< requires a decimal argument */ 58 EXTARG_OPT_DEC /**< may have an optional decimal argument */ 59 60 /* Add new things just above here ---^ 61 * This is part of the ABI, don't needlessly break compatibility */ 62}; 63 64/** struct lws_ext_options - Option arguments to the extension. These are 65 * used in the negotiation at ws upgrade time. 66 * The helper function lws_ext_parse_options() 67 * uses these to generate callbacks */ 68struct lws_ext_options { 69 const char *name; /**< Option name, eg, "server_no_context_takeover" */ 70 enum lws_ext_options_types type; /**< What kind of args the option can take */ 71 72 /* Add new things just above here ---^ 73 * This is part of the ABI, don't needlessly break compatibility */ 74}; 75 76/** struct lws_ext_option_arg */ 77struct lws_ext_option_arg { 78 const char *option_name; /**< may be NULL, option_index used then */ 79 int option_index; /**< argument ordinal to use if option_name missing */ 80 const char *start; /**< value */ 81 int len; /**< length of value */ 82}; 83 84/** 85 * typedef lws_extension_callback_function() - Hooks to allow extensions to operate 86 * \param context: Websockets context 87 * \param ext: This extension 88 * \param wsi: Opaque websocket instance pointer 89 * \param reason: The reason for the call 90 * \param user: Pointer to ptr to per-session user data allocated by library 91 * \param in: Pointer used for some callback reasons 92 * \param len: Length set for some callback reasons 93 * 94 * Each extension that is active on a particular connection receives 95 * callbacks during the connection lifetime to allow the extension to 96 * operate on websocket data and manage itself. 97 * 98 * Libwebsockets takes care of allocating and freeing "user" memory for 99 * each active extension on each connection. That is what is pointed to 100 * by the user parameter. 101 * 102 * LWS_EXT_CB_CONSTRUCT: called when the server has decided to 103 * select this extension from the list provided by the client, 104 * just before the server will send back the handshake accepting 105 * the connection with this extension active. This gives the 106 * extension a chance to initialize its connection context found 107 * in user. 108 * 109 * LWS_EXT_CB_CLIENT_CONSTRUCT: same as LWS_EXT_CB_CONSTRUCT 110 * but called when client is instantiating this extension. Some 111 * extensions will work the same on client and server side and then 112 * you can just merge handlers for both CONSTRUCTS. 113 * 114 * LWS_EXT_CB_DESTROY: called when the connection the extension was 115 * being used on is about to be closed and deallocated. It's the 116 * last chance for the extension to deallocate anything it has 117 * allocated in the user data (pointed to by user) before the 118 * user data is deleted. This same callback is used whether you 119 * are in client or server instantiation context. 120 * 121 * LWS_EXT_CB_PACKET_TX_PRESEND: this works the same way as 122 * LWS_EXT_CB_PACKET_RX_PREPARSE above, except it gives the 123 * extension a chance to change websocket data just before it will 124 * be sent out. Using the same lws_token pointer scheme in in, 125 * the extension can change the buffer and the length to be 126 * transmitted how it likes. Again if it wants to grow the 127 * buffer safely, it should copy the data into its own buffer and 128 * set the lws_tokens token pointer to it. 129 * 130 * LWS_EXT_CB_ARGS_VALIDATE: 131 */ 132typedef int 133lws_extension_callback_function(struct lws_context *context, 134 const struct lws_extension *ext, struct lws *wsi, 135 enum lws_extension_callback_reasons reason, 136 void *user, void *in, size_t len); 137 138/** struct lws_extension - An extension we support */ 139struct lws_extension { 140 const char *name; /**< Formal extension name, eg, "permessage-deflate" */ 141 lws_extension_callback_function *callback; /**< Service callback */ 142 const char *client_offer; /**< String containing exts and options client offers */ 143 144 /* Add new things just above here ---^ 145 * This is part of the ABI, don't needlessly break compatibility */ 146}; 147 148/** 149 * lws_set_extension_option(): set extension option if possible 150 * 151 * \param wsi: websocket connection 152 * \param ext_name: name of ext, like "permessage-deflate" 153 * \param opt_name: name of option, like "rx_buf_size" 154 * \param opt_val: value to set option to 155 */ 156LWS_VISIBLE LWS_EXTERN int 157lws_set_extension_option(struct lws *wsi, const char *ext_name, 158 const char *opt_name, const char *opt_val); 159 160/** 161 * lws_ext_parse_options() - deal with parsing negotiated extension options 162 * 163 * \param ext: related extension struct 164 * \param wsi: websocket connection 165 * \param ext_user: per-connection extension private data 166 * \param opts: list of supported options 167 * \param o: option string to parse 168 * \param len: length 169 */ 170LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 171lws_ext_parse_options(const struct lws_extension *ext, struct lws *wsi, 172 void *ext_user, const struct lws_ext_options *opts, 173 const char *o, int len); 174 175/** lws_extension_callback_pm_deflate() - extension for RFC7692 176 * 177 * \param context: lws context 178 * \param ext: related lws_extension struct 179 * \param wsi: websocket connection 180 * \param reason: incoming callback reason 181 * \param user: per-connection extension private data 182 * \param in: pointer parameter 183 * \param len: length parameter 184 * 185 * Built-in callback implementing RFC7692 permessage-deflate 186 */ 187LWS_EXTERN int 188lws_extension_callback_pm_deflate(struct lws_context *context, 189 const struct lws_extension *ext, 190 struct lws *wsi, 191 enum lws_extension_callback_reasons reason, 192 void *user, void *in, size_t len); 193 194/* 195 * The internal exts are part of the public abi 196 * If we add more extensions, publish the callback here ------v 197 */ 198///@}