was built from
</blockquote>
<hr>
-<h2>libwebsockets_hangup_on_client - Server calls to terminate client connection</h2>
-<i>void</i>
-<b>libwebsockets_hangup_on_client</b>
-(<i>struct libwebsocket_context *</i> <b>context</b>,
-<i>int</i> <b>fd</b>)
-<h3>Arguments</h3>
-<dl>
-<dt><b>context</b>
-<dd>libwebsockets context
-<dt><b>fd</b>
-<dd>Connection socket descriptor
-</dl>
-<hr>
<h2>libwebsockets_get_peer_addresses - Get client address information</h2>
<i>void</i>
<b>libwebsockets_get_peer_addresses</b>
<h3>Description</h3>
<blockquote>
This function takes a pollfd that has POLLIN or POLLOUT activity and
-services it according to the state of the associated struct libwebsocket.
+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.
undefined.
</blockquote>
<hr>
-<h2>libwebsocket_context_user - get the user data associated with the whole context</h2>
+<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>)
<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>struct libwebsocket_extension *</i> <b>extensions</b>,
-<i>const char *</i> <b>ssl_cert_filepath</b>,
-<i>const char *</i> <b>ssl_private_key_filepath</b>,
-<i>const char *</i> <b>ssl_ca_filepath</b>,
-<i>int</i> <b>gid</b>,
-<i>int</i> <b>uid</b>,
-<i>unsigned int</i> <b>options</b>,
-<i>void *</i> <b>user</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>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>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>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
<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>)
+<i>void (*</i><b>log_emit_function</b>) <i>(int level, const char *line)</i>)
<h3>Arguments</h3>
<dl>
<dt><b>level</b>
</dl>
<h3>Description</h3>
<blockquote>
-log level defaults to "err" and "warn" contexts enabled only and
+log level defaults to "err", "warn" and "notice" contexts enabled and
emission on stderr.
</blockquote>
<hr>
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>
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>
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
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
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.
<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>struct libwebsocket_context *</i> <b>owning_server</b>;<br>
<i>int</i> <b>protocol_index</b>;<br>
};<br>
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.
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