document extension callback reasons
Signed-off-by: Andy Green <andy@warmcat.com>
diff --git a/lib/libwebsockets.h b/lib/libwebsockets.h
index b759590..c5ca187 100644
--- a/lib/libwebsockets.h
+++ b/lib/libwebsockets.h
@@ -373,6 +373,65 @@
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 0169b58..4693387 100644
--- a/libwebsockets-api-doc.html
+++ b/libwebsockets-api-doc.html
@@ -711,6 +711,83 @@
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>