1 /* 2 * nghttp3 3 * 4 * Copyright (c) 2018 nghttp3 contributors 5 * Copyright (c) 2017 ngtcp2 contributors 6 * Copyright (c) 2017 nghttp2 contributors 7 * 8 * Permission is hereby granted, free of charge, to any person obtaining 9 * a copy of this software and associated documentation files (the 10 * "Software"), to deal in the Software without restriction, including 11 * without limitation the rights to use, copy, modify, merge, publish, 12 * distribute, sublicense, and/or sell copies of the Software, and to 13 * permit persons to whom the Software is furnished to do so, subject to 14 * the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 23 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 24 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 25 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 26 */ 27 #ifndef NGHTTP3_H 28 #define NGHTTP3_H 29 30 /* Define WIN32 when build target is Win32 API (borrowed from 31 libcurl) */ 32 #if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32) 33 # define WIN32 34 #endif 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 #include <stdlib.h> 41 #if defined(_MSC_VER) && (_MSC_VER < 1800) 42 /* MSVC < 2013 does not have inttypes.h because it is not C99 43 compliant. See compiler macros and version number in 44 https://sourceforge.net/p/predef/wiki/Compilers/ */ 45 # include <stdint.h> 46 #else /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */ 47 # include <inttypes.h> 48 #endif /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */ 49 #include <sys/types.h> 50 #include <stdarg.h> 51 #include <stddef.h> 52 53 #include <nghttp3/version.h> 54 55 #ifdef NGHTTP3_STATICLIB 56 # define NGHTTP3_EXTERN 57 #elif defined(WIN32) 58 # ifdef BUILDING_NGHTTP3 59 # define NGHTTP3_EXTERN __declspec(dllexport) 60 # else /* !BUILDING_NGHTTP3 */ 61 # define NGHTTP3_EXTERN __declspec(dllimport) 62 # endif /* !BUILDING_NGHTTP3 */ 63 #else /* !defined(WIN32) */ 64 # ifdef BUILDING_NGHTTP3 65 # define NGHTTP3_EXTERN __attribute__((visibility("default"))) 66 # else /* !BUILDING_NGHTTP3 */ 67 # define NGHTTP3_EXTERN 68 # endif /* !BUILDING_NGHTTP3 */ 69 #endif /* !defined(WIN32) */ 70 71 /** 72 * @typedef 73 * 74 * :type:`nghttp3_ssize` is signed counterpart of size_t. 75 */ 76 typedef ptrdiff_t nghttp3_ssize; 77 78 /** 79 * @macro 80 * 81 * :macro:`NGHTTP3_ALPN_H3` is a serialized form of HTTP/3 ALPN 82 * protocol identifier this library supports. Notice that the first 83 * byte is the length of the following protocol identifier. 84 */ 85 #define NGHTTP3_ALPN_H3 "\x2h3" 86 87 /** 88 * @macrosection 89 * 90 * nghttp3 library error codes 91 */ 92 93 /** 94 * @macro 95 * 96 * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT` indicates that a passed 97 * argument is invalid. 98 */ 99 #define NGHTTP3_ERR_INVALID_ARGUMENT -101 100 /** 101 * @macro 102 * 103 * :macro:`NGHTTP3_ERR_NOBUF` indicates that a provided buffer does 104 * not have enough space to store data. 105 */ 106 #define NGHTTP3_ERR_NOBUF -102 107 /** 108 * @macro 109 * 110 * :macro:`NGHTTP3_ERR_INVALID_STATE` indicates that a requested 111 * operation is not allowed at the current connection state. 112 */ 113 #define NGHTTP3_ERR_INVALID_STATE -103 114 /** 115 * @macro 116 * 117 * :macro:`NGHTTP3_ERR_WOULDBLOCK` indicates that an operation might 118 * block. 119 */ 120 #define NGHTTP3_ERR_WOULDBLOCK -104 121 /** 122 * @macro 123 * 124 * :macro:`NGHTTP3_ERR_STREAM_IN_USE` indicates that a stream ID is 125 * already in use. 126 */ 127 #define NGHTTP3_ERR_STREAM_IN_USE -105 128 /** 129 * @macro 130 * 131 * :macro:`NGHTTP3_ERR_MALFORMED_HTTP_HEADER` indicates that an HTTP 132 * header field is malformed. 133 */ 134 #define NGHTTP3_ERR_MALFORMED_HTTP_HEADER -107 135 /** 136 * @macro 137 * 138 * :macro:`NGHTTP3_ERR_REMOVE_HTTP_HEADER` indicates that an HTTP 139 * header field is discarded. 140 */ 141 #define NGHTTP3_ERR_REMOVE_HTTP_HEADER -108 142 /** 143 * @macro 144 * 145 * :macro:`NGHTTP3_ERR_MALFORMED_HTTP_MESSAGING` indicates that HTTP 146 * messaging is malformed. 147 */ 148 #define NGHTTP3_ERR_MALFORMED_HTTP_MESSAGING -109 149 /** 150 * @macro 151 * 152 * :macro:`NGHTTP3_ERR_QPACK_FATAL` indicates that a fatal error is 153 * occurred during QPACK processing and it cannot be recoverable. 154 */ 155 #define NGHTTP3_ERR_QPACK_FATAL -111 156 /** 157 * @macro 158 * 159 * :macro:`NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE` indicates that a header 160 * field is too large to process. 161 */ 162 #define NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE -112 163 /** 164 * @macro 165 * 166 * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND` indicates that a stream is 167 * not found. 168 */ 169 #define NGHTTP3_ERR_STREAM_NOT_FOUND -114 170 /** 171 * @macro 172 * 173 * :macro:`NGHTTP3_ERR_CONN_CLOSING` indicates that a connection is 174 * closing state. 175 */ 176 #define NGHTTP3_ERR_CONN_CLOSING -116 177 /** 178 * @macro 179 * 180 * :macro:`NGHTTP3_ERR_STREAM_DATA_OVERFLOW` indicates that the length 181 * of stream data is too long and causes overflow. 182 */ 183 #define NGHTTP3_ERR_STREAM_DATA_OVERFLOW -117 184 /** 185 * @macro 186 * 187 * :macro:`NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED` indicates that a 188 * QPACK decompression failed. 189 */ 190 #define NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED -402 191 /** 192 * @macro 193 * 194 * :macro:`NGHTTP3_ERR_QPACK_ENCODER_STREAM_ERROR` indicates that an 195 * error occurred while reading QPACK encoder stream. 196 */ 197 #define NGHTTP3_ERR_QPACK_ENCODER_STREAM_ERROR -403 198 /** 199 * @macro 200 * 201 * :macro:`NGHTTP3_ERR_QPACK_DECODER_STREAM_ERROR` indicates that an 202 * error occurred while reading QPACK decoder stream. 203 */ 204 #define NGHTTP3_ERR_QPACK_DECODER_STREAM_ERROR -404 205 /** 206 * @macro 207 * 208 * :macro:`NGHTTP3_ERR_H3_FRAME_UNEXPECTED` indicates that an 209 * unexpected HTTP/3 frame is received. 210 */ 211 #define NGHTTP3_ERR_H3_FRAME_UNEXPECTED -408 212 /** 213 * @macro 214 * 215 * :macro:`NGHTTP3_ERR_H3_FRAME_ERROR` indicates that an HTTP/3 frame 216 * is malformed. 217 */ 218 #define NGHTTP3_ERR_H3_FRAME_ERROR -409 219 /** 220 * @macro 221 * 222 * :macro:`NGHTTP3_ERR_H3_MISSING_SETTINGS` indicates that an HTTP/3 223 * SETTINGS frame is missing. 224 */ 225 #define NGHTTP3_ERR_H3_MISSING_SETTINGS -665 226 /** 227 * @macro 228 * 229 * :macro:`NGHTTP3_ERR_H3_INTERNAL_ERROR` indicates an internal error. 230 */ 231 #define NGHTTP3_ERR_H3_INTERNAL_ERROR -667 232 /** 233 * @macro 234 * 235 * :macro:`NGHTTP3_ERR_H3_CLOSED_CRITICAL_STREAM` indicates that a 236 * critical stream is closed. 237 */ 238 #define NGHTTP3_ERR_H3_CLOSED_CRITICAL_STREAM -668 239 /** 240 * @macro 241 * 242 * :macro:`NGHTTP3_ERR_H3_GENERAL_PROTOCOL_ERROR` indicates a general 243 * protocol error. This is typically a catch-all error. 244 */ 245 #define NGHTTP3_ERR_H3_GENERAL_PROTOCOL_ERROR -669 246 /** 247 * @macro 248 * 249 * :macro:`NGHTTP3_ERR_H3_ID_ERROR` indicates that an ID related error 250 * occurred. 251 */ 252 #define NGHTTP3_ERR_H3_ID_ERROR -670 253 /** 254 * @macro 255 * 256 * :macro:`NGHTTP3_ERR_H3_SETTINGS_ERROR` indicates that an HTTP/3 257 * SETTINGS frame is malformed. 258 */ 259 #define NGHTTP3_ERR_H3_SETTINGS_ERROR -671 260 /** 261 * @macro 262 * 263 * :macro:`NGHTTP3_ERR_H3_STREAM_CREATION_ERROR` indicates that a 264 * remote endpoint attempts to create a new stream which is not 265 * allowed. 266 */ 267 #define NGHTTP3_ERR_H3_STREAM_CREATION_ERROR -672 268 /** 269 * @macro 270 * 271 * :macro:`NGHTTP3_ERR_FATAL` indicates that error codes less than 272 * this value is fatal error. When this error is returned, an 273 * endpoint should drop connection immediately. 274 */ 275 #define NGHTTP3_ERR_FATAL -900 276 /** 277 * @macro 278 * 279 * :macro:`NGHTTP3_ERR_NOMEM` indicates out of memory. 280 */ 281 #define NGHTTP3_ERR_NOMEM -901 282 /** 283 * @macro 284 * 285 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` indicates that user defined 286 * callback function failed. 287 */ 288 #define NGHTTP3_ERR_CALLBACK_FAILURE -902 289 290 /** 291 * @macrosection 292 * 293 * HTTP/3 application error code 294 */ 295 296 /** 297 * @macro 298 * 299 * :macro:`NGHTTP3_H3_NO_ERROR` is HTTP/3 application error code 300 * ``H3_NO_ERROR``. 301 */ 302 #define NGHTTP3_H3_NO_ERROR 0x0100 303 /** 304 * @macro 305 * 306 * :macro:`NGHTTP3_H3_GENERAL_PROTOCOL_ERROR` is HTTP/3 application 307 * error code ``H3_GENERAL_PROTOCOL_ERROR``. 308 */ 309 #define NGHTTP3_H3_GENERAL_PROTOCOL_ERROR 0x0101 310 /** 311 * @macro 312 * 313 * :macro:`NGHTTP3_H3_INTERNAL_ERROR` is HTTP/3 application error code 314 * ``H3_INTERNAL_ERROR``. 315 */ 316 #define NGHTTP3_H3_INTERNAL_ERROR 0x0102 317 /** 318 * @macro 319 * 320 * :macro:`NGHTTP3_H3_STREAM_CREATION_ERROR` is HTTP/3 application 321 * error code ``H3_STREAM_CREATION_ERROR``. 322 */ 323 #define NGHTTP3_H3_STREAM_CREATION_ERROR 0x0103 324 /** 325 * @macro 326 * 327 * :macro:`NGHTTP3_H3_CLOSED_CRITICAL_STREAM` is HTTP/3 application 328 * error code ``H3_CLOSED_CRITICAL_STREAM``. 329 */ 330 #define NGHTTP3_H3_CLOSED_CRITICAL_STREAM 0x0104 331 /** 332 * @macro 333 * 334 * :macro:`NGHTTP3_H3_FRAME_UNEXPECTED` is HTTP/3 application error 335 * code ``H3_FRAME_UNEXPECTED``. 336 */ 337 #define NGHTTP3_H3_FRAME_UNEXPECTED 0x0105 338 /** 339 * @macro 340 * 341 * :macro:`NGHTTP3_H3_FRAME_ERROR` is HTTP/3 application error code 342 * ``H3_FRAME_ERROR``. 343 */ 344 #define NGHTTP3_H3_FRAME_ERROR 0x0106 345 /** 346 * @macro 347 * 348 * :macro:`NGHTTP3_H3_EXCESSIVE_LOAD` is HTTP/3 application error code 349 * ``H3_EXCESSIVE_LOAD``. 350 */ 351 #define NGHTTP3_H3_EXCESSIVE_LOAD 0x0107 352 /** 353 * @macro 354 * 355 * :macro:`NGHTTP3_H3_ID_ERROR` is HTTP/3 application error code 356 * ``H3_ID_ERROR``. 357 */ 358 #define NGHTTP3_H3_ID_ERROR 0x0108 359 /** 360 * @macro 361 * 362 * :macro:`NGHTTP3_H3_SETTINGS_ERROR` is HTTP/3 application error code 363 * ``H3_SETTINGS_ERROR``. 364 */ 365 #define NGHTTP3_H3_SETTINGS_ERROR 0x0109 366 /** 367 * @macro 368 * 369 * :macro:`NGHTTP3_H3_MISSING_SETTINGS` is HTTP/3 application error 370 * code ``H3_MISSING_SETTINGS``. 371 */ 372 #define NGHTTP3_H3_MISSING_SETTINGS 0x010a 373 /** 374 * @macro 375 * 376 * :macro:`NGHTTP3_H3_REQUEST_REJECTED` is HTTP/3 application error 377 * code ``H3_REQUEST_REJECTED``. 378 */ 379 #define NGHTTP3_H3_REQUEST_REJECTED 0x010b 380 /** 381 * @macro 382 * 383 * :macro:`NGHTTP3_H3_REQUEST_CANCELLED` is HTTP/3 application error 384 * code ``H3_REQUEST_CANCELLED``. 385 */ 386 #define NGHTTP3_H3_REQUEST_CANCELLED 0x010c 387 /** 388 * @macro 389 * 390 * :macro:`NGHTTP3_H3_REQUEST_INCOMPLETE` is HTTP/3 application error 391 * code ``H3_REQUEST_INCOMPLETE``. 392 */ 393 #define NGHTTP3_H3_REQUEST_INCOMPLETE 0x010d 394 /** 395 * @macro 396 * 397 * :macro:`NGHTTP3_H3_MESSAGE_ERROR` is HTTP/3 application error code 398 * ``H3_MESSAGE_ERROR``. 399 */ 400 #define NGHTTP3_H3_MESSAGE_ERROR 0x010e 401 /** 402 * @macro 403 * 404 * :macro:`NGHTTP3_H3_CONNECT_ERROR` is HTTP/3 application error code 405 * ``H3_CONNECT_ERROR``. 406 */ 407 #define NGHTTP3_H3_CONNECT_ERROR 0x010f 408 /** 409 * @macro 410 * 411 * :macro:`NGHTTP3_H3_VERSION_FALLBACK` is HTTP/3 application error 412 * code ``H3_VERSION_FALLBACK``. 413 */ 414 #define NGHTTP3_H3_VERSION_FALLBACK 0x0110 415 /** 416 * @macro 417 * 418 * :macro:`NGHTTP3_QPACK_DECOMPRESSION_FAILED` is HTTP/3 application 419 * error code ``QPACK_DECOMPRESSION_FAILED``. 420 */ 421 #define NGHTTP3_QPACK_DECOMPRESSION_FAILED 0x0200 422 /** 423 * @macro 424 * 425 * :macro:`NGHTTP3_QPACK_ENCODER_STREAM_ERROR` is HTTP/3 application 426 * error code ``QPACK_ENCODER_STREAM_ERROR``. 427 */ 428 #define NGHTTP3_QPACK_ENCODER_STREAM_ERROR 0x0201 429 /** 430 * @macro 431 * 432 * :macro:`NGHTTP3_QPACK_DECODER_STREAM_ERROR` is HTTP/3 application 433 * error code ``QPACK_DECODER_STREAM_ERROR``. 434 */ 435 #define NGHTTP3_QPACK_DECODER_STREAM_ERROR 0x0202 436 437 /** 438 * @functypedef 439 * 440 * Custom memory allocator to replace :manpage:`malloc(3)`. The 441 * |mem_user_data| is the mem_user_data member of :type:`nghttp3_mem` 442 * structure. 443 */ 444 typedef void *(*nghttp3_malloc)(size_t size, void *mem_user_data); 445 446 /** 447 * @functypedef 448 * 449 * Custom memory allocator to replace :manpage:`free(3)`. The 450 * |mem_user_data| is the mem_user_data member of :type:`nghttp3_mem` 451 * structure. 452 */ 453 typedef void (*nghttp3_free)(void *ptr, void *mem_user_data); 454 455 /** 456 * @functypedef 457 * 458 * Custom memory allocator to replace :manpage:`calloc(3)`. The 459 * |mem_user_data| is the mem_user_data member of :type:`nghttp3_mem` 460 * structure. 461 */ 462 typedef void *(*nghttp3_calloc)(size_t nmemb, size_t size, void *mem_user_data); 463 464 /** 465 * @functypedef 466 * 467 * Custom memory allocator to replace :manpage:`realloc(3)`. The 468 * |mem_user_data| is the mem_user_data member of :type:`nghttp3_mem` 469 * structure. 470 */ 471 typedef void *(*nghttp3_realloc)(void *ptr, size_t size, void *mem_user_data); 472 473 /** 474 * @struct 475 * 476 * :type:`nghttp3_mem` is a custom memory allocator functions and user 477 * defined pointer. The |mem_user_data| member is passed to each 478 * allocator function. This can be used, for example, to achieve 479 * per-session memory pool. 480 * 481 * In the following example code, ``my_malloc``, ``my_free``, 482 * ``my_calloc`` and ``my_realloc`` are the replacement of the 483 * standard allocators :manpage:`malloc(3)`, :manpage:`free(3)`, 484 * :manpage:`calloc(3)` and :manpage:`realloc(3)` respectively:: 485 * 486 * void *my_malloc_cb(size_t size, void *mem_user_data) { 487 * return my_malloc(size); 488 * } 489 * 490 * void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); } 491 * 492 * void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) { 493 * return my_calloc(nmemb, size); 494 * } 495 * 496 * void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) { 497 * return my_realloc(ptr, size); 498 * } 499 * 500 * void conn_new() { 501 * nghttp3_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb, 502 * my_realloc_cb}; 503 * 504 * ... 505 * } 506 */ 507 typedef struct nghttp3_mem { 508 /** 509 * :member:`mem_user_data` is an arbitrary user supplied data. This 510 * is passed to each allocator function. 511 */ 512 void *mem_user_data; 513 /** 514 * :member:`malloc` is a custom allocator function to replace 515 * :manpage:`malloc(3)`. 516 */ 517 nghttp3_malloc malloc; 518 /** 519 * :member:`free` is a custom allocator function to replace 520 * :manpage:`free(3)`. 521 */ 522 nghttp3_free free; 523 /** 524 * :member:`calloc` is a custom allocator function to replace 525 * :manpage:`calloc(3)`. 526 */ 527 nghttp3_calloc calloc; 528 /** 529 * :member:`realloc` is a custom allocator function to replace 530 * :manpage:`realloc(3)`. 531 */ 532 nghttp3_realloc realloc; 533 } nghttp3_mem; 534 535 /** 536 * @function 537 * 538 * `nghttp3_mem_default` returns the default memory allocator which 539 * uses malloc/calloc/realloc/free. 540 */ 541 NGHTTP3_EXTERN const nghttp3_mem *nghttp3_mem_default(void); 542 543 /** 544 * @struct 545 * 546 * :type:`nghttp3_vec` is ``struct iovec`` compatible structure to 547 * reference arbitrary array of bytes. 548 */ 549 typedef struct nghttp3_vec { 550 /** 551 * :member:`base` points to the data. 552 */ 553 uint8_t *base; 554 /** 555 * :member:`len` is the number of bytes which the buffer pointed by 556 * base contains. 557 */ 558 size_t len; 559 } nghttp3_vec; 560 561 /** 562 * @struct 563 * 564 * :type:`nghttp3_rcbuf` is the object representing reference counted 565 * buffer. The details of this structure are intentionally hidden 566 * from the public API. 567 */ 568 typedef struct nghttp3_rcbuf nghttp3_rcbuf; 569 570 /** 571 * @function 572 * 573 * `nghttp3_rcbuf_incref` increments the reference count of |rcbuf| by 574 * 1. 575 */ 576 NGHTTP3_EXTERN void nghttp3_rcbuf_incref(nghttp3_rcbuf *rcbuf); 577 578 /** 579 * @function 580 * 581 * `nghttp3_rcbuf_decref` decrements the reference count of |rcbuf| by 582 * 1. If the reference count becomes zero, the object pointed by 583 * |rcbuf| will be freed. In this case, application must not use 584 * |rcbuf| again. 585 */ 586 NGHTTP3_EXTERN void nghttp3_rcbuf_decref(nghttp3_rcbuf *rcbuf); 587 588 /** 589 * @function 590 * 591 * `nghttp3_rcbuf_get_buf` returns the underlying buffer managed by 592 * |rcbuf|. 593 */ 594 NGHTTP3_EXTERN nghttp3_vec nghttp3_rcbuf_get_buf(const nghttp3_rcbuf *rcbuf); 595 596 /** 597 * @function 598 * 599 * `nghttp3_rcbuf_is_static` returns nonzero if the underlying buffer 600 * is statically allocated, and 0 otherwise. This can be useful for 601 * language bindings that wish to avoid creating duplicate strings for 602 * these buffers. 603 */ 604 NGHTTP3_EXTERN int nghttp3_rcbuf_is_static(const nghttp3_rcbuf *rcbuf); 605 606 /** 607 * @struct 608 * 609 * :type:`nghttp3_buf` is the variable size buffer. 610 */ 611 typedef struct nghttp3_buf { 612 /** 613 * :member:`begin` points to the beginning of the buffer. 614 */ 615 uint8_t *begin; 616 /** 617 * :member:`end` points to the one beyond of the last byte of the 618 * buffer 619 */ 620 uint8_t *end; 621 /** 622 * :member:`pos` pointers to the start of data. Typically, this 623 * points to the point that next data should be read. Initially, it 624 * points to :member:`begin`. 625 */ 626 uint8_t *pos; 627 /** 628 * :member:`last` points to the one beyond of the last data of the 629 * buffer. Typically, new data is written at this point. 630 * Initially, it points to :member:`begin`. 631 */ 632 uint8_t *last; 633 } nghttp3_buf; 634 635 /** 636 * @function 637 * 638 * `nghttp3_buf_init` initializes empty |buf|. 639 */ 640 NGHTTP3_EXTERN void nghttp3_buf_init(nghttp3_buf *buf); 641 642 /** 643 * @function 644 * 645 * `nghttp3_buf_free` frees resources allocated for |buf| using |mem| 646 * as memory allocator. :member:`buf->begin <nghttp3_buf.begin>` must 647 * be a heap buffer allocated by |mem|. 648 */ 649 NGHTTP3_EXTERN void nghttp3_buf_free(nghttp3_buf *buf, const nghttp3_mem *mem); 650 651 /** 652 * @function 653 * 654 * `nghttp3_buf_left` returns the number of additional bytes which can 655 * be written to the underlying buffer. In other words, it returns 656 * :member:`buf->end <nghttp3_buf.end>` - :member:`buf->last 657 * <nghttp3_buf.last>`. 658 */ 659 NGHTTP3_EXTERN size_t nghttp3_buf_left(const nghttp3_buf *buf); 660 661 /** 662 * @function 663 * 664 * `nghttp3_buf_len` returns the number of bytes left to read. In 665 * other words, it returns :member:`buf->last <nghttp3_buf.last>` - 666 * :member:`buf->pos <nghttp3_buf.pos>`. 667 */ 668 NGHTTP3_EXTERN size_t nghttp3_buf_len(const nghttp3_buf *buf); 669 670 /** 671 * @function 672 * 673 * `nghttp3_buf_reset` sets :member:`buf->pos <nghttp3_buf.pos>` and 674 * :member:`buf->last <nghttp3_buf.last>` to :member:`buf->begin 675 * <nghttp3_buf.begin>`. 676 */ 677 NGHTTP3_EXTERN void nghttp3_buf_reset(nghttp3_buf *buf); 678 679 /** 680 * @macrosection 681 * 682 * Flags for header field name/value pair 683 */ 684 685 /** 686 * @macro 687 * 688 * :macro:`NGHTTP3_NV_FLAG_NONE` indicates no flag set. 689 */ 690 #define NGHTTP3_NV_FLAG_NONE 0 691 692 /** 693 * @macro 694 * 695 * :macro:`NGHTTP3_NV_FLAG_NEVER_INDEX` indicates that this name/value 696 * pair must not be indexed. Other implementation calls this bit as 697 * "sensitive". 698 */ 699 #define NGHTTP3_NV_FLAG_NEVER_INDEX 0x01 700 701 /** 702 * @macro 703 * 704 * :macro:`NGHTTP3_NV_FLAG_NO_COPY_NAME` is set solely by application. 705 * If this flag is set, the library does not make a copy of header 706 * field name. This could improve performance. 707 */ 708 #define NGHTTP3_NV_FLAG_NO_COPY_NAME 0x02 709 710 /** 711 * @macro 712 * 713 * :macro:`NGHTTP3_NV_FLAG_NO_COPY_VALUE` is set solely by 714 * application. If this flag is set, the library does not make a copy 715 * of header field value. This could improve performance. 716 */ 717 #define NGHTTP3_NV_FLAG_NO_COPY_VALUE 0x04 718 719 /** 720 * @struct 721 * 722 * :type:`nghttp3_nv` is the name/value pair, which mainly used to 723 * represent header fields. 724 */ 725 typedef struct nghttp3_nv { 726 /** 727 * :member:`name` is the header field name. 728 */ 729 uint8_t *name; 730 /** 731 * :member:`value` is the header field value. 732 */ 733 uint8_t *value; 734 /** 735 * :member:`namelen` is the length of the |name|, excluding 736 * terminating NULL. 737 */ 738 size_t namelen; 739 /** 740 * :member:`valuelen` is the length of the |value|, excluding 741 * terminating NULL. 742 */ 743 size_t valuelen; 744 /** 745 * :member:`flags` is bitwise OR of one or more of 746 * NGHTTP3_NV_FLAG_*. 747 */ 748 uint8_t flags; 749 } nghttp3_nv; 750 751 /* Generated by mkstatichdtbl.py */ 752 /** 753 * @enum 754 * 755 * :type:`nghttp3_qpack_token` defines HTTP header field name tokens 756 * to identify field name quickly. It appears in 757 * :member:`nghttp3_qpack_nv.token`. 758 */ 759 typedef enum nghttp3_qpack_token { 760 /** 761 * :enum:`NGHTTP3_QPACK_TOKEN__AUTHORITY` is a token for 762 * ``:authority``. 763 */ 764 NGHTTP3_QPACK_TOKEN__AUTHORITY = 0, 765 /** 766 * :enum:`NGHTTP3_QPACK_TOKEN__PATH` is a token for ``:path``. 767 */ 768 NGHTTP3_QPACK_TOKEN__PATH = 8, 769 /** 770 * :enum:`NGHTTP3_QPACK_TOKEN_AGE` is a token for ``age``. 771 */ 772 NGHTTP3_QPACK_TOKEN_AGE = 43, 773 /** 774 * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_DISPOSITION` is a token for 775 * ``content-disposition``. 776 */ 777 NGHTTP3_QPACK_TOKEN_CONTENT_DISPOSITION = 52, 778 /** 779 * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_LENGTH` is a token for 780 * ``content-length``. 781 */ 782 NGHTTP3_QPACK_TOKEN_CONTENT_LENGTH = 55, 783 /** 784 * :enum:`NGHTTP3_QPACK_TOKEN_COOKIE` is a token for ``cookie``. 785 */ 786 NGHTTP3_QPACK_TOKEN_COOKIE = 68, 787 /** 788 * :enum:`NGHTTP3_QPACK_TOKEN_DATE` is a token for ``date``. 789 */ 790 NGHTTP3_QPACK_TOKEN_DATE = 69, 791 /** 792 * :enum:`NGHTTP3_QPACK_TOKEN_ETAG` is a token for ``etag``. 793 */ 794 NGHTTP3_QPACK_TOKEN_ETAG = 71, 795 /** 796 * :enum:`NGHTTP3_QPACK_TOKEN_IF_MODIFIED_SINCE` is a token for 797 * ``if-modified-since``. 798 */ 799 NGHTTP3_QPACK_TOKEN_IF_MODIFIED_SINCE = 74, 800 /** 801 * :enum:`NGHTTP3_QPACK_TOKEN_IF_NONE_MATCH` is a token for 802 * ``if-none-match``. 803 */ 804 NGHTTP3_QPACK_TOKEN_IF_NONE_MATCH = 75, 805 /** 806 * :enum:`NGHTTP3_QPACK_TOKEN_LAST_MODIFIED` is a token for 807 * ``last-modified``. 808 */ 809 NGHTTP3_QPACK_TOKEN_LAST_MODIFIED = 77, 810 /** 811 * :enum:`NGHTTP3_QPACK_TOKEN_LINK` is a token for ``link``. 812 */ 813 NGHTTP3_QPACK_TOKEN_LINK = 78, 814 /** 815 * :enum:`NGHTTP3_QPACK_TOKEN_LOCATION` is a token for ``location``. 816 */ 817 NGHTTP3_QPACK_TOKEN_LOCATION = 79, 818 /** 819 * :enum:`NGHTTP3_QPACK_TOKEN_REFERER` is a token for ``referer``. 820 */ 821 NGHTTP3_QPACK_TOKEN_REFERER = 83, 822 /** 823 * :enum:`NGHTTP3_QPACK_TOKEN_SET_COOKIE` is a token for 824 * ``set-cookie``. 825 */ 826 NGHTTP3_QPACK_TOKEN_SET_COOKIE = 85, 827 /** 828 * :enum:`NGHTTP3_QPACK_TOKEN__METHOD` is a token for ``:method``. 829 */ 830 NGHTTP3_QPACK_TOKEN__METHOD = 1, 831 /** 832 * :enum:`NGHTTP3_QPACK_TOKEN__SCHEME` is a token for ``:scheme``. 833 */ 834 NGHTTP3_QPACK_TOKEN__SCHEME = 9, 835 /** 836 * :enum:`NGHTTP3_QPACK_TOKEN__STATUS` is a token for ``:status``. 837 */ 838 NGHTTP3_QPACK_TOKEN__STATUS = 11, 839 /** 840 * :enum:`NGHTTP3_QPACK_TOKEN_ACCEPT` is a token for ``accept``. 841 */ 842 NGHTTP3_QPACK_TOKEN_ACCEPT = 25, 843 /** 844 * :enum:`NGHTTP3_QPACK_TOKEN_ACCEPT_ENCODING` is a token for 845 * ``accept-encoding``. 846 */ 847 NGHTTP3_QPACK_TOKEN_ACCEPT_ENCODING = 27, 848 /** 849 * :enum:`NGHTTP3_QPACK_TOKEN_ACCEPT_RANGES` is a token for 850 * ``accept-ranges``. 851 */ 852 NGHTTP3_QPACK_TOKEN_ACCEPT_RANGES = 29, 853 /** 854 * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_HEADERS` is a 855 * token for ``access-control-allow-headers``. 856 */ 857 NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_HEADERS = 32, 858 /** 859 * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_ORIGIN` is a 860 * token for ``access-control-allow-origin``. 861 */ 862 NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_ORIGIN = 38, 863 /** 864 * :enum:`NGHTTP3_QPACK_TOKEN_CACHE_CONTROL` is a token for 865 * ``cache-control``. 866 */ 867 NGHTTP3_QPACK_TOKEN_CACHE_CONTROL = 46, 868 /** 869 * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_ENCODING` is a token for 870 * ``content-encoding``. 871 */ 872 NGHTTP3_QPACK_TOKEN_CONTENT_ENCODING = 53, 873 /** 874 * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_TYPE` is a token for 875 * ``content-type``. 876 */ 877 NGHTTP3_QPACK_TOKEN_CONTENT_TYPE = 57, 878 /** 879 * :enum:`NGHTTP3_QPACK_TOKEN_RANGE` is a token for ``range``. 880 */ 881 NGHTTP3_QPACK_TOKEN_RANGE = 82, 882 /** 883 * :enum:`NGHTTP3_QPACK_TOKEN_STRICT_TRANSPORT_SECURITY` is a token 884 * for ``strict-transport-security``. 885 */ 886 NGHTTP3_QPACK_TOKEN_STRICT_TRANSPORT_SECURITY = 86, 887 /** 888 * :enum:`NGHTTP3_QPACK_TOKEN_VARY` is a token for ``vary``. 889 */ 890 NGHTTP3_QPACK_TOKEN_VARY = 92, 891 /** 892 * :enum:`NGHTTP3_QPACK_TOKEN_X_CONTENT_TYPE_OPTIONS` is a token for 893 * ``x-content-type-options``. 894 */ 895 NGHTTP3_QPACK_TOKEN_X_CONTENT_TYPE_OPTIONS = 94, 896 /** 897 * :enum:`NGHTTP3_QPACK_TOKEN_X_XSS_PROTECTION` is a token for 898 * ``x-xss-protection``. 899 */ 900 NGHTTP3_QPACK_TOKEN_X_XSS_PROTECTION = 98, 901 /** 902 * :enum:`NGHTTP3_QPACK_TOKEN_ACCEPT_LANGUAGE` is a token for 903 * ``accept-language``. 904 */ 905 NGHTTP3_QPACK_TOKEN_ACCEPT_LANGUAGE = 28, 906 /** 907 * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_CREDENTIALS` is a 908 * token for ``access-control-allow-credentials``. 909 */ 910 NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_CREDENTIALS = 30, 911 /** 912 * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_METHODS` is a 913 * token for ``access-control-allow-methods``. 914 */ 915 NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_METHODS = 35, 916 /** 917 * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_EXPOSE_HEADERS` is a 918 * token for ``access-control-expose-headers``. 919 */ 920 NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_EXPOSE_HEADERS = 39, 921 /** 922 * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_HEADERS` is a 923 * token for ``access-control-request-headers``. 924 */ 925 NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_HEADERS = 40, 926 /** 927 * :enum:`NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_METHOD` is a 928 * token for ``access-control-request-method``. 929 */ 930 NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_METHOD = 41, 931 /** 932 * :enum:`NGHTTP3_QPACK_TOKEN_ALT_SVC` is a token for ``alt-svc``. 933 */ 934 NGHTTP3_QPACK_TOKEN_ALT_SVC = 44, 935 /** 936 * :enum:`NGHTTP3_QPACK_TOKEN_AUTHORIZATION` is a token for 937 * ``authorization``. 938 */ 939 NGHTTP3_QPACK_TOKEN_AUTHORIZATION = 45, 940 /** 941 * :enum:`NGHTTP3_QPACK_TOKEN_CONTENT_SECURITY_POLICY` is a token 942 * for ``content-security-policy``. 943 */ 944 NGHTTP3_QPACK_TOKEN_CONTENT_SECURITY_POLICY = 56, 945 /** 946 * :enum:`NGHTTP3_QPACK_TOKEN_EARLY_DATA` is a token for 947 * ``early-data``. 948 */ 949 NGHTTP3_QPACK_TOKEN_EARLY_DATA = 70, 950 /** 951 * :enum:`NGHTTP3_QPACK_TOKEN_EXPECT_CT` is a token for 952 * ``expect-ct``. 953 */ 954 NGHTTP3_QPACK_TOKEN_EXPECT_CT = 72, 955 /** 956 * :enum:`NGHTTP3_QPACK_TOKEN_FORWARDED` is a token for 957 * ``forwarded``. 958 */ 959 NGHTTP3_QPACK_TOKEN_FORWARDED = 73, 960 /** 961 * :enum:`NGHTTP3_QPACK_TOKEN_IF_RANGE` is a token for ``if-range``. 962 */ 963 NGHTTP3_QPACK_TOKEN_IF_RANGE = 76, 964 /** 965 * :enum:`NGHTTP3_QPACK_TOKEN_ORIGIN` is a token for ``origin``. 966 */ 967 NGHTTP3_QPACK_TOKEN_ORIGIN = 80, 968 /** 969 * :enum:`NGHTTP3_QPACK_TOKEN_PURPOSE` is a token for ``purpose``. 970 */ 971 NGHTTP3_QPACK_TOKEN_PURPOSE = 81, 972 /** 973 * :enum:`NGHTTP3_QPACK_TOKEN_SERVER` is a token for ``server``. 974 */ 975 NGHTTP3_QPACK_TOKEN_SERVER = 84, 976 /** 977 * :enum:`NGHTTP3_QPACK_TOKEN_TIMING_ALLOW_ORIGIN` is a token for 978 * ``timing-allow-origin``. 979 */ 980 NGHTTP3_QPACK_TOKEN_TIMING_ALLOW_ORIGIN = 89, 981 /** 982 * :enum:`NGHTTP3_QPACK_TOKEN_UPGRADE_INSECURE_REQUESTS` is a token 983 * for ``upgrade-insecure-requests``. 984 */ 985 NGHTTP3_QPACK_TOKEN_UPGRADE_INSECURE_REQUESTS = 90, 986 /** 987 * :enum:`NGHTTP3_QPACK_TOKEN_USER_AGENT` is a token for 988 * ``user-agent``. 989 */ 990 NGHTTP3_QPACK_TOKEN_USER_AGENT = 91, 991 /** 992 * :enum:`NGHTTP3_QPACK_TOKEN_X_FORWARDED_FOR` is a token for 993 * ``x-forwarded-for``. 994 */ 995 NGHTTP3_QPACK_TOKEN_X_FORWARDED_FOR = 95, 996 /** 997 * :enum:`NGHTTP3_QPACK_TOKEN_X_FRAME_OPTIONS` is a token for 998 * ``x-frame-options``. 999 */ 1000 NGHTTP3_QPACK_TOKEN_X_FRAME_OPTIONS = 96, 1001 1002 /* Additional header fields for HTTP messaging validation */ 1003 1004 /** 1005 * :enum:`NGHTTP3_QPACK_TOKEN_HOST` is a token for ``host``. 1006 */ 1007 NGHTTP3_QPACK_TOKEN_HOST = 1000, 1008 /** 1009 * :enum:`NGHTTP3_QPACK_TOKEN_CONNECTION` is a token for 1010 * ``connection``. 1011 */ 1012 NGHTTP3_QPACK_TOKEN_CONNECTION, 1013 /** 1014 * :enum:`NGHTTP3_QPACK_TOKEN_KEEP_ALIVE` is a token for 1015 * ``keep-alive``. 1016 */ 1017 NGHTTP3_QPACK_TOKEN_KEEP_ALIVE, 1018 /** 1019 * :enum:`NGHTTP3_QPACK_TOKEN_PROXY_CONNECTION` is a token for 1020 * ``proxy-connection``. 1021 */ 1022 NGHTTP3_QPACK_TOKEN_PROXY_CONNECTION, 1023 /** 1024 * :enum:`NGHTTP3_QPACK_TOKEN_TRANSFER_ENCODING` is a token for 1025 * ``transfer-encoding``. 1026 */ 1027 NGHTTP3_QPACK_TOKEN_TRANSFER_ENCODING, 1028 /** 1029 * :enum:`NGHTTP3_QPACK_TOKEN_UPGRADE` is a token for ``upgrade``. 1030 */ 1031 NGHTTP3_QPACK_TOKEN_UPGRADE, 1032 /** 1033 * :enum:`NGHTTP3_QPACK_TOKEN_TE` is a token for ``te``. 1034 */ 1035 NGHTTP3_QPACK_TOKEN_TE, 1036 /** 1037 * :enum:`NGHTTP3_QPACK_TOKEN__PROTOCOL` is a token for 1038 * ``:protocol``. 1039 */ 1040 NGHTTP3_QPACK_TOKEN__PROTOCOL, 1041 /** 1042 * :enum:`NGHTTP3_QPACK_TOKEN_PRIORITY` is a token for ``priority``. 1043 */ 1044 NGHTTP3_QPACK_TOKEN_PRIORITY 1045 } nghttp3_qpack_token; 1046 1047 /** 1048 * @struct 1049 * 1050 * :type:`nghttp3_qpack_nv` represents header field name/value pair 1051 * just like :type:`nghttp3_nv`. It is an extended version of 1052 * :type:`nghttp3_nv` and has reference counted buffers and tokens 1053 * which might be useful for applications. 1054 */ 1055 typedef struct nghttp3_qpack_nv { 1056 /** 1057 * :member:`name` is the buffer containing header field name. 1058 * NULL-termination is guaranteed. 1059 */ 1060 nghttp3_rcbuf *name; 1061 /** 1062 * :member:`value` is the buffer containing header field value. 1063 * NULL-termination is guaranteed. 1064 */ 1065 nghttp3_rcbuf *value; 1066 /** 1067 * :member:`token` is :type:`nghttp3_qpack_token` value of 1068 * :member:`name`. It could be -1 if we have no token for that 1069 * header field name. 1070 */ 1071 int32_t token; 1072 /** 1073 * :member:`flags` is a bitwise OR of one or more of 1074 * NGHTTP3_NV_FLAG_*. See :macro:`NGHTTP3_NV_FLAG_NONE`. 1075 */ 1076 uint8_t flags; 1077 } nghttp3_qpack_nv; 1078 1079 /** 1080 * @struct 1081 * 1082 * :type:`nghttp3_qpack_encoder` is QPACK encoder. 1083 */ 1084 typedef struct nghttp3_qpack_encoder nghttp3_qpack_encoder; 1085 1086 /** 1087 * @function 1088 * 1089 * `nghttp3_qpack_encoder_new` initializes QPACK encoder. |pencoder| 1090 * must be non-NULL pointer. |mem| is a memory allocator. This 1091 * function allocates memory for :type:`nghttp3_qpack_encoder` itself 1092 * and assigns its pointer to |*pencoder| if it succeeds. 1093 * 1094 * This function returns 0 if it succeeds, or one of the following 1095 * negative error codes: 1096 * 1097 * :macro:`NGHTTP3_ERR_NOMEM` 1098 * Out of memory. 1099 */ 1100 NGHTTP3_EXTERN int nghttp3_qpack_encoder_new(nghttp3_qpack_encoder **pencoder, 1101 const nghttp3_mem *mem); 1102 1103 /** 1104 * @function 1105 * 1106 * `nghttp3_qpack_encoder_del` frees memory allocated for |encoder|. 1107 * This function frees memory pointed by |encoder| itself. 1108 */ 1109 NGHTTP3_EXTERN void nghttp3_qpack_encoder_del(nghttp3_qpack_encoder *encoder); 1110 1111 /** 1112 * @function 1113 * 1114 * `nghttp3_qpack_encoder_encode` encodes the list of header fields 1115 * |nva|. |nvlen| is the length of |nva|. |stream_id| is the 1116 * identifier of the stream which this header fields belong to. This 1117 * function writes header block prefix, encoded header fields, and 1118 * encoder stream to |pbuf|, |rbuf|, and |ebuf| respectively. The 1119 * :member:`nghttp3_buf.last` will be adjusted when data is written. 1120 * An application should write |pbuf| and |rbuf| to the request stream 1121 * in this order. 1122 * 1123 * The buffer pointed by |pbuf|, |rbuf|, and |ebuf| can be empty 1124 * buffer. It is fine to pass a buffer initialized by 1125 * `nghttp3_buf_init(buf) <nghttp3_buf_init>`. This function 1126 * allocates memory for these buffers as necessary. In particular, it 1127 * frees and expands buffer if the current capacity of buffer is not 1128 * enough. If :member:`nghttp3_buf.begin` of any buffer is not NULL, 1129 * it must be allocated by the same memory allocator passed to 1130 * `nghttp3_qpack_encoder_new()`. 1131 * 1132 * This function returns 0 if it succeeds, or one of the following 1133 * negative error codes: 1134 * 1135 * :macro:`NGHTTP3_ERR_NOMEM` 1136 * Out of memory 1137 * :macro:`NGHTTP3_ERR_QPACK_FATAL` 1138 * |encoder| is in unrecoverable error state and cannot be used 1139 * anymore. 1140 */ 1141 NGHTTP3_EXTERN int nghttp3_qpack_encoder_encode( 1142 nghttp3_qpack_encoder *encoder, nghttp3_buf *pbuf, nghttp3_buf *rbuf, 1143 nghttp3_buf *ebuf, int64_t stream_id, const nghttp3_nv *nva, size_t nvlen); 1144 1145 /** 1146 * @function 1147 * 1148 * `nghttp3_qpack_encoder_read_decoder` reads decoder stream. The 1149 * buffer pointed by |src| of length |srclen| contains decoder stream. 1150 * 1151 * This function returns the number of bytes read, or one of the 1152 * following negative error codes: 1153 * 1154 * :macro:`NGHTTP3_ERR_NOMEM` 1155 * Out of memory 1156 * :macro:`NGHTTP3_ERR_QPACK_FATAL` 1157 * |encoder| is in unrecoverable error state and cannot be used 1158 * anymore. 1159 * :macro:`NGHTTP3_ERR_QPACK_DECODER_STREAM` 1160 * |encoder| is unable to process input because it is malformed. 1161 */ 1162 NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_encoder_read_decoder( 1163 nghttp3_qpack_encoder *encoder, const uint8_t *src, size_t srclen); 1164 1165 /** 1166 * @function 1167 * 1168 * `nghttp3_qpack_encoder_set_max_dtable_capacity` sets max dynamic 1169 * table size to |max_dtable_capacity|. |max_dtable_capacity| must be 1170 * equal to or smaller than the value passed to 1171 * `nghttp3_qpack_encoder_set_max_dtable_capacity`. 1172 * 1173 * This function returns 0 if it succeeds, or one of the 1174 * following negative error codes: 1175 * 1176 * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT` 1177 * |max_dtable_capacity| exceeds the hard limit that decoder 1178 * specifies. 1179 */ 1180 NGHTTP3_EXTERN int 1181 nghttp3_qpack_encoder_set_max_dtable_capacity(nghttp3_qpack_encoder *encoder, 1182 size_t max_dtable_capacity); 1183 1184 /** 1185 * @function 1186 * 1187 * `nghttp3_qpack_encoder_set_hard_max_dtable_capacity` sets hard 1188 * maximum dynamic table size to |hard_max_dtable_capacity|. This is 1189 * the real maximum capacity of dynamic table that encoder enforces. 1190 * This value is used to validate the passed value by 1191 * `nghttp3_qpack_encoder_set_max_dtable_capacity`. 1192 * 1193 * In HTTP/3, QPACK decoder side of the connection tells the maximum 1194 * size in SETTINGS_QPACK_MAX_TABLE_CAPACITY. It is dangerous to pass 1195 * the value as is to this function because the decoder can set the 1196 * large table size which may increase the memory consumption of 1197 * encoder. Therefore, it should be the minimum of the value of 1198 * SETTINGS_QPACK_MAX_TABLE_CAPACITY and the amount of memory that 1199 * encoder can afford. 1200 */ 1201 NGHTTP3_EXTERN void nghttp3_qpack_encoder_set_hard_max_dtable_capacity( 1202 nghttp3_qpack_encoder *encoder, size_t hard_max_dtable_capacity); 1203 1204 /** 1205 * @function 1206 * 1207 * `nghttp3_qpack_encoder_set_max_blocked_streams` sets the number of 1208 * streams which can be blocked to |max_blocked_streams|. 1209 */ 1210 NGHTTP3_EXTERN void 1211 nghttp3_qpack_encoder_set_max_blocked_streams(nghttp3_qpack_encoder *encoder, 1212 size_t max_blocked_streams); 1213 1214 /** 1215 * @function 1216 * 1217 * `nghttp3_qpack_encoder_ack_everything` tells |encoder| that all 1218 * encoded header blocks are acknowledged. This function is provided 1219 * for debugging purpose only. In HTTP/3, |encoder| knows this by 1220 * reading decoder stream with `nghttp3_qpack_encoder_read_decoder()`. 1221 */ 1222 NGHTTP3_EXTERN void 1223 nghttp3_qpack_encoder_ack_everything(nghttp3_qpack_encoder *encoder); 1224 1225 /** 1226 * @function 1227 * 1228 * `nghttp3_qpack_encoder_get_num_blocked_streams` returns the number 1229 * of streams which are potentially blocked at decoder side. 1230 */ 1231 NGHTTP3_EXTERN size_t 1232 nghttp3_qpack_encoder_get_num_blocked_streams(nghttp3_qpack_encoder *encoder); 1233 1234 /** 1235 * @struct 1236 * 1237 * :type:`nghttp3_qpack_stream_context` is a decoder context for an 1238 * individual stream. Its state is per header block. In order to 1239 * reuse this object for another header block, call 1240 * `nghttp3_qpack_stream_context_reset`. 1241 */ 1242 typedef struct nghttp3_qpack_stream_context nghttp3_qpack_stream_context; 1243 1244 /** 1245 * @function 1246 * 1247 * `nghttp3_qpack_stream_context_new` initializes stream context. 1248 * |psctx| must be non-NULL pointer. |stream_id| is stream ID. |mem| 1249 * is a memory allocator. This function allocates memory for 1250 * :type:`nghttp3_qpack_stream_context` itself and assigns its pointer 1251 * to |*psctx| if it succeeds. 1252 * 1253 * This function returns 0 if it succeeds, or one of the following 1254 * negative error codes: 1255 * 1256 * :macro:`NGHTTP3_ERR_NOMEM` 1257 * Out of memory. 1258 */ 1259 NGHTTP3_EXTERN int 1260 nghttp3_qpack_stream_context_new(nghttp3_qpack_stream_context **psctx, 1261 int64_t stream_id, const nghttp3_mem *mem); 1262 1263 /** 1264 * @function 1265 * 1266 * `nghttp3_qpack_stream_context_del` frees memory allocated for 1267 * |sctx|. This function frees memory pointed by |sctx| itself. 1268 */ 1269 NGHTTP3_EXTERN void 1270 nghttp3_qpack_stream_context_del(nghttp3_qpack_stream_context *sctx); 1271 1272 /** 1273 * @function 1274 * 1275 * `nghttp3_qpack_stream_context_get_ricnt` returns required insert 1276 * count. 1277 */ 1278 NGHTTP3_EXTERN uint64_t 1279 nghttp3_qpack_stream_context_get_ricnt(nghttp3_qpack_stream_context *sctx); 1280 1281 /** 1282 * @function 1283 * 1284 * `nghttp3_qpack_stream_context_reset` resets the state of |sctx|. 1285 * Then it can be reused for an another header block in the same 1286 * stream. 1287 */ 1288 NGHTTP3_EXTERN 1289 void nghttp3_qpack_stream_context_reset(nghttp3_qpack_stream_context *sctx); 1290 1291 /** 1292 * @struct 1293 * 1294 * :type:`nghttp3_qpack_decoder` is QPACK decoder. 1295 */ 1296 typedef struct nghttp3_qpack_decoder nghttp3_qpack_decoder; 1297 1298 /** 1299 * @function 1300 * 1301 * `nghttp3_qpack_decoder_new` initializes QPACK decoder. |pdecoder| 1302 * must be non-NULL pointer. |max_dtable_capacity| is the maximum 1303 * dynamic table size. |max_blocked_streams| is the maximum number of 1304 * streams which can be blocked. |mem| is a memory allocator. This 1305 * function allocates memory for :type:`nghttp3_qpack_decoder` itself 1306 * and assigns its pointer to |*pdecoder| if it succeeds. 1307 * 1308 * This function returns 0 if it succeeds, or one of the following 1309 * negative error codes: 1310 * 1311 * :macro:`NGHTTP3_ERR_NOMEM` 1312 * Out of memory. 1313 */ 1314 NGHTTP3_EXTERN int nghttp3_qpack_decoder_new(nghttp3_qpack_decoder **pdecoder, 1315 size_t max_dtable_capacity, 1316 size_t max_blocked_streams, 1317 const nghttp3_mem *mem); 1318 1319 /** 1320 * @function 1321 * 1322 * `nghttp3_qpack_decoder_del` frees memory allocated for |decoder|. 1323 * This function frees memory pointed by |decoder| itself. 1324 */ 1325 NGHTTP3_EXTERN void nghttp3_qpack_decoder_del(nghttp3_qpack_decoder *decoder); 1326 1327 /** 1328 * @function 1329 * 1330 * `nghttp3_qpack_decoder_read_encoder` reads encoder stream. The 1331 * buffer pointed by |src| of length |srclen| contains encoder stream. 1332 * 1333 * This function returns the number of bytes read, or one of the 1334 * following negative error codes: 1335 * 1336 * :macro:`NGHTTP3_ERR_NOMEM` 1337 * Out of memory. 1338 * :macro:`NGHTTP3_ERR_QPACK_FATAL` 1339 * |decoder| is in unrecoverable error state and cannot be used 1340 * anymore. 1341 * :macro:`NGHTTP3_ERR_QPACK_ENCODER_STREAM` 1342 * Could not interpret encoder stream instruction. 1343 */ 1344 NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_decoder_read_encoder( 1345 nghttp3_qpack_decoder *decoder, const uint8_t *src, size_t srclen); 1346 1347 /** 1348 * @function 1349 * 1350 * `nghttp3_qpack_decoder_get_icnt` returns insert count. 1351 */ 1352 NGHTTP3_EXTERN uint64_t 1353 nghttp3_qpack_decoder_get_icnt(const nghttp3_qpack_decoder *decoder); 1354 1355 /** 1356 * @macrosection 1357 * 1358 * Flags for QPACK decoder 1359 */ 1360 1361 /** 1362 * @macro 1363 * 1364 * :macro:`NGHTTP3_QPACK_DECODE_FLAG_NONE` indicates that no flag set. 1365 */ 1366 #define NGHTTP3_QPACK_DECODE_FLAG_NONE 0 1367 1368 /** 1369 * @macro 1370 * 1371 * :macro:`NGHTTP3_QPACK_DECODE_FLAG_EMIT` indicates that a header 1372 * field is successfully decoded. 1373 */ 1374 #define NGHTTP3_QPACK_DECODE_FLAG_EMIT 0x01 1375 1376 /** 1377 * @macro 1378 * 1379 * :macro:`NGHTTP3_QPACK_DECODE_FLAG_FINAL` indicates that all header 1380 * fields have been decoded. 1381 */ 1382 #define NGHTTP3_QPACK_DECODE_FLAG_FINAL 0x02 1383 1384 /** 1385 * @macro 1386 * 1387 * :macro:`NGHTTP3_QPACK_DECODE_FLAG_BLOCKED` indicates that decoding 1388 * has been blocked. 1389 */ 1390 #define NGHTTP3_QPACK_DECODE_FLAG_BLOCKED 0x04 1391 1392 /** 1393 * @function 1394 * 1395 * `nghttp3_qpack_decoder_read_request` reads request stream. The 1396 * request stream is given as the buffer pointed by |src| of length 1397 * |srclen|. |sctx| is the stream context and it must be created by 1398 * `nghttp3_qpack_stream_context_new()`. |*pflags| must be non-NULL 1399 * pointer. |nv| must be non-NULL pointer. 1400 * 1401 * If this function succeeds, it assigns flags to |*pflags|. If 1402 * |*pflags| has :macro:`NGHTTP3_QPACK_DECODE_FLAG_EMIT` set, a 1403 * decoded header field is assigned to |nv|. If |*pflags| has 1404 * :macro:`NGHTTP3_QPACK_DECODE_FLAG_FINAL` set, all header fields 1405 * have been successfully decoded. If |*pflags| has 1406 * :macro:`NGHTTP3_QPACK_DECODE_FLAG_BLOCKED` set, decoding is blocked 1407 * due to required insert count. 1408 * 1409 * When a header field is decoded, an application receives it in |nv|. 1410 * :member:`nv->name <nghttp3_qpack_nv.name>` and :member:`nv->value 1411 * <nghttp3_qpack_nv.value>` are reference counted buffer, and their 1412 * reference counts are already incremented for application use. 1413 * Therefore, when application finishes processing the header field, 1414 * it must call `nghttp3_rcbuf_decref(nv->name) 1415 * <nghttp3_rcbuf_decref>` and `nghttp3_rcbuf_decref(nv->value) 1416 * <nghttp3_rcbuf_decref>` or memory leak might occur. 1417 * 1418 * This function returns the number of bytes read, or one of the 1419 * following negative error codes: 1420 * 1421 * :macro:`NGHTTP3_ERR_NOMEM` 1422 * Out of memory. 1423 * :macro:`NGHTTP3_ERR_QPACK_FATAL` 1424 * |decoder| is in unrecoverable error state and cannot be used 1425 * anymore. 1426 * :macro:`NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED` 1427 * Could not interpret header block instruction. 1428 * :macro:`NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE` 1429 * Header field is too large. 1430 */ 1431 NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_decoder_read_request( 1432 nghttp3_qpack_decoder *decoder, nghttp3_qpack_stream_context *sctx, 1433 nghttp3_qpack_nv *nv, uint8_t *pflags, const uint8_t *src, size_t srclen, 1434 int fin); 1435 1436 /** 1437 * @function 1438 * 1439 * `nghttp3_qpack_decoder_write_decoder` writes decoder stream into 1440 * |dbuf|. 1441 * 1442 * The caller must ensure that `nghttp3_buf_left(dbuf) 1443 * <nghttp3_buf_left>` >= 1444 * `nghttp3_qpack_decoder_get_decoder_streamlen(decoder) 1445 * <nghttp3_qpack_decoder_get_decoder_streamlen>`. 1446 */ 1447 NGHTTP3_EXTERN void 1448 nghttp3_qpack_decoder_write_decoder(nghttp3_qpack_decoder *decoder, 1449 nghttp3_buf *dbuf); 1450 1451 /** 1452 * @function 1453 * 1454 * `nghttp3_qpack_decoder_get_decoder_streamlen` returns the length of 1455 * decoder stream. 1456 */ 1457 NGHTTP3_EXTERN size_t 1458 nghttp3_qpack_decoder_get_decoder_streamlen(nghttp3_qpack_decoder *decoder); 1459 1460 /** 1461 * @function 1462 * 1463 * `nghttp3_qpack_decoder_cancel_stream` cancels header decoding for 1464 * stream denoted by |stream_id|. 1465 * 1466 * This function returns 0 if it succeeds, or one of the following 1467 * negative error codes: 1468 * 1469 * :macro:`NGHTTP3_ERR_NOMEM` 1470 * Out of memory. 1471 * :macro:`NGHTTP3_ERR_QPACK_FATAL` 1472 * Decoder stream overflow. 1473 */ 1474 NGHTTP3_EXTERN int 1475 nghttp3_qpack_decoder_cancel_stream(nghttp3_qpack_decoder *decoder, 1476 int64_t stream_id); 1477 1478 /** 1479 * @function 1480 * 1481 * `nghttp3_qpack_decoder_set_max_dtable_capacity` sets 1482 * |max_dtable_capacity| as maximum dynamic table size. Normally, the 1483 * maximum capacity is communicated in encoder stream. This function 1484 * is provided for debugging and testing purpose. 1485 */ 1486 NGHTTP3_EXTERN void 1487 nghttp3_qpack_decoder_set_max_dtable_capacity(nghttp3_qpack_decoder *decoder, 1488 size_t max_dtable_capacity); 1489 1490 /** 1491 * @function 1492 * 1493 * `nghttp3_qpack_decoder_set_max_concurrent_streams` tells |decoder| 1494 * the maximum number of concurrent streams that a remote endpoint can 1495 * open, including both bidirectional and unidirectional streams which 1496 * potentially receive QPACK encoded HEADERS frame. This value is 1497 * used as a hint to limit the length of decoder stream. 1498 */ 1499 NGHTTP3_EXTERN void 1500 nghttp3_qpack_decoder_set_max_concurrent_streams(nghttp3_qpack_decoder *decoder, 1501 size_t max_concurrent_streams); 1502 1503 /** 1504 * @function 1505 * 1506 * `nghttp3_strerror` returns textual representation of |liberr|. 1507 */ 1508 NGHTTP3_EXTERN const char *nghttp3_strerror(int liberr); 1509 1510 /** 1511 * @function 1512 * 1513 * `nghttp3_err_infer_quic_app_error_code` returns a QUIC application 1514 * error code which corresponds to |liberr|. 1515 */ 1516 NGHTTP3_EXTERN uint64_t nghttp3_err_infer_quic_app_error_code(int liberr); 1517 1518 /** 1519 * @functypedef 1520 * 1521 * :type:`nghttp3_debug_vprintf_callback` is a callback function 1522 * invoked when the library outputs debug logging. The function is 1523 * called with arguments suitable for :manpage:`vfprintf(3)`. 1524 * 1525 * The debug output is only enabled if the library is built with 1526 * :macro:`DEBUGBUILD` macro defined. 1527 */ 1528 typedef void (*nghttp3_debug_vprintf_callback)(const char *format, 1529 va_list args); 1530 1531 /** 1532 * @function 1533 * 1534 * `nghttp3_set_debug_vprintf_callback` sets a debug output callback 1535 * called by the library when built with :macro:`DEBUGBUILD` macro 1536 * defined. If this option is not used, debug log is written into 1537 * standard error output. 1538 * 1539 * For builds without :macro:`DEBUGBUILD` macro defined, this function 1540 * is noop. 1541 * 1542 * Note that building with :macro:`DEBUGBUILD` may cause significant 1543 * performance penalty to libnghttp3 because of extra processing. It 1544 * should be used for debugging purpose only. 1545 * 1546 * .. Warning:: 1547 * 1548 * Building with :macro:`DEBUGBUILD` may cause significant 1549 * performance penalty to libnghttp3 because of extra processing. 1550 * It should be used for debugging purpose only. We write this two 1551 * times because this is important. 1552 */ 1553 NGHTTP3_EXTERN void nghttp3_set_debug_vprintf_callback( 1554 nghttp3_debug_vprintf_callback debug_vprintf_callback); 1555 1556 /** 1557 * @macrosection 1558 * 1559 * Shutdown related constants 1560 */ 1561 1562 /** 1563 * @macro 1564 * 1565 * :macro:`NGHTTP3_SHUTDOWN_NOTICE_STREAM_ID` specifies stream id sent 1566 * by a server when it initiates graceful shutdown of the connection 1567 * via `nghttp3_conn_submit_shutdown_notice`. 1568 */ 1569 #define NGHTTP3_SHUTDOWN_NOTICE_STREAM_ID ((1ull << 62) - 4) 1570 1571 /** 1572 * @macro 1573 * 1574 * :macro:`NGHTTP3_SHUTDOWN_NOTICE_PUSH_ID` specifies push id sent 1575 * by a client when it initiates graceful shutdown of the connection 1576 * via `nghttp3_conn_submit_shutdown_notice`. 1577 */ 1578 #define NGHTTP3_SHUTDOWN_NOTICE_PUSH_ID ((1ull << 62) - 1) 1579 1580 /** 1581 * @struct 1582 * 1583 * :type:`nghttp3_conn` represents a single HTTP/3 connection. 1584 */ 1585 typedef struct nghttp3_conn nghttp3_conn; 1586 1587 /** 1588 * @functypedef 1589 * 1590 * :type:`nghttp3_acked_stream_data` is a callback function which is 1591 * invoked when data sent on stream denoted by |stream_id| supplied 1592 * from application is acknowledged by remote endpoint. The number of 1593 * bytes acknowledged is given in |datalen|. 1594 * 1595 * The implementation of this callback must return 0 if it succeeds. 1596 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1597 * caller immediately. Any values other than 0 is treated as 1598 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1599 */ 1600 typedef int (*nghttp3_acked_stream_data)(nghttp3_conn *conn, int64_t stream_id, 1601 uint64_t datalen, void *conn_user_data, 1602 void *stream_user_data); 1603 1604 /** 1605 * @functypedef 1606 * 1607 * :type:`nghttp3_conn_stream_close` is a callback function which is 1608 * invoked when a stream identified by |stream_id| is closed. 1609 * |app_error_code| indicates the reason of this closure. 1610 * 1611 * The implementation of this callback must return 0 if it succeeds. 1612 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1613 * caller immediately. Any values other than 0 is treated as 1614 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1615 */ 1616 typedef int (*nghttp3_stream_close)(nghttp3_conn *conn, int64_t stream_id, 1617 uint64_t app_error_code, 1618 void *conn_user_data, 1619 void *stream_user_data); 1620 1621 /** 1622 * @functypedef 1623 * 1624 * :type:`nghttp3_recv_data` is a callback function which is invoked 1625 * when a part of request or response body on stream identified by 1626 * |stream_id| is received. |data| points to the received data and 1627 * its length is |datalen|. 1628 * 1629 * The application is responsible for increasing flow control credit 1630 * by |datalen| bytes. 1631 * 1632 * The implementation of this callback must return 0 if it succeeds. 1633 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1634 * caller immediately. Any values other than 0 is treated as 1635 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1636 */ 1637 typedef int (*nghttp3_recv_data)(nghttp3_conn *conn, int64_t stream_id, 1638 const uint8_t *data, size_t datalen, 1639 void *conn_user_data, void *stream_user_data); 1640 1641 /** 1642 * @functypedef 1643 * 1644 * :type:`nghttp3_deferred_consume` is a callback function which is 1645 * invoked when the library consumed |consumed| bytes for a stream 1646 * identified by |stream_id|. This callback is used to notify the 1647 * consumed bytes for stream blocked by QPACK decoder. The 1648 * application is responsible for increasing flow control credit by 1649 * |consumed| bytes. 1650 * 1651 * The implementation of this callback must return 0 if it succeeds. 1652 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1653 * caller immediately. Any values other than 0 is treated as 1654 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1655 */ 1656 typedef int (*nghttp3_deferred_consume)(nghttp3_conn *conn, int64_t stream_id, 1657 size_t consumed, void *conn_user_data, 1658 void *stream_user_data); 1659 1660 /** 1661 * @functypedef 1662 * 1663 * :type:`nghttp3_begin_headers` is a callback function which is 1664 * invoked when an incoming header block section is started on a 1665 * stream denoted by |stream_id|. Each header field is passed to 1666 * application by :type:`nghttp3_recv_header` callback. And then 1667 * :type:`nghttp3_end_headers` is called when a whole header block is 1668 * processed. 1669 * 1670 * The implementation of this callback must return 0 if it succeeds. 1671 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1672 * caller immediately. Any values other than 0 is treated as 1673 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1674 */ 1675 typedef int (*nghttp3_begin_headers)(nghttp3_conn *conn, int64_t stream_id, 1676 void *conn_user_data, 1677 void *stream_user_data); 1678 1679 /** 1680 * @functypedef 1681 * 1682 * :type:`nghttp3_recv_header` is a callback function which is invoked 1683 * when a header field is received on a stream denoted by |stream_id|. 1684 * |name| contains a field name and |value| contains a field value. 1685 * |token| is one of token defined in :type:`nghttp3_qpack_token` or 1686 * -1 if no token is defined for |name|. |flags| is bitwise OR of 1687 * zero or more of NGHTTP3_NV_FLAG_*. 1688 * 1689 * The buffers for |name| and |value| are reference counted. If 1690 * application needs to keep them, increment the reference count with 1691 * `nghttp3_rcbuf_incref`. When they are no longer used, call 1692 * `nghttp3_rcbuf_decref`. 1693 * 1694 * The implementation of this callback must return 0 if it succeeds. 1695 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1696 * caller immediately. Any values other than 0 is treated as 1697 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1698 */ 1699 typedef int (*nghttp3_recv_header)(nghttp3_conn *conn, int64_t stream_id, 1700 int32_t token, nghttp3_rcbuf *name, 1701 nghttp3_rcbuf *value, uint8_t flags, 1702 void *conn_user_data, 1703 void *stream_user_data); 1704 1705 /** 1706 * @functypedef 1707 * 1708 * :type:`nghttp3_end_headers` is a callback function which is invoked 1709 * when an incoming header block has ended. 1710 * 1711 * The implementation of this callback must return 0 if it succeeds. 1712 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1713 * caller immediately. Any values other than 0 is treated as 1714 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1715 */ 1716 typedef int (*nghttp3_end_headers)(nghttp3_conn *conn, int64_t stream_id, 1717 void *conn_user_data, 1718 void *stream_user_data); 1719 1720 /** 1721 * @functypedef 1722 * 1723 * :type:`nghttp3_end_stream` is a callback function which is invoked 1724 * when the receiving side of stream is closed. For server, this 1725 * callback function is invoked when HTTP request is received 1726 * completely. For client, this callback function is invoked when 1727 * HTTP response is received completely. 1728 * 1729 * The implementation of this callback must return 0 if it succeeds. 1730 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1731 * caller immediately. Any values other than 0 is treated as 1732 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1733 */ 1734 typedef int (*nghttp3_end_stream)(nghttp3_conn *conn, int64_t stream_id, 1735 void *conn_user_data, void *stream_user_data); 1736 1737 /** 1738 * @functypedef 1739 * 1740 * :type:`nghttp3_stop_sending` is a callback function which is 1741 * invoked when the library asks application to send STOP_SENDING to 1742 * the stream identified by |stream_id|. |app_error_code| indicates 1743 * the reason for this action. 1744 * 1745 * The implementation of this callback must return 0 if it succeeds. 1746 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1747 * caller immediately. Any values other than 0 is treated as 1748 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1749 */ 1750 typedef int (*nghttp3_stop_sending)(nghttp3_conn *conn, int64_t stream_id, 1751 uint64_t app_error_code, 1752 void *conn_user_data, 1753 void *stream_user_data); 1754 1755 /** 1756 * @functypedef 1757 * 1758 * :type:`nghttp3_reset_stream` is a callback function which is 1759 * invoked when the library asks application to reset stream 1760 * identified by |stream_id|. |app_error_code| indicates the reason 1761 * for this action. 1762 * 1763 * The implementation of this callback must return 0 if it succeeds. 1764 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1765 * caller immediately. Any values other than 0 is treated as 1766 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1767 */ 1768 typedef int (*nghttp3_reset_stream)(nghttp3_conn *conn, int64_t stream_id, 1769 uint64_t app_error_code, 1770 void *conn_user_data, 1771 void *stream_user_data); 1772 1773 /** 1774 * @functypedef 1775 * 1776 * :type:`nghttp3_shutdown` is a callback function which is invoked 1777 * when a shutdown is initiated by the remote endpoint. For client, 1778 * |id| contains a stream id of a client initiated stream, for server, 1779 * it contains a push id. All client streams with stream id or pushes 1780 * with push id equal to or larger than |id| are guaranteed to not be 1781 * processed by the remote endpoint. 1782 * 1783 * Parameter |id| for client can contain a special value 1784 * :macro:`NGHTTP3_SHUTDOWN_NOTICE_STREAM_ID` and for server it can 1785 * contain special value 1786 * :macro:`NGHTTP3_SHUTDOWN_NOTICE_PUSH_ID`. These values signal 1787 * request for graceful shutdown of the connection, triggered by 1788 * remote endpoint's invocation of 1789 * `nghttp3_conn_submit_shutdown_notice`. 1790 * 1791 * It is possible that this callback is invoked multiple times on a 1792 * single connection, however the |id| can only stay the same or 1793 * decrease, never increase. 1794 * 1795 * The implementation of this callback must return 0 if it succeeds. 1796 * Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the 1797 * caller immediately. Any values other than 0 is treated as 1798 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 1799 */ 1800 typedef int (*nghttp3_shutdown)(nghttp3_conn *conn, int64_t id, 1801 void *conn_user_data); 1802 1803 #define NGHTTP3_CALLBACKS_VERSION_V1 1 1804 #define NGHTTP3_CALLBACKS_VERSION NGHTTP3_CALLBACKS_VERSION_V1 1805 1806 /** 1807 * @struct 1808 * 1809 * :type:`nghttp3_callbacks` holds a set of callback functions. 1810 */ 1811 typedef struct nghttp3_callbacks { 1812 /** 1813 * :member:`acked_stream_data` is a callback function which is 1814 * invoked when data sent on a particular stream have been 1815 * acknowledged by a remote endpoint. 1816 */ 1817 nghttp3_acked_stream_data acked_stream_data; 1818 /** 1819 * :member:`stream_close` is a callback function which is invoked 1820 * when a particular stream has closed. 1821 */ 1822 nghttp3_stream_close stream_close; 1823 /** 1824 * :member:`recv_data` is a callback function which is invoked when 1825 * stream data is received. 1826 */ 1827 nghttp3_recv_data recv_data; 1828 /** 1829 * :member:`deferred_consume` is a callback function which is 1830 * invoked when the library consumed data for a particular stream 1831 * which had been blocked for synchronization between streams. 1832 */ 1833 nghttp3_deferred_consume deferred_consume; 1834 /** 1835 * :member:`begin_headers` is a callback function which is invoked 1836 * when a header block has started on a particular stream. 1837 */ 1838 nghttp3_begin_headers begin_headers; 1839 /** 1840 * :member:`recv_header` is a callback function which is invoked 1841 * when a single header field is received on a particular stream. 1842 */ 1843 nghttp3_recv_header recv_header; 1844 /** 1845 * :member:`end_headers` is a callback function which is invoked 1846 * when a header block has ended on a particular stream. 1847 */ 1848 nghttp3_end_headers end_headers; 1849 /** 1850 * :member:`begin_trailers` is a callback function which is invoked 1851 * when a trailer block has started on a particular stream. 1852 */ 1853 nghttp3_begin_headers begin_trailers; 1854 /** 1855 * :member:`recv_trailer` is a callback function which is invoked 1856 * when a single trailer field is received on a particular stream. 1857 */ 1858 nghttp3_recv_header recv_trailer; 1859 /** 1860 * :member:`end_trailers` is a callback function which is invoked 1861 * when a trailer block has ended on a particular stream. 1862 */ 1863 nghttp3_end_headers end_trailers; 1864 /** 1865 * :member:`stop_sending` is a callback function which is invoked 1866 * when the library asks application to send STOP_SENDING to a 1867 * particular stream. 1868 */ 1869 nghttp3_stop_sending stop_sending; 1870 /** 1871 * :member:`end_stream` is a callback function which is invoked when 1872 * a receiving side of stream has been closed. 1873 */ 1874 nghttp3_end_stream end_stream; 1875 /** 1876 * :member:`reset_stream` is a callback function which is invoked 1877 * when the library asks application to reset stream (by sending 1878 * RESET_STREAM). It is only used by server to reject a request. 1879 */ 1880 nghttp3_reset_stream reset_stream; 1881 /** 1882 * :member:`shutdown` is a callback function which is invoked when 1883 * the remote endpoint has signalled initiation of connection shutdown. 1884 */ 1885 nghttp3_shutdown shutdown; 1886 } nghttp3_callbacks; 1887 1888 #define NGHTTP3_SETTINGS_VERSION_V1 1 1889 #define NGHTTP3_SETTINGS_VERSION NGHTTP3_SETTINGS_VERSION_V1 1890 1891 /** 1892 * @struct 1893 * 1894 * :type:`nghttp3_settings` defines HTTP/3 settings. 1895 */ 1896 typedef struct nghttp3_settings { 1897 /** 1898 * :member:`max_field_section_size` specifies the maximum header 1899 * section (block) size. 1900 */ 1901 uint64_t max_field_section_size; 1902 /** 1903 * :member:`qpack_max_table_capacity` is the maximum size of QPACK 1904 * dynamic table. 1905 */ 1906 size_t qpack_max_table_capacity; 1907 /** 1908 * :member:`qpack_blocked_streams` is the maximum number of streams 1909 * which can be blocked while they are being decoded. 1910 */ 1911 size_t qpack_blocked_streams; 1912 /** 1913 * :member:`enable_connect_protocol`, if set to nonzero, enables 1914 * Extended CONNECT Method (see 1915 * https://www.ietf.org/archive/id/draft-ietf-httpbis-h3-websockets-00.html). 1916 * Client ignores this field. 1917 */ 1918 int enable_connect_protocol; 1919 } nghttp3_settings; 1920 1921 /** 1922 * @function 1923 * 1924 * `nghttp3_settings_default` fills |settings| with the default 1925 * values. 1926 */ 1927 NGHTTP3_EXTERN void 1928 nghttp3_settings_default_versioned(int settings_version, 1929 nghttp3_settings *settings); 1930 1931 /** 1932 * @function 1933 * 1934 * `nghttp3_conn_client_new` creates :type:`nghttp3_conn` and 1935 * initializes it for client use. The pointer to the object is stored 1936 * in |*pconn|. If |mem| is ``NULL``, the memory allocator returned 1937 * by `nghttp3_mem_default` is used. 1938 */ 1939 NGHTTP3_EXTERN int 1940 nghttp3_conn_client_new_versioned(nghttp3_conn **pconn, int callbacks_version, 1941 const nghttp3_callbacks *callbacks, 1942 int settings_version, 1943 const nghttp3_settings *settings, 1944 const nghttp3_mem *mem, void *conn_user_data); 1945 1946 /** 1947 * @function 1948 * 1949 * `nghttp3_conn_server_new` creates :type:`nghttp3_conn` and 1950 * initializes it for server use. The pointer to the object is stored 1951 * in |*pconn|. If |mem| is ``NULL``, the memory allocator returned 1952 * by `nghttp3_mem_default` is used. 1953 */ 1954 NGHTTP3_EXTERN int 1955 nghttp3_conn_server_new_versioned(nghttp3_conn **pconn, int callbacks_version, 1956 const nghttp3_callbacks *callbacks, 1957 int settings_version, 1958 const nghttp3_settings *settings, 1959 const nghttp3_mem *mem, void *conn_user_data); 1960 1961 /** 1962 * @function 1963 * 1964 * `nghttp3_conn_del` frees resources allocated for |conn|. 1965 */ 1966 NGHTTP3_EXTERN void nghttp3_conn_del(nghttp3_conn *conn); 1967 1968 /** 1969 * @function 1970 * 1971 * `nghttp3_conn_bind_control_stream` binds stream denoted by 1972 * |stream_id| to outgoing unidirectional control stream. 1973 * 1974 * This function returns 0 if it succeeds, or one of the following 1975 * negative error codes: 1976 * 1977 * :macro:`NGHTTP3_ERR_INVALID_STATE` 1978 * Control stream has already corresponding stream ID. 1979 * 1980 * TBD 1981 */ 1982 NGHTTP3_EXTERN int nghttp3_conn_bind_control_stream(nghttp3_conn *conn, 1983 int64_t stream_id); 1984 1985 /** 1986 * @function 1987 * 1988 * `nghttp3_conn_bind_qpack_streams` binds stream denoted by 1989 * |qenc_stream_id| to outgoing QPACK encoder stream and stream 1990 * denoted by |qdec_stream_id| to outgoing QPACK encoder stream. 1991 * 1992 * This function returns 0 if it succeeds, or one of the following 1993 * negative error codes: 1994 * 1995 * :macro:`NGHTTP3_ERR_INVALID_STATE` 1996 * QPACK encoder/decoder stream have already corresponding stream 1997 * IDs. 1998 * 1999 * TBD 2000 */ 2001 NGHTTP3_EXTERN int nghttp3_conn_bind_qpack_streams(nghttp3_conn *conn, 2002 int64_t qenc_stream_id, 2003 int64_t qdec_stream_id); 2004 2005 /** 2006 * @function 2007 * 2008 * `nghttp3_conn_read_stream` reads data |src| of length |srclen| on 2009 * stream identified by |stream_id|. It returns the number of bytes 2010 * consumed. The "consumed" means that application can increase flow 2011 * control credit (both stream and connection) of underlying QUIC 2012 * connection by that amount. It does not include the amount of data 2013 * carried by DATA frame which contains application data (excluding 2014 * any control or QPACK unidirectional streams) . See 2015 * :type:`nghttp3_recv_data` to handle those bytes. If |fin| is 2016 * nonzero, this is the last data from remote endpoint in this stream. 2017 */ 2018 NGHTTP3_EXTERN nghttp3_ssize nghttp3_conn_read_stream(nghttp3_conn *conn, 2019 int64_t stream_id, 2020 const uint8_t *src, 2021 size_t srclen, int fin); 2022 2023 /** 2024 * @function 2025 * 2026 * `nghttp3_conn_writev_stream` stores stream data to send to |vec| of 2027 * length |veccnt| and returns the number of nghttp3_vec object in 2028 * which it stored data. It stores stream ID to |*pstream_id|. An 2029 * application has to call `nghttp3_conn_add_write_offset` to inform 2030 * |conn| of the actual number of bytes that underlying QUIC stack 2031 * accepted. |*pfin| will be nonzero if this is the last data to 2032 * send. If there is no stream to write data or send fin, this 2033 * function returns 0, and -1 is assigned to |*pstream_id|. This 2034 * function may return 0 and |*pstream_id| is not -1 and |*pfin| is 2035 * nonzero. It means 0 length data to |*pstream_id| and it is the 2036 * last data to the stream. They must be passed to QUIC stack, and 2037 * they are accepted, the application has to call 2038 * `nghttp3_conn_add_write_offset`. 2039 */ 2040 NGHTTP3_EXTERN nghttp3_ssize nghttp3_conn_writev_stream(nghttp3_conn *conn, 2041 int64_t *pstream_id, 2042 int *pfin, 2043 nghttp3_vec *vec, 2044 size_t veccnt); 2045 2046 /** 2047 * @function 2048 * 2049 * `nghttp3_conn_add_write_offset` tells |conn| the number of bytes 2050 * |n| for stream denoted by |stream_id| QUIC stack accepted. 2051 * 2052 * If stream has no data to send but just sends fin (closing the write 2053 * side of a stream), the number of bytes sent is 0. It is important 2054 * to call this function even if |n| is 0 in this case. It is safe to 2055 * call this function if |n| is 0. 2056 * 2057 * `nghttp3_conn_writev_stream` must be called before calling this 2058 * function to get data to send, and those data must be fed into QUIC 2059 * stack. 2060 */ 2061 NGHTTP3_EXTERN int nghttp3_conn_add_write_offset(nghttp3_conn *conn, 2062 int64_t stream_id, size_t n); 2063 2064 /** 2065 * @function 2066 * 2067 * `nghttp3_conn_add_ack_offset` tells |conn| the number of bytes |n| 2068 * for stream denoted by |stream_id| QUIC stack has acknowledged. 2069 */ 2070 NGHTTP3_EXTERN int nghttp3_conn_add_ack_offset(nghttp3_conn *conn, 2071 int64_t stream_id, uint64_t n); 2072 2073 /** 2074 * @function 2075 * 2076 * `nghttp3_conn_block_stream` tells the library that stream 2077 * identified by |stream_id| is blocked due to QUIC flow control. 2078 */ 2079 NGHTTP3_EXTERN int nghttp3_conn_block_stream(nghttp3_conn *conn, 2080 int64_t stream_id); 2081 2082 /** 2083 * @function 2084 * 2085 * `nghttp3_conn_unblock_stream` tells the library that stream 2086 * identified by |stream_id| which was blocked by QUIC flow control is 2087 * unblocked. 2088 */ 2089 NGHTTP3_EXTERN int nghttp3_conn_unblock_stream(nghttp3_conn *conn, 2090 int64_t stream_id); 2091 2092 /** 2093 * @function 2094 * 2095 * `nghttp3_conn_shutdown_stream_write` tells the library that any 2096 * further write operation to stream identified by |stream_id| is 2097 * prohibited. This works like `nghttp3_conn_block_stream`, but it 2098 * cannot be unblocked by `nghttp3_conn_unblock_stream`. 2099 */ 2100 NGHTTP3_EXTERN int nghttp3_conn_shutdown_stream_write(nghttp3_conn *conn, 2101 int64_t stream_id); 2102 2103 /** 2104 * @function 2105 * 2106 * `nghttp3_conn_shutdown_stream_read` tells the library that 2107 * read-side of stream denoted by |stream_id| is abruptly closed and 2108 * any further incoming data and pending stream data should be 2109 * discarded. 2110 */ 2111 NGHTTP3_EXTERN int nghttp3_conn_shutdown_stream_read(nghttp3_conn *conn, 2112 int64_t stream_id); 2113 2114 /** 2115 * @function 2116 * 2117 * `nghttp3_conn_resume_stream` resumes stream identified by 2118 * |stream_id| which was previously unable to provide data. 2119 */ 2120 NGHTTP3_EXTERN int nghttp3_conn_resume_stream(nghttp3_conn *conn, 2121 int64_t stream_id); 2122 2123 /** 2124 * @function 2125 * 2126 * `nghttp3_conn_close_stream` closes stream identified by 2127 * |stream_id|. |app_error_code| is the reason of the closure. 2128 */ 2129 NGHTTP3_EXTERN int nghttp3_conn_close_stream(nghttp3_conn *conn, 2130 int64_t stream_id, 2131 uint64_t app_error_code); 2132 2133 /** 2134 * @macrosection 2135 * 2136 * Data flags 2137 */ 2138 2139 /** 2140 * @macro 2141 * 2142 * :macro:`NGHTTP3_DATA_FLAG_NONE` indicates no flag set. 2143 */ 2144 #define NGHTTP3_DATA_FLAG_NONE 0x00 2145 2146 /** 2147 * @macro 2148 * 2149 * :macro:`NGHTTP3_DATA_FLAG_EOF` indicates that all request or 2150 * response body has been provided to the library. It also indicates 2151 * that sending side of stream is closed unless 2152 * :macro:`NGHTTP3_DATA_FLAG_NO_END_STREAM` is given at the same time. 2153 */ 2154 #define NGHTTP3_DATA_FLAG_EOF 0x01 2155 2156 /** 2157 * @macro 2158 * 2159 * :macro:`NGHTTP3_DATA_FLAG_NO_END_STREAM` indicates that sending 2160 * side of stream is not closed even if :macro:`NGHTTP3_DATA_FLAG_EOF` 2161 * is set. Usually this flag is used to send trailer fields with 2162 * `nghttp3_conn_submit_trailers()`. If 2163 * `nghttp3_conn_submit_trailers()` has been called, regardless of 2164 * this flag, the submitted trailer fields are sent. 2165 */ 2166 #define NGHTTP3_DATA_FLAG_NO_END_STREAM 0x02 2167 2168 /** 2169 * @function 2170 * 2171 * `nghttp3_conn_set_max_client_streams_bidi` tells |conn| the 2172 * cumulative number of bidirectional streams that client can open. 2173 */ 2174 NGHTTP3_EXTERN void 2175 nghttp3_conn_set_max_client_streams_bidi(nghttp3_conn *conn, 2176 uint64_t max_streams); 2177 2178 /** 2179 * @function 2180 * 2181 * `nghttp3_conn_set_max_concurrent_streams` tells |conn| the maximum 2182 * number of concurrent streams that a remote endpoint can open, 2183 * including both bidirectional and unidirectional streams which 2184 * potentially receive QPACK encoded HEADERS frame. This value is 2185 * used as a hint to limit the internal resource consumption. 2186 */ 2187 NGHTTP3_EXTERN void 2188 nghttp3_conn_set_max_concurrent_streams(nghttp3_conn *conn, 2189 size_t max_concurrent_streams); 2190 2191 /** 2192 * @functypedef 2193 * 2194 * :type:`nghttp3_read_data_callback` is a callback function invoked 2195 * when the library asks an application to provide stream data for a 2196 * stream denoted by |stream_id|. 2197 * 2198 * The library provides |vec| of length |veccnt| to the application. 2199 * The application should fill data and its length to |vec|. It has 2200 * to return the number of the filled objects. The application must 2201 * retain data until they are safe to free. It is notified by 2202 * :type:`nghttp3_acked_stream_data` callback. 2203 * 2204 * If this is the last data to send (or there is no data to send 2205 * because all data have been sent already), set 2206 * :macro:`NGHTTP3_DATA_FLAG_EOF` to |*pflags|. 2207 * 2208 * If the application is unable to provide data temporarily, return 2209 * :macro:`NGHTTP3_ERR_WOULDBLOCK`. When it is ready to provide 2210 * data, call `nghttp3_conn_resume_stream()`. 2211 * 2212 * The callback should return the number of objects in |vec| that the 2213 * application filled if it succeeds, or 2214 * :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. 2215 * 2216 * TODO Add NGHTTP3_ERR_TEMPORAL_CALLBACK_FAILURE to reset just this 2217 * stream. 2218 */ 2219 typedef nghttp3_ssize (*nghttp3_read_data_callback)( 2220 nghttp3_conn *conn, int64_t stream_id, nghttp3_vec *vec, size_t veccnt, 2221 uint32_t *pflags, void *conn_user_data, void *stream_user_data); 2222 2223 /** 2224 * @struct 2225 * 2226 * :type:`nghttp3_data_reader` specifies the way how to generate 2227 * request or response body. 2228 */ 2229 typedef struct nghttp3_data_reader { 2230 /** 2231 * :member:`read_data` is a callback function to generate body. 2232 */ 2233 nghttp3_read_data_callback read_data; 2234 } nghttp3_data_reader; 2235 2236 /** 2237 * @function 2238 * 2239 * `nghttp3_conn_submit_request` submits HTTP request header fields 2240 * and body on the stream identified by |stream_id|. |stream_id| must 2241 * be a client initiated bidirectional stream. Only client can submit 2242 * HTTP request. |nva| of length |nvlen| specifies HTTP request 2243 * header fields. |dr| specifies a request body. If there is no 2244 * request body, specify NULL. If |dr| is NULL, it implies the end of 2245 * stream. |stream_user_data| is an opaque pointer attached to the 2246 * stream. 2247 */ 2248 NGHTTP3_EXTERN int nghttp3_conn_submit_request( 2249 nghttp3_conn *conn, int64_t stream_id, const nghttp3_nv *nva, size_t nvlen, 2250 const nghttp3_data_reader *dr, void *stream_user_data); 2251 2252 /** 2253 * @function 2254 * 2255 * `nghttp3_conn_submit_info` submits HTTP non-final response header 2256 * fields on the stream identified by |stream_id|. |nva| of length 2257 * |nvlen| specifies HTTP response header fields. 2258 */ 2259 NGHTTP3_EXTERN int nghttp3_conn_submit_info(nghttp3_conn *conn, 2260 int64_t stream_id, 2261 const nghttp3_nv *nva, 2262 size_t nvlen); 2263 2264 /** 2265 * @function 2266 * 2267 * `nghttp3_conn_submit_response` submits HTTP response header fields 2268 * and body on the stream identified by |stream_id|. |nva| of length 2269 * |nvlen| specifies HTTP response header fields. |dr| specifies a 2270 * response body. If there is no response body, specify NULL. If 2271 * |dr| is NULL, it implies the end of stream. 2272 */ 2273 NGHTTP3_EXTERN int nghttp3_conn_submit_response(nghttp3_conn *conn, 2274 int64_t stream_id, 2275 const nghttp3_nv *nva, 2276 size_t nvlen, 2277 const nghttp3_data_reader *dr); 2278 2279 /** 2280 * @function 2281 * 2282 * `nghttp3_conn_submit_trailers` submits HTTP trailer fields on the 2283 * stream identified by |stream_id|. |nva| of length |nvlen| 2284 * specifies HTTP trailer fields. Calling this function implies the 2285 * end of stream. 2286 */ 2287 NGHTTP3_EXTERN int nghttp3_conn_submit_trailers(nghttp3_conn *conn, 2288 int64_t stream_id, 2289 const nghttp3_nv *nva, 2290 size_t nvlen); 2291 2292 /** 2293 * @function 2294 * 2295 * `nghttp3_conn_submit_shutdown_notice` notifies the other endpoint 2296 * to stop creating new stream. After a couple of RTTs later, call 2297 * `nghttp3_conn_shutdown` to start graceful shutdown. 2298 */ 2299 NGHTTP3_EXTERN int nghttp3_conn_submit_shutdown_notice(nghttp3_conn *conn); 2300 2301 /** 2302 * @function 2303 * 2304 * `nghttp3_conn_shutdown` starts graceful shutdown. It should be 2305 * called after `nghttp3_conn_submit_shutdown_notice` and a couple of 2306 * RTT. After calling this function, the local endpoint starts 2307 * rejecting new incoming streams. The existing streams are processed 2308 * normally. 2309 */ 2310 NGHTTP3_EXTERN int nghttp3_conn_shutdown(nghttp3_conn *conn); 2311 2312 /** 2313 * @function 2314 * 2315 * `nghttp3_conn_set_stream_user_data` sets |stream_user_data| to the 2316 * stream identified by |stream_id|. 2317 */ 2318 NGHTTP3_EXTERN int nghttp3_conn_set_stream_user_data(nghttp3_conn *conn, 2319 int64_t stream_id, 2320 void *stream_user_data); 2321 2322 /** 2323 * @function 2324 * 2325 * `nghttp3_conn_get_frame_payload_left` returns the number of bytes 2326 * left to read current frame payload for a stream denoted by 2327 * |stream_id|. If no such stream is found, it returns 2328 * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND`. 2329 */ 2330 NGHTTP3_EXTERN int64_t nghttp3_conn_get_frame_payload_left(nghttp3_conn *conn, 2331 int64_t stream_id); 2332 2333 /** 2334 * @macrosection 2335 * 2336 * HTTP stream priority flags 2337 */ 2338 2339 /** 2340 * @macro 2341 * 2342 * :macro:`NGHTTP3_DEFAULT_URGENCY` is the default urgency level. 2343 */ 2344 #define NGHTTP3_DEFAULT_URGENCY 3 2345 2346 /** 2347 * @macro 2348 * 2349 * :macro:`NGHTTP3_URGENCY_HIGH` is the highest urgency level. 2350 */ 2351 #define NGHTTP3_URGENCY_HIGH 0 2352 2353 /** 2354 * @macro 2355 * 2356 * :macro:`NGHTTP3_URGENCY_LOW` is the lowest urgency level. 2357 */ 2358 #define NGHTTP3_URGENCY_LOW 7 2359 2360 /** 2361 * @macro 2362 * 2363 * :macro:`NGHTTP3_URGENCY_LEVELS` is the number of urgency levels. 2364 */ 2365 #define NGHTTP3_URGENCY_LEVELS (NGHTTP3_URGENCY_LOW + 1) 2366 2367 /** 2368 * @struct 2369 * 2370 * :type:`nghttp3_pri` represents HTTP priority. 2371 */ 2372 typedef struct nghttp3_pri { 2373 /** 2374 * :member:`urgency` is the urgency of a stream, it must be in 2375 * [:macro:`NGHTTP3_URGENCY_HIGH`, :macro:`NGHTTP3_URGENCY_LOW`], 2376 * inclusive, and 0 is the highest urgency. 2377 */ 2378 uint32_t urgency; 2379 /** 2380 * :member:`inc` indicates that a content can be processed 2381 * incrementally or not. If inc is 0, it cannot be processed 2382 * incrementally. If inc is 1, it can be processed incrementally. 2383 * Other value is not permitted. 2384 */ 2385 int inc; 2386 } nghttp3_pri; 2387 2388 /** 2389 * @function 2390 * 2391 * `nghttp3_conn_get_stream_priority` stores stream priority of a 2392 * stream denoted by |stream_id| into |*dest|. |stream_id| must 2393 * identify client initiated bidirectional stream. Only server can 2394 * use this function. 2395 * 2396 * This function must not be called if |conn| is initialized as 2397 * client. 2398 * 2399 * This function returns 0 if it succeeds, or one of the following 2400 * negative error codes: 2401 * 2402 * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND` 2403 * Stream not found. 2404 */ 2405 NGHTTP3_EXTERN int nghttp3_conn_get_stream_priority(nghttp3_conn *conn, 2406 nghttp3_pri *dest, 2407 int64_t stream_id); 2408 2409 /** 2410 * @function 2411 * 2412 * `nghttp3_conn_set_stream_priority` updates priority of a stream 2413 * denoted by |stream_id| with the value pointed by |pri|. 2414 * |stream_id| must identify client initiated bidirectional stream. 2415 * 2416 * Both client and server can update stream priority with this 2417 * function. 2418 * 2419 * If server updates stream priority with this function, it completely 2420 * overrides stream priority set by client and the attempts to update 2421 * priority by client are ignored. 2422 * 2423 * This function returns 0 if it succeeds, or one of the following 2424 * negative error codes: 2425 * 2426 * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT` 2427 * |stream_id| is not a client initiated bidirectional stream ID. 2428 * :macro:`NGHTTP3_ERR_STREAM_NOT_FOUND` 2429 * Stream not found. 2430 * :macro:`NGHTTP3_ERR_NOMEM` 2431 * Out of memory. 2432 */ 2433 NGHTTP3_EXTERN int nghttp3_conn_set_stream_priority(nghttp3_conn *conn, 2434 int64_t stream_id, 2435 const nghttp3_pri *pri); 2436 2437 /** 2438 * @function 2439 * 2440 * `nghttp3_conn_is_remote_qpack_encoder_stream` returns nonzero if a 2441 * stream denoted by |stream_id| is QPACK encoder stream of a remote 2442 * endpoint. 2443 */ 2444 NGHTTP3_EXTERN int 2445 nghttp3_conn_is_remote_qpack_encoder_stream(nghttp3_conn *conn, 2446 int64_t stream_id); 2447 2448 /** 2449 * @function 2450 * 2451 * `nghttp3_vec_len` returns the sum of length in |vec| of |cnt| 2452 * elements. 2453 */ 2454 NGHTTP3_EXTERN uint64_t nghttp3_vec_len(const nghttp3_vec *vec, size_t cnt); 2455 2456 /** 2457 * @function 2458 * 2459 * `nghttp3_check_header_name` returns nonzero if HTTP header field 2460 * name |name| of length |len| is valid according to 2461 * http://tools.ietf.org/html/rfc7230#section-3.2 2462 * 2463 * Because this is a header field name in HTTP/3, the upper cased 2464 * alphabet is treated as error. 2465 */ 2466 NGHTTP3_EXTERN int nghttp3_check_header_name(const uint8_t *name, size_t len); 2467 2468 /** 2469 * @function 2470 * 2471 * `nghttp3_check_header_value` returns nonzero if HTTP header field 2472 * value |value| of length |len| is valid according to 2473 * http://tools.ietf.org/html/rfc7230#section-3.2 2474 */ 2475 NGHTTP3_EXTERN int nghttp3_check_header_value(const uint8_t *value, size_t len); 2476 2477 /** 2478 * @function 2479 * 2480 * `nghttp3_http_parse_priority` parses priority HTTP header field 2481 * stored in the buffer pointed by |value| of length |len|. If it 2482 * successfully processed header field value, it stores the result 2483 * into |*dest|. This function just overwrites what it sees in the 2484 * header field value and does not initialize any field in |*dest|. 2485 * 2486 * This function returns 0 if it succeeds, or one of the following 2487 * negative error codes: 2488 * 2489 * :macro:`NGHTTP3_ERR_INVALID_ARGUMENT` 2490 * The function could not parse the provided value. 2491 */ 2492 NGHTTP3_EXTERN int nghttp3_http_parse_priority(nghttp3_pri *dest, 2493 const uint8_t *value, 2494 size_t len); 2495 2496 /** 2497 * @macrosection 2498 * 2499 * nghttp3_info flags 2500 */ 2501 2502 /** 2503 * @macro 2504 * 2505 * :macro:`NGHTTP3_VERSION_AGE` is the age of :type:`nghttp3_info`. 2506 */ 2507 #define NGHTTP3_VERSION_AGE 1 2508 2509 /** 2510 * @struct 2511 * 2512 * :type:`nghttp3_info` is what `nghttp3_version()` returns. It holds 2513 * information about the particular nghttp3 version. 2514 */ 2515 typedef struct nghttp3_info { 2516 /** 2517 * :member:`age` is the age of this struct. This instance of 2518 * nghttp3 sets it to :macro:`NGHTTP3_VERSION_AGE` but a future 2519 * version may bump it and add more struct fields at the bottom 2520 */ 2521 int age; 2522 /** 2523 * :member:`version_num` is the :macro:`NGHTTP3_VERSION_NUM` number 2524 * (since age ==1) 2525 */ 2526 int version_num; 2527 /** 2528 * :member:`version_str` points to the :macro:`NGHTTP3_VERSION` 2529 * string (since age ==1) 2530 */ 2531 const char *version_str; 2532 /* -------- the above fields all exist when age == 1 */ 2533 } nghttp3_info; 2534 2535 /** 2536 * @function 2537 * 2538 * `nghttp3_version` returns a pointer to a :type:`nghttp3_info` 2539 * struct with version information about the run-time library in use. 2540 * The |least_version| argument can be set to a 24 bit numerical value 2541 * for the least accepted version number and if the condition is not 2542 * met, this function will return a ``NULL``. Pass in 0 to skip the 2543 * version checking. 2544 */ 2545 NGHTTP3_EXTERN const nghttp3_info *nghttp3_version(int least_version); 2546 2547 /** 2548 * @function 2549 * 2550 * `nghttp3_err_is_fatal` returns nonzero if |liberr| is a fatal 2551 * error. |liberr| must be one of nghttp3 library error codes (which 2552 * is defined as NGHTTP3_ERR_* macro, such as 2553 * :macro:`NGHTTP3_ERR_NOMEM`). 2554 */ 2555 NGHTTP3_EXTERN int nghttp3_err_is_fatal(int liberr); 2556 2557 /* 2558 * Versioned function wrappers 2559 */ 2560 2561 /* 2562 * `nghttp3_settings_default` is a wrapper around 2563 * `nghttp3_settings_default_versioned` to set the correct struct 2564 * version. 2565 */ 2566 #define nghttp3_settings_default(SETTINGS) \ 2567 nghttp3_settings_default_versioned(NGHTTP3_SETTINGS_VERSION, (SETTINGS)) 2568 2569 /* 2570 * `nghttp3_conn_client_new` is a wrapper around 2571 * `nghttp3_conn_client_new_versioned` to set the correct struct 2572 * version. 2573 */ 2574 #define nghttp3_conn_client_new(PCONN, CALLBACKS, SETTINGS, MEM, USER_DATA) \ 2575 nghttp3_conn_client_new_versioned((PCONN), NGHTTP3_CALLBACKS_VERSION, \ 2576 (CALLBACKS), NGHTTP3_SETTINGS_VERSION, \ 2577 (SETTINGS), (MEM), (USER_DATA)) 2578 2579 /* 2580 * `nghttp3_conn_server_new` is a wrapper around 2581 * `nghttp3_conn_server_new_versioned` to set the correct struct 2582 * version. 2583 */ 2584 #define nghttp3_conn_server_new(PCONN, CALLBACKS, SETTINGS, MEM, USER_DATA) \ 2585 nghttp3_conn_server_new_versioned((PCONN), NGHTTP3_CALLBACKS_VERSION, \ 2586 (CALLBACKS), NGHTTP3_SETTINGS_VERSION, \ 2587 (SETTINGS), (MEM), (USER_DATA)) 2588 2589 #ifdef __cplusplus 2590 } 2591 #endif 2592 2593 #endif /* NGHTTP3_H */ 2594