mirror of
https://github.com/warmcat/libwebsockets.git
synced 2025-03-09 00:00:04 +01:00
document extension callback reasons
Signed-off-by: Andy Green <andy@warmcat.com>
This commit is contained in:
Andy Green
parent
3b84c006c9
commit
57b4e9af2b
2 changed files with 136 additions and 0 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue