From cad115bf6b36417331aa7890f967577ccd6e584b Mon Sep 17 00:00:00 2001 From: Andy Green Date: Thu, 7 Sep 2017 09:29:09 +0800 Subject: [PATCH] docs: add mising CALLBACK docs and some extra info https://github.com/warmcat/libwebsockets/issues/1015 --- README.coding.md | 27 ++++++++++++ lib/libwebsockets.h | 101 ++++++++++++++++++++++++++++++++++++-------- 2 files changed, 110 insertions(+), 18 deletions(-) diff --git a/README.coding.md b/README.coding.md index 7cc55e21..97ecc739 100644 --- a/README.coding.md +++ b/README.coding.md @@ -1,6 +1,24 @@ Notes about coding with lws =========================== +@section era Old lws and lws v2.0 + +Originally lws only supported the "manual" method of handling everything in the +user callback found in test-server.c. + +Since v2.0, the need for most or all of this manual boilerplate has been eliminated: +the protocols[0] http stuff is provided by a lib export `lws_callback_http_dummy()`. +You can serve parts of your filesystem at part of the URL space using mounts. + +It's much preferred to use the "automated" v2.0 type scheme, because it's less +code and it's easier to support. + +You can see an example of the new way in test-server-v2.0.c. + +If you just need generic serving capability, consider not writing any server code +and instead use lwsws and writing your user code in a standalone plugin. The +server is configured for mounts etc using JSON, see README.lwsws.md. + @section dae Daemonization There's a helper api `lws_daemonize` built by default that does everything you @@ -902,6 +920,15 @@ This allocation is only deleted / replaced when the connection accesses a URL region with a different protocol (or the default protocols[0] if no CALLBACK area matches it). +This "binding connection to a protocol" lifecycle in managed by +`LWS_CALLBACK_HTTP_BIND_PROTOCOL` and `LWS_CALLBACK_HTTP_DROP_PROTOCOL`. +Because of HTTP/1.1 connection pipelining, one connection may perform +many transactions, each of which may map to different URLs and need +binding to different protocols. So these messages are used to +create the binding of the wsi to your protocol including any +allocations, and to destroy the binding, at which point you should +destroy any related allocations. + @section BINDTODEV SO_BIND_TO_DEVICE The .bind_iface flag in the context / vhost creation struct lets you diff --git a/lib/libwebsockets.h b/lib/libwebsockets.h index 125db9e6..9b7b33d5 100644 --- a/lib/libwebsockets.h +++ b/lib/libwebsockets.h @@ -1188,45 +1188,110 @@ enum lws_callback_reasons { * connection. */ LWS_CALLBACK_WS_EXT_DEFAULTS = 39, - /**< */ + /**< Gives client connections an opportunity to adjust negotiated + * extension defaults. `user` is the extension name that was + * negotiated (eg, "permessage-deflate"). `in` points to a + * buffer and `len` is the buffer size. The user callback can + * set the buffer to a string describing options the extension + * should parse. Or just ignore for defaults. */ LWS_CALLBACK_CGI = 40, - /**< */ + /**< CGI: CGI IO events on stdin / out / err are sent here on + * protocols[0]. The provided `lws_callback_http_dummy()` + * handles this and the callback should be directed there if + * you use CGI. */ LWS_CALLBACK_CGI_TERMINATED = 41, - /**< */ + /**< CGI: The related CGI process ended, this is called before + * the wsi is closed. Used to, eg, terminate chunking. + * The provided `lws_callback_http_dummy()` + * handles this and the callback should be directed there if + * you use CGI. */ LWS_CALLBACK_CGI_STDIN_DATA = 42, - /**< */ + /**< CGI: Data is, to be sent to the CGI process stdin, eg from + * a POST body. The provided `lws_callback_http_dummy()` + * handles this and the callback should be directed there if + * you use CGI. */ LWS_CALLBACK_CGI_STDIN_COMPLETED = 43, - /**< */ + /**< CGI: no more stdin is coming. The provided + * `lws_callback_http_dummy()` handles this and the callback + * should be directed there if you use CGI. */ LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP = 44, - /**< */ + /**< The HTTP client connection has succeeded, and is now + * connected to the server */ LWS_CALLBACK_CLOSED_CLIENT_HTTP = 45, - /**< */ + /**< The HTTP client connection is closing */ LWS_CALLBACK_RECEIVE_CLIENT_HTTP = 46, - /**< */ + /**< This simply indicates data was received on the HTTP client + * connection. It does NOT drain or provide the data. + * This exists to neatly allow a proxying type situation, + * where this incoming data will go out on another connection. + * If the outgoing connection stalls, we should stall processing + * the incoming data. So a handler for this in that case should + * simply set a flag to indicate there is incoming data ready + * and ask for a writeable callback on the outgoing connection. + * In the writable callback he can check the flag and then get + * and drain the waiting incoming data using lws_http_client_read(). + * This will use callbacks to LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ + * to get and drain the incoming data, where it should be sent + * back out on the outgoing connection. */ LWS_CALLBACK_COMPLETED_CLIENT_HTTP = 47, - /**< */ + /**< The client transaction completed... at the moment this + * is the same as closing since transaction pipelining on + * client side is not yet supported. */ LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ = 48, - /**< */ + /**< This is generated by lws_http_client_read() used to drain + * incoming data. In the case the incoming data was chunked, + * it will be split into multiple smaller callbacks for each + * chunk block, removing the chunk headers. If not chunked, + * it will appear all in one callback. */ LWS_CALLBACK_HTTP_BIND_PROTOCOL = 49, - /**< */ + /**< By default, all HTTP handling is done in protocols[0]. + * However you can bind different protocols (by name) to + * different parts of the URL space using callback mounts. This + * callback occurs in the new protocol when a wsi is bound + * to that protocol. Any protocol allocation related to the + * http transaction processing should be created then. + * These specific callbacks are necessary because with HTTP/1.1, + * a single connection may perform at series of different + * transactions at different URLs, thus the lifetime of the + * protocol bind is just for one transaction, not connection. */ LWS_CALLBACK_HTTP_DROP_PROTOCOL = 50, - /**< */ + /**< This is called when a transaction is unbound from a protocol. + * It indicates the connection completed its transaction and may + * do something different now. Any protocol allocation related + * to the http transaction processing should be destroyed. */ LWS_CALLBACK_CHECK_ACCESS_RIGHTS = 51, - /**< */ + /**< This gives the user code a chance to forbid an http access. + * `in` points to a `struct lws_process_html_args`, which + * describes the URL, and a bit mask describing the type of + * authentication required. If the callback returns nonzero, + * the transaction ends with HTTP_STATUS_UNAUTHORIZED. */ LWS_CALLBACK_PROCESS_HTML = 52, - /**< */ + /**< This gives your user code a chance to mangle outgoing + * HTML. `in` points to a `struct lws_process_html_args` + * which describes the buffer containing outgoing HTML. + * The buffer may grow up to `.max_len` (currently +128 + * bytes per buffer). + * */ LWS_CALLBACK_ADD_HEADERS = 53, - /**< */ + /**< This gives your user code a chance to add headers to a + * transaction bound to your protocol. `in` points to a + * `struct lws_process_html_args` you can add headers into + * using the normal lws apis. See generic sessions for an + * example of how to use with cookies. */ LWS_CALLBACK_SESSION_INFO = 54, - /**< */ + /**< This is only generated by user code using generic sessions. + * It's used to get a `struct lws_session_info` filled in by + * generic sessions with information about the logged-in user. + * See the messageboard sample for an example of how to use. */ LWS_CALLBACK_GS_EVENT = 55, - /**< */ + /**< Indicates an event happened to the Generic Sessions session. + * `in` contains a `struct lws_gs_event_args` describing the event. */ LWS_CALLBACK_HTTP_PMO = 56, /**< per-mount options for this connection, called before * the normal LWS_CALLBACK_HTTP when the mount has per-mount - * options + * options. */ LWS_CALLBACK_CLIENT_HTTP_WRITEABLE = 57, /**< when doing an HTTP type client connection, you can call