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