Newer
Older
optional, if you don't handle it everything is fine.
<p>
Notice the callback is coming to protocols[0] all the time,
because there is no specific protocol handshook yet.
</blockquote>
<h3>LWS_CALLBACK_CONFIRM_EXTENSION_OKAY</h3>
<blockquote>
When the server handshake code
sees that it does support a requested extension, before
accepting the extension by additing to the list sent back to
the client it gives this callback just to check that it's okay
to use that extension. It calls back to the requested protocol
and with <tt><b>in</b></tt> being the extension name, <tt><b>len</b></tt> is 0 and <tt><b>user</b></tt> is
valid. Note though at this time the ESTABLISHED callback hasn't
happened yet so if you initialize <tt><b>user</b></tt> content there, <tt><b>user</b></tt>
content during this callback might not be useful for anything.
Notice this callback comes to protocols[0].
</blockquote>
<h3>LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED</h3>
<blockquote>
When a client
connection is being prepared to start a handshake to a server,
each supported extension is checked with protocols[0] callback
with this reason, giving the user code a chance to suppress the
claim to support that extension by returning non-zero. If
unhandled, by default 0 will be returned and the extension
support included in the header to the server. Notice this
callback comes to protocols[0].
</blockquote>
<h3>LWS_CALLBACK_PROTOCOL_INIT</h3>
<blockquote>
One-time call per protocol so it can
do initial setup / allocations etc
</blockquote>
<h3>LWS_CALLBACK_PROTOCOL_DESTROY</h3>
<blockquote>
One-time call per protocol indicating
this protocol won't get used at all after this callback, the
context is getting destroyed. Take the opportunity to
deallocate everything that was allocated by the protocol.
</blockquote>
<h3>LWS_CALLBACK_WSI_CREATE</h3>
<blockquote>
outermost (earliest) wsi create notification
</blockquote>
<h3>LWS_CALLBACK_WSI_DESTROY</h3>
<blockquote>
outermost (latest) wsi destroy notification
The next five reasons are optional and only need taking care of if you
will be integrating libwebsockets sockets into an external polling
array.
<p>
For these calls, <tt><b>in</b></tt> points to a struct lws_pollargs that
contains <tt><b>fd</b></tt>, <tt><b>events</b></tt> and <tt><b>prev_events</b></tt> members
</blockquote>
<h3>LWS_CALLBACK_ADD_POLL_FD</h3>
<blockquote>
libwebsocket deals with its <b>poll</b> loop
internally, but in the case you are integrating with another
server you will need to have libwebsocket sockets share a
polling array with the other server. This and the other
POLL_FD related callbacks let you put your specialized
poll array interface code in the callback for protocol 0, the
first protocol you support, usually the HTTP protocol in the
serving case.
This callback happens when a socket needs to be
</blockquote>
<h3>added to the polling loop</h3>
<blockquote>
<tt><b>in</b></tt> points to a struct
lws_pollargs; the <tt><b>fd</b></tt> member of the struct is the file
descriptor, and <tt><b>events</b></tt> contains the active events.
<p>
If you are using the internal polling loop (the "service"
callback), you can just ignore these callbacks.
</blockquote>
<h3>LWS_CALLBACK_DEL_POLL_FD</h3>
<blockquote>
This callback happens when a socket descriptor
needs to be removed from an external polling array. <tt><b>in</b></tt> is
again the struct lws_pollargs containing the <tt><b>fd</b></tt> member
to be removed. If you are using the internal polling
loop, you can just ignore it.
</blockquote>
<h3>LWS_CALLBACK_CHANGE_MODE_POLL_FD</h3>
This callback happens when
libwebsockets wants to modify the events for a connectiion.
<tt><b>in</b></tt> is the struct lws_pollargs with the <tt><b>fd</b></tt> to change.
The new event mask is in <tt><b>events</b></tt> member and the old mask is in
the <tt><b>prev_events</b></tt> member.
If you are using the internal polling loop, you can just ignore
it.
<h3>LWS_CALLBACK_UNLOCK_POLL</h3>
These allow the external poll changes driven
by libwebsockets to participate in an external thread locking
scheme around the changes, so the whole thing is threadsafe.
These are called around three activities in the library,
- inserting a new wsi in the wsi / fd table (len=1)
- deleting a wsi from the wsi / fd table (len=1)
- changing a wsi's POLLIN/OUT state (len=0)
Locking and unlocking external synchronization objects when
len == 1 allows external threads to be synchronized against
wsi lifecycle changes if it acquires the same lock for the
duration of wsi dereference from the other thread context.
<h2>extension_callback - Hooks to allow extensions to operate</h2>
(<i>struct lws_context *</i> <b>context</b>,
<i>struct lws *</i> <b>wsi</b>,
<i>enum lws_extension_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
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
<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_CLIENT_CONSTRUCT</h3>
<blockquote>
same as LWS_EXT_CALLBACK_CONSTRUCT
but called when client is instantiating this extension. Some
extensions will work the same on client and server side and then
you can just merge handlers for both CONSTRUCTS.
</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. This same callback is used whether you
are in client or server instantiation context.
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
</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 lws_protocols - List of protocols and handlers server supports.</h2>
<b>struct lws_protocols</b> {<br>
<i>const char *</i> <b>name</b>;<br>
<i>callback_function *</i> <b>callback</b>;<br>
<i>size_t</i> <b>per_session_data_size</b>;<br>
<i>size_t</i> <b>rx_buffer_size</b>;<br>
<i>unsigned int</i> <b>id</b>;<br>
<i>void *</i> <b>user</b>;<br>
};<br>
<h3>Members</h3>
<dl>
<dt><b>name</b>
<dd>Protocol name that must match the one given in the client
Javascript new WebSocket(url, 'protocol') name.
<dt><b>callback</b>
<dd>The service callback used for this protocol. It allows the
service action for an entire protocol to be encapsulated in
the protocol-specific callback
<dt><b>per_session_data_size</b>
<dd>Each new connection using this protocol gets
this much memory allocated on connection establishment and
freed on connection takedown. A pointer to this per-connection
allocation is passed into the callback in the 'user' parameter
<dt><b>rx_buffer_size</b>
<dd>if you want atomic frames delivered to the callback, you
should set this to the size of the biggest legal frame that
you support. If the frame size is exceeded, there is no
error, but the buffer will spill to the user callback when
full, which you can detect by using
<b>lws_remaining_packet_payload</b>. Notice that you
just talk about frame size here, the LWS_SEND_BUFFER_PRE_PADDING
and post-padding are automatically also allocated on top.
<dt><b>id</b>
<dd>ignored by lws, but useful to contain user information bound
to the selected protocol. For example if this protocol was
called "myprotocol-v2", you might set id to 2, and the user
code that acts differently according to the version can do so by
switch (wsi->protocol->id), user code might use some bits as
capability flags based on selected protocol version, etc.
<dt><b>user</b>
<dd>User provided context data at the protocol level.
Accessible via lws_get_protocol(wsi)->user
This should not be confused with wsi->user, it is not the same.
The library completely ignores any value in here.
</dl>
<h3>Description</h3>
<blockquote>
This structure represents one protocol supported by the server. An
array of these structures is passed to <b>lws_create_server</b>
allows as many protocols as you like to be handled by one server.
<p>
The first protocol given has its callback used for user callbacks when
there is no agreed protocol name, that's true during HTTP part of the
</blockquote>
<h3>connection and true if the client did not send a Protocol</h3>
<blockquote>
header.
<h2>struct lws_extension - An extension we know how to cope with</h2>
<b>struct lws_extension</b> {<br>
<i>const char *</i> <b>name</b>;<br>
<i>extension_callback_function *</i> <b>callback</b>;<br>
<i>size_t</i> <b>per_session_data_size</b>;<br>
<i>void *</i> <b>per_context_private_data</b>;<br>
};<br>
<h3>Members</h3>
<dl>
<dt><b>name</b>
<dd>Formal extension name, eg, "deflate-stream"
<dt><b>callback</b>
<dd>Service callback
<dt><b>per_session_data_size</b>
<dd>Libwebsockets will auto-malloc this much
memory for the use of the extension, a pointer
to it comes in the <tt><b>user</b></tt> callback parameter
<dt><b>per_context_private_data</b>
<dd>Optional storage for this extension that
is per-context, so it can track stuff across
all sessions, etc, if it wants
<h2>struct lws_context_creation_info - </h2>
<b>struct lws_context_creation_info</b> {<br>
<i>int</i> <b>port</b>;<br>
<i>const char *</i> <b>iface</b>;<br>
<i>const struct lws_protocols *</i> <b>protocols</b>;<br>
<i>const struct lws_extension *</i> <b>extensions</b>;<br>
<i>const struct lws_token_limits *</i> <b>token_limits</b>;<br>
<i>const char *</i> <b>ssl_cert_filepath</b>;<br>
<i>const char *</i> <b>ssl_private_key_filepath</b>;<br>
<i>const char *</i> <b>ssl_ca_filepath</b>;<br>
<i>const char *</i> <b>ssl_cipher_list</b>;<br>
<i>const char *</i> <b>http_proxy_address</b>;<br>
<i>unsigned int</i> <b>http_proxy_port</b>;<br>
<i>int</i> <b>gid</b>;<br>
<i>int</i> <b>uid</b>;<br>
<i>unsigned int</i> <b>options</b>;<br>
<i>void *</i> <b>user</b>;<br>
<i>int</i> <b>ka_time</b>;<br>
<i>int</i> <b>ka_probes</b>;<br>
<i>int</i> <b>ka_interval</b>;<br>
#ifdef LWS_OPENSSL_SUPPORT<br>
<i>void *</i> <b>provided_client_ssl_ctx</b>;<br>
#else<br>
<i>void *</i> <b>provided_client_ssl_ctx</b>;<br>
#endif<br>
};<br>
<h3>Members</h3>
<dl>
<dt><b>port</b>
<dd>Port to listen on... you can use CONTEXT_PORT_NO_LISTEN to
suppress listening on any port, that's what you want if you are
not running a websocket server at all but just using it as a
client
<dt><b>iface</b>
<dd>NULL to bind the listen socket to all interfaces, or the
interface name, eg, "eth2"
<dt><b>protocols</b>
<dd>Array of structures listing supported protocols and a protocol-
specific callback for each one. The list is ended with an
entry that has a NULL callback pointer.
It's not const because we write the owning_server member
<dt><b>extensions</b>
<dd>NULL or array of lws_extension structs listing the
extensions this context supports. If you configured with
--without-extensions, you should give NULL here.
<dt><b>token_limits</b>
<dd>NULL or struct lws_token_limits pointer which is initialized
<dt><b>ssl_cert_filepath</b>
<dd>If libwebsockets was compiled to use ssl, and you want
to listen using SSL, set to the filepath to fetch the
server cert from, otherwise NULL for unencrypted
<dt><b>ssl_private_key_filepath</b>
<dd>filepath to private key if wanting SSL mode;
if this is set to NULL but sll_cert_filepath is set, the
OPENSSL_CONTEXT_REQUIRES_PRIVATE_KEY callback is called to allow
setting of the private key directly via openSSL library calls
<dt><b>ssl_ca_filepath</b>
<dd>CA certificate filepath or NULL
<dt><b>ssl_cipher_list</b>
<dd>List of valid ciphers to use (eg,
"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
or you can leave it as NULL to get "DEFAULT"
<dt><b>http_proxy_address</b>
<dd>If non-NULL, attempts to proxy via the given address.
If proxy auth is required, use format
"username:password<tt><b>server</b></tt>:port"
<dt><b>http_proxy_port</b>
<dd>If http_proxy_address was non-NULL, uses this port at the address
<dt><b>gid</b>
<dd>group id to change to after setting listen socket, or -1.
<dt><b>uid</b>
<dd>user id to change to after setting listen socket, or -1.
<dt><b>options</b>
<dd>0, or LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK
<dt><b>user</b>
<dd>optional user pointer that can be recovered via the context
pointer using lws_context_user
<dt><b>ka_time</b>
<dd>0 for no keepalive, otherwise apply this keepalive timeout to
all libwebsocket sockets, client or server
<dt><b>ka_probes</b>
<dd>if ka_time was nonzero, after the timeout expires how many
times to try to get a response from the peer before giving up
and killing the connection
<dt><b>ka_interval</b>
<dd>if ka_time was nonzero, how long to wait before each ka_probes
attempt
<dt><b>provided_client_ssl_ctx</b>
<dd>If non-null, swap out libwebsockets ssl
implementation for the one provided by provided_ssl_ctx.
Libwebsockets no longer is responsible for freeing the context
if this option is selected.
<dt><b>provided_client_ssl_ctx</b>
<dd>If non-null, swap out libwebsockets ssl
implementation for the one provided by provided_ssl_ctx.
Libwebsockets no longer is responsible for freeing the context
if this option is selected.