1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25/*! \defgroup usercb User Callback
26 *
27 * ##User protocol callback
28 *
29 * The protocol callback is the primary way lws interacts with
30 * user code. For one of a list of a few dozen reasons the callback gets
31 * called at some event to be handled.
32 *
33 * All of the events can be ignored, returning 0 is taken as "OK" and returning
34 * nonzero in most cases indicates that the connection should be closed.
35 */
36///@{
37
38struct lws_ssl_info {
39 int where;
40 int ret;
41};
42
43enum lws_cert_update_state {
44 LWS_CUS_IDLE,
45 LWS_CUS_STARTING,
46 LWS_CUS_SUCCESS,
47 LWS_CUS_FAILED,
48
49 LWS_CUS_CREATE_KEYS,
50 LWS_CUS_REG,
51 LWS_CUS_AUTH,
52 LWS_CUS_CHALLENGE,
53 LWS_CUS_CREATE_REQ,
54 LWS_CUS_REQ,
55 LWS_CUS_CONFIRM,
56 LWS_CUS_ISSUE,
57};
58
59enum {
60 LWS_TLS_REQ_ELEMENT_COUNTRY,
61 LWS_TLS_REQ_ELEMENT_STATE,
62 LWS_TLS_REQ_ELEMENT_LOCALITY,
63 LWS_TLS_REQ_ELEMENT_ORGANIZATION,
64 LWS_TLS_REQ_ELEMENT_COMMON_NAME,
65 LWS_TLS_REQ_ELEMENT_SUBJECT_ALT_NAME,
66 LWS_TLS_REQ_ELEMENT_EMAIL,
67
68 LWS_TLS_REQ_ELEMENT_COUNT,
69
70 LWS_TLS_SET_DIR_URL = LWS_TLS_REQ_ELEMENT_COUNT,
71 LWS_TLS_SET_AUTH_PATH,
72 LWS_TLS_SET_CERT_PATH,
73 LWS_TLS_SET_KEY_PATH,
74
75 LWS_TLS_TOTAL_COUNT
76};
77
78struct lws_acme_cert_aging_args {
79 struct lws_vhost *vh;
80 const char *element_overrides[LWS_TLS_TOTAL_COUNT]; /* NULL = use pvo */
81};
82
83/*
84 * With LWS_CALLBACK_FILTER_NETWORK_CONNECTION callback, user_data pointer
85 * points to one of these
86 */
87
88struct lws_filter_network_conn_args {
89 struct sockaddr_storage cli_addr;
90 socklen_t clilen;
91 lws_sockfd_type accept_fd;
92};
93
94/*
95 * NOTE: These public enums are part of the abi. If you want to add one,
96 * add it at where specified so existing users are unaffected.
97 */
98/** enum lws_callback_reasons - reason you're getting a protocol callback */
99enum lws_callback_reasons {
100
101 /* ---------------------------------------------------------------------
102 * ----- Callbacks related to wsi and protocol binding lifecycle -----
103 */
104
105 LWS_CALLBACK_PROTOCOL_INIT = 27,
106 /**< One-time call per protocol, per-vhost using it, so it can
107 * do initial setup / allocations etc */
108
109 LWS_CALLBACK_PROTOCOL_DESTROY = 28,
110 /**< One-time call per protocol, per-vhost using it, indicating
111 * this protocol won't get used at all after this callback, the
112 * vhost is getting destroyed. Take the opportunity to
113 * deallocate everything that was allocated by the protocol. */
114
115 LWS_CALLBACK_WSI_CREATE = 29,
116 /**< outermost (earliest) wsi create notification to protocols[0] */
117
118 LWS_CALLBACK_WSI_DESTROY = 30,
119 /**< outermost (latest) wsi destroy notification to protocols[0] */
120
121 LWS_CALLBACK_WSI_TX_CREDIT_GET = 103,
122 /**< manually-managed connection received TX credit (len is int32) */
123
124
125 /* ---------------------------------------------------------------------
126 * ----- Callbacks related to Server TLS -----
127 */
128
129 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS = 21,
130 /**< if configured for
131 * including OpenSSL support, this callback allows your user code
132 * to perform extra SSL_CTX_load_verify_locations() or similar
133 * calls to direct OpenSSL where to find certificates the client
134 * can use to confirm the remote server identity. user is the
135 * OpenSSL SSL_CTX* */
136
137 LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS = 22,
138 /**< if configured for
139 * including OpenSSL support, this callback allows your user code
140 * to load extra certificates into the server which allow it to
141 * verify the validity of certificates returned by clients. user
142 * is the server's OpenSSL SSL_CTX* and in is the lws_vhost */
143
144 LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION = 23,
145 /**< if the libwebsockets vhost was created with the option
146 * LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
147 * callback is generated during OpenSSL verification of the cert
148 * sent from the client. It is sent to protocol[0] callback as
149 * no protocol has been negotiated on the connection yet.
150 * Notice that the libwebsockets context and wsi are both NULL
151 * during this callback. See
152 * http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
153 * to understand more detail about the OpenSSL callback that
154 * generates this libwebsockets callback and the meanings of the
155 * arguments passed. In this callback, user is the x509_ctx,
156 * in is the ssl pointer and len is preverify_ok
157 * Notice that this callback maintains libwebsocket return
158 * conventions, return 0 to mean the cert is OK or 1 to fail it.
159 * This also means that if you don't handle this callback then
160 * the default callback action of returning 0 allows the client
161 * certificates. */
162
163 LWS_CALLBACK_SSL_INFO = 67,
164 /**< SSL connections only. An event you registered an
165 * interest in at the vhost has occurred on a connection
166 * using the vhost. in is a pointer to a
167 * struct lws_ssl_info containing information about the
168 * event*/
169
170 /* ---------------------------------------------------------------------
171 * ----- Callbacks related to Client TLS -----
172 */
173
174 LWS_CALLBACK_OPENSSL_PERFORM_SERVER_CERT_VERIFICATION = 58,
175 /**< Similar to LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION
176 * this callback is called during OpenSSL verification of the cert
177 * sent from the server to the client. It is sent to protocol[0]
178 * callback as no protocol has been negotiated on the connection yet.
179 * Notice that the wsi is set because lws_client_connect_via_info was
180 * successful.
181 *
182 * See http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
183 * to understand more detail about the OpenSSL callback that
184 * generates this libwebsockets callback and the meanings of the
185 * arguments passed. In this callback, user is the x509_ctx,
186 * in is the ssl pointer and len is preverify_ok.
187 *
188 * THIS IS NOT RECOMMENDED BUT if a cert validation error shall be
189 * overruled and cert shall be accepted as ok,
190 * X509_STORE_CTX_set_error((X509_STORE_CTX*)user, X509_V_OK); must be
191 * called and return value must be 0 to mean the cert is OK;
192 * returning 1 will fail the cert in any case.
193 *
194 * This also means that if you don't handle this callback then
195 * the default callback action of returning 0 will not accept the
196 * certificate in case of a validation error decided by the SSL lib.
197 *
198 * This is expected and secure behaviour when validating certificates.
199 *
200 * Note: LCCSCF_ALLOW_SELFSIGNED and
201 * LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK still work without this
202 * callback being implemented.
203 */
204
205 /* ---------------------------------------------------------------------
206 * ----- Callbacks related to HTTP Server -----
207 */
208
209 LWS_CALLBACK_SERVER_NEW_CLIENT_INSTANTIATED = 19,
210 /**< A new client has been accepted by the ws server. This
211 * callback allows setting any relevant property to it. Because this
212 * happens immediately after the instantiation of a new client,
213 * there's no websocket protocol selected yet so this callback is
214 * issued only to protocol 0. Only wsi is defined, pointing to the
215 * new client, and the return value is ignored. */
216
217 LWS_CALLBACK_HTTP = 12,
218 /**< an http request has come from a client that is not
219 * asking to upgrade the connection to a websocket
220 * one. This is a chance to serve http content,
221 * for example, to send a script to the client
222 * which will then open the websockets connection.
223 * in points to the URI path requested and
224 * lws_serve_http_file() makes it very
225 * simple to send back a file to the client.
226 * Normally after sending the file you are done
227 * with the http connection, since the rest of the
228 * activity will come by websockets from the script
229 * that was delivered by http, so you will want to
230 * return 1; to close and free up the connection. */
231
232 LWS_CALLBACK_HTTP_BODY = 13,
233 /**< the next len bytes data from the http
234 * request body HTTP connection is now available in in. */
235
236 LWS_CALLBACK_HTTP_BODY_COMPLETION = 14,
237 /**< the expected amount of http request body has been delivered */
238
239 LWS_CALLBACK_HTTP_FILE_COMPLETION = 15,
240 /**< a file requested to be sent down http link has completed. */
241
242 LWS_CALLBACK_HTTP_WRITEABLE = 16,
243 /**< you can write more down the http protocol link now. */
244
245 LWS_CALLBACK_CLOSED_HTTP = 5,
246 /**< when a HTTP (non-websocket) session ends */
247
248 LWS_CALLBACK_FILTER_HTTP_CONNECTION = 18,
249 /**< called when the request has
250 * been received and parsed from the client, but the response is
251 * not sent yet. Return non-zero to disallow the connection.
252 * user is a pointer to the connection user space allocation,
253 * in is the URI, eg, "/"
254 * In your handler you can use the public APIs
255 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
256 * headers using the header enums lws_token_indexes from
257 * libwebsockets.h to check for and read the supported header
258 * presence and content before deciding to allow the http
259 * connection to proceed or to kill the connection. */
260
261 LWS_CALLBACK_ADD_HEADERS = 53,
262 /**< This gives your user code a chance to add headers to a server
263 * transaction bound to your protocol. `in` points to a
264 * `struct lws_process_html_args` describing a buffer and length
265 * you can add headers into using the normal lws apis.
266 *
267 * (see LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER to add headers to
268 * a client transaction)
269 *
270 * Only `args->p` and `args->len` are valid, and `args->p` should
271 * be moved on by the amount of bytes written, if any. Eg
272 *
273 * case LWS_CALLBACK_ADD_HEADERS:
274 *
275 * struct lws_process_html_args *args =
276 * (struct lws_process_html_args *)in;
277 *
278 * if (lws_add_http_header_by_name(wsi,
279 * (unsigned char *)"set-cookie:",
280 * (unsigned char *)cookie, cookie_len,
281 * (unsigned char **)&args->p,
282 * (unsigned char *)args->p + args->max_len))
283 * return 1;
284 *
285 * break;
286 */
287
288 LWS_CALLBACK_VERIFY_BASIC_AUTHORIZATION = 102,
289 /**< This gives the user code a chance to accept or reject credentials
290 * provided HTTP to basic authorization. It will only be called if the
291 * http mount's authentication_mode is set to LWSAUTHM_BASIC_AUTH_CALLBACK
292 * `in` points to a credential string of the form `username:password` If
293 * the callback returns zero (the default if unhandled), then the
294 * transaction ends with HTTP_STATUS_UNAUTHORIZED, otherwise the request
295 * will be processed */
296
297 LWS_CALLBACK_CHECK_ACCESS_RIGHTS = 51,
298 /**< This gives the user code a chance to forbid an http access.
299 * `in` points to a `struct lws_process_html_args`, which
300 * describes the URL, and a bit mask describing the type of
301 * authentication required. If the callback returns nonzero,
302 * the transaction ends with HTTP_STATUS_UNAUTHORIZED. */
303
304 LWS_CALLBACK_PROCESS_HTML = 52,
305 /**< This gives your user code a chance to mangle outgoing
306 * HTML. `in` points to a `struct lws_process_html_args`
307 * which describes the buffer containing outgoing HTML.
308 * The buffer may grow up to `.max_len` (currently +128
309 * bytes per buffer).
310 */
311
312 LWS_CALLBACK_HTTP_BIND_PROTOCOL = 49,
313 /**< By default, all HTTP handling is done in protocols[0].
314 * However you can bind different protocols (by name) to
315 * different parts of the URL space using callback mounts. This
316 * callback occurs in the new protocol when a wsi is bound
317 * to that protocol. Any protocol allocation related to the
318 * http transaction processing should be created then.
319 * These specific callbacks are necessary because with HTTP/1.1,
320 * a single connection may perform at series of different
321 * transactions at different URLs, thus the lifetime of the
322 * protocol bind is just for one transaction, not connection. */
323
324 LWS_CALLBACK_HTTP_DROP_PROTOCOL = 50,
325 /**< This is called when a transaction is unbound from a protocol.
326 * It indicates the connection completed its transaction and may
327 * do something different now. Any protocol allocation related
328 * to the http transaction processing should be destroyed. */
329
330 LWS_CALLBACK_HTTP_CONFIRM_UPGRADE = 86,
331 /**< This is your chance to reject an HTTP upgrade action. The
332 * name of the protocol being upgraded to is in 'in', and the ah
333 * is still bound to the wsi, so you can look at the headers.
334 *
335 * The default of returning 0 (ie, also if not handled) means the
336 * upgrade may proceed. Return <0 to just hang up the connection,
337 * or >0 if you have rejected the connection by returning http headers
338 * and response code yourself.
339 *
340 * There is no need for you to call transaction_completed() as the
341 * caller will take care of it when it sees you returned >0.
342 */
343
344 /* ---------------------------------------------------------------------
345 * ----- Callbacks related to HTTP Client -----
346 */
347
348 LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP = 44,
349 /**< The HTTP client connection has succeeded, and is now
350 * connected to the server */
351
352 LWS_CALLBACK_CLOSED_CLIENT_HTTP = 45,
353 /**< The HTTP client connection is closing */
354
355 LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ = 48,
356 /**< This is generated by lws_http_client_read() used to drain
357 * incoming data. In the case the incoming data was chunked, it will
358 * be split into multiple smaller callbacks for each chunk block,
359 * removing the chunk headers. If not chunked, it will appear all in
360 * one callback. */
361
362 LWS_CALLBACK_RECEIVE_CLIENT_HTTP = 46,
363 /**< This indicates data was received on the HTTP client connection. It
364 * does NOT actually drain or provide the data, so if you are doing
365 * http client, you MUST handle this and call lws_http_client_read().
366 * Failure to deal with it as in the minimal examples may cause spinning
367 * around the event loop as it's continuously signalled the same data
368 * is available for read. The related minimal examples show how to
369 * handle it.
370 *
371 * It's possible to defer calling lws_http_client_read() if you use
372 * rx flow control to stop further rx handling on the connection until
373 * you did deal with it. But normally you would call it in the handler.
374 *
375 * lws_http_client_read() strips any chunked framing and calls back
376 * with only payload data to LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ. The
377 * chunking is the reason this is not just all done in one callback for
378 * http.
379 */
380 LWS_CALLBACK_COMPLETED_CLIENT_HTTP = 47,
381 /**< The client transaction completed... at the moment this
382 * is the same as closing since transaction pipelining on
383 * client side is not yet supported. */
384
385 LWS_CALLBACK_CLIENT_HTTP_WRITEABLE = 57,
386 /**< when doing an HTTP type client connection, you can call
387 * lws_client_http_body_pending(wsi, 1) from
388 * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER to get these callbacks
389 * sending the HTTP headers.
390 *
391 * From this callback, when you have sent everything, you should let
392 * lws know by calling lws_client_http_body_pending(wsi, 0)
393 */
394
395 LWS_CALLBACK_CLIENT_HTTP_REDIRECT = 104,
396 /**< we're handling a 3xx redirect... return nonzero to hang up */
397
398 LWS_CALLBACK_CLIENT_HTTP_BIND_PROTOCOL = 85,
399 LWS_CALLBACK_CLIENT_HTTP_DROP_PROTOCOL = 76,
400
401 /* ---------------------------------------------------------------------
402 * ----- Callbacks related to Websocket Server -----
403 */
404
405 LWS_CALLBACK_ESTABLISHED = 0,
406 /**< (VH) after the server completes a handshake with an incoming
407 * client. If you built the library with ssl support, in is a
408 * pointer to the ssl struct associated with the connection or NULL.
409 *
410 * b0 of len is set if the connection was made using ws-over-h2
411 */
412
413 LWS_CALLBACK_CLOSED = 4,
414 /**< when the websocket session ends */
415
416 LWS_CALLBACK_SERVER_WRITEABLE = 11,
417 /**< See LWS_CALLBACK_CLIENT_WRITEABLE */
418
419 LWS_CALLBACK_RECEIVE = 6,
420 /**< data has appeared for this server endpoint from a
421 * remote client, it can be found at *in and is
422 * len bytes long */
423
424 LWS_CALLBACK_RECEIVE_PONG = 7,
425 /**< servers receive PONG packets with this callback reason */
426
427 LWS_CALLBACK_WS_PEER_INITIATED_CLOSE = 38,
428 /**< The peer has sent an unsolicited Close WS packet. in and
429 * len are the optional close code (first 2 bytes, network
430 * order) and the optional additional information which is not
431 * defined in the standard, and may be a string or non human-readable
432 * data.
433 * If you return 0 lws will echo the close and then close the
434 * connection. If you return nonzero lws will just close the
435 * connection. */
436
437 LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION = 20,
438 /**< called when the handshake has
439 * been received and parsed from the client, but the response is
440 * not sent yet. Return non-zero to disallow the connection.
441 * user is a pointer to the connection user space allocation,
442 * in is the requested protocol name
443 * In your handler you can use the public APIs
444 * lws_hdr_total_length() / lws_hdr_copy() to access all of the
445 * headers using the header enums lws_token_indexes from
446 * libwebsockets.h to check for and read the supported header
447 * presence and content before deciding to allow the handshake
448 * to proceed or to kill the connection. */
449
450 LWS_CALLBACK_CONFIRM_EXTENSION_OKAY = 25,
451 /**< When the server handshake code
452 * sees that it does support a requested extension, before
453 * accepting the extension by additing to the list sent back to
454 * the client it gives this callback just to check that it's okay
455 * to use that extension. It calls back to the requested protocol
456 * and with in being the extension name, len is 0 and user is
457 * valid. Note though at this time the ESTABLISHED callback hasn't
458 * happened yet so if you initialize user content there, user
459 * content during this callback might not be useful for anything. */
460
461 LWS_CALLBACK_WS_SERVER_BIND_PROTOCOL = 77,
462 LWS_CALLBACK_WS_SERVER_DROP_PROTOCOL = 78,
463
464 /* ---------------------------------------------------------------------
465 * ----- Callbacks related to Websocket Client -----
466 */
467
468 LWS_CALLBACK_CLIENT_CONNECTION_ERROR = 1,
469 /**< the request client connection has been unable to complete a
470 * handshake with the remote server. If in is non-NULL, you can
471 * find an error string of length len where it points to
472 *
473 * Diagnostic strings that may be returned include
474 *
475 * "getaddrinfo (ipv6) failed"
476 * "unknown address family"
477 * "getaddrinfo (ipv4) failed"
478 * "set socket opts failed"
479 * "insert wsi failed"
480 * "lws_ssl_client_connect1 failed"
481 * "lws_ssl_client_connect2 failed"
482 * "Peer hung up"
483 * "read failed"
484 * "HS: URI missing"
485 * "HS: Redirect code but no Location"
486 * "HS: URI did not parse"
487 * "HS: Redirect failed"
488 * "HS: Server did not return 200"
489 * "HS: OOM"
490 * "HS: disallowed by client filter"
491 * "HS: disallowed at ESTABLISHED"
492 * "HS: ACCEPT missing"
493 * "HS: ws upgrade response not 101"
494 * "HS: UPGRADE missing"
495 * "HS: Upgrade to something other than websocket"
496 * "HS: CONNECTION missing"
497 * "HS: UPGRADE malformed"
498 * "HS: PROTOCOL malformed"
499 * "HS: Cannot match protocol"
500 * "HS: EXT: list too big"
501 * "HS: EXT: failed setting defaults"
502 * "HS: EXT: failed parsing defaults"
503 * "HS: EXT: failed parsing options"
504 * "HS: EXT: Rejects server options"
505 * "HS: EXT: unknown ext"
506 * "HS: Accept hash wrong"
507 * "HS: Rejected by filter cb"
508 * "HS: OOM"
509 * "HS: SO_SNDBUF failed"
510 * "HS: Rejected at CLIENT_ESTABLISHED"
511 */
512
513 LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH = 2,
514 /**< this is the last chance for the client user code to examine the
515 * http headers and decide to reject the connection. If the
516 * content in the headers is interesting to the
517 * client (url, etc) it needs to copy it out at
518 * this point since it will be destroyed before
519 * the CLIENT_ESTABLISHED call */
520
521 LWS_CALLBACK_CLIENT_ESTABLISHED = 3,
522 /**< after your client connection completed the websocket upgrade
523 * handshake with the remote server */
524
525 LWS_CALLBACK_CLIENT_CLOSED = 75,
526 /**< when a client websocket session ends */
527
528 LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER = 24,
529 /**< this callback happens
530 * when a client handshake is being compiled. user is NULL,
531 * in is a char **, it's pointing to a char * which holds the
532 * next location in the header buffer where you can add
533 * headers, and len is the remaining space in the header buffer,
534 * which is typically some hundreds of bytes. So, to add a canned
535 * cookie, your handler code might look similar to:
536 *
537 * char **p = (char **)in, *end = (*p) + len;
538 *
539 * if (lws_add_http_header_by_token(wsi, WSI_TOKEN_HTTP_COOKIE,
540 * (unsigned char)"a=b", 3, p, end))
541 * return -1;
542 *
543 * See LWS_CALLBACK_ADD_HEADERS for adding headers to server
544 * transactions.
545 */
546
547 LWS_CALLBACK_CLIENT_RECEIVE = 8,
548 /**< data has appeared from the server for the client connection, it
549 * can be found at *in and is len bytes long */
550
551 LWS_CALLBACK_CLIENT_RECEIVE_PONG = 9,
552 /**< clients receive PONG packets with this callback reason */
553
554 LWS_CALLBACK_CLIENT_WRITEABLE = 10,
555 /**< If you call lws_callback_on_writable() on a connection, you will
556 * get one of these callbacks coming when the connection socket
557 * is able to accept another write packet without blocking.
558 * If it already was able to take another packet without blocking,
559 * you'll get this callback at the next call to the service loop
560 * function. Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
561 * and servers get LWS_CALLBACK_SERVER_WRITEABLE. */
562
563 LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED = 26,
564 /**< When a ws client
565 * connection is being prepared to start a handshake to a server,
566 * each supported extension is checked with protocols[0] callback
567 * with this reason, giving the user code a chance to suppress the
568 * claim to support that extension by returning non-zero. If
569 * unhandled, by default 0 will be returned and the extension
570 * support included in the header to the server. Notice this
571 * callback comes to protocols[0]. */
572
573 LWS_CALLBACK_WS_EXT_DEFAULTS = 39,
574 /**< Gives client connections an opportunity to adjust negotiated
575 * extension defaults. `user` is the extension name that was
576 * negotiated (eg, "permessage-deflate"). `in` points to a
577 * buffer and `len` is the buffer size. The user callback can
578 * set the buffer to a string describing options the extension
579 * should parse. Or just ignore for defaults. */
580
581
582 LWS_CALLBACK_FILTER_NETWORK_CONNECTION = 17,
583 /**< called when a client connects to
584 * the server at network level; the connection is accepted but then
585 * passed to this callback to decide whether to hang up immediately
586 * or not, based on the client IP.
587 *
588 * user_data in the callback points to a
589 * struct lws_filter_network_conn_args that is prepared with the
590 * sockfd, and the peer's address information.
591 *
592 * in contains the connection socket's descriptor.
593 *
594 * Since the client connection information is not available yet,
595 * wsi still pointing to the main server socket.
596 *
597 * Return non-zero to terminate the connection before sending or
598 * receiving anything. Because this happens immediately after the
599 * network connection from the client, there's no websocket protocol
600 * selected yet so this callback is issued only to protocol 0. */
601
602 LWS_CALLBACK_WS_CLIENT_BIND_PROTOCOL = 79,
603 LWS_CALLBACK_WS_CLIENT_DROP_PROTOCOL = 80,
604
605 /* ---------------------------------------------------------------------
606 * ----- Callbacks related to external poll loop integration -----
607 */
608
609 LWS_CALLBACK_GET_THREAD_ID = 31,
610 /**< lws can accept callback when writable requests from other
611 * threads, if you implement this callback and return an opaque
612 * current thread ID integer. */
613
614 /* external poll() management support */
615 LWS_CALLBACK_ADD_POLL_FD = 32,
616 /**< lws normally deals with its poll() or other event loop
617 * internally, but in the case you are integrating with another
618 * server you will need to have lws sockets share a
619 * polling array with the other server. This and the other
620 * POLL_FD related callbacks let you put your specialized
621 * poll array interface code in the callback for protocol 0, the
622 * first protocol you support, usually the HTTP protocol in the
623 * serving case.
624 * This callback happens when a socket needs to be
625 * added to the polling loop: in points to a struct
626 * lws_pollargs; the fd member of the struct is the file
627 * descriptor, and events contains the active events
628 *
629 * If you are using the internal lws polling / event loop
630 * you can just ignore these callbacks. */
631
632 LWS_CALLBACK_DEL_POLL_FD = 33,
633 /**< This callback happens when a socket descriptor
634 * needs to be removed from an external polling array. in is
635 * again the struct lws_pollargs containing the fd member
636 * to be removed. If you are using the internal polling
637 * loop, you can just ignore it. */
638
639 LWS_CALLBACK_CHANGE_MODE_POLL_FD = 34,
640 /**< This callback happens when lws wants to modify the events for
641 * a connection.
642 * in is the struct lws_pollargs with the fd to change.
643 * The new event mask is in events member and the old mask is in
644 * the prev_events member.
645 * If you are using the internal polling loop, you can just ignore
646 * it. */
647
648 LWS_CALLBACK_LOCK_POLL = 35,
649 /**< These allow the external poll changes driven
650 * by lws to participate in an external thread locking
651 * scheme around the changes, so the whole thing is threadsafe.
652 * These are called around three activities in the library,
653 * - inserting a new wsi in the wsi / fd table (len=1)
654 * - deleting a wsi from the wsi / fd table (len=1)
655 * - changing a wsi's POLLIN/OUT state (len=0)
656 * Locking and unlocking external synchronization objects when
657 * len == 1 allows external threads to be synchronized against
658 * wsi lifecycle changes if it acquires the same lock for the
659 * duration of wsi dereference from the other thread context. */
660
661 LWS_CALLBACK_UNLOCK_POLL = 36,
662 /**< See LWS_CALLBACK_LOCK_POLL, ignore if using lws internal poll */
663
664 /* ---------------------------------------------------------------------
665 * ----- Callbacks related to CGI serving -----
666 */
667
668 LWS_CALLBACK_CGI = 40,
669 /**< CGI: CGI IO events on stdin / out / err are sent here on
670 * protocols[0]. The provided `lws_callback_http_dummy()`
671 * handles this and the callback should be directed there if
672 * you use CGI. */
673
674 LWS_CALLBACK_CGI_TERMINATED = 41,
675 /**< CGI: The related CGI process ended, this is called before
676 * the wsi is closed. Used to, eg, terminate chunking.
677 * The provided `lws_callback_http_dummy()`
678 * handles this and the callback should be directed there if
679 * you use CGI. The child PID that terminated is in len. */
680
681 LWS_CALLBACK_CGI_STDIN_DATA = 42,
682 /**< CGI: Data is, to be sent to the CGI process stdin, eg from
683 * a POST body. The provided `lws_callback_http_dummy()`
684 * handles this and the callback should be directed there if
685 * you use CGI. */
686
687 LWS_CALLBACK_CGI_STDIN_COMPLETED = 43,
688 /**< CGI: no more stdin is coming. The provided
689 * `lws_callback_http_dummy()` handles this and the callback
690 * should be directed there if you use CGI. */
691
692 LWS_CALLBACK_CGI_PROCESS_ATTACH = 70,
693 /**< CGI: Sent when the CGI process is spawned for the wsi. The
694 * len parameter is the PID of the child process */
695
696 /* ---------------------------------------------------------------------
697 * ----- Callbacks related to Generic Sessions -----
698 */
699
700 LWS_CALLBACK_SESSION_INFO = 54,
701 /**< This is only generated by user code using generic sessions.
702 * It's used to get a `struct lws_session_info` filled in by
703 * generic sessions with information about the logged-in user.
704 * See the messageboard sample for an example of how to use. */
705
706 LWS_CALLBACK_GS_EVENT = 55,
707 /**< Indicates an event happened to the Generic Sessions session.
708 * `in` contains a `struct lws_gs_event_args` describing the event. */
709
710 LWS_CALLBACK_HTTP_PMO = 56,
711 /**< per-mount options for this connection, called before
712 * the normal LWS_CALLBACK_HTTP when the mount has per-mount
713 * options.
714 */
715
716 /* ---------------------------------------------------------------------
717 * ----- Callbacks related to RAW PROXY -----
718 */
719
720 LWS_CALLBACK_RAW_PROXY_CLI_RX = 89,
721 /**< RAW mode client (outgoing) RX */
722
723 LWS_CALLBACK_RAW_PROXY_SRV_RX = 90,
724 /**< RAW mode server (listening) RX */
725
726 LWS_CALLBACK_RAW_PROXY_CLI_CLOSE = 91,
727 /**< RAW mode client (outgoing) is closing */
728
729 LWS_CALLBACK_RAW_PROXY_SRV_CLOSE = 92,
730 /**< RAW mode server (listening) is closing */
731
732 LWS_CALLBACK_RAW_PROXY_CLI_WRITEABLE = 93,
733 /**< RAW mode client (outgoing) may be written */
734
735 LWS_CALLBACK_RAW_PROXY_SRV_WRITEABLE = 94,
736 /**< RAW mode server (listening) may be written */
737
738 LWS_CALLBACK_RAW_PROXY_CLI_ADOPT = 95,
739 /**< RAW mode client (onward) accepted socket was adopted
740 * (equivalent to 'wsi created') */
741
742 LWS_CALLBACK_RAW_PROXY_SRV_ADOPT = 96,
743 /**< RAW mode server (listening) accepted socket was adopted
744 * (equivalent to 'wsi created') */
745
746 LWS_CALLBACK_RAW_PROXY_CLI_BIND_PROTOCOL = 97,
747 LWS_CALLBACK_RAW_PROXY_SRV_BIND_PROTOCOL = 98,
748 LWS_CALLBACK_RAW_PROXY_CLI_DROP_PROTOCOL = 99,
749 LWS_CALLBACK_RAW_PROXY_SRV_DROP_PROTOCOL = 100,
750
751
752 /* ---------------------------------------------------------------------
753 * ----- Callbacks related to RAW sockets -----
754 */
755
756 LWS_CALLBACK_RAW_RX = 59,
757 /**< RAW mode connection RX */
758
759 LWS_CALLBACK_RAW_CLOSE = 60,
760 /**< RAW mode connection is closing */
761
762 LWS_CALLBACK_RAW_WRITEABLE = 61,
763 /**< RAW mode connection may be written */
764
765 LWS_CALLBACK_RAW_ADOPT = 62,
766 /**< RAW mode connection was adopted (equivalent to 'wsi created') */
767
768 LWS_CALLBACK_RAW_CONNECTED = 101,
769 /**< outgoing client RAW mode connection was connected */
770
771 LWS_CALLBACK_RAW_SKT_BIND_PROTOCOL = 81,
772 LWS_CALLBACK_RAW_SKT_DROP_PROTOCOL = 82,
773
774 /* ---------------------------------------------------------------------
775 * ----- Callbacks related to RAW file handles -----
776 */
777
778 LWS_CALLBACK_RAW_ADOPT_FILE = 63,
779 /**< RAW mode file was adopted (equivalent to 'wsi created') */
780
781 LWS_CALLBACK_RAW_RX_FILE = 64,
782 /**< This is the indication the RAW mode file has something to read.
783 * This doesn't actually do the read of the file and len is always
784 * 0... your code should do the read having been informed there is
785 * something to read now. */
786
787 LWS_CALLBACK_RAW_WRITEABLE_FILE = 65,
788 /**< RAW mode file is writeable */
789
790 LWS_CALLBACK_RAW_CLOSE_FILE = 66,
791 /**< RAW mode wsi that adopted a file is closing */
792
793 LWS_CALLBACK_RAW_FILE_BIND_PROTOCOL = 83,
794 LWS_CALLBACK_RAW_FILE_DROP_PROTOCOL = 84,
795
796 /* ---------------------------------------------------------------------
797 * ----- Callbacks related to generic wsi events -----
798 */
799
800 LWS_CALLBACK_TIMER = 73,
801 /**< When the time elapsed after a call to
802 * lws_set_timer_usecs(wsi, usecs) is up, the wsi will get one of
803 * these callbacks. The deadline can be continuously extended into the
804 * future by later calls to lws_set_timer_usecs() before the deadline
805 * expires, or cancelled by lws_set_timer_usecs(wsi, -1);
806 */
807
808 LWS_CALLBACK_EVENT_WAIT_CANCELLED = 71,
809 /**< This is sent to every protocol of every vhost in response
810 * to lws_cancel_service() or lws_cancel_service_pt(). This
811 * callback is serialized in the lws event loop normally, even
812 * if the lws_cancel_service[_pt]() call was from a different
813 * thread. */
814
815 LWS_CALLBACK_CHILD_CLOSING = 69,
816 /**< Sent to parent to notify them a child is closing / being
817 * destroyed. in is the child wsi.
818 */
819
820 LWS_CALLBACK_CONNECTING = 105,
821 /**< Called before a socketfd is about to connect(). In is the
822 * socketfd, cast to a (void *), if on a platform where the socketfd
823 * is an int, recover portably using (lws_sockfd_type)(intptr_t)in.
824 *
825 * It's also called in SOCKS5 or http_proxy cases where the socketfd is
826 * going to try to connect to its proxy.
827 */
828
829 /* ---------------------------------------------------------------------
830 * ----- Callbacks related to TLS certificate management -----
831 */
832
833 LWS_CALLBACK_VHOST_CERT_AGING = 72,
834 /**< When a vhost TLS cert has its expiry checked, this callback
835 * is broadcast to every protocol of every vhost in case the
836 * protocol wants to take some action with this information.
837 * \p in is a pointer to a struct lws_acme_cert_aging_args,
838 * and \p len is the number of days left before it expires, as
839 * a (ssize_t). In the struct lws_acme_cert_aging_args, vh
840 * points to the vhost the cert aging information applies to,
841 * and element_overrides[] is an optional way to update information
842 * from the pvos... NULL in an index means use the information from
843 * from the pvo for the cert renewal, non-NULL in the array index
844 * means use that pointer instead for the index. */
845
846 LWS_CALLBACK_VHOST_CERT_UPDATE = 74,
847 /**< When a vhost TLS cert is being updated, progress is
848 * reported to the vhost in question here, including completion
849 * and failure. in points to optional JSON, and len represents the
850 * connection state using enum lws_cert_update_state */
851
852 /* ---------------------------------------------------------------------
853 * ----- Callbacks related to MQTT Client -----
854 */
855
856 LWS_CALLBACK_MQTT_NEW_CLIENT_INSTANTIATED = 200,
857 LWS_CALLBACK_MQTT_IDLE = 201,
858 LWS_CALLBACK_MQTT_CLIENT_ESTABLISHED = 202,
859 LWS_CALLBACK_MQTT_SUBSCRIBED = 203,
860 LWS_CALLBACK_MQTT_CLIENT_WRITEABLE = 204,
861 LWS_CALLBACK_MQTT_CLIENT_RX = 205,
862 LWS_CALLBACK_MQTT_UNSUBSCRIBED = 206,
863 LWS_CALLBACK_MQTT_DROP_PROTOCOL = 207,
864 LWS_CALLBACK_MQTT_CLIENT_CLOSED = 208,
865 LWS_CALLBACK_MQTT_ACK = 209,
866 /**< When a message is fully sent, if QoS0 this callback is generated
867 * to locally "acknowledge" it. For QoS1, this callback is only
868 * generated when the matching PUBACK is received. Return nonzero to
869 * close the wsi.
870 */
871 LWS_CALLBACK_MQTT_RESEND = 210,
872 /**< In QoS1 or QoS2, this callback is generated instead of the _ACK one
873 * if we timed out waiting for a PUBACK or a PUBREC, and we must resend
874 * the message. Return nonzero to close the wsi.
875 */
876 LWS_CALLBACK_MQTT_UNSUBSCRIBE_TIMEOUT = 211,
877 /**< When a UNSUBSCRIBE is sent, this callback is generated instead of
878 * the _UNSUBSCRIBED one if we timed out waiting for a UNSUBACK.
879 * Return nonzero to close the wsi.
880 */
881 LWS_CALLBACK_MQTT_SHADOW_TIMEOUT = 212,
882 /**< When a Device Shadow is sent, this callback is generated if we
883 * timed out waiting for a response from AWS IoT.
884 * Return nonzero to close the wsi.
885 */
886
887 /****** add new things just above ---^ ******/
888
889 LWS_CALLBACK_USER = 1000,
890 /**< user code can use any including above without fear of clashes */
891};
892
893
894
895/**
896 * typedef lws_callback_function() - User server actions
897 * \param wsi: Opaque websocket instance pointer
898 * \param reason: The reason for the call
899 * \param user: Pointer to per-session user data allocated by library
900 * \param in: Pointer used for some callback reasons
901 * \param len: Length set for some callback reasons
902 *
903 * This callback is the way the user controls what is served. All the
904 * protocol detail is hidden and handled by the library.
905 *
906 * For each connection / session there is user data allocated that is
907 * pointed to by "user". You set the size of this user data area when
908 * the library is initialized with lws_create_server.
909 */
910typedef int
911lws_callback_function(struct lws *wsi, enum lws_callback_reasons reason,
912 void *user, void *in, size_t len);
913
914#define LWS_CB_REASON_AUX_BF__CGI 1
915#define LWS_CB_REASON_AUX_BF__PROXY 2
916#define LWS_CB_REASON_AUX_BF__CGI_CHUNK_END 4
917#define LWS_CB_REASON_AUX_BF__CGI_HEADERS 8
918#define LWS_CB_REASON_AUX_BF__PROXY_TRANS_END 16
919#define LWS_CB_REASON_AUX_BF__PROXY_HEADERS 32
920///@}
921