-<h2>libwebsockets_hangup_on_client - Server calls to terminate client connection</h2>
-<i>void</i>
-<b>libwebsockets_hangup_on_client</b>
+<h2>libwebsocket_client_connect - Connect to another websocket server</h2>
+<i>struct libwebsocket *</i>
+<b>libwebsocket_client_connect</b>
(<i>struct libwebsocket_context *</i> <b>context</b>,
-<i>int</i> <b>fd</b>)
+<i>const char *</i> <b>address</b>,
+<i>int</i> <b>port</b>,
+<i>int</i> <b>ssl_connection</b>,
+<i>const char *</i> <b>path</b>,
+<i>const char *</i> <b>host</b>,
+<i>const char *</i> <b>origin</b>,
+<i>const char *</i> <b>protocol</b>,
+<i>int</i> <b>ietf_version_or_minus_one</b>)
<h3>Arguments</h3>
<dl>
<dt><b>context</b>
-<dd>libwebsockets context
-<dt><b>fd</b>
-<dd>Connection socket descriptor
+<dd>Websocket context
+<dt><b>address</b>
+<dd>Remote server address, eg, "myserver.com"
+<dt><b>port</b>
+<dd>Port to connect to on the remote server, eg, 80
+<dt><b>ssl_connection</b>
+<dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
+signed certs
+<dt><b>path</b>
+<dd>Websocket path on server
+<dt><b>host</b>
+<dd>Hostname on server
+<dt><b>origin</b>
+<dd>Socket origin name
+<dt><b>protocol</b>
+<dd>Comma-separated list of protocols being asked for from
+the server, or just one. The server will pick the one it
+likes best.
+<dt><b>ietf_version_or_minus_one</b>
+<dd>-1 to ask to connect using the default, latest
+protocol supported, or the specific protocol ordinal
+</dl>
+<h3>Description</h3>
+<blockquote>
+This function creates a connection to a remote server
+</blockquote>
+<hr>
+<h2>libwebsocket_client_connect_extended - Connect to another websocket server</h2>
+<i>struct libwebsocket *</i>
+<b>libwebsocket_client_connect_extended</b>
+(<i>struct libwebsocket_context *</i> <b>context</b>,
+<i>const char *</i> <b>address</b>,
+<i>int</i> <b>port</b>,
+<i>int</i> <b>ssl_connection</b>,
+<i>const char *</i> <b>path</b>,
+<i>const char *</i> <b>host</b>,
+<i>const char *</i> <b>origin</b>,
+<i>const char *</i> <b>protocol</b>,
+<i>int</i> <b>ietf_version_or_minus_one</b>,
+<i>void *</i> <b>userdata</b>)
+<h3>Arguments</h3>
+<dl>
+<dt><b>context</b>
+<dd>Websocket context
+<dt><b>address</b>
+<dd>Remote server address, eg, "myserver.com"
+<dt><b>port</b>
+<dd>Port to connect to on the remote server, eg, 80
+<dt><b>ssl_connection</b>
+<dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
+signed certs
+<dt><b>path</b>
+<dd>Websocket path on server
+<dt><b>host</b>
+<dd>Hostname on server
+<dt><b>origin</b>
+<dd>Socket origin name
+<dt><b>protocol</b>
+<dd>Comma-separated list of protocols being asked for from
+the server, or just one. The server will pick the one it
+likes best.
+<dt><b>ietf_version_or_minus_one</b>
+<dd>-1 to ask to connect using the default, latest
+protocol supported, or the specific protocol ordinal
+<dt><b>userdata</b>
+<dd>Pre-allocated user data
</dl>
+<h3>Description</h3>
+<blockquote>
+This function creates a connection to a remote server
+</blockquote>
+<hr>
+<h2>lws_get_library_version - </h2>
+<i>const char *</i>
+<b>lws_get_library_version</b>
+(<i></i> <b>void</b>)
+<h3>Arguments</h3>
+<dl>
+<dt><b>void</b>
+<dd>no arguments
+</dl>
+<h3>Description</h3>
+<blockquote>
+<p>
+returns a const char * to a string like "1.1 178d78c"
+representing the library version followed by the git head hash it
+was built from
+</blockquote>
<hr>
<h2>libwebsockets_get_peer_addresses - Get client address information</h2>
<i>void</i>
<b>libwebsockets_get_peer_addresses</b>
-(<i>int</i> <b>fd</b>,
+(<i>struct libwebsocket_context *</i> <b>context</b>,
+<i>struct libwebsocket *</i> <b>wsi</b>,
+<i>int</i> <b>fd</b>,
<i>char *</i> <b>name</b>,
<i>int</i> <b>name_len</b>,
<i>char *</i> <b>rip</b>,
<i>int</i> <b>rip_len</b>)
<h3>Arguments</h3>
<dl>
+<dt><b>context</b>
+<dd>Libwebsockets context
+<dt><b>wsi</b>
+<dd>Local struct libwebsocket associated with
<dt><b>fd</b>
<dd>Connection socket descriptor
<dt><b>name</b>
</dl>
<h3>Description</h3>
<blockquote>
-This function closes any active connections and then frees the
-context. After calling this, any further use of the context is
-undefined.
+This function takes a pollfd that has POLLIN or POLLOUT activity and
+services it according to the state of the associated
+struct libwebsocket.
+<p>
+The one call deals with all "service" that might happen on a socket
+including listen accepts, http files as well as websocket protocol.
</blockquote>
<hr>
<h2>libwebsocket_context_destroy - Destroy the websocket context</h2>
undefined.
</blockquote>
<hr>
+<h2>libwebsocket_context_user - get the user data associated with the context</h2>
+<i>LWS_EXTERN void *</i>
+<b>libwebsocket_context_user</b>
+(<i>struct libwebsocket_context *</i> <b>context</b>)
+<h3>Arguments</h3>
+<dl>
+<dt><b>context</b>
+<dd>Websocket context
+</dl>
+<h3>Description</h3>
+<blockquote>
+This returns the optional user allocation that can be attached to
+the context the sockets live in at context_create time. It's a way
+to let all sockets serviced in the same context share data without
+using globals statics in the user code.
+</blockquote>
+<hr>
<h2>libwebsocket_service - Service any pending websocket activity</h2>
<i>int</i>
<b>libwebsocket_service</b>
<p>
1) Accept new connections to our context's server
<p>
-2) Perform pending broadcast writes initiated from other forked
-processes (effectively serializing asynchronous broadcasts)
-<p>
-3) Call the receive callback for incoming frame data received by
+2) Call the receive callback for incoming frame data received by
server or client connections.
<p>
You need to call this service function periodically to all the above
<h2>libwebsocket_create_context - Create the websocket handler</h2>
<i>struct libwebsocket_context *</i>
<b>libwebsocket_create_context</b>
-(<i>int</i> <b>port</b>,
-<i>const char *</i> <b>interf</b>,
-<i>struct libwebsocket_protocols *</i> <b>protocols</b>,
-<i>const char *</i> <b>ssl_cert_filepath</b>,
-<i>const char *</i> <b>ssl_private_key_filepath</b>,
-<i>int</i> <b>gid</b>,
-<i>int</i> <b>uid</b>,
-<i>unsigned int</i> <b>options</b>)
+(<i>struct lws_context_creation_info *</i> <b>info</b>)
<h3>Arguments</h3>
<dl>
-<dt><b>port</b>
-<dd>Port to listen on... you can use 0 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>interf</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>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,
-else ignored
-<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>info</b>
+<dd>pointer to struct with parameters
</dl>
<h3>Description</h3>
<blockquote>
-This function creates the listening socket and takes care
+This function creates the listening socket (if serving) and takes care
of all initialization in one step.
<p>
After initialization, it returns a struct libwebsocket_context * that
one place; they're all handled in the user callback.
</blockquote>
<hr>
-<h2>libwebsockets_fork_service_loop - Optional helper function forks off a process for the websocket server loop. You don't have to use this but if not, you have to make sure you are calling libwebsocket_service periodically to service the websocket traffic</h2>
-<i>int</i>
-<b>libwebsockets_fork_service_loop</b>
-(<i>struct libwebsocket_context *</i> <b>context</b>)
-<h3>Arguments</h3>
-<dl>
-<dt><b>context</b>
-<dd>server context returned by creation function
-</dl>
-<hr>
<h2>libwebsockets_get_protocol - Returns a protocol pointer from a websocket connection.</h2>
<i>const struct libwebsocket_protocols *</i>
<b>libwebsockets_get_protocol</b>
<h3>Description</h3>
<blockquote>
<p>
-This is useful to get the protocol to broadcast back to from inside
-the callback.
+Some apis can act on all live connections of a given protocol,
+this is how you can get a pointer to the active protocol if needed.
</blockquote>
<hr>
-<h2>libwebsockets_broadcast - Sends a buffer to the callback for all active connections of the given protocol.</h2>
-<i>int</i>
-<b>libwebsockets_broadcast</b>
-(<i>const struct libwebsocket_protocols *</i> <b>protocol</b>,
-<i>unsigned char *</i> <b>buf</b>,
-<i>size_t</i> <b>len</b>)
+<h2>lws_set_log_level - Set the logging bitfield</h2>
+<i>void</i>
+<b>lws_set_log_level</b>
+(<i>int</i> <b>level</b>,
+<i>void (*</i><b>log_emit_function</b>) <i>(int level, const char *line)</i>)
<h3>Arguments</h3>
<dl>
-<dt><b>protocol</b>
-<dd>pointer to the protocol you will broadcast to all members of
-<dt><b>buf</b>
-<dd>buffer containing the data to be broadcase. NOTE: this has to be
-allocated with LWS_SEND_BUFFER_PRE_PADDING valid bytes before
-the pointer and LWS_SEND_BUFFER_POST_PADDING afterwards in the
-case you are calling this function from callback context.
-<dt><b>len</b>
-<dd>length of payload data in buf, starting from buf.
+<dt><b>level</b>
+<dd>OR together the LLL_ debug contexts you want output from
+<dt><b>log_emit_function</b>
+<dd>NULL to leave it as it is, or a user-supplied
+function to perform log string emission instead of
+the default stderr one.
</dl>
<h3>Description</h3>
<blockquote>
-This function allows bulk sending of a packet to every connection using
-the given protocol. It does not send the data directly; instead it calls
-the callback with a reason type of LWS_CALLBACK_BROADCAST. If the callback
-wants to actually send the data for that connection, the callback itself
-should call <b>libwebsocket_write</b>.
-<p>
-<b>libwebsockets_broadcast</b> can be called from another fork context without
-having to take any care about data visibility between the processes, it'll
-"just work".
+log level defaults to "err", "warn" and "notice" contexts enabled and
+emission on stderr.
</blockquote>
<hr>
<h2>libwebsocket_write - Apply protocol then write data to client</h2>
valid storage before and after buf as explained above. This scheme
allows maximum efficiency of sending data and protocol in a single
packet while not burdening the user code with any protocol knowledge.
+<p>
+Return may be -1 for a fatal error needing connection close, or a
+positive number reflecting the amount of bytes actually sent. This
+can be less than the requested number of bytes due to OS memory
+pressure at any given time.
</blockquote>
<hr>
<h2>libwebsockets_serve_http_file - Send a file back to the client using http</h2>
<i>int</i>
<b>libwebsockets_serve_http_file</b>
-(<i>struct libwebsocket *</i> <b>wsi</b>,
+(<i>struct libwebsocket_context *</i> <b>context</b>,
+<i>struct libwebsocket *</i> <b>wsi</b>,
<i>const char *</i> <b>file</b>,
<i>const char *</i> <b>content_type</b>)
<h3>Arguments</h3>
<dl>
+<dt><b>context</b>
+<dd>libwebsockets context
<dt><b>wsi</b>
<dd>Websocket instance (available from user callback)
<dt><b>file</b>
This function is intended to be called from the callback in response
to http requests from the client. It allows the callback to issue
local files down the http link in a single step.
+<p>
+Returning <0 indicates error and the wsi should be closed. Returning
+>0 indicates the file was completely sent and the wsi should be closed.
+==0 indicates the file transfer is started and needs more service later,
+the wsi should be left alone.
+</blockquote>
+<hr>
+<h2>lws_frame_is_binary - </h2>
+<i>int</i>
+<b>lws_frame_is_binary</b>
+(<i>struct libwebsocket *</i> <b>wsi</b>)
+<h3>Arguments</h3>
+<dl>
+<dt><b>wsi</b>
+<dd>the connection we are inquiring about
+</dl>
+<h3>Description</h3>
+<blockquote>
+This is intended to be called from the LWS_CALLBACK_RECEIVE callback if
+it's interested to see if the frame it's dealing with was sent in binary
+mode.
</blockquote>
<hr>
<h2>libwebsockets_remaining_packet_payload - Bytes to come before "overall" rx packet is complete</h2>
Many protocols won't care becuse their packets are always small.
</blockquote>
<hr>
-<h2>libwebsocket_client_connect - Connect to another websocket server</h2>
-<i>struct libwebsocket *</i>
-<b>libwebsocket_client_connect</b>
-(<i>struct libwebsocket_context *</i> <b>context</b>,
-<i>const char *</i> <b>address</b>,
-<i>int</i> <b>port</b>,
-<i>int</i> <b>ssl_connection</b>,
-<i>const char *</i> <b>path</b>,
-<i>const char *</i> <b>host</b>,
-<i>const char *</i> <b>origin</b>,
-<i>const char *</i> <b>protocol</b>,
-<i>int</i> <b>ietf_version_or_minus_one</b>)
-<h3>Arguments</h3>
-<dl>
-<dt><b>context</b>
-<dd>Websocket context
-<dt><b>address</b>
-<dd>Remote server address, eg, "myserver.com"
-<dt><b>port</b>
-<dd>Port to connect to on the remote server, eg, 80
-<dt><b>ssl_connection</b>
-<dd>0 = ws://, 1 = wss:// encrypted, 2 = wss:// allow self
-signed certs
-<dt><b>path</b>
-<dd>Websocket path on server
-<dt><b>host</b>
-<dd>Hostname on server
-<dt><b>origin</b>
-<dd>Socket origin name
-<dt><b>protocol</b>
-<dd>Comma-separated list of protocols being asked for from
-the server, or just one. The server will pick the one it
-likes best.
-<dt><b>ietf_version_or_minus_one</b>
-<dd>-1 to ask to connect using the default, latest
-protocol supported, or the specific protocol ordinal
-</dl>
-<h3>Description</h3>
-<blockquote>
-This function creates a connection to a remote server
-</blockquote>
-<hr>
<h2>callback - User server actions</h2>
-<i>int</i>
+<i>LWS_EXTERN int</i>
<b>callback</b>
(<i>struct libwebsocket_context *</i> <b>context</b>,
<i>struct libwebsocket *</i> <b>wsi</b>,
after the server completes a handshake with
an incoming client
</blockquote>
+<h3>LWS_CALLBACK_CLIENT_CONNECTION_ERROR</h3>
+<blockquote>
+the request client connection has
+been unable to complete a handshake with the remote server
+</blockquote>
+<h3>LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH</h3>
+<blockquote>
+this is the last chance for the
+client user code to examine the http headers
+and decide to reject the connection. If the
+content in the headers is interesting to the
+client (url, etc) it needs to copy it out at
+this point since it will be destroyed before
+the CLIENT_ESTABLISHED call
+</blockquote>
<h3>LWS_CALLBACK_CLIENT_ESTABLISHED</h3>
<blockquote>
after your client connection completed
<blockquote>
when the websocket session ends
</blockquote>
-<h3>LWS_CALLBACK_BROADCAST</h3>
-<blockquote>
-signal to send to client (you would use
-<b>libwebsocket_write</b> taking care about the
-special buffer requirements
-</blockquote>
<h3>LWS_CALLBACK_RECEIVE</h3>
<blockquote>
data has appeared for this server endpoint from a
<tt><b>in</b></tt> points to the URI path requested and
<b>libwebsockets_serve_http_file</b> makes it very
simple to send back a file to the client.
+Normally after sending the file you are done
+with the http connection, since the rest of the
+activity will come by websockets from the script
+that was delivered by http, so you will want to
+return 1; to close and free up the connection.
+That's important because it uses a slot in the
+total number of client connections allowed set
+by MAX_CLIENTS.
+</blockquote>
+<h3>LWS_CALLBACK_HTTP_WRITEABLE</h3>
+<blockquote>
+you can write more down the http protocol
+link now.
+</blockquote>
+<h3>LWS_CALLBACK_HTTP_FILE_COMPLETION</h3>
+<blockquote>
+a file requested to be send down
+http link has completed.
</blockquote>
-<h3>LWS_CALLBACK_CLIENT_WRITEABLE</h3>
+<h3>LWS_CALLBACK_SERVER_WRITEABLE</h3>
<blockquote>
-if you call
+If you call
<b>libwebsocket_callback_on_writable</b> on a connection, you will
-get this callback coming when the connection socket is able to
-accept another write packet without blocking. If it already
-was able to take another packet without blocking, you'll get
-this callback at the next call to the service loop function.
+get one of these callbacks coming when the connection socket
+is able to accept another write packet without blocking.
+If it already was able to take another packet without blocking,
+you'll get this callback at the next call to the service loop
+function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
+and servers get LWS_CALLBACK_SERVER_WRITEABLE.
</blockquote>
<h3>LWS_CALLBACK_FILTER_NETWORK_CONNECTION</h3>
<blockquote>
called when a client connects to
the server at network level; the connection is accepted but then
passed to this callback to decide whether to hang up immediately
-or not, based on the client IP. <tt><b>user</b></tt> contains the connection
+or not, based on the client IP. <tt><b>in</b></tt> contains the connection
socket's descriptor. Return non-zero to terminate
the connection before sending or receiving anything.
Because this happens immediately after the network connection
<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.
<p>
The next four reasons are optional and only need taking care of if you
will be integrating libwebsockets sockets into an external polling
</blockquote>
<h3>added to the polling loop</h3>
<blockquote>
-<tt><b>user</b></tt> contains the fd, and
+<tt><b>in</b></tt> contains the fd, and
<tt><b>len</b></tt> is the events bitmap (like, POLLIN). If you are using the
internal polling loop (the "service" callback), you can just
ignore these callbacks.
<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>user</b></tt> is
+needs to be removed from an external polling array. <tt><b>in</b></tt> is
the socket desricptor. If you are using the internal polling
loop, you can just ignore it.
</blockquote>
<h3>LWS_CALLBACK_SET_MODE_POLL_FD</h3>
<blockquote>
This callback happens when libwebsockets
-wants to modify the events for the socket descriptor in <tt><b>user</b></tt>.
+wants to modify the events for the socket descriptor in <tt><b>in</b></tt>.
The handler should OR <tt><b>len</b></tt> on to the events member of the pollfd
struct for this socket descriptor. If you are using the
internal polling loop, you can just ignore it.
<h3>LWS_CALLBACK_CLEAR_MODE_POLL_FD</h3>
<blockquote>
This callback occurs when libwebsockets
-wants to modify the events for the socket descriptor in <tt><b>user</b></tt>.
+wants to modify the events for the socket descriptor in <tt><b>in</b></tt>.
The handler should AND ~<tt><b>len</b></tt> on to the events member of the
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>LWS_EXTERN int</i>
+<b>extension_callback</b>
+(<i>struct libwebsocket_context *</i> <b>context</b>,
+<i>struct libwebsocket_extension *</i> <b>ext</b>,
+<i>struct libwebsocket *</i> <b>wsi</b>,
+<i>enum libwebsocket_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
+<dt><b>ext</b>
+<dd>This extension
+<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.
+</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>
- <i>int (*</i><b>callback</b>) <i>(struct libwebsocket_context * context,struct libwebsocket *wsi,enum libwebsocket_callback_reasons reason, void *user,void *in, size_t len)</i>;<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>struct libwebsocket_context *</i> <b>owning_server</b>;<br>
- <i>int</i> <b>broadcast_socket_port</b>;<br>
- <i>int</i> <b>broadcast_socket_user_fd</b>;<br>
<i>int</i> <b>protocol_index</b>;<br>
};<br>
<h3>Members</h3>
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>libwebsockets_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>owning_server</b>
<dd>the server init call fills in this opaque pointer when
registering this protocol with the server.
-<dt><b>broadcast_socket_port</b>
-<dd>the server init call fills this in with the
-localhost port number used to forward broadcasts for this
-protocol
-<dt><b>broadcast_socket_user_fd</b>
-<dd>the server init call fills this in ... the <b>main</b>
-process context can write to this socket to perform broadcasts
-(use the <b>libwebsockets_broadcast</b> api to do this instead,
-it works from any process context)
<dt><b>protocol_index</b>
<dd>which protocol we are starting from zero
</dl>
allows as many protocols as you like to be handled by one server.
</blockquote>
<hr>
+<h2>struct libwebsocket_extension - An extension we know how to cope with</h2>
+<b>struct libwebsocket_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
+</dl>
+<hr>
+<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>struct libwebsocket_protocols *</i> <b>protocols</b>;<br>
+ <i>struct libwebsocket_extension *</i> <b>extensions</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>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>
+};<br>
+<h3>Members</h3>
+<dl>
+<dt><b>port</b>
+<dd>Port to listen on... you can use 0 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 libwebsocket_extension structs listing the
+extensions this context supports. If you configured with
+--without-extensions, you should give NULL here.
+<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,
+else ignored
+<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>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 libwebsocket_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
+</dl>
+<hr>
projects / profile / ivi / libwebsockets.git / blobdiff