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_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 */ 910 typedef int 911 lws_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