document extension callback reasons

Signed-off-by: Andy Green <andy@warmcat.com>

1 files changed, 77 insertions, 0 deletions

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 @@ 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>