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 (file)
--- 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 0169b58..4693387 100644 (file)
--- 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>
 &nbsp; &nbsp; <i>const char *</i> <b>name</b>;<br>