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