diff --git a/lib/libwebsockets.h b/lib/libwebsockets.h index b759590b..c5ca187c 100644 --- a/lib/libwebsockets.h +++ b/lib/libwebsockets.h @@ -373,6 +373,65 @@ extern int callback(struct libwebsocket_context * context, enum libwebsocket_callback_reasons reason, void *user, void *in, size_t len); +/* document the generic extension callback (it's a fake prototype under this) */ +/** + * extension_callback() - Hooks to allow extensions to operate + * @context: Websockets context + * @wsi: Opaque websocket instance pointer + * @reason: The reason for the call + * @user: Pointer to per-session user data allocated by library + * @in: Pointer used for some callback reasons + * @len: Length 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_CALLBACK_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_CALLBACK_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. + * + * LWS_EXT_CALLBACK_PACKET_RX_PREPARSE: when this extension was active on + * a connection, and a packet of data arrived at the connection, + * it is passed to this callback to give the extension a chance to + * change the data, eg, decompress it. @user is pointing to the + * extension's private connection context data, @in is pointing + * to an lws_tokens struct, it consists of a char * pointer called + * token, and an int called token_len. At entry, these are + * set to point to the received buffer and set to the content + * length. If the extension will grow the content, it should use + * a new buffer allocated in its private user context data and + * set the pointed-to lws_tokens members to point to its buffer. + * + * LWS_EXT_CALLBACK_PACKET_TX_PRESEND: this works the same way as + * LWS_EXT_CALLBACK_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. + */ + +extern int extension_callback(struct libwebsocket_context * context, + struct libwebsocket *wsi, + enum libwebsocket_callback_reasons reason, void *user, + void *in, size_t len); + + /** * struct libwebsocket_protocols - List of protocols and handlers server * supports. diff --git a/libwebsockets-api-doc.html b/libwebsockets-api-doc.html index 0169b580..46933879 100644 --- a/libwebsockets-api-doc.html +++ b/libwebsockets-api-doc.html @@ -711,6 +711,83 @@ pollfd struct for this socket descriptor. If you are using the internal polling loop, you can just ignore it. </blockquote> <hr> +<h2>extension_callback - Hooks to allow extensions to operate</h2> +<i>int</i> +<b>extension_callback</b> +(<i>struct libwebsocket_context *</i> <b>context</b>, +<i>struct libwebsocket *</i> <b>wsi</b>, +<i>enum libwebsocket_callback_reasons</i> <b>reason</b>, +<i>void *</i> <b>user</b>, +<i>void *</i> <b>in</b>, +<i>size_t</i> <b>len</b>) +<h3>Arguments</h3> +<dl> +<dt><b>context</b> +<dd>Websockets context +<dt><b>wsi</b> +<dd>Opaque websocket instance pointer +<dt><b>reason</b> +<dd>The reason for the call +<dt><b>user</b> +<dd>Pointer to per-session user data allocated by library +<dt><b>in</b> +<dd>Pointer used for some callback reasons +<dt><b>len</b> +<dd>Length set for some callback reasons +</dl> +<h3>Description</h3> +<blockquote> +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. +<p> +Libwebsockets takes care of allocating and freeing "user" memory for +each active extension on each connection. That is what is pointed to +by the <tt><b>user</b></tt> parameter. +</blockquote> +<h3>LWS_EXT_CALLBACK_CONSTRUCT</h3> +<blockquote> +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 <tt><b>user</b></tt>. +</blockquote> +<h3>LWS_EXT_CALLBACK_DESTROY</h3> +<blockquote> +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 <tt><b>user</b></tt>) before the +user data is deleted. +</blockquote> +<h3>LWS_EXT_CALLBACK_PACKET_RX_PREPARSE</h3> +<blockquote> +when this extension was active on +a connection, and a packet of data arrived at the connection, +it is passed to this callback to give the extension a chance to +change the data, eg, decompress it. <tt><b>user</b></tt> is pointing to the +extension's private connection context data, <tt><b>in</b></tt> is pointing +to an lws_tokens struct, it consists of a char * pointer called +token, and an int called token_len. At entry, these are +set to point to the received buffer and set to the content +length. If the extension will grow the content, it should use +a new buffer allocated in its private user context data and +set the pointed-to lws_tokens members to point to its buffer. +</blockquote> +<h3>LWS_EXT_CALLBACK_PACKET_TX_PRESEND</h3> +<blockquote> +this works the same way as +LWS_EXT_CALLBACK_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 <tt><b>in</b></tt>, +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. +</blockquote> +<hr> <h2>struct libwebsocket_protocols - List of protocols and handlers server supports.</h2> <b>struct libwebsocket_protocols</b> {<br> <i>const char *</i> <b>name</b>;<br>