1API Reference 2============= 3 4.. highlight:: c 5 6Preliminaries 7------------- 8 9All declarations are in :file:`lsquic.h`, so it is enough to 10 11:: 12 13 #include <lsquic.h> 14 15in each source file. 16 17 18Library Version 19--------------- 20 21LSQUIC follows the following versioning model. The version number 22has the form MAJOR.MINOR.PATCH, where 23 24- MAJOR changes when a large redesign occurs; 25- MINOR changes when an API change or another significant change occurs; and 26- PATCH changes when a bug is fixed or another small, API-compatible change occurs. 27 28QUIC Versions 29------------- 30 31LSQUIC supports two types of QUIC protocol: Google QUIC and IETF QUIC. The 32former will at some point become obsolete, while the latter is still being 33developed by the IETF. Both types are included in a single enum: 34 35.. type:: enum lsquic_version 36 37 .. member:: LSQVER_043 38 39 Google QUIC version Q043 40 41 .. member:: LSQVER_046 42 43 Google QUIC version Q046 44 45 .. member:: LSQVER_050 46 47 Google QUIC version Q050 48 49 .. member:: LSQVER_ID27 50 51 IETF QUIC version ID (Internet-Draft) 27; this version is deprecated. 52 53 .. member:: LSQVER_ID29 54 55 IETF QUIC version ID 29 56 57 .. member:: LSQVER_ID34 58 59 IETF QUIC version ID 34 60 61 .. member:: LSQVER_I001 62 63 IETF QUIC version 1. (This version is disabled by default until 64 the QUIC RFC is released). 65 66 .. member:: N_LSQVER 67 68 Special value indicating the number of versions in the enum. It 69 may be used as argument to :func:`lsquic_engine_connect()`. 70 71Several version lists (as bitmasks) are defined in :file:`lsquic.h`: 72 73.. macro:: LSQUIC_SUPPORTED_VERSIONS 74 75List of all supported versions. 76 77.. macro:: LSQUIC_FORCED_TCID0_VERSIONS 78 79List of versions in which the server never includes CID in short packets. 80 81.. macro:: LSQUIC_EXPERIMENTAL_VERSIONS 82 83Experimental versions. 84 85.. macro:: LSQUIC_DEPRECATED_VERSIONS 86 87Deprecated versions. 88 89.. macro:: LSQUIC_GQUIC_HEADER_VERSIONS 90 91Versions that have Google QUIC-like headers. Only Q043 remains in this 92list. 93 94.. macro:: LSQUIC_IETF_VERSIONS 95 96IETF QUIC versions. 97 98.. macro:: LSQUIC_IETF_DRAFT_VERSIONS 99 100IETF QUIC *draft* versions. When IETF QUIC v1 is released, it will not 101be included in this list. 102 103LSQUIC Types 104------------ 105 106LSQUIC declares several types used by many of its public functions. They are: 107 108.. type:: lsquic_engine_t 109 110 Instance of LSQUIC engine. 111 112.. type:: lsquic_conn_t 113 114 QUIC connection. 115 116.. type:: lsquic_stream_t 117 118 QUIC stream. 119 120.. type:: lsquic_stream_id_t 121 122 Stream ID. 123 124.. type:: lsquic_conn_ctx_t 125 126 Connection context. This is the return value of :member:`lsquic_stream_if.on_new_conn`. 127 To LSQUIC, this is just an opaque pointer. User code is expected to 128 use it for its own purposes. 129 130.. type:: lsquic_stream_ctx_t 131 132 Stream context. This is the return value of :func:`on_new_stream()`. 133 To LSQUIC, this is just an opaque pointer. User code is expected to 134 use it for its own purposes. 135 136.. type:: lsquic_http_headers_t 137 138 HTTP headers 139 140Library Initialization 141---------------------- 142 143Before using the library, internal structures must be initialized using 144the global initialization function: 145 146:: 147 148 if (0 == lsquic_global_init(LSQUIC_GLOBAL_CLIENT|LSQUIC_GLOBAL_SERVER)) 149 /* OK, do something useful */ 150 ; 151 152This call only needs to be made once. Afterwards, any number of LSQUIC 153engines may be instantiated. 154 155After a process is done using LSQUIC, it should clean up: 156 157:: 158 159 lsquic_global_cleanup(); 160 161Logging 162------- 163 164.. type:: struct lsquic_logger_if 165 166 .. member:: int (*log_buf)(void *logger_ctx, const char *buf, size_t len) 167 168.. function:: void lsquic_logger_init (const struct lsquic_logger_if *logger_if, void *logger_ctx, enum lsquic_logger_timestamp_style) 169 170 Call this if you want to do something with LSQUIC log messages, as they are thrown out by default. 171 172.. function:: int lsquic_set_log_level (const char *log_level) 173 174 Set log level for all LSQUIC modules. 175 176 :param log_level: Acceptable values are debug, info, notice, warning, error, alert, emerg, crit (case-insensitive). 177 :return: 0 on success or -1 on failure (invalid log level). 178 179.. function:: int lsquic_logger_lopt (const char *log_specs) 180 181 Set log level for a particular module or several modules. 182 183 :param log_specs: 184 185 One or more "module=level" specifications serapated by comma. 186 For example, "event=debug,engine=info". See `List of Log Modules`_ 187 188Engine Instantiation and Destruction 189------------------------------------ 190 191To use the library, an instance of the ``struct lsquic_engine`` needs to be 192created: 193 194.. function:: lsquic_engine_t *lsquic_engine_new (unsigned flags, const struct lsquic_engine_api *api) 195 196 Create a new engine. 197 198 :param flags: This is is a bitmask of :macro:`LSENG_SERVER` and 199 :macro:`LSENG_HTTP`. 200 :param api: Pointer to an initialized :type:`lsquic_engine_api`. 201 202 The engine can be instantiated either in server mode (when ``LSENG_SERVER`` 203 is set) or client mode. If you need both server and client in your program, 204 create two engines (or as many as you'd like). 205 206 Specifying ``LSENG_HTTP`` flag enables the HTTP functionality: HTTP/2-like 207 for Google QUIC connections and HTTP/3 functionality for IETF QUIC 208 connections. 209 210.. macro:: LSENG_SERVER 211 212 One of possible bitmask values passed as first argument to 213 :type:`lsquic_engine_new`. When set, the engine instance 214 will be in the server mode. 215 216.. macro:: LSENG_HTTP 217 218 One of possible bitmask values passed as first argument to 219 :type:`lsquic_engine_new`. When set, the engine instance 220 will enable HTTP functionality. 221 222.. function:: void lsquic_engine_cooldown (lsquic_engine_t *engine) 223 224 This function closes all mini connections and marks all full connections 225 as going away. In server mode, this also causes the engine to stop 226 creating new connections. 227 228.. function:: void lsquic_engine_destroy (lsquic_engine_t *engine) 229 230 Destroy engine and all its resources. 231 232Engine Callbacks 233---------------- 234 235``struct lsquic_engine_api`` contains a few mandatory members and several 236optional members. 237 238.. type:: struct lsquic_engine_api 239 240 .. member:: const struct lsquic_stream_if *ea_stream_if 241 .. member:: void *ea_stream_if_ctx 242 243 ``ea_stream_if`` is mandatory. This structure contains pointers 244 to callbacks that handle connections and stream events. 245 246 .. member:: lsquic_packets_out_f ea_packets_out 247 .. member:: void *ea_packets_out_ctx 248 249 ``ea_packets_out`` is used by the engine to send packets. 250 251 .. member:: const struct lsquic_engine_settings *ea_settings 252 253 If ``ea_settings`` is set to NULL, the engine uses default settings 254 (see :func:`lsquic_engine_init_settings()`) 255 256 .. member:: lsquic_lookup_cert_f ea_lookup_cert 257 .. member:: void *ea_cert_lu_ctx 258 259 Look up certificate. Mandatory in server mode. 260 261 .. member:: struct ssl_ctx_st * (*ea_get_ssl_ctx)(void *peer_ctx, const struct sockaddr *local) 262 263 Get SSL_CTX associated with a peer context. Mandatory in server 264 mode. This is used for default values for SSL instantiation. 265 266 .. member:: const struct lsquic_hset_if *ea_hsi_if 267 .. member:: void *ea_hsi_ctx 268 269 Optional header set interface. If not specified, the incoming headers 270 are converted to HTTP/1.x format and are read from stream and have to 271 be parsed again. 272 273 .. member:: const struct lsquic_shared_hash_if *ea_shi 274 .. member:: void *ea_shi_ctx 275 276 Shared hash interface can be used to share state between several 277 processes of a single QUIC server. 278 279 .. member:: const struct lsquic_packout_mem_if *ea_pmi 280 .. member:: void *ea_pmi_ctx 281 282 Optional set of functions to manage memory allocation for outgoing 283 packets. 284 285 .. member:: lsquic_cids_update_f ea_new_scids 286 .. member:: lsquic_cids_update_f ea_live_scids 287 .. member:: lsquic_cids_update_f ea_old_scids 288 .. member:: void *ea_cids_update_ctx 289 290 In a multi-process setup, it may be useful to observe the CID 291 lifecycle. This optional set of callbacks makes it possible. 292 293 .. member:: const char *ea_alpn 294 295 The optional ALPN string is used by the client if :macro:`LSENG_HTTP` 296 is not set. 297 298 .. member:: void (*ea_generate_scid)(lsquic_conn_t *, lsquic_cid_t *, unsigned) 299 300 Optional interface to control the creation of connection IDs. 301 302.. _apiref-engine-settings: 303 304Engine Settings 305--------------- 306 307Engine behavior can be controlled by several settings specified in the 308settings structure: 309 310.. type:: struct lsquic_engine_settings 311 312 .. member:: unsigned es_versions 313 314 This is a bit mask wherein each bit corresponds to a value in 315 :type:`lsquic_version`. Client starts negotiating with the highest 316 version and goes down. Server supports either of the versions 317 specified here. This setting applies to both Google and IETF QUIC. 318 319 The default value is :macro:`LSQUIC_DF_VERSIONS`. 320 321 .. member:: unsigned es_cfcw 322 323 Initial default connection flow control window. 324 325 In server mode, per-connection values may be set lower than 326 this if resources are scarce. 327 328 Do not set es_cfcw and es_sfcw lower than :macro:`LSQUIC_MIN_FCW`. 329 330 .. member:: unsigned es_sfcw 331 332 Initial default stream flow control window. 333 334 In server mode, per-connection values may be set lower than 335 this if resources are scarce. 336 337 Do not set es_cfcw and es_sfcw lower than :macro:`LSQUIC_MIN_FCW`. 338 339 .. member:: unsigned es_max_cfcw 340 341 This value is used to specify maximum allowed value CFCW is allowed 342 to reach due to window auto-tuning. By default, this value is zero, 343 which means that CFCW is not allowed to increase from its initial 344 value. 345 346 This setting is applicable to both gQUIC and IETF QUIC. 347 348 See :member:`lsquic_engine_settings.es_cfcw`, 349 :member:`lsquic_engine_settings.es_init_max_data`. 350 351 .. member:: unsigned es_max_sfcw 352 353 This value is used to specify the maximum value stream flow control 354 window is allowed to reach due to auto-tuning. By default, this 355 value is zero, meaning that auto-tuning is turned off. 356 357 This setting is applicable to both gQUIC and IETF QUIC. 358 359 See :member:`lsquic_engine_settings.es_sfcw`, 360 :member:`lsquic_engine_settings.es_init_max_stream_data_bidi_local`, 361 :member:`lsquic_engine_settings.es_init_max_stream_data_bidi_remote`. 362 363 .. member:: unsigned es_max_streams_in 364 365 Maximum incoming streams, a.k.a. MIDS. 366 367 Google QUIC only. 368 369 .. member:: unsigned long es_handshake_to 370 371 Handshake timeout in microseconds. 372 373 For client, this can be set to an arbitrary value (zero turns the 374 timeout off). 375 376 For server, this value is limited to about 16 seconds. Do not set 377 it to zero. 378 379 Defaults to :macro:`LSQUIC_DF_HANDSHAKE_TO`. 380 381 .. member:: unsigned long es_idle_conn_to 382 383 Idle connection timeout, a.k.a ICSL, in microseconds; GQUIC only. 384 385 Defaults to :macro:`LSQUIC_DF_IDLE_CONN_TO` 386 387 .. member:: int es_silent_close 388 389 When true, ``CONNECTION_CLOSE`` is not sent when connection times out. 390 The server will also not send a reply to client's ``CONNECTION_CLOSE``. 391 392 Corresponds to SCLS (silent close) gQUIC option. 393 394 .. member:: unsigned es_max_header_list_size 395 396 This corresponds to SETTINGS_MAX_HEADER_LIST_SIZE 397 (:rfc:`7540#section-6.5.2`). 0 means no limit. Defaults 398 to :func:`LSQUIC_DF_MAX_HEADER_LIST_SIZE`. 399 400 .. member:: const char *es_ua 401 402 UAID -- User-Agent ID. Defaults to :macro:`LSQUIC_DF_UA`. 403 404 Google QUIC only. 405 406 407 More parameters for server 408 409 .. member:: unsigned es_max_inchoate 410 411 Maximum number of incoming connections in inchoate state. (In 412 other words, maximum number of mini connections.) 413 414 This is only applicable in server mode. 415 416 Defaults to :macro:`LSQUIC_DF_MAX_INCHOATE`. 417 418 .. member:: int es_support_push 419 420 Setting this value to 0 means that 421 422 For client: 423 424 1. we send a SETTINGS frame to indicate that we do not support server 425 push; and 426 2. all incoming pushed streams get reset immediately. 427 428 (For maximum effect, set es_max_streams_in to 0.) 429 430 For server: 431 432 1. :func:`lsquic_conn_push_stream()` will return -1. 433 434 .. member:: int es_support_tcid0 435 436 If set to true value, the server will not include connection ID in 437 outgoing packets if client's CHLO specifies TCID=0. 438 439 For client, this means including TCID=0 into CHLO message. Note that 440 in this case, the engine tracks connections by the 441 (source-addr, dest-addr) tuple, thereby making it necessary to create 442 a socket for each connection. 443 444 This option has no effect in Q046 and Q050, as the server never includes 445 CIDs in the short packets. 446 447 This setting is applicable to gQUIC only. 448 449 The default is :func:`LSQUIC_DF_SUPPORT_TCID0`. 450 451 .. member:: int es_support_nstp 452 453 Q037 and higher support "No STOP_WAITING frame" mode. When set, the 454 client will send NSTP option in its Client Hello message and will not 455 sent STOP_WAITING frames, while ignoring incoming STOP_WAITING frames, 456 if any. Note that if the version negotiation happens to downgrade the 457 client below Q037, this mode will *not* be used. 458 459 This option does not affect the server, as it must support NSTP mode 460 if it was specified by the client. 461 462 Defaults to :macro:`LSQUIC_DF_SUPPORT_NSTP`. 463 464 .. member:: int es_honor_prst 465 466 If set to true value, the library will drop connections when it 467 receives corresponding Public Reset packet. The default is to 468 ignore these packets. 469 470 The default is :macro:`LSQUIC_DF_HONOR_PRST`. 471 472 .. member:: int es_send_prst 473 474 If set to true value, the library will send Public Reset packets 475 in response to incoming packets with unknown Connection IDs. 476 477 The default is :macro:`LSQUIC_DF_SEND_PRST`. 478 479 .. member:: unsigned es_progress_check 480 481 A non-zero value enables internal checks that identify suspected 482 infinite loops in user `on_read` and `on_write` callbacks 483 and break them. An infinite loop may occur if user code keeps 484 on performing the same operation without checking status, e.g. 485 reading from a closed stream etc. 486 487 The value of this parameter is as follows: should a callback return 488 this number of times in a row without making progress (that is, 489 reading, writing, or changing stream state), loop break will occur. 490 491 The defaut value is :macro:`LSQUIC_DF_PROGRESS_CHECK`. 492 493 .. member:: int es_rw_once 494 495 A non-zero value make stream dispatch its read-write events once 496 per call. 497 498 When zero, read and write events are dispatched until the stream 499 is no longer readable or writeable, respectively, or until the 500 user signals unwillingness to read or write using 501 :func:`lsquic_stream_wantread()` or :func:`lsquic_stream_wantwrite()` 502 or shuts down the stream. 503 504 The default value is :macro:`LSQUIC_DF_RW_ONCE`. 505 506 .. member:: unsigned es_proc_time_thresh 507 508 If set, this value specifies the number of microseconds that 509 :func:`lsquic_engine_process_conns()` and 510 :func:`lsquic_engine_send_unsent_packets()` are allowed to spend 511 before returning. 512 513 This is not an exact science and the connections must make 514 progress, so the deadline is checked after all connections get 515 a chance to tick (in the case of :func:`lsquic_engine_process_conns())` 516 and at least one batch of packets is sent out. 517 518 When processing function runs out of its time slice, immediate 519 calls to :func:`lsquic_engine_has_unsent_packets()` return false. 520 521 The default value is :func:`LSQUIC_DF_PROC_TIME_THRESH`. 522 523 .. member:: int es_pace_packets 524 525 If set to true, packet pacing is implemented per connection. 526 527 The default value is :func:`LSQUIC_DF_PACE_PACKETS`. 528 529 .. member:: unsigned es_clock_granularity 530 531 Clock granularity information is used by the pacer. The value 532 is in microseconds; default is :func:`LSQUIC_DF_CLOCK_GRANULARITY`. 533 534 .. member:: unsigned es_init_max_data 535 536 Initial max data. 537 538 This is a transport parameter. 539 540 Depending on the engine mode, the default value is either 541 :macro:`LSQUIC_DF_INIT_MAX_DATA_CLIENT` or 542 :macro:`LSQUIC_DF_INIT_MAX_DATA_SERVER`. 543 544 IETF QUIC only. 545 546 .. member:: unsigned es_init_max_stream_data_bidi_remote 547 548 Initial max stream data. 549 550 This is a transport parameter. 551 552 Depending on the engine mode, the default value is either 553 :macro:`LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_CLIENT` or 554 :macro:`LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_SERVER`. 555 556 IETF QUIC only. 557 558 .. member:: unsigned es_init_max_stream_data_bidi_local 559 560 Initial max stream data. 561 562 This is a transport parameter. 563 564 Depending on the engine mode, the default value is either 565 :macro:`LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_CLIENT` or 566 :macro:`LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_SERVER`. 567 568 IETF QUIC only. 569 570 .. member:: unsigned es_init_max_stream_data_uni 571 572 Initial max stream data for unidirectional streams initiated 573 by remote endpoint. 574 575 This is a transport parameter. 576 577 Depending on the engine mode, the default value is either 578 :macro:`LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_CLIENT` or 579 :macro:`LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER`. 580 581 IETF QUIC only. 582 583 .. member:: unsigned es_init_max_streams_bidi 584 585 Maximum initial number of bidirectional stream. 586 587 This is a transport parameter. 588 589 Default value is :macro:`LSQUIC_DF_INIT_MAX_STREAMS_BIDI`. 590 591 IETF QUIC only. 592 593 .. member:: unsigned es_init_max_streams_uni 594 595 Maximum initial number of unidirectional stream. 596 597 This is a transport parameter. 598 599 Default value is :macro:`LSQUIC_DF_INIT_MAX_STREAMS_UNI_CLIENT` or 600 :macro:`LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER`. 601 602 IETF QUIC only. 603 604 .. member:: unsigned es_idle_timeout 605 606 Idle connection timeout. 607 608 This is a transport parameter. 609 610 (Note: `es_idle_conn_to` is not reused because it is in microseconds, 611 which, I now realize, was not a good choice. Since it will be 612 obsoleted some time after the switchover to IETF QUIC, we do not 613 have to keep on using strange units.) 614 615 Default value is :macro:`LSQUIC_DF_IDLE_TIMEOUT`. 616 617 Maximum value is 600 seconds. 618 619 IETF QUIC only. 620 621 .. member:: unsigned es_ping_period 622 623 Ping period. If set to non-zero value, the connection will generate and 624 send PING frames in the absence of other activity. 625 626 By default, the server does not send PINGs and the period is set to zero. 627 The client's defaut value is :macro:`LSQUIC_DF_PING_PERIOD`. 628 629 IETF QUIC only. 630 631 .. member:: unsigned es_scid_len 632 633 Source Connection ID length. Valid values are 0 through 20, inclusive. 634 635 Default value is :macro:`LSQUIC_DF_SCID_LEN`. 636 637 IETF QUIC only. 638 639 .. member:: unsigned es_scid_iss_rate 640 641 Source Connection ID issuance rate. This field is measured in CIDs 642 per minute. Using value 0 indicates that there is no rate limit for 643 CID issuance. 644 645 Default value is :macro:`LSQUIC_DF_SCID_ISS_RATE`. 646 647 IETF QUIC only. 648 649 .. member:: unsigned es_qpack_dec_max_size 650 651 Maximum size of the QPACK dynamic table that the QPACK decoder will 652 use. 653 654 The default is :macro:`LSQUIC_DF_QPACK_DEC_MAX_SIZE`. 655 656 IETF QUIC only. 657 658 .. member:: unsigned es_qpack_dec_max_blocked 659 660 Maximum number of blocked streams that the QPACK decoder is willing 661 to tolerate. 662 663 The default is :macro:`LSQUIC_DF_QPACK_DEC_MAX_BLOCKED`. 664 665 IETF QUIC only. 666 667 .. member:: unsigned es_qpack_enc_max_size 668 669 Maximum size of the dynamic table that the encoder is willing to use. 670 The actual size of the dynamic table will not exceed the minimum of 671 this value and the value advertized by peer. 672 673 The default is :macro:`LSQUIC_DF_QPACK_ENC_MAX_SIZE`. 674 675 IETF QUIC only. 676 677 .. member:: unsigned es_qpack_enc_max_blocked 678 679 Maximum number of blocked streams that the QPACK encoder is willing 680 to risk. The actual number of blocked streams will not exceed the 681 minimum of this value and the value advertized by peer. 682 683 The default is :macro:`LSQUIC_DF_QPACK_ENC_MAX_BLOCKED`. 684 685 IETF QUIC only. 686 687 .. member:: int es_ecn 688 689 Enable ECN support. 690 691 The default is :macro:`LSQUIC_DF_ECN` 692 693 IETF QUIC only. 694 695 .. member:: int es_allow_migration 696 697 Allow peer to migrate connection. 698 699 The default is :macro:`LSQUIC_DF_ALLOW_MIGRATION` 700 701 IETF QUIC only. 702 703 .. member:: unsigned es_cc_algo 704 705 Congestion control algorithm to use. 706 707 - 0: Use default (:macro:`LSQUIC_DF_CC_ALGO`) 708 - 1: Cubic 709 - 2: BBRv1 710 - 3: Adaptive congestion control. 711 712 Adaptive congestion control adapts to the environment. It figures 713 out whether to use Cubic or BBRv1 based on the RTT. 714 715 .. member:: unsigned es_cc_rtt_thresh 716 717 Congestion controller RTT threshold in microseconds. 718 719 Adaptive congestion control uses BBRv1 until RTT is determined. At 720 that point a permanent choice of congestion controller is made. If 721 RTT is smaller than or equal to 722 :member:`lsquic_engine_settings.es_cc_rtt_thresh`, congestion 723 controller is switched to Cubic; otherwise, BBRv1 is picked. 724 725 The default value is :macro:`LSQUIC_DF_CC_RTT_THRESH` 726 727 .. member:: int es_ql_bits 728 729 Use QL loss bits. Allowed values are: 730 731 - 0: Do not use loss bits 732 - 1: Allow loss bits 733 - 2: Allow and send loss bits 734 735 Default value is :macro:`LSQUIC_DF_QL_BITS` 736 737 .. member:: int es_spin 738 739 Enable spin bit. Allowed values are 0 and 1. 740 741 Default value is :macro:`LSQUIC_DF_SPIN` 742 743 .. member:: int es_delayed_acks 744 745 Enable delayed ACKs extension. Allowed values are 0 and 1. 746 747 Default value is :macro:`LSQUIC_DF_DELAYED_ACKS` 748 749 .. member:: int es_timestamps 750 751 Enable timestamps extension. Allowed values are 0 and 1. 752 753 Default value is @ref LSQUIC_DF_TIMESTAMPS 754 755 .. member:: unsigned short es_max_udp_payload_size_rx 756 757 Maximum packet size we are willing to receive. This is sent to 758 peer in transport parameters: the library does not enforce this 759 limit for incoming packets. 760 761 If set to zero, limit is not set. 762 763 Default value is :macro:`LSQUIC_DF_MAX_UDP_PAYLOAD_SIZE_RX` 764 765 .. member:: int es_dplpmtud 766 767 If set to true value, enable DPLPMTUD -- Datagram Packetization 768 Layer Path MTU Discovery. 769 770 Default value is :macro:`LSQUIC_DF_DPLPMTUD` 771 772 .. member:: unsigned short es_base_plpmtu 773 774 PLPMTU size expected to work for most paths. 775 776 If set to zero, this value is calculated based on QUIC and IP versions. 777 778 Default value is :macro:`LSQUIC_DF_BASE_PLPMTU` 779 780 .. member:: unsigned short es_max_plpmtu 781 782 Largest PLPMTU size the engine will try. 783 784 If set to zero, picking this value is left to the engine. 785 786 Default value is :macro:`LSQUIC_DF_MAX_PLPMTU` 787 788 .. member:: unsigned es_mtu_probe_timer 789 790 This value specifies how long the DPLPMTUD probe timer is, in 791 milliseconds. :rfc:`8899` says: 792 793 PROBE_TIMER: The PROBE_TIMER is configured to expire after a period 794 longer than the maximum time to receive an acknowledgment to a 795 probe packet. This value MUST NOT be smaller than 1 second, and 796 SHOULD be larger than 15 seconds. Guidance on selection of the 797 timer value are provided in section 3.1.1 of the UDP Usage 798 Guidelines :rfc:`8085#section-3.1`. 799 800 If set to zero, the default is used. 801 802 Default value is :macro:`LSQUIC_DF_MTU_PROBE_TIMER` 803 804 .. member:: unsigned es_noprogress_timeout 805 806 No progress timeout. 807 808 If connection does not make progress for this number of seconds, the 809 connection is dropped. Here, progress is defined as user streams 810 being written to or read from. 811 812 If this value is zero, this timeout is disabled. 813 814 Default value is :macro:`LSQUIC_DF_NOPROGRESS_TIMEOUT_SERVER` in server 815 mode and :macro:`LSQUIC_DF_NOPROGRESS_TIMEOUT_CLIENT` in client mode. 816 817 .. member:: int es_grease_quic_bit 818 819 Enable the "QUIC bit grease" extension. When set to a true value, 820 lsquic will grease the QUIC bit on the outgoing QUIC packets if 821 the peer sent the "grease_quic_bit" transport parameter. 822 823 Default value is :macro:`LSQUIC_DF_GREASE_QUIC_BIT` 824 825 .. member:: int es_datagrams 826 827 Enable datagrams extension. Allowed values are 0 and 1. 828 829 Default value is :macro:`LSQUIC_DF_DATAGRAMS` 830 831 .. member:: int es_optimistic_nat 832 833 If set to true, changes in peer port are assumed to be due to a 834 benign NAT rebinding and path characteristics -- MTU, RTT, and 835 CC state -- are not reset. 836 837 Default value is :macro:`LSQUIC_DF_OPTIMISTIC_NAT` 838 839 .. member:: int es_ext_http_prio 840 841 If set to true, Extensible HTTP Priorities are enabled. This 842 is HTTP/3-only setting. 843 844 Default value is :macro:`LSQUIC_DF_EXT_HTTP_PRIO` 845 846 .. member:: int es_qpack_experiment 847 848 If set to 1, QPACK statistics are logged per connection. 849 850 If set to 2, QPACK experiments are run. In this mode, encoder 851 and decoder setting values are randomly selected (from the range 852 [0, whatever is specified in es_qpack_(enc|dec)_*]) and these 853 values along with compression ratio and user agent are logged at 854 NOTICE level when connection is destroyed. The purpose of these 855 experiments is to use compression performance statistics to figure 856 out a good set of default values. 857 858 Default value is :macro:`LSQUIC_DF_QPACK_EXPERIMENT` 859 860 .. member:: int es_delay_onclose 861 862 When set to true, :member:`lsquic_stream_if.on_close` will be delayed until the 863 peer acknowledges all data sent on the stream. (Or until the connection 864 is destroyed in some manner -- either explicitly closed by the user or 865 as a result of an engine shutdown.) To find out whether all data written 866 to peer has been acknowledged, use `lsquic_stream_has_unacked_data()`. 867 868 Default value is :macro:`LSQUIC_DF_DELAY_ONCLOSE` 869 870 .. member:: int es_max_batch_size 871 872 If set to a non-zero value, specifies maximum batch size. (The 873 batch of packets passed to :member:`lsquic_engine_api.ea_packets_out`). 874 Must be no larger than 1024. 875 876 Default value is :macro:`LSQUIC_DF_MAX_BATCH_SIZE` 877 878 .. member:: int es_check_tp_sanity 879 880 When true, sanity checks are performed on peer's transport parameter 881 values. If some limits are set suspiciously low, the connection won't 882 be established. 883 884 Default value is :macro:`LSQUIC_DF_CHECK_TP_SANITY` 885 886To initialize the settings structure to library defaults, use the following 887convenience function: 888 889.. function:: lsquic_engine_init_settings (struct lsquic_engine_settings *, unsigned flags) 890 891 ``flags`` is a bitmask of ``LSENG_SERVER`` and ``LSENG_HTTP`` 892 893After doing this, change just the settings you'd like. To check whether 894the values are correct, another convenience function is provided: 895 896.. function:: lsquic_engine_check_settings (const struct lsquic_engine_settings *, unsigned flags, char *err_buf, size_t err_buf_sz) 897 898 Check settings for errors. Return 0 if settings are OK, -1 otherwise. 899 900 If `err_buf` and `err_buf_sz` are set, an error string is written to the 901 buffers. 902 903The following macros in :file:`lsquic.h` specify default values: 904 905*Note that, despite our best efforts, documentation may accidentally get 906out of date. Please check your :file:`lsquic.h` for actual values.* 907 908.. macro:: LSQUIC_MIN_FCW 909 910 Minimum flow control window is set to 16 KB for both client and server. 911 This means we can send up to this amount of data before handshake gets 912 completed. 913 914.. macro:: LSQUIC_DF_VERSIONS 915 916 By default, deprecated and experimental versions are not included. 917 918.. macro:: LSQUIC_DF_CFCW_SERVER 919.. macro:: LSQUIC_DF_CFCW_CLIENT 920.. macro:: LSQUIC_DF_SFCW_SERVER 921.. macro:: LSQUIC_DF_SFCW_CLIENT 922.. macro:: LSQUIC_DF_MAX_STREAMS_IN 923 924.. macro:: LSQUIC_DF_INIT_MAX_DATA_SERVER 925.. macro:: LSQUIC_DF_INIT_MAX_DATA_CLIENT 926.. macro:: LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_SERVER 927.. macro:: LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_SERVER 928.. macro:: LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_REMOTE_CLIENT 929.. macro:: LSQUIC_DF_INIT_MAX_STREAM_DATA_BIDI_LOCAL_CLIENT 930.. macro:: LSQUIC_DF_INIT_MAX_STREAMS_BIDI 931.. macro:: LSQUIC_DF_INIT_MAX_STREAMS_UNI_CLIENT 932.. macro:: LSQUIC_DF_INIT_MAX_STREAMS_UNI_SERVER 933.. macro:: LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_CLIENT 934.. macro:: LSQUIC_DF_INIT_MAX_STREAM_DATA_UNI_SERVER 935 936.. macro:: LSQUIC_DF_IDLE_TIMEOUT 937 938 Default idle connection timeout is 30 seconds. 939 940.. macro:: LSQUIC_DF_PING_PERIOD 941 942 Default ping period is 15 seconds. 943 944.. macro:: LSQUIC_DF_HANDSHAKE_TO 945 946 Default handshake timeout is 10,000,000 microseconds (10 seconds). 947 948.. macro:: LSQUIC_DF_IDLE_CONN_TO 949 950 Default idle connection timeout is 30,000,000 microseconds. 951 952.. macro:: LSQUIC_DF_SILENT_CLOSE 953 954 By default, connections are closed silenty when they time out (no 955 ``CONNECTION_CLOSE`` frame is sent) and the server does not reply with 956 own ``CONNECTION_CLOSE`` after it receives one. 957 958.. macro:: LSQUIC_DF_MAX_HEADER_LIST_SIZE 959 960 Default value of maximum header list size. If set to non-zero value, 961 SETTINGS_MAX_HEADER_LIST_SIZE will be sent to peer after handshake is 962 completed (assuming the peer supports this setting frame type). 963 964.. macro:: LSQUIC_DF_UA 965 966 Default value of UAID (user-agent ID). 967 968.. macro:: LSQUIC_DF_MAX_INCHOATE 969 970 Default is 1,000,000. 971 972.. macro:: LSQUIC_DF_SUPPORT_NSTP 973 974 NSTP is not used by default. 975 976.. macro:: LSQUIC_DF_SUPPORT_PUSH 977 978 Push promises are supported by default. 979 980.. macro:: LSQUIC_DF_SUPPORT_TCID0 981 982 Support for TCID=0 is enabled by default. 983 984.. macro:: LSQUIC_DF_HONOR_PRST 985 986 By default, LSQUIC ignores Public Reset packets. 987 988.. macro:: LSQUIC_DF_SEND_PRST 989 990 By default, LSQUIC will not send Public Reset packets in response to 991 packets that specify unknown connections. 992 993.. macro:: LSQUIC_DF_PROGRESS_CHECK 994 995 By default, infinite loop checks are turned on. 996 997.. macro:: LSQUIC_DF_RW_ONCE 998 999 By default, read/write events are dispatched in a loop. 1000 1001.. macro:: LSQUIC_DF_PROC_TIME_THRESH 1002 1003 By default, the threshold is not enabled. 1004 1005.. macro:: LSQUIC_DF_PACE_PACKETS 1006 1007 By default, packets are paced 1008 1009.. macro:: LSQUIC_DF_CLOCK_GRANULARITY 1010 1011 Default clock granularity is 1000 microseconds. 1012 1013.. macro:: LSQUIC_DF_SCID_LEN 1014 1015 The default value is 8 for simplicity and speed. 1016 1017.. macro:: LSQUIC_DF_SCID_ISS_RATE 1018 1019 The default value is 60 CIDs per minute. 1020 1021.. macro:: LSQUIC_DF_QPACK_DEC_MAX_BLOCKED 1022 1023 Default value is 100. 1024 1025.. macro:: LSQUIC_DF_QPACK_DEC_MAX_SIZE 1026 1027 Default value is 4,096 bytes. 1028 1029.. macro:: LSQUIC_DF_QPACK_ENC_MAX_BLOCKED 1030 1031 Default value is 100. 1032 1033.. macro:: LSQUIC_DF_QPACK_ENC_MAX_SIZE 1034 1035 Default value is 4,096 bytes. 1036 1037.. macro:: LSQUIC_DF_ECN 1038 1039 ECN is disabled by default. 1040 1041.. macro:: LSQUIC_DF_ALLOW_MIGRATION 1042 1043 Allow migration by default. 1044 1045.. macro:: LSQUIC_DF_QL_BITS 1046 1047 Use QL loss bits by default. 1048 1049.. macro:: LSQUIC_DF_SPIN 1050 1051 Turn spin bit on by default. 1052 1053.. macro:: LSQUIC_DF_CC_ALGO 1054 1055 Use Adaptive Congestion Controller by default. 1056 1057.. macro:: LSQUIC_DF_CC_RTT_THRESH 1058 1059 Default value of the CC RTT threshold is 1500 microseconds 1060 1061.. macro:: LSQUIC_DF_DELAYED_ACKS 1062 1063 The Delayed ACKs extension is on by default. 1064 1065.. macro:: LSQUIC_DF_MAX_UDP_PAYLOAD_SIZE_RX 1066 1067 By default, incoming packet size is not limited. 1068 1069.. macro:: LSQUIC_DF_DPLPMTUD 1070 1071 By default, DPLPMTUD is enabled 1072 1073.. macro:: LSQUIC_DF_BASE_PLPMTU 1074 1075 By default, this value is left up to the engine. 1076 1077.. macro:: LSQUIC_DF_MAX_PLPMTU 1078 1079 By default, this value is left up to the engine. 1080 1081.. macro:: LSQUIC_DF_MTU_PROBE_TIMER 1082 1083 By default, we use the minimum timer of 1000 milliseconds. 1084 1085.. macro:: LSQUIC_DF_NOPROGRESS_TIMEOUT_SERVER 1086 1087 By default, drop no-progress connections after 60 seconds on the server. 1088 1089.. macro:: LSQUIC_DF_NOPROGRESS_TIMEOUT_CLIENT 1090 1091 By default, do not use no-progress timeout on the client. 1092 1093.. macro:: LSQUIC_DF_GREASE_QUIC_BIT 1094 1095 By default, greasing the QUIC bit is enabled (if peer sent 1096 the "grease_quic_bit" transport parameter). 1097 1098.. macro:: LSQUIC_DF_TIMESTAMPS 1099 1100 Timestamps are on by default. 1101 1102.. macro:: LSQUIC_DF_DATAGRAMS 1103 1104 Datagrams are off by default. 1105 1106.. macro:: LSQUIC_DF_OPTIMISTIC_NAT 1107 1108 Assume optimistic NAT by default. 1109 1110.. macro:: LSQUIC_DF_EXT_HTTP_PRIO 1111 1112 Turn on Extensible HTTP Priorities by default. 1113 1114.. macro:: LSQUIC_DF_QPACK_EXPERIMENT 1115 1116 By default, QPACK experiments are turned off. 1117 1118.. macro:: LSQUIC_DF_DELAY_ONCLOSE 1119 1120 By default, calling :member:`lsquic_stream_if.on_close()` is not delayed. 1121 1122.. macro:: LSQUIC_DF_MAX_BATCH_SIZE 1123 1124 By default, maximum batch size is not specified, leaving it up to the 1125 library. 1126 1127.. macro:: LSQUIC_DF_CHECK_TP_SANITY 1128 1129 Transport parameter sanity checks are performed by default. 1130 1131Receiving Packets 1132----------------- 1133 1134Incoming packets are supplied to the engine using :func:`lsquic_engine_packet_in()`. 1135It is up to the engine to decide what do to with the packet. It can find an existing 1136connection and dispatch the packet there, create a new connection (in server mode), or 1137schedule a version negotiation or stateless reset packet. 1138 1139.. function:: int lsquic_engine_packet_in (lsquic_engine_t *engine, const unsigned char *data, size_t size, const struct sockaddr *local, const struct sockaddr *peer, void *peer_ctx, int ecn) 1140 1141 Pass incoming packet to the QUIC engine. This function can be called 1142 more than once in a row. After you add one or more packets, call 1143 :func:`lsquic_engine_process_conns()` to schedule outgoing packets, if any. 1144 1145 :param engine: Engine instance. 1146 :param data: Pointer to UDP datagram payload. 1147 :param size: Size of UDP datagram. 1148 :param local: Local address. 1149 :param peer: Peer address. 1150 :param peer_ctx: Peer context. 1151 :param ecn: ECN marking associated with this UDP datagram. 1152 1153 :return: 1154 1155 - ``0``: Packet was processed by a real connection. 1156 - ``1``: Packet was handled successfully, but not by a connection. 1157 This may happen with version negotiation and public reset 1158 packets as well as some packets that may be ignored. 1159 - ``-1``: Some error occurred. Possible reasons are invalid packet 1160 size or failure to allocate memory. 1161 1162.. function:: int lsquic_engine_earliest_adv_tick (lsquic_engine_t *engine, int *diff) 1163 1164 Returns true if there are connections to be processed, false otherwise. 1165 1166 :param engine: 1167 1168 Engine instance. 1169 1170 :param diff: 1171 1172 If the function returns a true value, the pointed to integer is set to the 1173 difference between the earliest advisory tick time and now. 1174 If the former is in the past, this difference is negative. 1175 1176 :return: 1177 1178 True if there are connections to be processed, false otherwise. 1179 1180Sending Packets 1181--------------- 1182 1183User specifies a callback :type:`lsquic_packets_out_f` in :type:`lsquic_engine_api` 1184that the library uses to send packets. 1185 1186.. type:: struct lsquic_out_spec 1187 1188 This structure describes an outgoing packet. 1189 1190 .. member:: struct iovec *iov 1191 1192 A vector with payload. 1193 1194 .. member:: size_t iovlen 1195 1196 Vector length. 1197 1198 .. member:: const struct sockaddr *local_sa 1199 1200 Local address. 1201 1202 .. member:: const struct sockaddr *dest_sa 1203 1204 Destination address. 1205 1206 .. member:: void *peer_ctx 1207 1208 Peer context associated with the local address. 1209 1210 .. member:: int ecn 1211 1212 ECN: Valid values are 0 - 3. See :rfc:`3168`. 1213 1214 ECN may be set by IETF QUIC connections if ``es_ecn`` is set. 1215 1216.. type:: typedef int (*lsquic_packets_out_f)(void *packets_out_ctx, const struct lsquic_out_spec *out_spec, unsigned n_packets_out) 1217 1218 Returns number of packets successfully sent out or -1 on error. -1 should 1219 only be returned if no packets were sent out. If -1 is returned or if the 1220 return value is smaller than ``n_packets_out``, this indicates that sending 1221 of packets is not possible. 1222 1223 If not all packets could be sent out, then: 1224 1225 - errno is examined. If it is not EAGAIN or EWOULDBLOCK, the connection 1226 whose packet caused the error is closed forthwith. 1227 - No packets are attempted to be sent out until :func:`lsquic_engine_send_unsent_packets()` 1228 is called. 1229 1230.. function:: void lsquic_engine_process_conns (lsquic_engine_t *engine) 1231 1232 Process tickable connections. This function must be called often enough so 1233 that packets and connections do not expire. The preferred method of doing 1234 so is by using :func:`lsquic_engine_earliest_adv_tick()`. 1235 1236.. function:: int lsquic_engine_has_unsent_packets (lsquic_engine_t *engine) 1237 1238 Returns true if engine has some unsent packets. This happens if 1239 :member:`lsquic_engine_api.ea_packets_out` could not send everything out 1240 or if processing deadline was exceeded (see 1241 :member:`lsquic_engine_settings.es_proc_time_thresh`). 1242 1243.. function:: void lsquic_engine_send_unsent_packets (lsquic_engine_t *engine) 1244 1245 Send out as many unsent packets as possibe: until we are out of unsent 1246 packets or until ``ea_packets_out()`` fails. 1247 1248 If ``ea_packets_out()`` cannot send all packets, this function must be 1249 called to signify that sending of packets is possible again. 1250 1251Stream Callback Interface 1252------------------------- 1253 1254The stream callback interface structure lists the callbacks used by 1255the engine to communicate with the user code: 1256 1257.. type:: struct lsquic_stream_if 1258 1259 .. member:: lsquic_conn_ctx_t *(*on_new_conn)(void *stream_if_ctx, lsquic_conn_t *) 1260 1261 Called when a new connection has been created. In server mode, 1262 this means that the handshake has been successful. In client mode, 1263 on the other hand, this callback is called as soon as connection 1264 object is created inside the engine, but before the handshake is 1265 done. 1266 1267 The return value is the connection context associated with this 1268 connection. Use :func:`lsquic_conn_get_ctx()` to get back this 1269 context. It is OK for this function to return NULL. 1270 1271 This callback is mandatory. 1272 1273 .. member:: void (*on_conn_closed)(lsquic_conn_t *) 1274 1275 Connection is closed. 1276 1277 This callback is mandatory. 1278 1279 .. member:: lsquic_stream_ctx_t * (*on_new_stream)(void *stream_if_ctx, lsquic_stream_t *) 1280 1281 If you need to initiate a connection, call lsquic_conn_make_stream(). 1282 This will cause `on_new_stream` callback to be called when appropriate 1283 (this operation is delayed when maximum number of outgoing streams is 1284 reached). 1285 1286 If connection is going away, this callback may be called with the 1287 second parameter set to NULL. 1288 1289 The return value is the stream context associated with the stream. 1290 A pointer to it is passed to `on_read()`, `on_write()`, and `on_close()` 1291 callbacks. It is OK for this function to return NULL. 1292 1293 This callback is mandatory. 1294 1295 .. member:: void (*on_read) (lsquic_stream_t *s, lsquic_stream_ctx_t *h) 1296 1297 Stream is readable: either there are bytes to be read or an error 1298 is ready to be collected. 1299 1300 This callback is mandatory. 1301 1302 .. member:: void (*on_write) (lsquic_stream_t *s, lsquic_stream_ctx_t *h) 1303 1304 Stream is writeable. 1305 1306 This callback is mandatory. 1307 1308 .. member:: void (*on_close) (lsquic_stream_t *s, lsquic_stream_ctx_t *h) 1309 1310 After this callback returns, the stream is no longer accessible. This is 1311 a good time to clean up the stream context. 1312 1313 This callback is mandatory. 1314 1315 .. member:: void (*on_reset) (lsquic_stream_t *s, lsquic_stream_ctx_t *h, int how) 1316 1317 This callback is called as soon as the peer resets a stream. 1318 The argument `how` is either 0, 1, or 2, meaning "read", "write", and 1319 "read and write", respectively (just like in ``shutdown(2)``). This 1320 signals the user to stop reading, writing, or both. 1321 1322 Note that resets differ in gQUIC and IETF QUIC. In gQUIC, `how` is 1323 always 2; in IETF QUIC, `how` is either 0 or 1 because one can reset 1324 just one direction in IETF QUIC. 1325 1326 This callback is optional. The reset error can still be collected 1327 during next "on read" or "on write" event. 1328 1329 .. member:: void (*on_hsk_done)(lsquic_conn_t *c, enum lsquic_hsk_status s) 1330 1331 When handshake is completed, this callback is called. 1332 1333 This callback is optional. 1334 1335 .. member:: void (*on_goaway_received)(lsquic_conn_t *) 1336 1337 This is called when our side received GOAWAY frame. After this, 1338 new streams should not be created. 1339 1340 This callback is optional. 1341 1342 .. member:: void (*on_new_token)(lsquic_conn_t *c, const unsigned char *token, size_t token_size) 1343 1344 When client receives a token in NEW_TOKEN frame, this callback is called. 1345 1346 This callback is optional. 1347 1348 .. member:: void (*on_sess_resume_info)(lsquic_conn_t *c, const unsigned char *, size_t) 1349 1350 This callback lets client record information needed to 1351 perform session resumption next time around. 1352 1353 For IETF QUIC, this is called only if :member:`lsquic_engine_api.ea_get_ssl_ctx_st` 1354 is *not* set, in which case the library creates its own SSL_CTX. 1355 1356 Note: this callback will be deprecated when gQUIC support is removed. 1357 1358 This callback is optional. 1359 1360 .. member:: ssize_t (*on_dg_write)(lsquic_conn_t *c, void *buf, size_t buf_sz) 1361 1362 Called when datagram is ready to be written. Write at most 1363 ``buf_sz`` bytes to ``buf`` and return number of bytes 1364 written. 1365 1366 .. member:: void (*on_datagram)(lsquic_conn_t *c, const void *buf, size_t sz) 1367 1368 Called when datagram is read from a packet. This callback is 1369 required when :member:`lsquic_engine_settings.es_datagrams` is true. 1370 Take care to process it quickly, as this is called during 1371 :func:`lsquic_engine_packet_in()`. 1372 1373Creating Connections 1374-------------------- 1375 1376In server mode, the connections are created by the library based on incoming 1377packets. After handshake is completed, the library calls :member:`lsquic_stream_if.on_new_conn` 1378callback. 1379 1380In client mode, a new connection is created by 1381 1382.. function:: lsquic_conn_t * lsquic_engine_connect (lsquic_engine_t *engine, enum lsquic_version version, const struct sockaddr *local_sa, const struct sockaddr *peer_sa, void *peer_ctx, lsquic_conn_ctx_t *conn_ctx, const char *sni, unsigned short base_plpmtu, const unsigned char *sess_resume, size_t sess_resume_len, const unsigned char *token, size_t token_sz) 1383 1384 :param engine: Engine to use. 1385 1386 :param version: 1387 1388 To let the engine specify QUIC version, use N_LSQVER. If session resumption 1389 information is supplied, version is picked from there instead. 1390 1391 :param local_sa: 1392 1393 Local address. 1394 1395 :param peer_sa: 1396 1397 Address of the server. 1398 1399 :param peer_ctx: 1400 1401 Context associated with the peer. This is what gets passed to TODO. 1402 1403 :param conn_ctx: 1404 1405 Connection context can be set early using this parameter. Useful if 1406 you need the connection context to be available in `on_conn_new()`. 1407 Note that that callback's return value replaces the connection 1408 context set here. 1409 1410 :param sni: 1411 1412 The SNI is required for Google QUIC connections; it is optional for 1413 IETF QUIC and may be set to NULL. 1414 1415 :param base_plpmtu: 1416 1417 Base PLPMTU. If set to zero, it is selected based on the 1418 engine settings (see 1419 :member:`lsquic_engine_settings.es_base_plpmtu`), 1420 QUIC version, and IP version. 1421 1422 :param sess_resume: 1423 1424 Pointer to previously saved session resumption data needed for 1425 TLS resumption. May be NULL. 1426 1427 :param sess_resume_len: 1428 1429 Size of session resumption data. 1430 1431 :param token: 1432 1433 Pointer to previously received token to include in the Initial 1434 packet. Tokens are used by IETF QUIC to pre-validate client 1435 connections, potentially avoiding a retry. 1436 1437 See :member:`lsquic_stream_if.on_new_token` callback. 1438 1439 May be NULL. 1440 1441 :param token_sz: 1442 1443 Size of data pointed to by ``token``. 1444 1445Closing Connections 1446------------------- 1447 1448.. function:: void lsquic_conn_going_away (lsquic_conn_t *conn) 1449 1450 Mark connection as going away: send GOAWAY frame and do not accept 1451 any more incoming streams, nor generate streams of our own. 1452 1453 Only applicable to HTTP/3 and GQUIC connections. Otherwise a no-op. 1454 1455.. function:: void lsquic_conn_close (lsquic_conn_t *conn) 1456 1457 This closes the connection. :member:`lsquic_stream_if.on_conn_closed` 1458 and :member:`lsquic_stream_if.on_close` callbacks will be called. 1459 1460.. function:: void lsquic_conn_abort (lsquic_conn_t *conn) 1461 1462 This aborts the connection. The connection and all associated objects 1463 will be destroyed (with necessary callbacks called) during the next time 1464 :func:`lsquic_engine_process_conns()` is invoked. 1465 1466Creating Streams 1467---------------- 1468 1469Similar to connections, streams are created by the library in server mode; they 1470correspond to requests. In client mode, a new stream is created by 1471 1472.. function:: void lsquic_conn_make_stream (lsquic_conn_t *) 1473 1474 Create a new request stream. This causes :member:`on_new_stream()` callback 1475 to be called. If creating more requests is not permitted at the moment 1476 (due to number of concurrent streams limit), stream creation is registered 1477 as "pending" and the stream is created later when number of streams dips 1478 under the limit again. Any number of pending streams can be created. 1479 Use :func:`lsquic_conn_n_pending_streams()` and 1480 :func:`lsquic_conn_cancel_pending_streams()` to manage pending streams. 1481 1482 If connection is going away, :func:`on_new_stream()` is called with the 1483 stream parameter set to NULL. 1484 1485Stream Events 1486------------- 1487 1488To register or unregister an interest in a read or write event, use the 1489following functions: 1490 1491.. function:: int lsquic_stream_wantread (lsquic_stream_t *stream, int want) 1492 1493 :param stream: Stream to read from. 1494 :param want: Boolean value indicating whether the caller wants to read 1495 from stream. 1496 :return: Previous value of ``want`` or ``-1`` if the stream has already 1497 been closed for reading. 1498 1499 A stream becomes readable if there is was an error: for example, the 1500 peer may have reset the stream. In this case, reading from the stream 1501 will return an error. 1502 1503.. function:: int lsquic_stream_wantwrite (lsquic_stream_t *stream, int want) 1504 1505 :param stream: Stream to write to. 1506 :param want: Boolean value indicating whether the caller wants to write 1507 to stream. 1508 :return: Previous value of ``want`` or ``-1`` if the stream has already 1509 been closed for writing. 1510 1511Reading From Streams 1512-------------------- 1513 1514.. function:: ssize_t lsquic_stream_read (lsquic_stream_t *stream, unsigned char *buf, size_t sz) 1515 1516 :param stream: Stream to read from. 1517 :param buf: Buffer to copy data to. 1518 :param sz: Size of the buffer. 1519 :return: Number of bytes read, zero if EOS has been reached, or -1 on error. 1520 1521 Read up to ``sz`` bytes from ``stream`` into buffer ``buf``. 1522 1523 ``-1`` is returned on error, in which case ``errno`` is set: 1524 1525 - ``EBADF``: The stream is closed. 1526 - ``ECONNRESET``: The stream has been reset. 1527 - ``EWOULDBLOCK``: There is no data to be read. 1528 1529.. function:: ssize_t lsquic_stream_readv (lsquic_stream_t *stream, const struct iovec *vec, int iovcnt) 1530 1531 :param stream: Stream to read from. 1532 :param vec: Array of ``iovec`` structures. 1533 :param iovcnt: Number of elements in ``vec``. 1534 :return: Number of bytes read, zero if EOS has been reached, or -1 on error. 1535 1536 Similar to :func:`lsquic_stream_read()`, but reads data into a vector. 1537 1538.. function:: ssize_t lsquic_stream_readf (lsquic_stream_t *stream, size_t (*readf)(void *ctx, const unsigned char *buf, size_t len, int fin), void *ctx) 1539 1540 :param stream: Stream to read from. 1541 1542 :param readf: 1543 1544 The callback takes four parameters: 1545 1546 - Pointer to user-supplied context; 1547 - Pointer to the data; 1548 - Data size (can be zero); and 1549 - Indicator whether the FIN follows the data. 1550 1551 The callback returns number of bytes processed. If this number is zero 1552 or is smaller than ``len``, reading from stream stops. 1553 1554 :param ctx: Context pointer passed to ``readf``. 1555 1556 This function allows user-supplied callback to read the stream contents. 1557 It is meant to be used for zero-copy stream processing. 1558 1559 Return value and errors are same as in :func:`lsquic_stream_read()`. 1560 1561Writing To Streams 1562------------------ 1563 1564.. function:: ssize_t lsquic_stream_write (lsquic_stream_t *stream, const void *buf, size_t len) 1565 1566 :param stream: Stream to write to. 1567 :param buf: Buffer to copy data from. 1568 :param len: Number of bytes to copy. 1569 :return: Number of bytes written -- which may be smaller than ``len`` -- or a negative 1570 value when an error occurs. 1571 1572 Write ``len`` bytes to the stream. Returns number of bytes written, which 1573 may be smaller that ``len``. 1574 1575 A negative return value indicates a serious error (the library is likely 1576 to have aborted the connection because of it). 1577 1578.. function:: ssize_t lsquic_stream_writev (lsquic_stream_t *s, const struct iovec *vec, int count) 1579 1580 Like :func:`lsquic_stream_write()`, but read data from a vector. 1581 1582.. type:: struct lsquic_reader 1583 1584 Used as argument to :func:`lsquic_stream_writef()`. 1585 1586 .. member:: size_t (*lsqr_read) (void *lsqr_ctx, void *buf, size_t count) 1587 1588 :param lsqr_ctx: Pointer to user-specified context. 1589 :param buf: Memory location to write to. 1590 :param count: Size of available memory pointed to by ``buf``. 1591 :return: 1592 1593 Number of bytes written. This is not a ``ssize_t`` because 1594 the read function is not supposed to return an error. If an error 1595 occurs in the read function (for example, when reading from a file 1596 fails), it is supposed to deal with the error itself. 1597 1598 .. member:: size_t (*lsqr_size) (void *lsqr_ctx) 1599 1600 Return number of bytes remaining in the reader. 1601 1602 .. member:: void *lsqr_ctx 1603 1604 Context pointer passed both to ``lsqr_read()`` and to ``lsqr_size()``. 1605 1606.. function:: ssize_t lsquic_stream_writef (lsquic_stream_t *stream, struct lsquic_reader *reader) 1607 1608 :param stream: Stream to write to. 1609 :param reader: Reader to read from. 1610 :return: Number of bytes written or -1 on error. 1611 1612 Write to stream using :type:`lsquic_reader`. This is the most generic of 1613 the write functions -- :func:`lsquic_stream_write()` and 1614 :func:`lsquic_stream_writev()` utilize the same mechanism. 1615 1616.. function:: ssize_t lsquic_stream_pwritev (struct lsquic_stream *stream, ssize_t (*preadv)(void *user_data, const struct iovec *iov, int iovcnt), void *user_data, size_t n_to_write) 1617 1618 :param stream: Stream to write to. 1619 :param preadv: Pointer to a custom ``preadv(2)``-like function. 1620 :param user_data: Data to pass to ``preadv`` function. 1621 :param n_to_write: Number of bytes to write. 1622 :return: Number of bytes written or -1 on error. 1623 1624 Write to stream using user-supplied ``preadv()`` function. 1625 The stream allocates one or more packets and calls ``preadv()``, 1626 which then fills the array of buffers. This is a good way to 1627 minimize the number of ``read(2)`` system calls; the user can call 1628 ``preadv(2)`` instead. 1629 1630 The number of bytes available in the ``iov`` vector passed back to 1631 the user callback may be smaller than ``n_to_write``. The expected 1632 use pattern is to pass the number of bytes remaining in the file 1633 and keep on calling ``preadv(2)``. 1634 1635 Note that, unlike other stream-writing functions above, 1636 ``lsquic_stream_pwritev()`` does *not* buffer bytes inside the 1637 stream; it only writes to packets. That means the caller must be 1638 prepared for this function to return 0 even inside the "on write" 1639 stream callback. In that case, the caller should fall back to using 1640 another write function. 1641 1642 It is OK for the ``preadv`` callback to write fewer bytes that 1643 ``n_to_write``. (This can happen if the underlying data source 1644 is truncated.) 1645 1646:: 1647 1648 /* 1649 * For example, the return value of zero can be handled as follows: 1650 */ 1651 nw = lsquic_stream_pwritev(stream, my_readv, some_ctx, n_to_write); 1652 if (nw == 0) 1653 nw = lsquic_stream_write(stream, rem_bytes_buf, rem_bytes_len); 1654 1655.. function:: int lsquic_stream_flush (lsquic_stream_t *stream) 1656 1657 :param stream: Stream to flush. 1658 :return: 0 on success and -1 on failure. 1659 1660 Flush any buffered data. This triggers packetizing even a single byte 1661 into a separate frame. Flushing a closed stream is an error. 1662 1663Closing Streams 1664--------------- 1665 1666Streams can be closed for reading, writing, or both. 1667``on_close()`` callback is called at some point after a stream is closed 1668for both reading and writing, 1669 1670.. function:: int lsquic_stream_shutdown (lsquic_stream_t *stream, int how) 1671 1672 :param stream: Stream to shut down. 1673 :param how: 1674 1675 This parameter specifies what do to. Allowed values are: 1676 1677 - 0: Stop reading. 1678 - 1: Stop writing. 1679 - 2: Stop both reading and writing. 1680 1681 :return: 0 on success or -1 on failure. 1682 1683.. function:: int lsquic_stream_close (lsquic_stream_t *stream) 1684 1685 :param stream: Stream to close. 1686 :return: 0 on success or -1 on failure. 1687 1688Sending HTTP Headers 1689-------------------- 1690 1691.. type:: struct lsxpack_header 1692 1693This type is defined in _lsxpack_header.h_. See that header file for 1694more information. 1695 1696 .. member:: char *buf 1697 1698 the buffer for headers 1699 1700 .. member:: uint32_t name_hash 1701 1702 hash value for name 1703 1704 .. member:: uint32_t nameval_hash 1705 1706 hash value for name + value 1707 1708 .. member:: lsxpack_strlen_t name_offset 1709 1710 the offset for name in the buffer 1711 1712 .. member:: lsxpack_strlen_t name_len 1713 1714 the length of name 1715 1716 .. member:: lsxpack_strlen_t val_offset 1717 1718 the offset for value in the buffer 1719 1720 .. member:: lsxpack_strlen_t val_len 1721 1722 the length of value 1723 1724 .. member:: uint16_t chain_next_idx 1725 1726 mainly for cookie value chain 1727 1728 .. member:: uint8_t hpack_index 1729 1730 HPACK static table index 1731 1732 .. member:: uint8_t qpack_index 1733 1734 QPACK static table index 1735 1736 .. member:: uint8_t app_index 1737 1738 APP header index 1739 1740 .. member:: enum lsxpack_flag flags:8 1741 1742 combination of lsxpack_flag 1743 1744 .. member:: uint8_t indexed_type 1745 1746 control to disable index or not 1747 1748 .. member:: uint8_t dec_overhead 1749 1750 num of extra bytes written to decoded buffer 1751 1752.. type:: lsquic_http_headers_t 1753 1754 .. member:: int count 1755 1756 Number of headers in ``headers``. 1757 1758 .. member:: struct lsxpack_header *headers 1759 1760 Pointer to an array of HTTP headers. 1761 1762 HTTP header list structure. Contains a list of HTTP headers. 1763 1764.. function:: int lsquic_stream_send_headers (lsquic_stream_t *stream, const lsquic_http_headers_t *headers, int eos) 1765 1766 :param stream: 1767 1768 Stream to send headers on. 1769 1770 :param headers: 1771 1772 Headers to send. 1773 1774 :param eos: 1775 1776 Boolean value to indicate whether these headers constitute the whole 1777 HTTP message. 1778 1779 :return: 1780 1781 0 on success or -1 on error. 1782 1783Receiving HTTP Headers 1784---------------------- 1785 1786If ``ea_hsi_if`` is not set in :type:`lsquic_engine_api`, the library will translate 1787HPACK- and QPACK-encoded headers into HTTP/1.x-like headers and prepend them to the 1788stream. To the stream-reading function, it will look as if a standard HTTP/1.x 1789message. 1790 1791Alternatively, you can specify header-processing set of functions and manage header 1792fields yourself. In that case, the header set must be "read" from the stream via 1793:func:`lsquic_stream_get_hset()`. 1794 1795.. type:: struct lsquic_hset_if 1796 1797 .. member:: void * (*hsi_create_header_set)(void *hsi_ctx, lsquic_stream_t *stream, int is_push_promise) 1798 1799 :param hsi_ctx: User context. This is the pointer specifed in ``ea_hsi_ctx``. 1800 :param stream: Stream with which the header set is associated. May be set 1801 to NULL in server mode. 1802 :param is_push_promise: Boolean value indicating whether this header set is 1803 for a push promise. 1804 :return: Pointer to user-defined header set object. 1805 1806 Create a new header set. This object is (and must be) fetched from a 1807 stream by calling :func:`lsquic_stream_get_hset()` before the stream can 1808 be read. 1809 1810 .. member:: struct lsxpack_header * (*hsi_prepare_decode)(void *hdr_set, struct lsxpack_header *hdr, size_t space) 1811 1812 Return a header set prepared for decoding. If ``hdr`` is NULL, this 1813 means return a new structure with at least ``space`` bytes available 1814 in the decoder buffer. On success, a newly prepared header is 1815 returned. 1816 1817 If ``hdr`` is not NULL, it means there was not enough decoder buffer 1818 and it must be increased to at least ``space`` bytes. ``buf``, ``val_len``, 1819 and ``name_offset`` member of the ``hdr`` structure may change. On 1820 success, the return value is the same as ``hdr``. 1821 1822 If NULL is returned, the space cannot be allocated. 1823 1824 .. member:: int (*hsi_process_header)(void *hdr_set, struct lsxpack_header *hdr) 1825 1826 Process new header. 1827 1828 :param hdr_set: 1829 1830 Header set to add the new header field to. This is the object 1831 returned by ``hsi_create_header_set()``. 1832 1833 :param hdr: 1834 1835 The header returned by @ref ``hsi_prepare_decode()``. 1836 1837 :return: 1838 1839 Return 0 on success, a positive value if a header error occured, 1840 or a negative value on any other error. A positive return value 1841 will result in cancellation of associated stream. A negative return 1842 value will result in connection being aborted. 1843 1844 .. member:: void (*hsi_discard_header_set)(void *hdr_set) 1845 1846 :param hdr_set: Header set to discard. 1847 1848 Discard header set. This is called for unclaimed header sets and 1849 header sets that had an error. 1850 1851 .. member:: enum lsquic_hsi_flag hsi_flags 1852 1853 These flags specify properties of decoded headers passed to 1854 ``hsi_process_header()``. This is only applicable to QPACK headers; 1855 HPACK library header properties are based on compilation, not 1856 run-time, options. 1857 1858.. function:: void * lsquic_stream_get_hset (lsquic_stream_t *stream) 1859 1860 :param stream: Stream to fetch header set from. 1861 1862 :return: Header set associated with the stream. 1863 1864 Get header set associated with the stream. The header set is created by 1865 ``hsi_create_header_set()`` callback. After this call, the ownership of 1866 the header set is transferred to the caller. 1867 1868 This call must precede calls to :func:`lsquic_stream_read()`, 1869 :func:`lsquic_stream_readv()`, and :func:`lsquic_stream_readf()`. 1870 1871 If the optional header set interface is not specified, 1872 this function returns NULL. 1873 1874Push Promises 1875------------- 1876 1877.. function:: int lsquic_conn_push_stream (lsquic_conn_t *conn, void *hdr_set, lsquic_stream_t *stream, const lsquic_http_headers_t *headers) 1878 1879 :return: 1880 1881 - 0: Stream pushed successfully. 1882 - 1: Stream push failed because it is disabled or because we hit 1883 stream limit or connection is going away. 1884 - -1: Stream push failed because of an internal error. 1885 1886 A server may push a stream. This call creates a new stream in reference 1887 to stream ``stream``. It will behave as if the client made a request: it will 1888 trigger ``on_new_stream()`` event and it can be used as a regular client-initiated stream. 1889 1890 ``hdr_set`` must be set. It is passed as-is to :func:`lsquic_stream_get_hset()`. 1891 1892.. function:: int lsquic_conn_is_push_enabled (lsquic_conn_t *conn) 1893 1894 :return: Boolean value indicating whether push promises are enabled. 1895 1896 Only makes sense in server mode: the client cannot push a stream and this 1897 function always returns false in client mode. 1898 1899.. function:: int lsquic_stream_is_pushed (const lsquic_stream_t *stream) 1900 1901 :return: Boolean value indicating whether this is a pushed stream. 1902 1903.. function:: int lsquic_stream_refuse_push (lsquic_stream_t *stream) 1904 1905 Refuse pushed stream. Call it from ``on_new_stream()``. No need to 1906 call :func:`lsquic_stream_close()` after this. ``on_close()`` will be called. 1907 1908.. function:: int lsquic_stream_push_info (const lsquic_stream_t *stream, lsquic_stream_id_t *ref_stream_id, void **hdr_set) 1909 1910 Get information associated with pushed stream 1911 1912 :param ref_stream_id: Stream ID in response to which push promise was sent. 1913 :param hdr_set: Header set. This object was passed to or generated by :func:`lsquic_conn_push_stream()`. 1914 1915 :return: 0 on success and -1 if this is not a pushed stream. 1916 1917Stream Priorities 1918----------------- 1919 1920.. function:: unsigned lsquic_stream_priority (const lsquic_stream_t *stream) 1921 1922 Return current priority of the stream. 1923 1924.. function:: int lsquic_stream_set_priority (lsquic_stream_t *stream, unsigned priority) 1925 1926 Set stream priority. Valid priority values are 1 through 256, inclusive. 1927 Lower value means higher priority. 1928 1929 :return: 0 on success of -1 on failure (this happens if priority value is invalid). 1930 1931Miscellaneous Engine Functions 1932------------------------------ 1933 1934.. function:: unsigned lsquic_engine_quic_versions (const lsquic_engine_t *engine) 1935 1936 Return the list of QUIC versions (as bitmask) this engine instance supports. 1937 1938.. function:: unsigned lsquic_engine_count_attq (lsquic_engine_t *engine, int from_now) 1939 1940 Return number of connections whose advisory tick time is before current 1941 time plus ``from_now`` microseconds from now. ``from_now`` can be negative. 1942 1943Miscellaneous Connection Functions 1944---------------------------------- 1945 1946.. function:: enum lsquic_version lsquic_conn_quic_version (const lsquic_conn_t *conn) 1947 1948 Get QUIC version used by the connection. 1949 1950 If version has not yet been negotiated (can happen in client mode), ``-1`` is 1951 returned. 1952 1953.. function:: const lsquic_cid_t * lsquic_conn_id (const lsquic_conn_t *conn) 1954 1955 Get connection ID. 1956 1957.. function:: lsquic_engine_t * lsquic_conn_get_engine (lsquic_conn_t *conn) 1958 1959 Get pointer to the engine. 1960 1961.. function:: int lsquic_conn_get_sockaddr (lsquic_conn_t *conn, const struct sockaddr **local, const struct sockaddr **peer) 1962 1963 Get current (last used) addresses associated with the current path 1964 used by the connection. 1965 1966.. function:: struct stack_st_X509 * lsquic_conn_get_server_cert_chain (lsquic_conn_t *conn) 1967 1968 Get certificate chain returned by the server. This can be used for 1969 server certificate verification. 1970 1971 The caller releases the stack using sk_X509_free(). 1972 1973.. function:: lsquic_conn_ctx_t * lsquic_conn_get_ctx (const lsquic_conn_t *conn) 1974 1975 Get user-supplied context associated with the connection. 1976 1977.. function:: void lsquic_conn_set_ctx (lsquic_conn_t *conn, lsquic_conn_ctx_t *ctx) 1978 1979 Set user-supplied context associated with the connection. 1980 1981.. function:: void * lsquic_conn_get_peer_ctx (lsquic_conn_t *conn, const struct sockaddr *local_sa) 1982 1983 Get peer context associated with the connection and local address. 1984 1985.. function:: const char * lsquic_conn_get_sni (lsquic_conn_t *conn) 1986 1987 Get SNI sent by the client. 1988 1989.. function:: enum LSQUIC_CONN_STATUS lsquic_conn_status (lsquic_conn_t *conn, char *errbuf, size_t bufsz) 1990 1991 Get connection status. 1992 1993Miscellaneous Stream Functions 1994------------------------------ 1995 1996.. function:: unsigned lsquic_conn_n_avail_streams (const lsquic_conn_t *conn) 1997 1998 Return max allowed outbound streams less current outbound streams. 1999 2000.. function:: unsigned lsquic_conn_n_pending_streams (const lsquic_conn_t *conn) 2001 2002 Return number of delayed streams currently pending. 2003 2004.. function:: unsigned lsquic_conn_cancel_pending_streams (lsquic_conn_t *, unsigned n) 2005 2006 Cancel ``n`` pending streams. Returns new number of pending streams. 2007 2008.. function:: lsquic_conn_t * lsquic_stream_conn (const lsquic_stream_t *stream) 2009 2010 Get a pointer to the connection object. Use it with connection functions. 2011 2012.. function:: int lsquic_stream_is_rejected (const lsquic_stream_t *stream) 2013 2014 Returns true if this stream was rejected, false otherwise. Use this as 2015 an aid to distinguish between errors. 2016 2017.. function:: int lsquic_stream_has_unacked_data (const lsquic_stream_t *stream) 2018 2019 Return true if peer has not ACKed all data written to the stream. This 2020 includes both packetized and buffered data. 2021 2022Other Functions 2023--------------- 2024 2025.. function:: lsquic_conn_t lsquic_ssl_to_conn (const SSL *) 2026 2027 Get connection associated with this SSL object. 2028 2029.. function:: enum lsquic_version lsquic_str2ver (const char *str, size_t len) 2030 2031 Translate string QUIC version to LSQUIC QUIC version representation. 2032 2033.. function:: enum lsquic_version lsquic_alpn2ver (const char *alpn, size_t len) 2034 2035 Translate ALPN (e.g. "h3", "h3-23", "h3-Q046") to LSQUIC enum. 2036 2037Miscellaneous Types 2038------------------- 2039 2040.. type:: struct lsquic_shared_hash_if 2041 2042 The shared hash interface is used to share data between multiple LSQUIC instances. 2043 2044 .. member:: int (*shi_insert)(void *shi_ctx, void *key, unsigned key_sz, void *data, unsigned data_sz, time_t expiry) 2045 2046 :param shi_ctx: 2047 2048 Shared memory context pointer 2049 2050 :param key: 2051 2052 Key data. 2053 2054 :param key_sz: 2055 2056 Key size. 2057 2058 :param data: 2059 2060 Pointer to the data to store. 2061 2062 :param data_sz: 2063 2064 Data size. 2065 2066 :param expiry: When this item expires. If you want your item to never expire, set this to zero. 2067 2068 :return: 0 on success, -1 on failure. 2069 2070 If inserted successfully, ``free()`` will be called on ``data`` and ``key`` 2071 pointer when the element is deleted, whether due to expiration 2072 or explicit deletion. 2073 2074 .. member:: int (*shi_delete)(void *shi_ctx, const void *key, unsigned key_sz) 2075 2076 Delete item from shared hash 2077 2078 :return: 0 on success, -1 on failure. 2079 2080 .. member:: int (*shi_lookup)(void *shi_ctx, const void *key, unsigned key_sz, void **data, unsigned *data_sz) 2081 2082 :param shi_ctx: 2083 2084 Shared memory context pointer 2085 2086 :param key: 2087 2088 Key data. 2089 2090 :param key_sz: 2091 2092 Key size. 2093 2094 :param data: 2095 2096 Pointer to set to the result. 2097 2098 :param data_sz: 2099 2100 Pointer to the data size. 2101 2102 :return: 2103 2104 - ``1``: found. 2105 - ``0``: not found. 2106 - ``-1``: error (perhaps not enough room in ``data`` if copy was attempted). 2107 2108 The implementation may choose to copy the object into buffer pointed 2109 to by ``data``, so you should have it ready. 2110 2111.. type:: struct lsquic_packout_mem_if 2112 2113 The packet out memory interface is used by LSQUIC to get buffers to 2114 which outgoing packets will be written before they are passed to 2115 :member:`lsquic_engine_api.ea_packets_out` callback. 2116 2117 If not specified, malloc() and free() are used. 2118 2119 .. member:: void * (*pmi_allocate) (void *pmi_ctx, void *peer_ctx, lsquic_conn_get_ctx *conn_ctx, unsigned short sz, char is_ipv6) 2120 2121 Allocate buffer for sending. 2122 2123 .. member:: void (*pmi_release) (void *pmi_ctx, void *peer_ctx, void *buf, char is_ipv6) 2124 2125 This function is used to release the allocated buffer after it is 2126 sent via ``ea_packets_out()``. 2127 2128 .. member:: void (*pmi_return) (void *pmi_ctx, void *peer_ctx, void *buf, char is_ipv6) 2129 2130 If allocated buffer is not going to be sent, return it to the 2131 caller using this function. 2132 2133.. type:: typedef void (*lsquic_cids_update_f)(void *ctx, void **peer_ctx, const lsquic_cid_t *cids, unsigned n_cids) 2134 2135 :param ctx: 2136 2137 Context associated with the CID lifecycle callbacks (ea_cids_update_ctx). 2138 2139 :param peer_ctx: 2140 2141 Array of peer context pointers. 2142 2143 :param cids: 2144 2145 Array of connection IDs. 2146 2147 :param n_cids: 2148 2149 Number of elements in the peer context pointer and connection ID arrays. 2150 2151.. type:: enum lsquic_logger_timestamp_style 2152 2153 Enumerate timestamp styles supported by LSQUIC logger mechanism. 2154 2155 .. member:: LLTS_NONE 2156 2157 No timestamp is generated. 2158 2159 .. member:: LLTS_HHMMSSMS 2160 2161 The timestamp consists of 24 hours, minutes, seconds, and milliseconds. Example: 13:43:46.671 2162 2163 .. member:: LLTS_YYYYMMDD_HHMMSSMS 2164 2165 Like above, plus date, e.g: 2017-03-21 13:43:46.671 2166 2167 .. member:: LLTS_CHROMELIKE 2168 2169 This is Chrome-like timestamp used by proto-quic. The timestamp 2170 includes month, date, hours, minutes, seconds, and microseconds. 2171 2172 Example: 1223/104613.946956 (instead of 12/23 10:46:13.946956). 2173 2174 This is to facilitate reading two logs side-by-side. 2175 2176 .. member:: LLTS_HHMMSSUS 2177 2178 The timestamp consists of 24 hours, minutes, seconds, and microseconds. Example: 13:43:46.671123 2179 2180 .. member:: LLTS_YYYYMMDD_HHMMSSUS 2181 2182 Date and time using microsecond resolution, e.g: 2017-03-21 13:43:46.671123 2183 2184.. type:: enum LSQUIC_CONN_STATUS 2185 2186 .. member:: LSCONN_ST_HSK_IN_PROGRESS 2187 .. member:: LSCONN_ST_CONNECTED 2188 .. member:: LSCONN_ST_HSK_FAILURE 2189 .. member:: LSCONN_ST_GOING_AWAY 2190 .. member:: LSCONN_ST_TIMED_OUT 2191 .. member:: LSCONN_ST_RESET 2192 2193 If es_honor_prst is not set, the connection will never get public 2194 reset packets and this flag will not be set. 2195 2196 .. member:: LSCONN_ST_USER_ABORTED 2197 .. member:: LSCONN_ST_ERROR 2198 .. member:: LSCONN_ST_CLOSED 2199 .. member:: LSCONN_ST_PEER_GOING_AWAY 2200 2201.. type:: enum lsquic_hsi_flag 2202 2203 These flags are ORed together to specify properties of 2204 :type:`lsxpack_header` passed to :member:`lsquic_hset_if.hsi_process_header`. 2205 2206 .. member:: LSQUIC_HSI_HTTP1X 2207 2208 Turn HTTP/1.x mode on or off. In this mode, decoded name and value 2209 pair are separated by ``": "`` and ``"\r\n"`` is appended to the end 2210 of the string. By default, this mode is off. 2211 2212 .. member:: LSQUIC_HSI_HASH_NAME 2213 2214 Include name hash into lsxpack_header. 2215 2216 .. member:: LSQUIC_HSI_HASH_NAMEVAL 2217 2218 Include nameval hash into lsxpack_header. 2219 2220Global Variables 2221---------------- 2222 2223.. var:: const char *const lsquic_ver2str[N_LSQVER] 2224 2225 Convert LSQUIC version to human-readable string 2226 2227List of Log Modules 2228------------------- 2229 2230The following log modules are defined: 2231 2232- *alarmset*: Alarm processing. 2233- *bbr*: BBRv1 congestion controller. 2234- *bw-sampler*: Bandwidth sampler (used by BBR). 2235- *cfcw*: Connection flow control window. 2236- *conn*: Connection. 2237- *crypto*: Low-level Google QUIC cryptography tracing. 2238- *cubic*: Cubic congestion controller. 2239- *di*: "Data In" handler (storing incoming data before it is read). 2240- *eng-hist*: Engine history. 2241- *engine*: Engine. 2242- *event*: Cross-module significant events. 2243- *frame-reader*: Reader of the HEADERS stream in Google QUIC. 2244- *frame-writer*: Writer of the HEADERS stream in Google QUIC. 2245- *handshake*: Handshake and packet encryption and decryption. 2246- *hcsi-reader*: Reader of the HTTP/3 control stream. 2247- *hcso-writer*: Writer of the HTTP/3 control stream. 2248- *headers*: HEADERS stream (Google QUIC). 2249- *hsk-adapter*: 2250- *http1x*: Header conversion to HTTP/1.x. 2251- *logger*: Logger. 2252- *mini-conn*: Mini connection. 2253- *pacer*: Pacer. 2254- *parse*: Parsing. 2255- *prq*: PRQ stands for Packet Request Queue. This logs scheduling 2256 and sending packets not associated with a connection: version 2257 negotiation and stateless resets. 2258- *purga*: CID purgatory. 2259- *qdec-hdl*: QPACK decoder stream handler. 2260- *qenc-hdl*: QPACK encoder stream handler. 2261- *qlog*: QLOG output. At the moment, it is out of date. 2262- *qpack-dec*: QPACK decoder. 2263- *qpack-enc*: QPACK encoder. 2264- *sendctl*: Send controller. 2265- *sfcw*: Stream flow control window. 2266- *spi*: Stream priority iterator. 2267- *stream*: Stream operation. 2268- *tokgen*: Token generation and validation. 2269- *trapa*: Transport parameter processing. 2270 2271.. _extensible-http-priorities: 2272 2273Extensible HTTP Priorities 2274-------------------------- 2275 2276lsquic supports the 2277`Extensible HTTP Priorities Extension <https://tools.ietf.org/html/draft-ietf-httpbis-priority>`_. 2278It is enabled by default when HTTP/3 is used. The "urgency" and "incremental" 2279parameters are included into a dedicated type: 2280 2281.. type:: struct lsquic_ext_http_prio 2282 2283 .. member:: unsigned char urgency 2284 2285 This value's range is [0, 7], where 0 is the highest and 7 is 2286 the lowest urgency. 2287 2288 .. member:: signed char incremental 2289 2290 This is a boolean value. The valid range is [0, 1]. 2291 2292Some useful macros are also available: 2293 2294.. macro:: LSQUIC_MAX_HTTP_URGENCY 2295 2296The maximum value of the "urgency" parameter is 7. 2297 2298.. macro:: LSQUIC_DEF_HTTP_URGENCY 2299 2300The default value of the "urgency" parameter is 3. 2301 2302.. macro:: LSQUIC_DEF_HTTP_INCREMENTAL 2303 2304The default value of the "incremental" parameter is 0. 2305 2306There are two functions to 2307manage a stream's priority: 2308 2309.. function:: int lsquic_stream_get_http_prio (lsquic_stream_t \*stream, struct lsquic_ext_http_prio \*ehp) 2310 2311 Get a stream's priority information. 2312 2313 :param stream: The stream whose priority informaion we want. 2314 2315 :param ehp: Structure that is to be populated with the stream's 2316 priority information. 2317 2318 :return: Returns zero on success of a negative value on failure. 2319 A failure occurs if this is not an HTTP/3 stream or if 2320 Extensible HTTP Priorities have not been enabled. 2321 See :member:`lsquic_engine_settings.es_ext_http_prio`. 2322 2323.. function:: int lsquic_stream_set_http_prio (lsquic_stream_t \*stream, const struct lsquic_ext_http_prio \*ehp) 2324 2325 Set a stream's priority information. 2326 2327 :param stream: The stream whose priority we want to set. 2328 2329 :param ehp: Structure containing the stream's new priority information. 2330 2331 :return: Returns zero on success of a negative value on failure. 2332 A failure occurs if some internal error occured or if this 2333 is not an HTTP/3 stream or if Extensible HTTP Priorities 2334 haven't been enabled. 2335 See :member:`lsquic_engine_settings.es_ext_http_prio`. 2336 2337.. _apiref-datagrams: 2338 2339Datagrams 2340--------- 2341 2342lsquic supports the 2343`Unreliable Datagram Extension <https://tools.ietf.org/html/draft-pauly-quic-datagram-05>`_. 2344To enable datagrams, set :member:`lsquic_engine_settings.es_datagrams` to 2345true and specify 2346:member:`lsquic_stream_if.on_datagram` 2347and 2348:member:`lsquic_stream_if.on_dg_write` callbacks. 2349 2350.. function:: int lsquic_conn_want_datagram_write (lsquic_conn_t *conn, int want) 2351 2352 Indicate desire (or lack thereof) to write a datagram. 2353 2354 :param conn: Connection on which to send a datagram. 2355 :param want: Boolean value indicating whether the caller wants to write 2356 a datagram. 2357 :return: Previous value of ``want`` or ``-1`` if the datagrams cannot be 2358 written. 2359 2360.. function:: size_t lsquic_conn_get_min_datagram_size (lsquic_conn_t *conn) 2361 2362 Get minimum datagram size. By default, this value is zero. 2363 2364.. function:: int lsquic_conn_set_min_datagram_size (lsquic_conn_t *conn, size_t sz) 2365 2366 Set minimum datagram size. This is the minumum value of the buffer 2367 passed to the :member:`lsquic_stream_if.on_dg_write` callback. 2368 Returns 0 on success and -1 on error. 2369