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