1 /* 2 * nghttp2 - HTTP/2 C Library 3 * 4 * Copyright (c) 2013, 2014 Tatsuhiro Tsujikawa 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining 7 * a copy of this software and associated documentation files (the 8 * "Software"), to deal in the Software without restriction, including 9 * without limitation the rights to use, copy, modify, merge, publish, 10 * distribute, sublicense, and/or sell copies of the Software, and to 11 * permit persons to whom the Software is furnished to do so, subject to 12 * the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be 15 * included in all copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 24 */ 25 #ifndef NGHTTP2_H 26 #define NGHTTP2_H 27 28 /* Define WIN32 when build target is Win32 API (borrowed from 29 libcurl) */ 30 #if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32) 31 # define WIN32 32 #endif 33 34 /* Compatibility for non-Clang compilers */ 35 #ifndef __has_declspec_attribute 36 # define __has_declspec_attribute(x) 0 37 #endif 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 #include <stdlib.h> 44 #if defined(_MSC_VER) && (_MSC_VER < 1800) 45 /* MSVC < 2013 does not have inttypes.h because it is not C99 46 compliant. See compiler macros and version number in 47 https://sourceforge.net/p/predef/wiki/Compilers/ */ 48 # include <stdint.h> 49 #else /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */ 50 # include <inttypes.h> 51 #endif /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */ 52 #include <sys/types.h> 53 #include <stdarg.h> 54 55 #include <nghttp2/nghttp2ver.h> 56 57 #ifdef NGHTTP2_STATICLIB 58 # define NGHTTP2_EXTERN 59 #elif defined(WIN32) || (__has_declspec_attribute(dllexport) && \ 60 __has_declspec_attribute(dllimport)) 61 # ifdef BUILDING_NGHTTP2 62 # define NGHTTP2_EXTERN __declspec(dllexport) 63 # else /* !BUILDING_NGHTTP2 */ 64 # define NGHTTP2_EXTERN __declspec(dllimport) 65 # endif /* !BUILDING_NGHTTP2 */ 66 #else /* !defined(WIN32) */ 67 # ifdef BUILDING_NGHTTP2 68 # define NGHTTP2_EXTERN __attribute__((visibility("default"))) 69 # else /* !BUILDING_NGHTTP2 */ 70 # define NGHTTP2_EXTERN 71 # endif /* !BUILDING_NGHTTP2 */ 72 #endif /* !defined(WIN32) */ 73 74 /** 75 * @macro 76 * 77 * The protocol version identification string of this library 78 * supports. This identifier is used if HTTP/2 is used over TLS. 79 */ 80 #define NGHTTP2_PROTO_VERSION_ID "h2" 81 /** 82 * @macro 83 * 84 * The length of :macro:`NGHTTP2_PROTO_VERSION_ID`. 85 */ 86 #define NGHTTP2_PROTO_VERSION_ID_LEN 2 87 88 /** 89 * @macro 90 * 91 * The serialized form of ALPN protocol identifier this library 92 * supports. Notice that first byte is the length of following 93 * protocol identifier. This is the same wire format of `TLS ALPN 94 * extension <https://tools.ietf.org/html/rfc7301>`_. This is useful 95 * to process incoming ALPN tokens in wire format. 96 */ 97 #define NGHTTP2_PROTO_ALPN "\x2h2" 98 99 /** 100 * @macro 101 * 102 * The length of :macro:`NGHTTP2_PROTO_ALPN`. 103 */ 104 #define NGHTTP2_PROTO_ALPN_LEN (sizeof(NGHTTP2_PROTO_ALPN) - 1) 105 106 /** 107 * @macro 108 * 109 * The protocol version identification string of this library 110 * supports. This identifier is used if HTTP/2 is used over cleartext 111 * TCP. 112 */ 113 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID "h2c" 114 115 /** 116 * @macro 117 * 118 * The length of :macro:`NGHTTP2_CLEARTEXT_PROTO_VERSION_ID`. 119 */ 120 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN 3 121 122 struct nghttp2_session; 123 /** 124 * @struct 125 * 126 * The primary structure to hold the resources needed for a HTTP/2 127 * session. The details of this structure are intentionally hidden 128 * from the public API. 129 */ 130 typedef struct nghttp2_session nghttp2_session; 131 132 /** 133 * @macro 134 * 135 * The age of :type:`nghttp2_info` 136 */ 137 #define NGHTTP2_VERSION_AGE 1 138 139 /** 140 * @struct 141 * 142 * This struct is what `nghttp2_version()` returns. It holds 143 * information about the particular nghttp2 version. 144 */ 145 typedef struct { 146 /** 147 * Age of this struct. This instance of nghttp2 sets it to 148 * :macro:`NGHTTP2_VERSION_AGE` but a future version may bump it and 149 * add more struct fields at the bottom 150 */ 151 int age; 152 /** 153 * the :macro:`NGHTTP2_VERSION_NUM` number (since age ==1) 154 */ 155 int version_num; 156 /** 157 * points to the :macro:`NGHTTP2_VERSION` string (since age ==1) 158 */ 159 const char *version_str; 160 /** 161 * points to the :macro:`NGHTTP2_PROTO_VERSION_ID` string this 162 * instance implements (since age ==1) 163 */ 164 const char *proto_str; 165 /* -------- the above fields all exist when age == 1 */ 166 } nghttp2_info; 167 168 /** 169 * @macro 170 * 171 * The default weight of stream dependency. 172 */ 173 #define NGHTTP2_DEFAULT_WEIGHT 16 174 175 /** 176 * @macro 177 * 178 * The maximum weight of stream dependency. 179 */ 180 #define NGHTTP2_MAX_WEIGHT 256 181 182 /** 183 * @macro 184 * 185 * The minimum weight of stream dependency. 186 */ 187 #define NGHTTP2_MIN_WEIGHT 1 188 189 /** 190 * @macro 191 * 192 * The maximum window size 193 */ 194 #define NGHTTP2_MAX_WINDOW_SIZE ((int32_t)((1U << 31) - 1)) 195 196 /** 197 * @macro 198 * 199 * The initial window size for stream level flow control. 200 */ 201 #define NGHTTP2_INITIAL_WINDOW_SIZE ((1 << 16) - 1) 202 /** 203 * @macro 204 * 205 * The initial window size for connection level flow control. 206 */ 207 #define NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE ((1 << 16) - 1) 208 209 /** 210 * @macro 211 * 212 * The default header table size. 213 */ 214 #define NGHTTP2_DEFAULT_HEADER_TABLE_SIZE (1 << 12) 215 216 /** 217 * @macro 218 * 219 * The client magic string, which is the first 24 bytes byte string of 220 * client connection preface. 221 */ 222 #define NGHTTP2_CLIENT_MAGIC "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n" 223 224 /** 225 * @macro 226 * 227 * The length of :macro:`NGHTTP2_CLIENT_MAGIC`. 228 */ 229 #define NGHTTP2_CLIENT_MAGIC_LEN 24 230 231 /** 232 * @macro 233 * 234 * The default max number of settings per SETTINGS frame 235 */ 236 #define NGHTTP2_DEFAULT_MAX_SETTINGS 32 237 238 /** 239 * @enum 240 * 241 * Error codes used in this library. The code range is [-999, -500], 242 * inclusive. The following values are defined: 243 */ 244 typedef enum { 245 /** 246 * Invalid argument passed. 247 */ 248 NGHTTP2_ERR_INVALID_ARGUMENT = -501, 249 /** 250 * Out of buffer space. 251 */ 252 NGHTTP2_ERR_BUFFER_ERROR = -502, 253 /** 254 * The specified protocol version is not supported. 255 */ 256 NGHTTP2_ERR_UNSUPPORTED_VERSION = -503, 257 /** 258 * Used as a return value from :type:`nghttp2_send_callback`, 259 * :type:`nghttp2_recv_callback` and 260 * :type:`nghttp2_send_data_callback` to indicate that the operation 261 * would block. 262 */ 263 NGHTTP2_ERR_WOULDBLOCK = -504, 264 /** 265 * General protocol error 266 */ 267 NGHTTP2_ERR_PROTO = -505, 268 /** 269 * The frame is invalid. 270 */ 271 NGHTTP2_ERR_INVALID_FRAME = -506, 272 /** 273 * The peer performed a shutdown on the connection. 274 */ 275 NGHTTP2_ERR_EOF = -507, 276 /** 277 * Used as a return value from 278 * :func:`nghttp2_data_source_read_callback` to indicate that data 279 * transfer is postponed. See 280 * :func:`nghttp2_data_source_read_callback` for details. 281 */ 282 NGHTTP2_ERR_DEFERRED = -508, 283 /** 284 * Stream ID has reached the maximum value. Therefore no stream ID 285 * is available. 286 */ 287 NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE = -509, 288 /** 289 * The stream is already closed; or the stream ID is invalid. 290 */ 291 NGHTTP2_ERR_STREAM_CLOSED = -510, 292 /** 293 * RST_STREAM has been added to the outbound queue. The stream is 294 * in closing state. 295 */ 296 NGHTTP2_ERR_STREAM_CLOSING = -511, 297 /** 298 * The transmission is not allowed for this stream (e.g., a frame 299 * with END_STREAM flag set has already sent). 300 */ 301 NGHTTP2_ERR_STREAM_SHUT_WR = -512, 302 /** 303 * The stream ID is invalid. 304 */ 305 NGHTTP2_ERR_INVALID_STREAM_ID = -513, 306 /** 307 * The state of the stream is not valid (e.g., DATA cannot be sent 308 * to the stream if response HEADERS has not been sent). 309 */ 310 NGHTTP2_ERR_INVALID_STREAM_STATE = -514, 311 /** 312 * Another DATA frame has already been deferred. 313 */ 314 NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515, 315 /** 316 * Starting new stream is not allowed (e.g., GOAWAY has been sent 317 * and/or received). 318 */ 319 NGHTTP2_ERR_START_STREAM_NOT_ALLOWED = -516, 320 /** 321 * GOAWAY has already been sent. 322 */ 323 NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517, 324 /** 325 * The received frame contains the invalid header block (e.g., There 326 * are duplicate header names; or the header names are not encoded 327 * in US-ASCII character set and not lower cased; or the header name 328 * is zero-length string; or the header value contains multiple 329 * in-sequence NUL bytes). 330 */ 331 NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518, 332 /** 333 * Indicates that the context is not suitable to perform the 334 * requested operation. 335 */ 336 NGHTTP2_ERR_INVALID_STATE = -519, 337 /** 338 * The user callback function failed due to the temporal error. 339 */ 340 NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE = -521, 341 /** 342 * The length of the frame is invalid, either too large or too small. 343 */ 344 NGHTTP2_ERR_FRAME_SIZE_ERROR = -522, 345 /** 346 * Header block inflate/deflate error. 347 */ 348 NGHTTP2_ERR_HEADER_COMP = -523, 349 /** 350 * Flow control error 351 */ 352 NGHTTP2_ERR_FLOW_CONTROL = -524, 353 /** 354 * Insufficient buffer size given to function. 355 */ 356 NGHTTP2_ERR_INSUFF_BUFSIZE = -525, 357 /** 358 * Callback was paused by the application 359 */ 360 NGHTTP2_ERR_PAUSE = -526, 361 /** 362 * There are too many in-flight SETTING frame and no more 363 * transmission of SETTINGS is allowed. 364 */ 365 NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGS = -527, 366 /** 367 * The server push is disabled. 368 */ 369 NGHTTP2_ERR_PUSH_DISABLED = -528, 370 /** 371 * DATA or HEADERS frame for a given stream has been already 372 * submitted and has not been fully processed yet. Application 373 * should wait for the transmission of the previously submitted 374 * frame before submitting another. 375 */ 376 NGHTTP2_ERR_DATA_EXIST = -529, 377 /** 378 * The current session is closing due to a connection error or 379 * `nghttp2_session_terminate_session()` is called. 380 */ 381 NGHTTP2_ERR_SESSION_CLOSING = -530, 382 /** 383 * Invalid HTTP header field was received and stream is going to be 384 * closed. 385 */ 386 NGHTTP2_ERR_HTTP_HEADER = -531, 387 /** 388 * Violation in HTTP messaging rule. 389 */ 390 NGHTTP2_ERR_HTTP_MESSAGING = -532, 391 /** 392 * Stream was refused. 393 */ 394 NGHTTP2_ERR_REFUSED_STREAM = -533, 395 /** 396 * Unexpected internal error, but recovered. 397 */ 398 NGHTTP2_ERR_INTERNAL = -534, 399 /** 400 * Indicates that a processing was canceled. 401 */ 402 NGHTTP2_ERR_CANCEL = -535, 403 /** 404 * When a local endpoint expects to receive SETTINGS frame, it 405 * receives an other type of frame. 406 */ 407 NGHTTP2_ERR_SETTINGS_EXPECTED = -536, 408 /** 409 * When a local endpoint receives too many settings entries 410 * in a single SETTINGS frame. 411 */ 412 NGHTTP2_ERR_TOO_MANY_SETTINGS = -537, 413 /** 414 * The errors < :enum:`nghttp2_error.NGHTTP2_ERR_FATAL` mean that 415 * the library is under unexpected condition and processing was 416 * terminated (e.g., out of memory). If application receives this 417 * error code, it must stop using that :type:`nghttp2_session` 418 * object and only allowed operation for that object is deallocate 419 * it using `nghttp2_session_del()`. 420 */ 421 NGHTTP2_ERR_FATAL = -900, 422 /** 423 * Out of memory. This is a fatal error. 424 */ 425 NGHTTP2_ERR_NOMEM = -901, 426 /** 427 * The user callback function failed. This is a fatal error. 428 */ 429 NGHTTP2_ERR_CALLBACK_FAILURE = -902, 430 /** 431 * Invalid client magic (see :macro:`NGHTTP2_CLIENT_MAGIC`) was 432 * received and further processing is not possible. 433 */ 434 NGHTTP2_ERR_BAD_CLIENT_MAGIC = -903, 435 /** 436 * Possible flooding by peer was detected in this HTTP/2 session. 437 * Flooding is measured by how many PING and SETTINGS frames with 438 * ACK flag set are queued for transmission. These frames are 439 * response for the peer initiated frames, and peer can cause memory 440 * exhaustion on server side to send these frames forever and does 441 * not read network. 442 */ 443 NGHTTP2_ERR_FLOODED = -904 444 } nghttp2_error; 445 446 /** 447 * @struct 448 * 449 * The object representing single contiguous buffer. 450 */ 451 typedef struct { 452 /** 453 * The pointer to the buffer. 454 */ 455 uint8_t *base; 456 /** 457 * The length of the buffer. 458 */ 459 size_t len; 460 } nghttp2_vec; 461 462 struct nghttp2_rcbuf; 463 464 /** 465 * @struct 466 * 467 * The object representing reference counted buffer. The details of 468 * this structure are intentionally hidden from the public API. 469 */ 470 typedef struct nghttp2_rcbuf nghttp2_rcbuf; 471 472 /** 473 * @function 474 * 475 * Increments the reference count of |rcbuf| by 1. 476 */ 477 NGHTTP2_EXTERN void nghttp2_rcbuf_incref(nghttp2_rcbuf *rcbuf); 478 479 /** 480 * @function 481 * 482 * Decrements the reference count of |rcbuf| by 1. If the reference 483 * count becomes zero, the object pointed by |rcbuf| will be freed. 484 * In this case, application must not use |rcbuf| again. 485 */ 486 NGHTTP2_EXTERN void nghttp2_rcbuf_decref(nghttp2_rcbuf *rcbuf); 487 488 /** 489 * @function 490 * 491 * Returns the underlying buffer managed by |rcbuf|. 492 */ 493 NGHTTP2_EXTERN nghttp2_vec nghttp2_rcbuf_get_buf(nghttp2_rcbuf *rcbuf); 494 495 /** 496 * @function 497 * 498 * Returns nonzero if the underlying buffer is statically allocated, 499 * and 0 otherwise. This can be useful for language bindings that wish 500 * to avoid creating duplicate strings for these buffers. 501 */ 502 NGHTTP2_EXTERN int nghttp2_rcbuf_is_static(const nghttp2_rcbuf *rcbuf); 503 504 /** 505 * @enum 506 * 507 * The flags for header field name/value pair. 508 */ 509 typedef enum { 510 /** 511 * No flag set. 512 */ 513 NGHTTP2_NV_FLAG_NONE = 0, 514 /** 515 * Indicates that this name/value pair must not be indexed ("Literal 516 * Header Field never Indexed" representation must be used in HPACK 517 * encoding). Other implementation calls this bit as "sensitive". 518 */ 519 NGHTTP2_NV_FLAG_NO_INDEX = 0x01, 520 /** 521 * This flag is set solely by application. If this flag is set, the 522 * library does not make a copy of header field name. This could 523 * improve performance. 524 */ 525 NGHTTP2_NV_FLAG_NO_COPY_NAME = 0x02, 526 /** 527 * This flag is set solely by application. If this flag is set, the 528 * library does not make a copy of header field value. This could 529 * improve performance. 530 */ 531 NGHTTP2_NV_FLAG_NO_COPY_VALUE = 0x04 532 } nghttp2_nv_flag; 533 534 /** 535 * @struct 536 * 537 * The name/value pair, which mainly used to represent header fields. 538 */ 539 typedef struct { 540 /** 541 * The |name| byte string. If this struct is presented from library 542 * (e.g., :type:`nghttp2_on_frame_recv_callback`), |name| is 543 * guaranteed to be NULL-terminated. For some callbacks 544 * (:type:`nghttp2_before_frame_send_callback`, 545 * :type:`nghttp2_on_frame_send_callback`, and 546 * :type:`nghttp2_on_frame_not_send_callback`), it may not be 547 * NULL-terminated if header field is passed from application with 548 * the flag :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`). 549 * When application is constructing this struct, |name| is not 550 * required to be NULL-terminated. 551 */ 552 uint8_t *name; 553 /** 554 * The |value| byte string. If this struct is presented from 555 * library (e.g., :type:`nghttp2_on_frame_recv_callback`), |value| 556 * is guaranteed to be NULL-terminated. For some callbacks 557 * (:type:`nghttp2_before_frame_send_callback`, 558 * :type:`nghttp2_on_frame_send_callback`, and 559 * :type:`nghttp2_on_frame_not_send_callback`), it may not be 560 * NULL-terminated if header field is passed from application with 561 * the flag :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE`). 562 * When application is constructing this struct, |value| is not 563 * required to be NULL-terminated. 564 */ 565 uint8_t *value; 566 /** 567 * The length of the |name|, excluding terminating NULL. 568 */ 569 size_t namelen; 570 /** 571 * The length of the |value|, excluding terminating NULL. 572 */ 573 size_t valuelen; 574 /** 575 * Bitwise OR of one or more of :type:`nghttp2_nv_flag`. 576 */ 577 uint8_t flags; 578 } nghttp2_nv; 579 580 /** 581 * @enum 582 * 583 * The frame types in HTTP/2 specification. 584 */ 585 typedef enum { 586 /** 587 * The DATA frame. 588 */ 589 NGHTTP2_DATA = 0, 590 /** 591 * The HEADERS frame. 592 */ 593 NGHTTP2_HEADERS = 0x01, 594 /** 595 * The PRIORITY frame. 596 */ 597 NGHTTP2_PRIORITY = 0x02, 598 /** 599 * The RST_STREAM frame. 600 */ 601 NGHTTP2_RST_STREAM = 0x03, 602 /** 603 * The SETTINGS frame. 604 */ 605 NGHTTP2_SETTINGS = 0x04, 606 /** 607 * The PUSH_PROMISE frame. 608 */ 609 NGHTTP2_PUSH_PROMISE = 0x05, 610 /** 611 * The PING frame. 612 */ 613 NGHTTP2_PING = 0x06, 614 /** 615 * The GOAWAY frame. 616 */ 617 NGHTTP2_GOAWAY = 0x07, 618 /** 619 * The WINDOW_UPDATE frame. 620 */ 621 NGHTTP2_WINDOW_UPDATE = 0x08, 622 /** 623 * The CONTINUATION frame. This frame type won't be passed to any 624 * callbacks because the library processes this frame type and its 625 * preceding HEADERS/PUSH_PROMISE as a single frame. 626 */ 627 NGHTTP2_CONTINUATION = 0x09, 628 /** 629 * The ALTSVC frame, which is defined in `RFC 7383 630 * <https://tools.ietf.org/html/rfc7838#section-4>`_. 631 */ 632 NGHTTP2_ALTSVC = 0x0a, 633 /** 634 * The ORIGIN frame, which is defined by `RFC 8336 635 * <https://tools.ietf.org/html/rfc8336>`_. 636 */ 637 NGHTTP2_ORIGIN = 0x0c 638 } nghttp2_frame_type; 639 640 /** 641 * @enum 642 * 643 * The flags for HTTP/2 frames. This enum defines all flags for all 644 * frames. 645 */ 646 typedef enum { 647 /** 648 * No flag set. 649 */ 650 NGHTTP2_FLAG_NONE = 0, 651 /** 652 * The END_STREAM flag. 653 */ 654 NGHTTP2_FLAG_END_STREAM = 0x01, 655 /** 656 * The END_HEADERS flag. 657 */ 658 NGHTTP2_FLAG_END_HEADERS = 0x04, 659 /** 660 * The ACK flag. 661 */ 662 NGHTTP2_FLAG_ACK = 0x01, 663 /** 664 * The PADDED flag. 665 */ 666 NGHTTP2_FLAG_PADDED = 0x08, 667 /** 668 * The PRIORITY flag. 669 */ 670 NGHTTP2_FLAG_PRIORITY = 0x20 671 } nghttp2_flag; 672 673 /** 674 * @enum 675 * The SETTINGS ID. 676 */ 677 typedef enum { 678 /** 679 * SETTINGS_HEADER_TABLE_SIZE 680 */ 681 NGHTTP2_SETTINGS_HEADER_TABLE_SIZE = 0x01, 682 /** 683 * SETTINGS_ENABLE_PUSH 684 */ 685 NGHTTP2_SETTINGS_ENABLE_PUSH = 0x02, 686 /** 687 * SETTINGS_MAX_CONCURRENT_STREAMS 688 */ 689 NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS = 0x03, 690 /** 691 * SETTINGS_INITIAL_WINDOW_SIZE 692 */ 693 NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE = 0x04, 694 /** 695 * SETTINGS_MAX_FRAME_SIZE 696 */ 697 NGHTTP2_SETTINGS_MAX_FRAME_SIZE = 0x05, 698 /** 699 * SETTINGS_MAX_HEADER_LIST_SIZE 700 */ 701 NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE = 0x06, 702 /** 703 * SETTINGS_ENABLE_CONNECT_PROTOCOL 704 * (`RFC 8441 <https://tools.ietf.org/html/rfc8441>`_) 705 */ 706 NGHTTP2_SETTINGS_ENABLE_CONNECT_PROTOCOL = 0x08 707 } nghttp2_settings_id; 708 /* Note: If we add SETTINGS, update the capacity of 709 NGHTTP2_INBOUND_NUM_IV as well */ 710 711 /** 712 * @macro 713 * 714 * .. warning:: 715 * 716 * Deprecated. The initial max concurrent streams is 0xffffffffu. 717 * 718 * Default maximum number of incoming concurrent streams. Use 719 * `nghttp2_submit_settings()` with 720 * :enum:`nghttp2_settings_id.NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS` 721 * to change the maximum number of incoming concurrent streams. 722 * 723 * .. note:: 724 * 725 * The maximum number of outgoing concurrent streams is 100 by 726 * default. 727 */ 728 #define NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS ((1U << 31) - 1) 729 730 /** 731 * @enum 732 * The status codes for the RST_STREAM and GOAWAY frames. 733 */ 734 typedef enum { 735 /** 736 * No errors. 737 */ 738 NGHTTP2_NO_ERROR = 0x00, 739 /** 740 * PROTOCOL_ERROR 741 */ 742 NGHTTP2_PROTOCOL_ERROR = 0x01, 743 /** 744 * INTERNAL_ERROR 745 */ 746 NGHTTP2_INTERNAL_ERROR = 0x02, 747 /** 748 * FLOW_CONTROL_ERROR 749 */ 750 NGHTTP2_FLOW_CONTROL_ERROR = 0x03, 751 /** 752 * SETTINGS_TIMEOUT 753 */ 754 NGHTTP2_SETTINGS_TIMEOUT = 0x04, 755 /** 756 * STREAM_CLOSED 757 */ 758 NGHTTP2_STREAM_CLOSED = 0x05, 759 /** 760 * FRAME_SIZE_ERROR 761 */ 762 NGHTTP2_FRAME_SIZE_ERROR = 0x06, 763 /** 764 * REFUSED_STREAM 765 */ 766 NGHTTP2_REFUSED_STREAM = 0x07, 767 /** 768 * CANCEL 769 */ 770 NGHTTP2_CANCEL = 0x08, 771 /** 772 * COMPRESSION_ERROR 773 */ 774 NGHTTP2_COMPRESSION_ERROR = 0x09, 775 /** 776 * CONNECT_ERROR 777 */ 778 NGHTTP2_CONNECT_ERROR = 0x0a, 779 /** 780 * ENHANCE_YOUR_CALM 781 */ 782 NGHTTP2_ENHANCE_YOUR_CALM = 0x0b, 783 /** 784 * INADEQUATE_SECURITY 785 */ 786 NGHTTP2_INADEQUATE_SECURITY = 0x0c, 787 /** 788 * HTTP_1_1_REQUIRED 789 */ 790 NGHTTP2_HTTP_1_1_REQUIRED = 0x0d 791 } nghttp2_error_code; 792 793 /** 794 * @struct 795 * The frame header. 796 */ 797 typedef struct { 798 /** 799 * The length field of this frame, excluding frame header. 800 */ 801 size_t length; 802 /** 803 * The stream identifier (aka, stream ID) 804 */ 805 int32_t stream_id; 806 /** 807 * The type of this frame. See `nghttp2_frame_type`. 808 */ 809 uint8_t type; 810 /** 811 * The flags. 812 */ 813 uint8_t flags; 814 /** 815 * Reserved bit in frame header. Currently, this is always set to 0 816 * and application should not expect something useful in here. 817 */ 818 uint8_t reserved; 819 } nghttp2_frame_hd; 820 821 /** 822 * @union 823 * 824 * This union represents the some kind of data source passed to 825 * :type:`nghttp2_data_source_read_callback`. 826 */ 827 typedef union { 828 /** 829 * The integer field, suitable for a file descriptor. 830 */ 831 int fd; 832 /** 833 * The pointer to an arbitrary object. 834 */ 835 void *ptr; 836 } nghttp2_data_source; 837 838 /** 839 * @enum 840 * 841 * The flags used to set in |data_flags| output parameter in 842 * :type:`nghttp2_data_source_read_callback`. 843 */ 844 typedef enum { 845 /** 846 * No flag set. 847 */ 848 NGHTTP2_DATA_FLAG_NONE = 0, 849 /** 850 * Indicates EOF was sensed. 851 */ 852 NGHTTP2_DATA_FLAG_EOF = 0x01, 853 /** 854 * Indicates that END_STREAM flag must not be set even if 855 * NGHTTP2_DATA_FLAG_EOF is set. Usually this flag is used to send 856 * trailer fields with `nghttp2_submit_request()` or 857 * `nghttp2_submit_response()`. 858 */ 859 NGHTTP2_DATA_FLAG_NO_END_STREAM = 0x02, 860 /** 861 * Indicates that application will send complete DATA frame in 862 * :type:`nghttp2_send_data_callback`. 863 */ 864 NGHTTP2_DATA_FLAG_NO_COPY = 0x04 865 } nghttp2_data_flag; 866 867 /** 868 * @functypedef 869 * 870 * Callback function invoked when the library wants to read data from 871 * the |source|. The read data is sent in the stream |stream_id|. 872 * The implementation of this function must read at most |length| 873 * bytes of data from |source| (or possibly other places) and store 874 * them in |buf| and return number of data stored in |buf|. If EOF is 875 * reached, set :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` flag 876 * in |*data_flags|. 877 * 878 * Sometime it is desirable to avoid copying data into |buf| and let 879 * application to send data directly. To achieve this, set 880 * :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` to 881 * |*data_flags| (and possibly other flags, just like when we do 882 * copy), and return the number of bytes to send without copying data 883 * into |buf|. The library, seeing 884 * :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY`, will invoke 885 * :type:`nghttp2_send_data_callback`. The application must send 886 * complete DATA frame in that callback. 887 * 888 * If this callback is set by `nghttp2_submit_request()`, 889 * `nghttp2_submit_response()` or `nghttp2_submit_headers()` and 890 * `nghttp2_submit_data()` with flag parameter 891 * :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` set, and 892 * :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` flag is set to 893 * |*data_flags|, DATA frame will have END_STREAM flag set. Usually, 894 * this is expected behaviour and all are fine. One exception is send 895 * trailer fields. You cannot send trailer fields after sending frame 896 * with END_STREAM set. To avoid this problem, one can set 897 * :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_END_STREAM` along 898 * with :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` to signal the 899 * library not to set END_STREAM in DATA frame. Then application can 900 * use `nghttp2_submit_trailer()` to send trailer fields. 901 * `nghttp2_submit_trailer()` can be called inside this callback. 902 * 903 * If the application wants to postpone DATA frames (e.g., 904 * asynchronous I/O, or reading data blocks for long time), it is 905 * achieved by returning :enum:`nghttp2_error.NGHTTP2_ERR_DEFERRED` 906 * without reading any data in this invocation. The library removes 907 * DATA frame from the outgoing queue temporarily. To move back 908 * deferred DATA frame to outgoing queue, call 909 * `nghttp2_session_resume_data()`. 910 * 911 * By default, |length| is limited to 16KiB at maximum. If peer 912 * allows larger frames, application can enlarge transmission buffer 913 * size. See :type:`nghttp2_data_source_read_length_callback` for 914 * more details. 915 * 916 * If the application just wants to return from 917 * `nghttp2_session_send()` or `nghttp2_session_mem_send()` without 918 * sending anything, return :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE`. 919 * 920 * In case of error, there are 2 choices. Returning 921 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will 922 * close the stream by issuing RST_STREAM with 923 * :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. If a different 924 * error code is desirable, use `nghttp2_submit_rst_stream()` with a 925 * desired error code and then return 926 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. 927 * Returning :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will 928 * signal the entire session failure. 929 */ 930 typedef ssize_t (*nghttp2_data_source_read_callback)( 931 nghttp2_session *session, int32_t stream_id, uint8_t *buf, size_t length, 932 uint32_t *data_flags, nghttp2_data_source *source, void *user_data); 933 934 /** 935 * @struct 936 * 937 * This struct represents the data source and the way to read a chunk 938 * of data from it. 939 */ 940 typedef struct { 941 /** 942 * The data source. 943 */ 944 nghttp2_data_source source; 945 /** 946 * The callback function to read a chunk of data from the |source|. 947 */ 948 nghttp2_data_source_read_callback read_callback; 949 } nghttp2_data_provider; 950 951 /** 952 * @struct 953 * 954 * The DATA frame. The received data is delivered via 955 * :type:`nghttp2_on_data_chunk_recv_callback`. 956 */ 957 typedef struct { 958 nghttp2_frame_hd hd; 959 /** 960 * The length of the padding in this frame. This includes PAD_HIGH 961 * and PAD_LOW. 962 */ 963 size_t padlen; 964 } nghttp2_data; 965 966 /** 967 * @enum 968 * 969 * The category of HEADERS, which indicates the role of the frame. In 970 * HTTP/2 spec, request, response, push response and other arbitrary 971 * headers (e.g., trailer fields) are all called just HEADERS. To 972 * give the application the role of incoming HEADERS frame, we define 973 * several categories. 974 */ 975 typedef enum { 976 /** 977 * The HEADERS frame is opening new stream, which is analogous to 978 * SYN_STREAM in SPDY. 979 */ 980 NGHTTP2_HCAT_REQUEST = 0, 981 /** 982 * The HEADERS frame is the first response headers, which is 983 * analogous to SYN_REPLY in SPDY. 984 */ 985 NGHTTP2_HCAT_RESPONSE = 1, 986 /** 987 * The HEADERS frame is the first headers sent against reserved 988 * stream. 989 */ 990 NGHTTP2_HCAT_PUSH_RESPONSE = 2, 991 /** 992 * The HEADERS frame which does not apply for the above categories, 993 * which is analogous to HEADERS in SPDY. If non-final response 994 * (e.g., status 1xx) is used, final response HEADERS frame will be 995 * categorized here. 996 */ 997 NGHTTP2_HCAT_HEADERS = 3 998 } nghttp2_headers_category; 999 1000 /** 1001 * @struct 1002 * 1003 * The structure to specify stream dependency. 1004 */ 1005 typedef struct { 1006 /** 1007 * The stream ID of the stream to depend on. Specifying 0 makes 1008 * stream not depend any other stream. 1009 */ 1010 int32_t stream_id; 1011 /** 1012 * The weight of this dependency. 1013 */ 1014 int32_t weight; 1015 /** 1016 * nonzero means exclusive dependency 1017 */ 1018 uint8_t exclusive; 1019 } nghttp2_priority_spec; 1020 1021 /** 1022 * @struct 1023 * 1024 * The HEADERS frame. It has the following members: 1025 */ 1026 typedef struct { 1027 /** 1028 * The frame header. 1029 */ 1030 nghttp2_frame_hd hd; 1031 /** 1032 * The length of the padding in this frame. This includes PAD_HIGH 1033 * and PAD_LOW. 1034 */ 1035 size_t padlen; 1036 /** 1037 * The priority specification 1038 */ 1039 nghttp2_priority_spec pri_spec; 1040 /** 1041 * The name/value pairs. 1042 */ 1043 nghttp2_nv *nva; 1044 /** 1045 * The number of name/value pairs in |nva|. 1046 */ 1047 size_t nvlen; 1048 /** 1049 * The category of this HEADERS frame. 1050 */ 1051 nghttp2_headers_category cat; 1052 } nghttp2_headers; 1053 1054 /** 1055 * @struct 1056 * 1057 * The PRIORITY frame. It has the following members: 1058 */ 1059 typedef struct { 1060 /** 1061 * The frame header. 1062 */ 1063 nghttp2_frame_hd hd; 1064 /** 1065 * The priority specification. 1066 */ 1067 nghttp2_priority_spec pri_spec; 1068 } nghttp2_priority; 1069 1070 /** 1071 * @struct 1072 * 1073 * The RST_STREAM frame. It has the following members: 1074 */ 1075 typedef struct { 1076 /** 1077 * The frame header. 1078 */ 1079 nghttp2_frame_hd hd; 1080 /** 1081 * The error code. See :type:`nghttp2_error_code`. 1082 */ 1083 uint32_t error_code; 1084 } nghttp2_rst_stream; 1085 1086 /** 1087 * @struct 1088 * 1089 * The SETTINGS ID/Value pair. It has the following members: 1090 */ 1091 typedef struct { 1092 /** 1093 * The SETTINGS ID. See :type:`nghttp2_settings_id`. 1094 */ 1095 int32_t settings_id; 1096 /** 1097 * The value of this entry. 1098 */ 1099 uint32_t value; 1100 } nghttp2_settings_entry; 1101 1102 /** 1103 * @struct 1104 * 1105 * The SETTINGS frame. It has the following members: 1106 */ 1107 typedef struct { 1108 /** 1109 * The frame header. 1110 */ 1111 nghttp2_frame_hd hd; 1112 /** 1113 * The number of SETTINGS ID/Value pairs in |iv|. 1114 */ 1115 size_t niv; 1116 /** 1117 * The pointer to the array of SETTINGS ID/Value pair. 1118 */ 1119 nghttp2_settings_entry *iv; 1120 } nghttp2_settings; 1121 1122 /** 1123 * @struct 1124 * 1125 * The PUSH_PROMISE frame. It has the following members: 1126 */ 1127 typedef struct { 1128 /** 1129 * The frame header. 1130 */ 1131 nghttp2_frame_hd hd; 1132 /** 1133 * The length of the padding in this frame. This includes PAD_HIGH 1134 * and PAD_LOW. 1135 */ 1136 size_t padlen; 1137 /** 1138 * The name/value pairs. 1139 */ 1140 nghttp2_nv *nva; 1141 /** 1142 * The number of name/value pairs in |nva|. 1143 */ 1144 size_t nvlen; 1145 /** 1146 * The promised stream ID 1147 */ 1148 int32_t promised_stream_id; 1149 /** 1150 * Reserved bit. Currently this is always set to 0 and application 1151 * should not expect something useful in here. 1152 */ 1153 uint8_t reserved; 1154 } nghttp2_push_promise; 1155 1156 /** 1157 * @struct 1158 * 1159 * The PING frame. It has the following members: 1160 */ 1161 typedef struct { 1162 /** 1163 * The frame header. 1164 */ 1165 nghttp2_frame_hd hd; 1166 /** 1167 * The opaque data 1168 */ 1169 uint8_t opaque_data[8]; 1170 } nghttp2_ping; 1171 1172 /** 1173 * @struct 1174 * 1175 * The GOAWAY frame. It has the following members: 1176 */ 1177 typedef struct { 1178 /** 1179 * The frame header. 1180 */ 1181 nghttp2_frame_hd hd; 1182 /** 1183 * The last stream stream ID. 1184 */ 1185 int32_t last_stream_id; 1186 /** 1187 * The error code. See :type:`nghttp2_error_code`. 1188 */ 1189 uint32_t error_code; 1190 /** 1191 * The additional debug data 1192 */ 1193 uint8_t *opaque_data; 1194 /** 1195 * The length of |opaque_data| member. 1196 */ 1197 size_t opaque_data_len; 1198 /** 1199 * Reserved bit. Currently this is always set to 0 and application 1200 * should not expect something useful in here. 1201 */ 1202 uint8_t reserved; 1203 } nghttp2_goaway; 1204 1205 /** 1206 * @struct 1207 * 1208 * The WINDOW_UPDATE frame. It has the following members: 1209 */ 1210 typedef struct { 1211 /** 1212 * The frame header. 1213 */ 1214 nghttp2_frame_hd hd; 1215 /** 1216 * The window size increment. 1217 */ 1218 int32_t window_size_increment; 1219 /** 1220 * Reserved bit. Currently this is always set to 0 and application 1221 * should not expect something useful in here. 1222 */ 1223 uint8_t reserved; 1224 } nghttp2_window_update; 1225 1226 /** 1227 * @struct 1228 * 1229 * The extension frame. It has following members: 1230 */ 1231 typedef struct { 1232 /** 1233 * The frame header. 1234 */ 1235 nghttp2_frame_hd hd; 1236 /** 1237 * The pointer to extension payload. The exact pointer type is 1238 * determined by hd.type. 1239 * 1240 * Currently, no extension is supported. This is a place holder for 1241 * the future extensions. 1242 */ 1243 void *payload; 1244 } nghttp2_extension; 1245 1246 /** 1247 * @union 1248 * 1249 * This union includes all frames to pass them to various function 1250 * calls as nghttp2_frame type. The CONTINUATION frame is omitted 1251 * from here because the library deals with it internally. 1252 */ 1253 typedef union { 1254 /** 1255 * The frame header, which is convenient to inspect frame header. 1256 */ 1257 nghttp2_frame_hd hd; 1258 /** 1259 * The DATA frame. 1260 */ 1261 nghttp2_data data; 1262 /** 1263 * The HEADERS frame. 1264 */ 1265 nghttp2_headers headers; 1266 /** 1267 * The PRIORITY frame. 1268 */ 1269 nghttp2_priority priority; 1270 /** 1271 * The RST_STREAM frame. 1272 */ 1273 nghttp2_rst_stream rst_stream; 1274 /** 1275 * The SETTINGS frame. 1276 */ 1277 nghttp2_settings settings; 1278 /** 1279 * The PUSH_PROMISE frame. 1280 */ 1281 nghttp2_push_promise push_promise; 1282 /** 1283 * The PING frame. 1284 */ 1285 nghttp2_ping ping; 1286 /** 1287 * The GOAWAY frame. 1288 */ 1289 nghttp2_goaway goaway; 1290 /** 1291 * The WINDOW_UPDATE frame. 1292 */ 1293 nghttp2_window_update window_update; 1294 /** 1295 * The extension frame. 1296 */ 1297 nghttp2_extension ext; 1298 } nghttp2_frame; 1299 1300 /** 1301 * @functypedef 1302 * 1303 * Callback function invoked when |session| wants to send data to the 1304 * remote peer. The implementation of this function must send at most 1305 * |length| bytes of data stored in |data|. The |flags| is currently 1306 * not used and always 0. It must return the number of bytes sent if 1307 * it succeeds. If it cannot send any single byte without blocking, 1308 * it must return :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. For 1309 * other errors, it must return 1310 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. The 1311 * |user_data| pointer is the third argument passed in to the call to 1312 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`. 1313 * 1314 * This callback is required if the application uses 1315 * `nghttp2_session_send()` to send data to the remote endpoint. If 1316 * the application uses solely `nghttp2_session_mem_send()` instead, 1317 * this callback function is unnecessary. 1318 * 1319 * To set this callback to :type:`nghttp2_session_callbacks`, use 1320 * `nghttp2_session_callbacks_set_send_callback()`. 1321 * 1322 * .. note:: 1323 * 1324 * The |length| may be very small. If that is the case, and 1325 * application disables Nagle algorithm (``TCP_NODELAY``), then just 1326 * writing |data| to the network stack leads to very small packet, 1327 * and it is very inefficient. An application should be responsible 1328 * to buffer up small chunks of data as necessary to avoid this 1329 * situation. 1330 */ 1331 typedef ssize_t (*nghttp2_send_callback)(nghttp2_session *session, 1332 const uint8_t *data, size_t length, 1333 int flags, void *user_data); 1334 1335 /** 1336 * @functypedef 1337 * 1338 * Callback function invoked when 1339 * :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` is used in 1340 * :type:`nghttp2_data_source_read_callback` to send complete DATA 1341 * frame. 1342 * 1343 * The |frame| is a DATA frame to send. The |framehd| is the 1344 * serialized frame header (9 bytes). The |length| is the length of 1345 * application data to send (this does not include padding). The 1346 * |source| is the same pointer passed to 1347 * :type:`nghttp2_data_source_read_callback`. 1348 * 1349 * The application first must send frame header |framehd| of length 9 1350 * bytes. If ``frame->data.padlen > 0``, send 1 byte of value 1351 * ``frame->data.padlen - 1``. Then send exactly |length| bytes of 1352 * application data. Finally, if ``frame->data.padlen > 1``, send 1353 * ``frame->data.padlen - 1`` bytes of zero as padding. 1354 * 1355 * The application has to send complete DATA frame in this callback. 1356 * If all data were written successfully, return 0. 1357 * 1358 * If it cannot send any data at all, just return 1359 * :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`; the library will call 1360 * this callback with the same parameters later (It is recommended to 1361 * send complete DATA frame at once in this function to deal with 1362 * error; if partial frame data has already sent, it is impossible to 1363 * send another data in that state, and all we can do is tear down 1364 * connection). When data is fully processed, but application wants 1365 * to make `nghttp2_session_mem_send()` or `nghttp2_session_send()` 1366 * return immediately without processing next frames, return 1367 * :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE`. If application decided to 1368 * reset this stream, return 1369 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`, then 1370 * the library will send RST_STREAM with INTERNAL_ERROR as error code. 1371 * The application can also return 1372 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, which will 1373 * result in connection closure. Returning any other value is treated 1374 * as :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned. 1375 */ 1376 typedef int (*nghttp2_send_data_callback)(nghttp2_session *session, 1377 nghttp2_frame *frame, 1378 const uint8_t *framehd, size_t length, 1379 nghttp2_data_source *source, 1380 void *user_data); 1381 1382 /** 1383 * @functypedef 1384 * 1385 * Callback function invoked when |session| wants to receive data from 1386 * the remote peer. The implementation of this function must read at 1387 * most |length| bytes of data and store it in |buf|. The |flags| is 1388 * currently not used and always 0. It must return the number of 1389 * bytes written in |buf| if it succeeds. If it cannot read any 1390 * single byte without blocking, it must return 1391 * :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. If it gets EOF 1392 * before it reads any single byte, it must return 1393 * :enum:`nghttp2_error.NGHTTP2_ERR_EOF`. For other errors, it must 1394 * return :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1395 * Returning 0 is treated as 1396 * :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. The |user_data| 1397 * pointer is the third argument passed in to the call to 1398 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`. 1399 * 1400 * This callback is required if the application uses 1401 * `nghttp2_session_recv()` to receive data from the remote endpoint. 1402 * If the application uses solely `nghttp2_session_mem_recv()` 1403 * instead, this callback function is unnecessary. 1404 * 1405 * To set this callback to :type:`nghttp2_session_callbacks`, use 1406 * `nghttp2_session_callbacks_set_recv_callback()`. 1407 */ 1408 typedef ssize_t (*nghttp2_recv_callback)(nghttp2_session *session, uint8_t *buf, 1409 size_t length, int flags, 1410 void *user_data); 1411 1412 /** 1413 * @functypedef 1414 * 1415 * Callback function invoked by `nghttp2_session_recv()` and 1416 * `nghttp2_session_mem_recv()` when a frame is received. The 1417 * |user_data| pointer is the third argument passed in to the call to 1418 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`. 1419 * 1420 * If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen`` 1421 * member of their data structure are always ``NULL`` and 0 1422 * respectively. The header name/value pairs are emitted via 1423 * :type:`nghttp2_on_header_callback`. 1424 * 1425 * For HEADERS, PUSH_PROMISE and DATA frames, this callback may be 1426 * called after stream is closed (see 1427 * :type:`nghttp2_on_stream_close_callback`). The application should 1428 * check that stream is still alive using its own stream management or 1429 * :func:`nghttp2_session_get_stream_user_data()`. 1430 * 1431 * Only HEADERS and DATA frame can signal the end of incoming data. 1432 * If ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the 1433 * |frame| is the last frame from the remote peer in this stream. 1434 * 1435 * This callback won't be called for CONTINUATION frames. 1436 * HEADERS/PUSH_PROMISE + CONTINUATIONs are treated as single frame. 1437 * 1438 * The implementation of this function must return 0 if it succeeds. 1439 * If nonzero value is returned, it is treated as fatal error and 1440 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions 1441 * immediately return 1442 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1443 * 1444 * To set this callback to :type:`nghttp2_session_callbacks`, use 1445 * `nghttp2_session_callbacks_set_on_frame_recv_callback()`. 1446 */ 1447 typedef int (*nghttp2_on_frame_recv_callback)(nghttp2_session *session, 1448 const nghttp2_frame *frame, 1449 void *user_data); 1450 1451 /** 1452 * @functypedef 1453 * 1454 * Callback function invoked by `nghttp2_session_recv()` and 1455 * `nghttp2_session_mem_recv()` when an invalid non-DATA frame is 1456 * received. The error is indicated by the |lib_error_code|, which is 1457 * one of the values defined in :type:`nghttp2_error`. When this 1458 * callback function is invoked, the library automatically submits 1459 * either RST_STREAM or GOAWAY frame. The |user_data| pointer is the 1460 * third argument passed in to the call to 1461 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`. 1462 * 1463 * If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen`` 1464 * member of their data structure are always ``NULL`` and 0 1465 * respectively. 1466 * 1467 * The implementation of this function must return 0 if it succeeds. 1468 * If nonzero is returned, it is treated as fatal error and 1469 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions 1470 * immediately return 1471 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1472 * 1473 * To set this callback to :type:`nghttp2_session_callbacks`, use 1474 * `nghttp2_session_callbacks_set_on_invalid_frame_recv_callback()`. 1475 */ 1476 typedef int (*nghttp2_on_invalid_frame_recv_callback)( 1477 nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code, 1478 void *user_data); 1479 1480 /** 1481 * @functypedef 1482 * 1483 * Callback function invoked when a chunk of data in DATA frame is 1484 * received. The |stream_id| is the stream ID this DATA frame belongs 1485 * to. The |flags| is the flags of DATA frame which this data chunk 1486 * is contained. ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not 1487 * necessarily mean this chunk of data is the last one in the stream. 1488 * You should use :type:`nghttp2_on_frame_recv_callback` to know all 1489 * data frames are received. The |user_data| pointer is the third 1490 * argument passed in to the call to `nghttp2_session_client_new()` or 1491 * `nghttp2_session_server_new()`. 1492 * 1493 * If the application uses `nghttp2_session_mem_recv()`, it can return 1494 * :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` to make 1495 * `nghttp2_session_mem_recv()` return without processing further 1496 * input bytes. The memory by pointed by the |data| is retained until 1497 * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called. 1498 * The application must retain the input bytes which was used to 1499 * produce the |data| parameter, because it may refer to the memory 1500 * region included in the input bytes. 1501 * 1502 * The implementation of this function must return 0 if it succeeds. 1503 * If nonzero is returned, it is treated as fatal error, and 1504 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions 1505 * immediately return 1506 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1507 * 1508 * To set this callback to :type:`nghttp2_session_callbacks`, use 1509 * `nghttp2_session_callbacks_set_on_data_chunk_recv_callback()`. 1510 */ 1511 typedef int (*nghttp2_on_data_chunk_recv_callback)(nghttp2_session *session, 1512 uint8_t flags, 1513 int32_t stream_id, 1514 const uint8_t *data, 1515 size_t len, void *user_data); 1516 1517 /** 1518 * @functypedef 1519 * 1520 * Callback function invoked just before the non-DATA frame |frame| is 1521 * sent. The |user_data| pointer is the third argument passed in to 1522 * the call to `nghttp2_session_client_new()` or 1523 * `nghttp2_session_server_new()`. 1524 * 1525 * The implementation of this function must return 0 if it succeeds. 1526 * It can also return :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL` to 1527 * cancel the transmission of the given frame. 1528 * 1529 * If there is a fatal error while executing this callback, the 1530 * implementation should return 1531 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, which makes 1532 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions 1533 * immediately return 1534 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1535 * 1536 * If the other value is returned, it is treated as if 1537 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned. 1538 * But the implementation should not rely on this since the library 1539 * may define new return value to extend its capability. 1540 * 1541 * To set this callback to :type:`nghttp2_session_callbacks`, use 1542 * `nghttp2_session_callbacks_set_before_frame_send_callback()`. 1543 */ 1544 typedef int (*nghttp2_before_frame_send_callback)(nghttp2_session *session, 1545 const nghttp2_frame *frame, 1546 void *user_data); 1547 1548 /** 1549 * @functypedef 1550 * 1551 * Callback function invoked after the frame |frame| is sent. The 1552 * |user_data| pointer is the third argument passed in to the call to 1553 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`. 1554 * 1555 * The implementation of this function must return 0 if it succeeds. 1556 * If nonzero is returned, it is treated as fatal error and 1557 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions 1558 * immediately return 1559 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1560 * 1561 * To set this callback to :type:`nghttp2_session_callbacks`, use 1562 * `nghttp2_session_callbacks_set_on_frame_send_callback()`. 1563 */ 1564 typedef int (*nghttp2_on_frame_send_callback)(nghttp2_session *session, 1565 const nghttp2_frame *frame, 1566 void *user_data); 1567 1568 /** 1569 * @functypedef 1570 * 1571 * Callback function invoked after the non-DATA frame |frame| is not 1572 * sent because of the error. The error is indicated by the 1573 * |lib_error_code|, which is one of the values defined in 1574 * :type:`nghttp2_error`. The |user_data| pointer is the third 1575 * argument passed in to the call to `nghttp2_session_client_new()` or 1576 * `nghttp2_session_server_new()`. 1577 * 1578 * The implementation of this function must return 0 if it succeeds. 1579 * If nonzero is returned, it is treated as fatal error and 1580 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions 1581 * immediately return 1582 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1583 * 1584 * `nghttp2_session_get_stream_user_data()` can be used to get 1585 * associated data. 1586 * 1587 * To set this callback to :type:`nghttp2_session_callbacks`, use 1588 * `nghttp2_session_callbacks_set_on_frame_not_send_callback()`. 1589 */ 1590 typedef int (*nghttp2_on_frame_not_send_callback)(nghttp2_session *session, 1591 const nghttp2_frame *frame, 1592 int lib_error_code, 1593 void *user_data); 1594 1595 /** 1596 * @functypedef 1597 * 1598 * Callback function invoked when the stream |stream_id| is closed. 1599 * The reason of closure is indicated by the |error_code|. The 1600 * |error_code| is usually one of :enum:`nghttp2_error_code`, but that 1601 * is not guaranteed. The stream_user_data, which was specified in 1602 * `nghttp2_submit_request()` or `nghttp2_submit_headers()`, is still 1603 * available in this function. The |user_data| pointer is the third 1604 * argument passed in to the call to `nghttp2_session_client_new()` or 1605 * `nghttp2_session_server_new()`. 1606 * 1607 * This function is also called for a stream in reserved state. 1608 * 1609 * The implementation of this function must return 0 if it succeeds. 1610 * If nonzero is returned, it is treated as fatal error and 1611 * `nghttp2_session_recv()`, `nghttp2_session_mem_recv()`, 1612 * `nghttp2_session_send()`, and `nghttp2_session_mem_send()` 1613 * functions immediately return 1614 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1615 * 1616 * To set this callback to :type:`nghttp2_session_callbacks`, use 1617 * `nghttp2_session_callbacks_set_on_stream_close_callback()`. 1618 */ 1619 typedef int (*nghttp2_on_stream_close_callback)(nghttp2_session *session, 1620 int32_t stream_id, 1621 uint32_t error_code, 1622 void *user_data); 1623 1624 /** 1625 * @functypedef 1626 * 1627 * Callback function invoked when the reception of header block in 1628 * HEADERS or PUSH_PROMISE is started. Each header name/value pair 1629 * will be emitted by :type:`nghttp2_on_header_callback`. 1630 * 1631 * The ``frame->hd.flags`` may not have 1632 * :enum:`nghttp2_flag.NGHTTP2_FLAG_END_HEADERS` flag set, which 1633 * indicates that one or more CONTINUATION frames are involved. But 1634 * the application does not need to care about that because the header 1635 * name/value pairs are emitted transparently regardless of 1636 * CONTINUATION frames. 1637 * 1638 * The server applications probably create an object to store 1639 * information about new stream if ``frame->hd.type == 1640 * NGHTTP2_HEADERS`` and ``frame->headers.cat == 1641 * NGHTTP2_HCAT_REQUEST``. If |session| is configured as server side, 1642 * ``frame->headers.cat`` is either ``NGHTTP2_HCAT_REQUEST`` 1643 * containing request headers or ``NGHTTP2_HCAT_HEADERS`` containing 1644 * trailer fields and never get PUSH_PROMISE in this callback. 1645 * 1646 * For the client applications, ``frame->hd.type`` is either 1647 * ``NGHTTP2_HEADERS`` or ``NGHTTP2_PUSH_PROMISE``. In case of 1648 * ``NGHTTP2_HEADERS``, ``frame->headers.cat == 1649 * NGHTTP2_HCAT_RESPONSE`` means that it is the first response 1650 * headers, but it may be non-final response which is indicated by 1xx 1651 * status code. In this case, there may be zero or more HEADERS frame 1652 * with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS`` which has 1653 * non-final response code and finally client gets exactly one HEADERS 1654 * frame with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS`` 1655 * containing final response headers (non-1xx status code). The 1656 * trailer fields also has ``frame->headers.cat == 1657 * NGHTTP2_HCAT_HEADERS`` which does not contain any status code. 1658 * 1659 * Returning 1660 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will 1661 * close the stream (promised stream if frame is PUSH_PROMISE) by 1662 * issuing RST_STREAM with 1663 * :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. In this case, 1664 * :type:`nghttp2_on_header_callback` and 1665 * :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a 1666 * different error code is desirable, use 1667 * `nghttp2_submit_rst_stream()` with a desired error code and then 1668 * return :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. 1669 * Again, use ``frame->push_promise.promised_stream_id`` as stream_id 1670 * parameter in `nghttp2_submit_rst_stream()` if frame is 1671 * PUSH_PROMISE. 1672 * 1673 * The implementation of this function must return 0 if it succeeds. 1674 * It can return 1675 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` to 1676 * reset the stream (promised stream if frame is PUSH_PROMISE). For 1677 * critical errors, it must return 1678 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other 1679 * value is returned, it is treated as if 1680 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned. If 1681 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned, 1682 * `nghttp2_session_mem_recv()` function will immediately return 1683 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1684 * 1685 * To set this callback to :type:`nghttp2_session_callbacks`, use 1686 * `nghttp2_session_callbacks_set_on_begin_headers_callback()`. 1687 */ 1688 typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session, 1689 const nghttp2_frame *frame, 1690 void *user_data); 1691 1692 /** 1693 * @functypedef 1694 * 1695 * Callback function invoked when a header name/value pair is received 1696 * for the |frame|. The |name| of length |namelen| is header name. 1697 * The |value| of length |valuelen| is header value. The |flags| is 1698 * bitwise OR of one or more of :type:`nghttp2_nv_flag`. 1699 * 1700 * If :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_INDEX` is set in 1701 * |flags|, the receiver must not index this name/value pair when 1702 * forwarding it to the next hop. More specifically, "Literal Header 1703 * Field never Indexed" representation must be used in HPACK encoding. 1704 * 1705 * When this callback is invoked, ``frame->hd.type`` is either 1706 * :enum:`nghttp2_frame_type.NGHTTP2_HEADERS` or 1707 * :enum:`nghttp2_frame_type.NGHTTP2_PUSH_PROMISE`. After all header 1708 * name/value pairs are processed with this callback, and no error has 1709 * been detected, :type:`nghttp2_on_frame_recv_callback` will be 1710 * invoked. If there is an error in decompression, 1711 * :type:`nghttp2_on_frame_recv_callback` for the |frame| will not be 1712 * invoked. 1713 * 1714 * Both |name| and |value| are guaranteed to be NULL-terminated. The 1715 * |namelen| and |valuelen| do not include terminal NULL. If 1716 * `nghttp2_option_set_no_http_messaging()` is used with nonzero 1717 * value, NULL character may be included in |name| or |value| before 1718 * terminating NULL. 1719 * 1720 * Please note that unless `nghttp2_option_set_no_http_messaging()` is 1721 * used, nghttp2 library does perform validation against the |name| 1722 * and the |value| using `nghttp2_check_header_name()` and 1723 * `nghttp2_check_header_value()`. In addition to this, nghttp2 1724 * performs validation based on HTTP Messaging rule, which is briefly 1725 * explained in :ref:`http-messaging` section. 1726 * 1727 * If the application uses `nghttp2_session_mem_recv()`, it can return 1728 * :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` to make 1729 * `nghttp2_session_mem_recv()` return without processing further 1730 * input bytes. The memory pointed by |frame|, |name| and |value| 1731 * parameters are retained until `nghttp2_session_mem_recv()` or 1732 * `nghttp2_session_recv()` is called. The application must retain 1733 * the input bytes which was used to produce these parameters, because 1734 * it may refer to the memory region included in the input bytes. 1735 * 1736 * Returning 1737 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will 1738 * close the stream (promised stream if frame is PUSH_PROMISE) by 1739 * issuing RST_STREAM with 1740 * :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. In this case, 1741 * :type:`nghttp2_on_header_callback` and 1742 * :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a 1743 * different error code is desirable, use 1744 * `nghttp2_submit_rst_stream()` with a desired error code and then 1745 * return :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. 1746 * Again, use ``frame->push_promise.promised_stream_id`` as stream_id 1747 * parameter in `nghttp2_submit_rst_stream()` if frame is 1748 * PUSH_PROMISE. 1749 * 1750 * The implementation of this function must return 0 if it succeeds. 1751 * It may return :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` or 1752 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. For 1753 * other critical failures, it must return 1754 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other 1755 * nonzero value is returned, it is treated as 1756 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If 1757 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned, 1758 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions 1759 * immediately return 1760 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1761 * 1762 * To set this callback to :type:`nghttp2_session_callbacks`, use 1763 * `nghttp2_session_callbacks_set_on_header_callback()`. 1764 * 1765 * .. warning:: 1766 * 1767 * Application should properly limit the total buffer size to store 1768 * incoming header fields. Without it, peer may send large number 1769 * of header fields or large header fields to cause out of memory in 1770 * local endpoint. Due to how HPACK works, peer can do this 1771 * effectively without using much memory on their own. 1772 */ 1773 typedef int (*nghttp2_on_header_callback)(nghttp2_session *session, 1774 const nghttp2_frame *frame, 1775 const uint8_t *name, size_t namelen, 1776 const uint8_t *value, size_t valuelen, 1777 uint8_t flags, void *user_data); 1778 1779 /** 1780 * @functypedef 1781 * 1782 * Callback function invoked when a header name/value pair is received 1783 * for the |frame|. The |name| is header name. The |value| is header 1784 * value. The |flags| is bitwise OR of one or more of 1785 * :type:`nghttp2_nv_flag`. 1786 * 1787 * This callback behaves like :type:`nghttp2_on_header_callback`, 1788 * except that |name| and |value| are stored in reference counted 1789 * buffer. If application wishes to keep these references without 1790 * copying them, use `nghttp2_rcbuf_incref()` to increment their 1791 * reference count. It is the application's responsibility to call 1792 * `nghttp2_rcbuf_decref()` if they called `nghttp2_rcbuf_incref()` so 1793 * as not to leak memory. If the |session| is created by 1794 * `nghttp2_session_server_new3()` or `nghttp2_session_client_new3()`, 1795 * the function to free memory is the one belongs to the mem 1796 * parameter. As long as this free function alives, |name| and 1797 * |value| can live after |session| was destroyed. 1798 */ 1799 typedef int (*nghttp2_on_header_callback2)(nghttp2_session *session, 1800 const nghttp2_frame *frame, 1801 nghttp2_rcbuf *name, 1802 nghttp2_rcbuf *value, uint8_t flags, 1803 void *user_data); 1804 1805 /** 1806 * @functypedef 1807 * 1808 * Callback function invoked when a invalid header name/value pair is 1809 * received for the |frame|. 1810 * 1811 * The parameter and behaviour are similar to 1812 * :type:`nghttp2_on_header_callback`. The difference is that this 1813 * callback is only invoked when a invalid header name/value pair is 1814 * received which is treated as stream error if this callback is not 1815 * set. Only invalid regular header field are passed to this 1816 * callback. In other words, invalid pseudo header field is not 1817 * passed to this callback. Also header fields which includes upper 1818 * cased latter are also treated as error without passing them to this 1819 * callback. 1820 * 1821 * This callback is only considered if HTTP messaging validation is 1822 * turned on (which is on by default, see 1823 * `nghttp2_option_set_no_http_messaging()`). 1824 * 1825 * With this callback, application inspects the incoming invalid 1826 * field, and it also can reset stream from this callback by returning 1827 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. By 1828 * default, the error code is 1829 * :enum:`nghttp2_error_code.NGHTTP2_PROTOCOL_ERROR`. To change the 1830 * error code, call `nghttp2_submit_rst_stream()` with the error code 1831 * of choice in addition to returning 1832 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. 1833 * 1834 * If 0 is returned, the header field is ignored, and the stream is 1835 * not reset. 1836 */ 1837 typedef int (*nghttp2_on_invalid_header_callback)( 1838 nghttp2_session *session, const nghttp2_frame *frame, const uint8_t *name, 1839 size_t namelen, const uint8_t *value, size_t valuelen, uint8_t flags, 1840 void *user_data); 1841 1842 /** 1843 * @functypedef 1844 * 1845 * Callback function invoked when a invalid header name/value pair is 1846 * received for the |frame|. 1847 * 1848 * The parameter and behaviour are similar to 1849 * :type:`nghttp2_on_header_callback2`. The difference is that this 1850 * callback is only invoked when a invalid header name/value pair is 1851 * received which is silently ignored if this callback is not set. 1852 * Only invalid regular header field are passed to this callback. In 1853 * other words, invalid pseudo header field is not passed to this 1854 * callback. Also header fields which includes upper cased latter are 1855 * also treated as error without passing them to this callback. 1856 * 1857 * This callback is only considered if HTTP messaging validation is 1858 * turned on (which is on by default, see 1859 * `nghttp2_option_set_no_http_messaging()`). 1860 * 1861 * With this callback, application inspects the incoming invalid 1862 * field, and it also can reset stream from this callback by returning 1863 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. By 1864 * default, the error code is 1865 * :enum:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. To change the 1866 * error code, call `nghttp2_submit_rst_stream()` with the error code 1867 * of choice in addition to returning 1868 * :enum:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. 1869 */ 1870 typedef int (*nghttp2_on_invalid_header_callback2)( 1871 nghttp2_session *session, const nghttp2_frame *frame, nghttp2_rcbuf *name, 1872 nghttp2_rcbuf *value, uint8_t flags, void *user_data); 1873 1874 /** 1875 * @functypedef 1876 * 1877 * Callback function invoked when the library asks application how 1878 * many padding bytes are required for the transmission of the 1879 * |frame|. The application must choose the total length of payload 1880 * including padded bytes in range [frame->hd.length, max_payloadlen], 1881 * inclusive. Choosing number not in this range will be treated as 1882 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Returning 1883 * ``frame->hd.length`` means no padding is added. Returning 1884 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will make 1885 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions 1886 * immediately return 1887 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1888 * 1889 * To set this callback to :type:`nghttp2_session_callbacks`, use 1890 * `nghttp2_session_callbacks_set_select_padding_callback()`. 1891 */ 1892 typedef ssize_t (*nghttp2_select_padding_callback)(nghttp2_session *session, 1893 const nghttp2_frame *frame, 1894 size_t max_payloadlen, 1895 void *user_data); 1896 1897 /** 1898 * @functypedef 1899 * 1900 * Callback function invoked when library wants to get max length of 1901 * data to send data to the remote peer. The implementation of this 1902 * function should return a value in the following range. [1, 1903 * min(|session_remote_window_size|, |stream_remote_window_size|, 1904 * |remote_max_frame_size|)]. If a value greater than this range is 1905 * returned than the max allow value will be used. Returning a value 1906 * smaller than this range is treated as 1907 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. The 1908 * |frame_type| is provided for future extensibility and identifies 1909 * the type of frame (see :type:`nghttp2_frame_type`) for which to get 1910 * the length for. Currently supported frame types are: 1911 * :enum:`nghttp2_frame_type.NGHTTP2_DATA`. 1912 * 1913 * This callback can be used to control the length in bytes for which 1914 * :type:`nghttp2_data_source_read_callback` is allowed to send to the 1915 * remote endpoint. This callback is optional. Returning 1916 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will signal the 1917 * entire session failure. 1918 * 1919 * To set this callback to :type:`nghttp2_session_callbacks`, use 1920 * `nghttp2_session_callbacks_set_data_source_read_length_callback()`. 1921 */ 1922 typedef ssize_t (*nghttp2_data_source_read_length_callback)( 1923 nghttp2_session *session, uint8_t frame_type, int32_t stream_id, 1924 int32_t session_remote_window_size, int32_t stream_remote_window_size, 1925 uint32_t remote_max_frame_size, void *user_data); 1926 1927 /** 1928 * @functypedef 1929 * 1930 * Callback function invoked when a frame header is received. The 1931 * |hd| points to received frame header. 1932 * 1933 * Unlike :type:`nghttp2_on_frame_recv_callback`, this callback will 1934 * also be called when frame header of CONTINUATION frame is received. 1935 * 1936 * If both :type:`nghttp2_on_begin_frame_callback` and 1937 * :type:`nghttp2_on_begin_headers_callback` are set and HEADERS or 1938 * PUSH_PROMISE is received, :type:`nghttp2_on_begin_frame_callback` 1939 * will be called first. 1940 * 1941 * The implementation of this function must return 0 if it succeeds. 1942 * If nonzero value is returned, it is treated as fatal error and 1943 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions 1944 * immediately return 1945 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1946 * 1947 * To set this callback to :type:`nghttp2_session_callbacks`, use 1948 * `nghttp2_session_callbacks_set_on_begin_frame_callback()`. 1949 */ 1950 typedef int (*nghttp2_on_begin_frame_callback)(nghttp2_session *session, 1951 const nghttp2_frame_hd *hd, 1952 void *user_data); 1953 1954 /** 1955 * @functypedef 1956 * 1957 * Callback function invoked when chunk of extension frame payload is 1958 * received. The |hd| points to frame header. The received 1959 * chunk is |data| of length |len|. 1960 * 1961 * The implementation of this function must return 0 if it succeeds. 1962 * 1963 * To abort processing this extension frame, return 1964 * :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`. 1965 * 1966 * If fatal error occurred, application should return 1967 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case, 1968 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions 1969 * immediately return 1970 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other 1971 * values are returned, currently they are treated as 1972 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 1973 */ 1974 typedef int (*nghttp2_on_extension_chunk_recv_callback)( 1975 nghttp2_session *session, const nghttp2_frame_hd *hd, const uint8_t *data, 1976 size_t len, void *user_data); 1977 1978 /** 1979 * @functypedef 1980 * 1981 * Callback function invoked when library asks the application to 1982 * unpack extension payload from its wire format. The extension 1983 * payload has been passed to the application using 1984 * :type:`nghttp2_on_extension_chunk_recv_callback`. The frame header 1985 * is already unpacked by the library and provided as |hd|. 1986 * 1987 * To receive extension frames, the application must tell desired 1988 * extension frame type to the library using 1989 * `nghttp2_option_set_user_recv_extension_type()`. 1990 * 1991 * The implementation of this function may store the pointer to the 1992 * created object as a result of unpacking in |*payload|, and returns 1993 * 0. The pointer stored in |*payload| is opaque to the library, and 1994 * the library does not own its pointer. |*payload| is initialized as 1995 * ``NULL``. The |*payload| is available as ``frame->ext.payload`` in 1996 * :type:`nghttp2_on_frame_recv_callback`. Therefore if application 1997 * can free that memory inside :type:`nghttp2_on_frame_recv_callback` 1998 * callback. Of course, application has a liberty not ot use 1999 * |*payload|, and do its own mechanism to process extension frames. 2000 * 2001 * To abort processing this extension frame, return 2002 * :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`. 2003 * 2004 * If fatal error occurred, application should return 2005 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case, 2006 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions 2007 * immediately return 2008 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other 2009 * values are returned, currently they are treated as 2010 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 2011 */ 2012 typedef int (*nghttp2_unpack_extension_callback)(nghttp2_session *session, 2013 void **payload, 2014 const nghttp2_frame_hd *hd, 2015 void *user_data); 2016 2017 /** 2018 * @functypedef 2019 * 2020 * Callback function invoked when library asks the application to pack 2021 * extension payload in its wire format. The frame header will be 2022 * packed by library. Application must pack payload only. 2023 * ``frame->ext.payload`` is the object passed to 2024 * `nghttp2_submit_extension()` as payload parameter. Application 2025 * must pack extension payload to the |buf| of its capacity |len| 2026 * bytes. The |len| is at least 16KiB. 2027 * 2028 * The implementation of this function should return the number of 2029 * bytes written into |buf| when it succeeds. 2030 * 2031 * To abort processing this extension frame, return 2032 * :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`, and 2033 * :type:`nghttp2_on_frame_not_send_callback` will be invoked. 2034 * 2035 * If fatal error occurred, application should return 2036 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case, 2037 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions 2038 * immediately return 2039 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other 2040 * values are returned, currently they are treated as 2041 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the return 2042 * value is strictly larger than |len|, it is treated as 2043 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 2044 */ 2045 typedef ssize_t (*nghttp2_pack_extension_callback)(nghttp2_session *session, 2046 uint8_t *buf, size_t len, 2047 const nghttp2_frame *frame, 2048 void *user_data); 2049 2050 /** 2051 * @functypedef 2052 * 2053 * Callback function invoked when library provides the error message 2054 * intended for human consumption. This callback is solely for 2055 * debugging purpose. The |msg| is typically NULL-terminated string 2056 * of length |len|. |len| does not include the sentinel NULL 2057 * character. 2058 * 2059 * This function is deprecated. The new application should use 2060 * :type:`nghttp2_error_callback2`. 2061 * 2062 * The format of error message may change between nghttp2 library 2063 * versions. The application should not depend on the particular 2064 * format. 2065 * 2066 * Normally, application should return 0 from this callback. If fatal 2067 * error occurred while doing something in this callback, application 2068 * should return :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 2069 * In this case, library will return immediately with return value 2070 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Currently, if 2071 * nonzero value is returned from this callback, they are treated as 2072 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, but application 2073 * should not rely on this details. 2074 */ 2075 typedef int (*nghttp2_error_callback)(nghttp2_session *session, const char *msg, 2076 size_t len, void *user_data); 2077 2078 /** 2079 * @functypedef 2080 * 2081 * Callback function invoked when library provides the error code, and 2082 * message. This callback is solely for debugging purpose. 2083 * |lib_error_code| is one of error code defined in 2084 * :enum:`nghttp2_error`. The |msg| is typically NULL-terminated 2085 * string of length |len|, and intended for human consumption. |len| 2086 * does not include the sentinel NULL character. 2087 * 2088 * The format of error message may change between nghttp2 library 2089 * versions. The application should not depend on the particular 2090 * format. 2091 * 2092 * Normally, application should return 0 from this callback. If fatal 2093 * error occurred while doing something in this callback, application 2094 * should return :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. 2095 * In this case, library will return immediately with return value 2096 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Currently, if 2097 * nonzero value is returned from this callback, they are treated as 2098 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, but application 2099 * should not rely on this details. 2100 */ 2101 typedef int (*nghttp2_error_callback2)(nghttp2_session *session, 2102 int lib_error_code, const char *msg, 2103 size_t len, void *user_data); 2104 2105 struct nghttp2_session_callbacks; 2106 2107 /** 2108 * @struct 2109 * 2110 * Callback functions for :type:`nghttp2_session`. The details of 2111 * this structure are intentionally hidden from the public API. 2112 */ 2113 typedef struct nghttp2_session_callbacks nghttp2_session_callbacks; 2114 2115 /** 2116 * @function 2117 * 2118 * Initializes |*callbacks_ptr| with NULL values. 2119 * 2120 * The initialized object can be used when initializing multiple 2121 * :type:`nghttp2_session` objects. 2122 * 2123 * When the application finished using this object, it can use 2124 * `nghttp2_session_callbacks_del()` to free its memory. 2125 * 2126 * This function returns 0 if it succeeds, or one of the following 2127 * negative error codes: 2128 * 2129 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2130 * Out of memory. 2131 */ 2132 NGHTTP2_EXTERN int 2133 nghttp2_session_callbacks_new(nghttp2_session_callbacks **callbacks_ptr); 2134 2135 /** 2136 * @function 2137 * 2138 * Frees any resources allocated for |callbacks|. If |callbacks| is 2139 * ``NULL``, this function does nothing. 2140 */ 2141 NGHTTP2_EXTERN void 2142 nghttp2_session_callbacks_del(nghttp2_session_callbacks *callbacks); 2143 2144 /** 2145 * @function 2146 * 2147 * Sets callback function invoked when a session wants to send data to 2148 * the remote peer. This callback is not necessary if the application 2149 * uses solely `nghttp2_session_mem_send()` to serialize data to 2150 * transmit. 2151 */ 2152 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_callback( 2153 nghttp2_session_callbacks *cbs, nghttp2_send_callback send_callback); 2154 2155 /** 2156 * @function 2157 * 2158 * Sets callback function invoked when the a session wants to receive 2159 * data from the remote peer. This callback is not necessary if the 2160 * application uses solely `nghttp2_session_mem_recv()` to process 2161 * received data. 2162 */ 2163 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_recv_callback( 2164 nghttp2_session_callbacks *cbs, nghttp2_recv_callback recv_callback); 2165 2166 /** 2167 * @function 2168 * 2169 * Sets callback function invoked by `nghttp2_session_recv()` and 2170 * `nghttp2_session_mem_recv()` when a frame is received. 2171 */ 2172 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_recv_callback( 2173 nghttp2_session_callbacks *cbs, 2174 nghttp2_on_frame_recv_callback on_frame_recv_callback); 2175 2176 /** 2177 * @function 2178 * 2179 * Sets callback function invoked by `nghttp2_session_recv()` and 2180 * `nghttp2_session_mem_recv()` when an invalid non-DATA frame is 2181 * received. 2182 */ 2183 NGHTTP2_EXTERN void 2184 nghttp2_session_callbacks_set_on_invalid_frame_recv_callback( 2185 nghttp2_session_callbacks *cbs, 2186 nghttp2_on_invalid_frame_recv_callback on_invalid_frame_recv_callback); 2187 2188 /** 2189 * @function 2190 * 2191 * Sets callback function invoked when a chunk of data in DATA frame 2192 * is received. 2193 */ 2194 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_data_chunk_recv_callback( 2195 nghttp2_session_callbacks *cbs, 2196 nghttp2_on_data_chunk_recv_callback on_data_chunk_recv_callback); 2197 2198 /** 2199 * @function 2200 * 2201 * Sets callback function invoked before a non-DATA frame is sent. 2202 */ 2203 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_before_frame_send_callback( 2204 nghttp2_session_callbacks *cbs, 2205 nghttp2_before_frame_send_callback before_frame_send_callback); 2206 2207 /** 2208 * @function 2209 * 2210 * Sets callback function invoked after a frame is sent. 2211 */ 2212 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_send_callback( 2213 nghttp2_session_callbacks *cbs, 2214 nghttp2_on_frame_send_callback on_frame_send_callback); 2215 2216 /** 2217 * @function 2218 * 2219 * Sets callback function invoked when a non-DATA frame is not sent 2220 * because of an error. 2221 */ 2222 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_not_send_callback( 2223 nghttp2_session_callbacks *cbs, 2224 nghttp2_on_frame_not_send_callback on_frame_not_send_callback); 2225 2226 /** 2227 * @function 2228 * 2229 * Sets callback function invoked when the stream is closed. 2230 */ 2231 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_stream_close_callback( 2232 nghttp2_session_callbacks *cbs, 2233 nghttp2_on_stream_close_callback on_stream_close_callback); 2234 2235 /** 2236 * @function 2237 * 2238 * Sets callback function invoked when the reception of header block 2239 * in HEADERS or PUSH_PROMISE is started. 2240 */ 2241 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_begin_headers_callback( 2242 nghttp2_session_callbacks *cbs, 2243 nghttp2_on_begin_headers_callback on_begin_headers_callback); 2244 2245 /** 2246 * @function 2247 * 2248 * Sets callback function invoked when a header name/value pair is 2249 * received. If both 2250 * `nghttp2_session_callbacks_set_on_header_callback()` and 2251 * `nghttp2_session_callbacks_set_on_header_callback2()` are used to 2252 * set callbacks, the latter has the precedence. 2253 */ 2254 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_header_callback( 2255 nghttp2_session_callbacks *cbs, 2256 nghttp2_on_header_callback on_header_callback); 2257 2258 /** 2259 * @function 2260 * 2261 * Sets callback function invoked when a header name/value pair is 2262 * received. 2263 */ 2264 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_header_callback2( 2265 nghttp2_session_callbacks *cbs, 2266 nghttp2_on_header_callback2 on_header_callback2); 2267 2268 /** 2269 * @function 2270 * 2271 * Sets callback function invoked when a invalid header name/value 2272 * pair is received. If both 2273 * `nghttp2_session_callbacks_set_on_invalid_header_callback()` and 2274 * `nghttp2_session_callbacks_set_on_invalid_header_callback2()` are 2275 * used to set callbacks, the latter takes the precedence. 2276 */ 2277 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_invalid_header_callback( 2278 nghttp2_session_callbacks *cbs, 2279 nghttp2_on_invalid_header_callback on_invalid_header_callback); 2280 2281 /** 2282 * @function 2283 * 2284 * Sets callback function invoked when a invalid header name/value 2285 * pair is received. 2286 */ 2287 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_invalid_header_callback2( 2288 nghttp2_session_callbacks *cbs, 2289 nghttp2_on_invalid_header_callback2 on_invalid_header_callback2); 2290 2291 /** 2292 * @function 2293 * 2294 * Sets callback function invoked when the library asks application 2295 * how many padding bytes are required for the transmission of the 2296 * given frame. 2297 */ 2298 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_select_padding_callback( 2299 nghttp2_session_callbacks *cbs, 2300 nghttp2_select_padding_callback select_padding_callback); 2301 2302 /** 2303 * @function 2304 * 2305 * Sets callback function determine the length allowed in 2306 * :type:`nghttp2_data_source_read_callback`. 2307 */ 2308 NGHTTP2_EXTERN void 2309 nghttp2_session_callbacks_set_data_source_read_length_callback( 2310 nghttp2_session_callbacks *cbs, 2311 nghttp2_data_source_read_length_callback data_source_read_length_callback); 2312 2313 /** 2314 * @function 2315 * 2316 * Sets callback function invoked when a frame header is received. 2317 */ 2318 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_begin_frame_callback( 2319 nghttp2_session_callbacks *cbs, 2320 nghttp2_on_begin_frame_callback on_begin_frame_callback); 2321 2322 /** 2323 * @function 2324 * 2325 * Sets callback function invoked when 2326 * :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` is used in 2327 * :type:`nghttp2_data_source_read_callback` to avoid data copy. 2328 */ 2329 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_data_callback( 2330 nghttp2_session_callbacks *cbs, 2331 nghttp2_send_data_callback send_data_callback); 2332 2333 /** 2334 * @function 2335 * 2336 * Sets callback function invoked when the library asks the 2337 * application to pack extension frame payload in wire format. 2338 */ 2339 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_pack_extension_callback( 2340 nghttp2_session_callbacks *cbs, 2341 nghttp2_pack_extension_callback pack_extension_callback); 2342 2343 /** 2344 * @function 2345 * 2346 * Sets callback function invoked when the library asks the 2347 * application to unpack extension frame payload from wire format. 2348 */ 2349 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_unpack_extension_callback( 2350 nghttp2_session_callbacks *cbs, 2351 nghttp2_unpack_extension_callback unpack_extension_callback); 2352 2353 /** 2354 * @function 2355 * 2356 * Sets callback function invoked when chunk of extension frame 2357 * payload is received. 2358 */ 2359 NGHTTP2_EXTERN void 2360 nghttp2_session_callbacks_set_on_extension_chunk_recv_callback( 2361 nghttp2_session_callbacks *cbs, 2362 nghttp2_on_extension_chunk_recv_callback on_extension_chunk_recv_callback); 2363 2364 /** 2365 * @function 2366 * 2367 * Sets callback function invoked when library tells error message to 2368 * the application. 2369 * 2370 * This function is deprecated. The new application should use 2371 * `nghttp2_session_callbacks_set_error_callback2()`. 2372 * 2373 * If both :type:`nghttp2_error_callback` and 2374 * :type:`nghttp2_error_callback2` are set, the latter takes 2375 * precedence. 2376 */ 2377 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_error_callback( 2378 nghttp2_session_callbacks *cbs, nghttp2_error_callback error_callback); 2379 2380 /** 2381 * @function 2382 * 2383 * Sets callback function invoked when library tells error code, and 2384 * message to the application. 2385 * 2386 * If both :type:`nghttp2_error_callback` and 2387 * :type:`nghttp2_error_callback2` are set, the latter takes 2388 * precedence. 2389 */ 2390 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_error_callback2( 2391 nghttp2_session_callbacks *cbs, nghttp2_error_callback2 error_callback2); 2392 2393 /** 2394 * @functypedef 2395 * 2396 * Custom memory allocator to replace malloc(). The |mem_user_data| 2397 * is the mem_user_data member of :type:`nghttp2_mem` structure. 2398 */ 2399 typedef void *(*nghttp2_malloc)(size_t size, void *mem_user_data); 2400 2401 /** 2402 * @functypedef 2403 * 2404 * Custom memory allocator to replace free(). The |mem_user_data| is 2405 * the mem_user_data member of :type:`nghttp2_mem` structure. 2406 */ 2407 typedef void (*nghttp2_free)(void *ptr, void *mem_user_data); 2408 2409 /** 2410 * @functypedef 2411 * 2412 * Custom memory allocator to replace calloc(). The |mem_user_data| 2413 * is the mem_user_data member of :type:`nghttp2_mem` structure. 2414 */ 2415 typedef void *(*nghttp2_calloc)(size_t nmemb, size_t size, void *mem_user_data); 2416 2417 /** 2418 * @functypedef 2419 * 2420 * Custom memory allocator to replace realloc(). The |mem_user_data| 2421 * is the mem_user_data member of :type:`nghttp2_mem` structure. 2422 */ 2423 typedef void *(*nghttp2_realloc)(void *ptr, size_t size, void *mem_user_data); 2424 2425 /** 2426 * @struct 2427 * 2428 * Custom memory allocator functions and user defined pointer. The 2429 * |mem_user_data| member is passed to each allocator function. This 2430 * can be used, for example, to achieve per-session memory pool. 2431 * 2432 * In the following example code, ``my_malloc``, ``my_free``, 2433 * ``my_calloc`` and ``my_realloc`` are the replacement of the 2434 * standard allocators ``malloc``, ``free``, ``calloc`` and 2435 * ``realloc`` respectively:: 2436 * 2437 * void *my_malloc_cb(size_t size, void *mem_user_data) { 2438 * return my_malloc(size); 2439 * } 2440 * 2441 * void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); } 2442 * 2443 * void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) { 2444 * return my_calloc(nmemb, size); 2445 * } 2446 * 2447 * void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) { 2448 * return my_realloc(ptr, size); 2449 * } 2450 * 2451 * void session_new() { 2452 * nghttp2_session *session; 2453 * nghttp2_session_callbacks *callbacks; 2454 * nghttp2_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb, 2455 * my_realloc_cb}; 2456 * 2457 * ... 2458 * 2459 * nghttp2_session_client_new3(&session, callbacks, NULL, NULL, &mem); 2460 * 2461 * ... 2462 * } 2463 */ 2464 typedef struct { 2465 /** 2466 * An arbitrary user supplied data. This is passed to each 2467 * allocator function. 2468 */ 2469 void *mem_user_data; 2470 /** 2471 * Custom allocator function to replace malloc(). 2472 */ 2473 nghttp2_malloc malloc; 2474 /** 2475 * Custom allocator function to replace free(). 2476 */ 2477 nghttp2_free free; 2478 /** 2479 * Custom allocator function to replace calloc(). 2480 */ 2481 nghttp2_calloc calloc; 2482 /** 2483 * Custom allocator function to replace realloc(). 2484 */ 2485 nghttp2_realloc realloc; 2486 } nghttp2_mem; 2487 2488 struct nghttp2_option; 2489 2490 /** 2491 * @struct 2492 * 2493 * Configuration options for :type:`nghttp2_session`. The details of 2494 * this structure are intentionally hidden from the public API. 2495 */ 2496 typedef struct nghttp2_option nghttp2_option; 2497 2498 /** 2499 * @function 2500 * 2501 * Initializes |*option_ptr| with default values. 2502 * 2503 * When the application finished using this object, it can use 2504 * `nghttp2_option_del()` to free its memory. 2505 * 2506 * This function returns 0 if it succeeds, or one of the following 2507 * negative error codes: 2508 * 2509 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2510 * Out of memory. 2511 */ 2512 NGHTTP2_EXTERN int nghttp2_option_new(nghttp2_option **option_ptr); 2513 2514 /** 2515 * @function 2516 * 2517 * Frees any resources allocated for |option|. If |option| is 2518 * ``NULL``, this function does nothing. 2519 */ 2520 NGHTTP2_EXTERN void nghttp2_option_del(nghttp2_option *option); 2521 2522 /** 2523 * @function 2524 * 2525 * This option prevents the library from sending WINDOW_UPDATE for a 2526 * connection automatically. If this option is set to nonzero, the 2527 * library won't send WINDOW_UPDATE for DATA until application calls 2528 * `nghttp2_session_consume()` to indicate the consumed amount of 2529 * data. Don't use `nghttp2_submit_window_update()` for this purpose. 2530 * By default, this option is set to zero. 2531 */ 2532 NGHTTP2_EXTERN void 2533 nghttp2_option_set_no_auto_window_update(nghttp2_option *option, int val); 2534 2535 /** 2536 * @function 2537 * 2538 * This option sets the SETTINGS_MAX_CONCURRENT_STREAMS value of 2539 * remote endpoint as if it is received in SETTINGS frame. Without 2540 * specifying this option, the maximum number of outgoing concurrent 2541 * streams is initially limited to 100 to avoid issues when the local 2542 * endpoint submits lots of requests before receiving initial SETTINGS 2543 * frame from the remote endpoint, since sending them at once to the 2544 * remote endpoint could lead to rejection of some of the requests. 2545 * This value will be overwritten when the local endpoint receives 2546 * initial SETTINGS frame from the remote endpoint, either to the 2547 * value advertised in SETTINGS_MAX_CONCURRENT_STREAMS or to the 2548 * default value (unlimited) if none was advertised. 2549 */ 2550 NGHTTP2_EXTERN void 2551 nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option, 2552 uint32_t val); 2553 2554 /** 2555 * @function 2556 * 2557 * By default, nghttp2 library, if configured as server, requires 2558 * first 24 bytes of client magic byte string (MAGIC). In most cases, 2559 * this will simplify the implementation of server. But sometimes 2560 * server may want to detect the application protocol based on first 2561 * few bytes on clear text communication. 2562 * 2563 * If this option is used with nonzero |val|, nghttp2 library does not 2564 * handle MAGIC. It still checks following SETTINGS frame. This 2565 * means that applications should deal with MAGIC by themselves. 2566 * 2567 * If this option is not used or used with zero value, if MAGIC does 2568 * not match :macro:`NGHTTP2_CLIENT_MAGIC`, `nghttp2_session_recv()` 2569 * and `nghttp2_session_mem_recv()` will return error 2570 * :enum:`nghttp2_error.NGHTTP2_ERR_BAD_CLIENT_MAGIC`, which is fatal 2571 * error. 2572 */ 2573 NGHTTP2_EXTERN void 2574 nghttp2_option_set_no_recv_client_magic(nghttp2_option *option, int val); 2575 2576 /** 2577 * @function 2578 * 2579 * By default, nghttp2 library enforces subset of HTTP Messaging rules 2580 * described in `HTTP/2 specification, section 8 2581 * <https://tools.ietf.org/html/rfc7540#section-8>`_. See 2582 * :ref:`http-messaging` section for details. For those applications 2583 * who use nghttp2 library as non-HTTP use, give nonzero to |val| to 2584 * disable this enforcement. Please note that disabling this feature 2585 * does not change the fundamental client and server model of HTTP. 2586 * That is, even if the validation is disabled, only client can send 2587 * requests. 2588 */ 2589 NGHTTP2_EXTERN void nghttp2_option_set_no_http_messaging(nghttp2_option *option, 2590 int val); 2591 2592 /** 2593 * @function 2594 * 2595 * RFC 7540 does not enforce any limit on the number of incoming 2596 * reserved streams (in RFC 7540 terms, streams in reserved (remote) 2597 * state). This only affects client side, since only server can push 2598 * streams. Malicious server can push arbitrary number of streams, 2599 * and make client's memory exhausted. This option can set the 2600 * maximum number of such incoming streams to avoid possible memory 2601 * exhaustion. If this option is set, and pushed streams are 2602 * automatically closed on reception, without calling user provided 2603 * callback, if they exceed the given limit. The default value is 2604 * 200. If session is configured as server side, this option has no 2605 * effect. Server can control the number of streams to push. 2606 */ 2607 NGHTTP2_EXTERN void 2608 nghttp2_option_set_max_reserved_remote_streams(nghttp2_option *option, 2609 uint32_t val); 2610 2611 /** 2612 * @function 2613 * 2614 * Sets extension frame type the application is willing to handle with 2615 * user defined callbacks (see 2616 * :type:`nghttp2_on_extension_chunk_recv_callback` and 2617 * :type:`nghttp2_unpack_extension_callback`). The |type| is 2618 * extension frame type, and must be strictly greater than 0x9. 2619 * Otherwise, this function does nothing. The application can call 2620 * this function multiple times to set more than one frame type to 2621 * receive. The application does not have to call this function if it 2622 * just sends extension frames. 2623 */ 2624 NGHTTP2_EXTERN void 2625 nghttp2_option_set_user_recv_extension_type(nghttp2_option *option, 2626 uint8_t type); 2627 2628 /** 2629 * @function 2630 * 2631 * Sets extension frame type the application is willing to receive 2632 * using builtin handler. The |type| is the extension frame type to 2633 * receive, and must be strictly greater than 0x9. Otherwise, this 2634 * function does nothing. The application can call this function 2635 * multiple times to set more than one frame type to receive. The 2636 * application does not have to call this function if it just sends 2637 * extension frames. 2638 * 2639 * If same frame type is passed to both 2640 * `nghttp2_option_set_builtin_recv_extension_type()` and 2641 * `nghttp2_option_set_user_recv_extension_type()`, the latter takes 2642 * precedence. 2643 */ 2644 NGHTTP2_EXTERN void 2645 nghttp2_option_set_builtin_recv_extension_type(nghttp2_option *option, 2646 uint8_t type); 2647 2648 /** 2649 * @function 2650 * 2651 * This option prevents the library from sending PING frame with ACK 2652 * flag set automatically when PING frame without ACK flag set is 2653 * received. If this option is set to nonzero, the library won't send 2654 * PING frame with ACK flag set in the response for incoming PING 2655 * frame. The application can send PING frame with ACK flag set using 2656 * `nghttp2_submit_ping()` with :enum:`nghttp2_flag.NGHTTP2_FLAG_ACK` 2657 * as flags parameter. 2658 */ 2659 NGHTTP2_EXTERN void nghttp2_option_set_no_auto_ping_ack(nghttp2_option *option, 2660 int val); 2661 2662 /** 2663 * @function 2664 * 2665 * This option sets the maximum length of header block (a set of 2666 * header fields per one HEADERS frame) to send. The length of a 2667 * given set of header fields is calculated using 2668 * `nghttp2_hd_deflate_bound()`. The default value is 64KiB. If 2669 * application attempts to send header fields larger than this limit, 2670 * the transmission of the frame fails with error code 2671 * :enum:`nghttp2_error.NGHTTP2_ERR_FRAME_SIZE_ERROR`. 2672 */ 2673 NGHTTP2_EXTERN void 2674 nghttp2_option_set_max_send_header_block_length(nghttp2_option *option, 2675 size_t val); 2676 2677 /** 2678 * @function 2679 * 2680 * This option sets the maximum dynamic table size for deflating 2681 * header fields. The default value is 4KiB. In HTTP/2, receiver of 2682 * deflated header block can specify maximum dynamic table size. The 2683 * actual maximum size is the minimum of the size receiver specified 2684 * and this option value. 2685 */ 2686 NGHTTP2_EXTERN void 2687 nghttp2_option_set_max_deflate_dynamic_table_size(nghttp2_option *option, 2688 size_t val); 2689 2690 /** 2691 * @function 2692 * 2693 * This option prevents the library from retaining closed streams to 2694 * maintain the priority tree. If this option is set to nonzero, 2695 * applications can discard closed stream completely to save memory. 2696 */ 2697 NGHTTP2_EXTERN void nghttp2_option_set_no_closed_streams(nghttp2_option *option, 2698 int val); 2699 2700 /** 2701 * @function 2702 * 2703 * This function sets the maximum number of outgoing SETTINGS ACK and 2704 * PING ACK frames retained in :type:`nghttp2_session` object. If 2705 * more than those frames are retained, the peer is considered to be 2706 * misbehaving and session will be closed. The default value is 1000. 2707 */ 2708 NGHTTP2_EXTERN void nghttp2_option_set_max_outbound_ack(nghttp2_option *option, 2709 size_t val); 2710 2711 /** 2712 * @function 2713 * 2714 * This function sets the maximum number of SETTINGS entries per 2715 * SETTINGS frame that will be accepted. If more than those entries 2716 * are received, the peer is considered to be misbehaving and session 2717 * will be closed. The default value is 32. 2718 */ 2719 NGHTTP2_EXTERN void nghttp2_option_set_max_settings(nghttp2_option *option, 2720 size_t val); 2721 2722 /** 2723 * @function 2724 * 2725 * Initializes |*session_ptr| for client use. The all members of 2726 * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr| 2727 * does not store |callbacks|. The |user_data| is an arbitrary user 2728 * supplied data, which will be passed to the callback functions. 2729 * 2730 * The :type:`nghttp2_send_callback` must be specified. If the 2731 * application code uses `nghttp2_session_recv()`, the 2732 * :type:`nghttp2_recv_callback` must be specified. The other members 2733 * of |callbacks| can be ``NULL``. 2734 * 2735 * If this function fails, |*session_ptr| is left untouched. 2736 * 2737 * This function returns 0 if it succeeds, or one of the following 2738 * negative error codes: 2739 * 2740 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2741 * Out of memory. 2742 */ 2743 NGHTTP2_EXTERN int 2744 nghttp2_session_client_new(nghttp2_session **session_ptr, 2745 const nghttp2_session_callbacks *callbacks, 2746 void *user_data); 2747 2748 /** 2749 * @function 2750 * 2751 * Initializes |*session_ptr| for server use. The all members of 2752 * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr| 2753 * does not store |callbacks|. The |user_data| is an arbitrary user 2754 * supplied data, which will be passed to the callback functions. 2755 * 2756 * The :type:`nghttp2_send_callback` must be specified. If the 2757 * application code uses `nghttp2_session_recv()`, the 2758 * :type:`nghttp2_recv_callback` must be specified. The other members 2759 * of |callbacks| can be ``NULL``. 2760 * 2761 * If this function fails, |*session_ptr| is left untouched. 2762 * 2763 * This function returns 0 if it succeeds, or one of the following 2764 * negative error codes: 2765 * 2766 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2767 * Out of memory. 2768 */ 2769 NGHTTP2_EXTERN int 2770 nghttp2_session_server_new(nghttp2_session **session_ptr, 2771 const nghttp2_session_callbacks *callbacks, 2772 void *user_data); 2773 2774 /** 2775 * @function 2776 * 2777 * Like `nghttp2_session_client_new()`, but with additional options 2778 * specified in the |option|. 2779 * 2780 * The |option| can be ``NULL`` and the call is equivalent to 2781 * `nghttp2_session_client_new()`. 2782 * 2783 * This function does not take ownership |option|. The application is 2784 * responsible for freeing |option| if it finishes using the object. 2785 * 2786 * The library code does not refer to |option| after this function 2787 * returns. 2788 * 2789 * This function returns 0 if it succeeds, or one of the following 2790 * negative error codes: 2791 * 2792 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2793 * Out of memory. 2794 */ 2795 NGHTTP2_EXTERN int 2796 nghttp2_session_client_new2(nghttp2_session **session_ptr, 2797 const nghttp2_session_callbacks *callbacks, 2798 void *user_data, const nghttp2_option *option); 2799 2800 /** 2801 * @function 2802 * 2803 * Like `nghttp2_session_server_new()`, but with additional options 2804 * specified in the |option|. 2805 * 2806 * The |option| can be ``NULL`` and the call is equivalent to 2807 * `nghttp2_session_server_new()`. 2808 * 2809 * This function does not take ownership |option|. The application is 2810 * responsible for freeing |option| if it finishes using the object. 2811 * 2812 * The library code does not refer to |option| after this function 2813 * returns. 2814 * 2815 * This function returns 0 if it succeeds, or one of the following 2816 * negative error codes: 2817 * 2818 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2819 * Out of memory. 2820 */ 2821 NGHTTP2_EXTERN int 2822 nghttp2_session_server_new2(nghttp2_session **session_ptr, 2823 const nghttp2_session_callbacks *callbacks, 2824 void *user_data, const nghttp2_option *option); 2825 2826 /** 2827 * @function 2828 * 2829 * Like `nghttp2_session_client_new2()`, but with additional custom 2830 * memory allocator specified in the |mem|. 2831 * 2832 * The |mem| can be ``NULL`` and the call is equivalent to 2833 * `nghttp2_session_client_new2()`. 2834 * 2835 * This function does not take ownership |mem|. The application is 2836 * responsible for freeing |mem|. 2837 * 2838 * The library code does not refer to |mem| pointer after this 2839 * function returns, so the application can safely free it. 2840 * 2841 * This function returns 0 if it succeeds, or one of the following 2842 * negative error codes: 2843 * 2844 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2845 * Out of memory. 2846 */ 2847 NGHTTP2_EXTERN int nghttp2_session_client_new3( 2848 nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks, 2849 void *user_data, const nghttp2_option *option, nghttp2_mem *mem); 2850 2851 /** 2852 * @function 2853 * 2854 * Like `nghttp2_session_server_new2()`, but with additional custom 2855 * memory allocator specified in the |mem|. 2856 * 2857 * The |mem| can be ``NULL`` and the call is equivalent to 2858 * `nghttp2_session_server_new2()`. 2859 * 2860 * This function does not take ownership |mem|. The application is 2861 * responsible for freeing |mem|. 2862 * 2863 * The library code does not refer to |mem| pointer after this 2864 * function returns, so the application can safely free it. 2865 * 2866 * This function returns 0 if it succeeds, or one of the following 2867 * negative error codes: 2868 * 2869 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2870 * Out of memory. 2871 */ 2872 NGHTTP2_EXTERN int nghttp2_session_server_new3( 2873 nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks, 2874 void *user_data, const nghttp2_option *option, nghttp2_mem *mem); 2875 2876 /** 2877 * @function 2878 * 2879 * Frees any resources allocated for |session|. If |session| is 2880 * ``NULL``, this function does nothing. 2881 */ 2882 NGHTTP2_EXTERN void nghttp2_session_del(nghttp2_session *session); 2883 2884 /** 2885 * @function 2886 * 2887 * Sends pending frames to the remote peer. 2888 * 2889 * This function retrieves the highest prioritized frame from the 2890 * outbound queue and sends it to the remote peer. It does this as 2891 * many times as possible until the user callback 2892 * :type:`nghttp2_send_callback` returns 2893 * :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`, the outbound queue 2894 * becomes empty or flow control is triggered (remote window size 2895 * becomes depleted or maximum number of concurrent streams is 2896 * reached). This function calls several callback functions which are 2897 * passed when initializing the |session|. Here is the simple time 2898 * chart which tells when each callback is invoked: 2899 * 2900 * 1. Get the next frame to send from outbound queue. 2901 * 2902 * 2. Prepare transmission of the frame. 2903 * 2904 * 3. If the control frame cannot be sent because some preconditions 2905 * are not met (e.g., request HEADERS cannot be sent after GOAWAY), 2906 * :type:`nghttp2_on_frame_not_send_callback` is invoked. Abort 2907 * the following steps. 2908 * 2909 * 4. If the frame is HEADERS, PUSH_PROMISE or DATA, 2910 * :type:`nghttp2_select_padding_callback` is invoked. 2911 * 2912 * 5. If the frame is request HEADERS, the stream is opened here. 2913 * 2914 * 6. :type:`nghttp2_before_frame_send_callback` is invoked. 2915 * 2916 * 7. If :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL` is returned from 2917 * :type:`nghttp2_before_frame_send_callback`, the current frame 2918 * transmission is canceled, and 2919 * :type:`nghttp2_on_frame_not_send_callback` is invoked. Abort 2920 * the following steps. 2921 * 2922 * 8. :type:`nghttp2_send_callback` is invoked one or more times to 2923 * send the frame. 2924 * 2925 * 9. :type:`nghttp2_on_frame_send_callback` is invoked. 2926 * 2927 * 10. If the transmission of the frame triggers closure of the 2928 * stream, the stream is closed and 2929 * :type:`nghttp2_on_stream_close_callback` is invoked. 2930 * 2931 * This function returns 0 if it succeeds, or one of the following 2932 * negative error codes: 2933 * 2934 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2935 * Out of memory. 2936 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` 2937 * The callback function failed. 2938 */ 2939 NGHTTP2_EXTERN int nghttp2_session_send(nghttp2_session *session); 2940 2941 /** 2942 * @function 2943 * 2944 * Returns the serialized data to send. 2945 * 2946 * This function behaves like `nghttp2_session_send()` except that it 2947 * does not use :type:`nghttp2_send_callback` to transmit data. 2948 * Instead, it assigns the pointer to the serialized data to the 2949 * |*data_ptr| and returns its length. The other callbacks are called 2950 * in the same way as they are in `nghttp2_session_send()`. 2951 * 2952 * If no data is available to send, this function returns 0. 2953 * 2954 * This function may not return all serialized data in one invocation. 2955 * To get all data, call this function repeatedly until it returns 0 2956 * or one of negative error codes. 2957 * 2958 * The assigned |*data_ptr| is valid until the next call of 2959 * `nghttp2_session_mem_send()` or `nghttp2_session_send()`. 2960 * 2961 * The caller must send all data before sending the next chunk of 2962 * data. 2963 * 2964 * This function returns the length of the data pointed by the 2965 * |*data_ptr| if it succeeds, or one of the following negative error 2966 * codes: 2967 * 2968 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 2969 * Out of memory. 2970 * 2971 * .. note:: 2972 * 2973 * This function may produce very small byte string. If that is the 2974 * case, and application disables Nagle algorithm (``TCP_NODELAY``), 2975 * then writing this small chunk leads to very small packet, and it 2976 * is very inefficient. An application should be responsible to 2977 * buffer up small chunks of data as necessary to avoid this 2978 * situation. 2979 */ 2980 NGHTTP2_EXTERN ssize_t nghttp2_session_mem_send(nghttp2_session *session, 2981 const uint8_t **data_ptr); 2982 2983 /** 2984 * @function 2985 * 2986 * Receives frames from the remote peer. 2987 * 2988 * This function receives as many frames as possible until the user 2989 * callback :type:`nghttp2_recv_callback` returns 2990 * :enum:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. This function calls 2991 * several callback functions which are passed when initializing the 2992 * |session|. Here is the simple time chart which tells when each 2993 * callback is invoked: 2994 * 2995 * 1. :type:`nghttp2_recv_callback` is invoked one or more times to 2996 * receive frame header. 2997 * 2998 * 2. When frame header is received, 2999 * :type:`nghttp2_on_begin_frame_callback` is invoked. 3000 * 3001 * 3. If the frame is DATA frame: 3002 * 3003 * 1. :type:`nghttp2_recv_callback` is invoked to receive DATA 3004 * payload. For each chunk of data, 3005 * :type:`nghttp2_on_data_chunk_recv_callback` is invoked. 3006 * 3007 * 2. If one DATA frame is completely received, 3008 * :type:`nghttp2_on_frame_recv_callback` is invoked. If the 3009 * reception of the frame triggers the closure of the stream, 3010 * :type:`nghttp2_on_stream_close_callback` is invoked. 3011 * 3012 * 4. If the frame is the control frame: 3013 * 3014 * 1. :type:`nghttp2_recv_callback` is invoked one or more times to 3015 * receive whole frame. 3016 * 3017 * 2. If the received frame is valid, then following actions are 3018 * taken. If the frame is either HEADERS or PUSH_PROMISE, 3019 * :type:`nghttp2_on_begin_headers_callback` is invoked. Then 3020 * :type:`nghttp2_on_header_callback` is invoked for each header 3021 * name/value pair. For invalid header field, 3022 * :type:`nghttp2_on_invalid_header_callback` is called. After 3023 * all name/value pairs are emitted successfully, 3024 * :type:`nghttp2_on_frame_recv_callback` is invoked. For other 3025 * frames, :type:`nghttp2_on_frame_recv_callback` is invoked. 3026 * If the reception of the frame triggers the closure of the 3027 * stream, :type:`nghttp2_on_stream_close_callback` is invoked. 3028 * 3029 * 3. If the received frame is unpacked but is interpreted as 3030 * invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is 3031 * invoked. 3032 * 3033 * This function returns 0 if it succeeds, or one of the following 3034 * negative error codes: 3035 * 3036 * :enum:`nghttp2_error.NGHTTP2_ERR_EOF` 3037 * The remote peer did shutdown on the connection. 3038 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3039 * Out of memory. 3040 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` 3041 * The callback function failed. 3042 * :enum:`nghttp2_error.NGHTTP2_ERR_BAD_CLIENT_MAGIC` 3043 * Invalid client magic was detected. This error only returns 3044 * when |session| was configured as server and 3045 * `nghttp2_option_set_no_recv_client_magic()` is not used with 3046 * nonzero value. 3047 * :enum:`nghttp2_error.NGHTTP2_ERR_FLOODED` 3048 * Flooding was detected in this HTTP/2 session, and it must be 3049 * closed. This is most likely caused by misbehaviour of peer. 3050 */ 3051 NGHTTP2_EXTERN int nghttp2_session_recv(nghttp2_session *session); 3052 3053 /** 3054 * @function 3055 * 3056 * Processes data |in| as an input from the remote endpoint. The 3057 * |inlen| indicates the number of bytes to receive in the |in|. 3058 * 3059 * This function behaves like `nghttp2_session_recv()` except that it 3060 * does not use :type:`nghttp2_recv_callback` to receive data; the 3061 * |in| is the only data for the invocation of this function. If all 3062 * bytes are processed, this function returns. The other callbacks 3063 * are called in the same way as they are in `nghttp2_session_recv()`. 3064 * 3065 * In the current implementation, this function always tries to 3066 * processes |inlen| bytes of input data unless either an error occurs or 3067 * :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` is returned from 3068 * :type:`nghttp2_on_header_callback` or 3069 * :type:`nghttp2_on_data_chunk_recv_callback`. If 3070 * :enum:`nghttp2_error.NGHTTP2_ERR_PAUSE` is used, the return value 3071 * includes the number of bytes which was used to produce the data or 3072 * frame for the callback. 3073 * 3074 * This function returns the number of processed bytes, or one of the 3075 * following negative error codes: 3076 * 3077 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3078 * Out of memory. 3079 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` 3080 * The callback function failed. 3081 * :enum:`nghttp2_error.NGHTTP2_ERR_BAD_CLIENT_MAGIC` 3082 * Invalid client magic was detected. This error only returns 3083 * when |session| was configured as server and 3084 * `nghttp2_option_set_no_recv_client_magic()` is not used with 3085 * nonzero value. 3086 * :enum:`nghttp2_error.NGHTTP2_ERR_FLOODED` 3087 * Flooding was detected in this HTTP/2 session, and it must be 3088 * closed. This is most likely caused by misbehaviour of peer. 3089 */ 3090 NGHTTP2_EXTERN ssize_t nghttp2_session_mem_recv(nghttp2_session *session, 3091 const uint8_t *in, 3092 size_t inlen); 3093 3094 /** 3095 * @function 3096 * 3097 * Puts back previously deferred DATA frame in the stream |stream_id| 3098 * to the outbound queue. 3099 * 3100 * This function returns 0 if it succeeds, or one of the following 3101 * negative error codes: 3102 * 3103 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3104 * The stream does not exist; or no deferred data exist. 3105 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3106 * Out of memory. 3107 */ 3108 NGHTTP2_EXTERN int nghttp2_session_resume_data(nghttp2_session *session, 3109 int32_t stream_id); 3110 3111 /** 3112 * @function 3113 * 3114 * Returns nonzero value if |session| wants to receive data from the 3115 * remote peer. 3116 * 3117 * If both `nghttp2_session_want_read()` and 3118 * `nghttp2_session_want_write()` return 0, the application should 3119 * drop the connection. 3120 */ 3121 NGHTTP2_EXTERN int nghttp2_session_want_read(nghttp2_session *session); 3122 3123 /** 3124 * @function 3125 * 3126 * Returns nonzero value if |session| wants to send data to the remote 3127 * peer. 3128 * 3129 * If both `nghttp2_session_want_read()` and 3130 * `nghttp2_session_want_write()` return 0, the application should 3131 * drop the connection. 3132 */ 3133 NGHTTP2_EXTERN int nghttp2_session_want_write(nghttp2_session *session); 3134 3135 /** 3136 * @function 3137 * 3138 * Returns stream_user_data for the stream |stream_id|. The 3139 * stream_user_data is provided by `nghttp2_submit_request()`, 3140 * `nghttp2_submit_headers()` or 3141 * `nghttp2_session_set_stream_user_data()`. Unless it is set using 3142 * `nghttp2_session_set_stream_user_data()`, if the stream is 3143 * initiated by the remote endpoint, stream_user_data is always 3144 * ``NULL``. If the stream does not exist, this function returns 3145 * ``NULL``. 3146 */ 3147 NGHTTP2_EXTERN void * 3148 nghttp2_session_get_stream_user_data(nghttp2_session *session, 3149 int32_t stream_id); 3150 3151 /** 3152 * @function 3153 * 3154 * Sets the |stream_user_data| to the stream denoted by the 3155 * |stream_id|. If a stream user data is already set to the stream, 3156 * it is replaced with the |stream_user_data|. It is valid to specify 3157 * ``NULL`` in the |stream_user_data|, which nullifies the associated 3158 * data pointer. 3159 * 3160 * It is valid to set the |stream_user_data| to the stream reserved by 3161 * PUSH_PROMISE frame. 3162 * 3163 * This function returns 0 if it succeeds, or one of following 3164 * negative error codes: 3165 * 3166 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3167 * The stream does not exist 3168 */ 3169 NGHTTP2_EXTERN int 3170 nghttp2_session_set_stream_user_data(nghttp2_session *session, 3171 int32_t stream_id, void *stream_user_data); 3172 3173 /** 3174 * @function 3175 * 3176 * Sets |user_data| to |session|, overwriting the existing user data 3177 * specified in `nghttp2_session_client_new()`, or 3178 * `nghttp2_session_server_new()`. 3179 */ 3180 NGHTTP2_EXTERN void nghttp2_session_set_user_data(nghttp2_session *session, 3181 void *user_data); 3182 3183 /** 3184 * @function 3185 * 3186 * Returns the number of frames in the outbound queue. This does not 3187 * include the deferred DATA frames. 3188 */ 3189 NGHTTP2_EXTERN size_t 3190 nghttp2_session_get_outbound_queue_size(nghttp2_session *session); 3191 3192 /** 3193 * @function 3194 * 3195 * Returns the number of DATA payload in bytes received without 3196 * WINDOW_UPDATE transmission for the stream |stream_id|. The local 3197 * (receive) window size can be adjusted by 3198 * `nghttp2_submit_window_update()`. This function takes into account 3199 * that and returns effective data length. In particular, if the 3200 * local window size is reduced by submitting negative 3201 * window_size_increment with `nghttp2_submit_window_update()`, this 3202 * function returns the number of bytes less than actually received. 3203 * 3204 * This function returns -1 if it fails. 3205 */ 3206 NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_effective_recv_data_length( 3207 nghttp2_session *session, int32_t stream_id); 3208 3209 /** 3210 * @function 3211 * 3212 * Returns the local (receive) window size for the stream |stream_id|. 3213 * The local window size can be adjusted by 3214 * `nghttp2_submit_window_update()`. This function takes into account 3215 * that and returns effective window size. 3216 * 3217 * This function does not take into account the amount of received 3218 * data from the remote endpoint. Use 3219 * `nghttp2_session_get_stream_local_window_size()` to know the amount 3220 * of data the remote endpoint can send without receiving stream level 3221 * WINDOW_UPDATE frame. Note that each stream is still subject to the 3222 * connection level flow control. 3223 * 3224 * This function returns -1 if it fails. 3225 */ 3226 NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_effective_local_window_size( 3227 nghttp2_session *session, int32_t stream_id); 3228 3229 /** 3230 * @function 3231 * 3232 * Returns the amount of flow-controlled payload (e.g., DATA) that the 3233 * remote endpoint can send without receiving stream level 3234 * WINDOW_UPDATE frame. It is also subject to the connection level 3235 * flow control. So the actual amount of data to send is 3236 * min(`nghttp2_session_get_stream_local_window_size()`, 3237 * `nghttp2_session_get_local_window_size()`). 3238 * 3239 * This function returns -1 if it fails. 3240 */ 3241 NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_local_window_size( 3242 nghttp2_session *session, int32_t stream_id); 3243 3244 /** 3245 * @function 3246 * 3247 * Returns the number of DATA payload in bytes received without 3248 * WINDOW_UPDATE transmission for a connection. The local (receive) 3249 * window size can be adjusted by `nghttp2_submit_window_update()`. 3250 * This function takes into account that and returns effective data 3251 * length. In particular, if the local window size is reduced by 3252 * submitting negative window_size_increment with 3253 * `nghttp2_submit_window_update()`, this function returns the number 3254 * of bytes less than actually received. 3255 * 3256 * This function returns -1 if it fails. 3257 */ 3258 NGHTTP2_EXTERN int32_t 3259 nghttp2_session_get_effective_recv_data_length(nghttp2_session *session); 3260 3261 /** 3262 * @function 3263 * 3264 * Returns the local (receive) window size for a connection. The 3265 * local window size can be adjusted by 3266 * `nghttp2_submit_window_update()`. This function takes into account 3267 * that and returns effective window size. 3268 * 3269 * This function does not take into account the amount of received 3270 * data from the remote endpoint. Use 3271 * `nghttp2_session_get_local_window_size()` to know the amount of 3272 * data the remote endpoint can send without receiving 3273 * connection-level WINDOW_UPDATE frame. Note that each stream is 3274 * still subject to the stream level flow control. 3275 * 3276 * This function returns -1 if it fails. 3277 */ 3278 NGHTTP2_EXTERN int32_t 3279 nghttp2_session_get_effective_local_window_size(nghttp2_session *session); 3280 3281 /** 3282 * @function 3283 * 3284 * Returns the amount of flow-controlled payload (e.g., DATA) that the 3285 * remote endpoint can send without receiving connection level 3286 * WINDOW_UPDATE frame. Note that each stream is still subject to the 3287 * stream level flow control (see 3288 * `nghttp2_session_get_stream_local_window_size()`). 3289 * 3290 * This function returns -1 if it fails. 3291 */ 3292 NGHTTP2_EXTERN int32_t 3293 nghttp2_session_get_local_window_size(nghttp2_session *session); 3294 3295 /** 3296 * @function 3297 * 3298 * Returns the remote window size for a given stream |stream_id|. 3299 * 3300 * This is the amount of flow-controlled payload (e.g., DATA) that the 3301 * local endpoint can send without stream level WINDOW_UPDATE. There 3302 * is also connection level flow control, so the effective size of 3303 * payload that the local endpoint can actually send is 3304 * min(`nghttp2_session_get_stream_remote_window_size()`, 3305 * `nghttp2_session_get_remote_window_size()`). 3306 * 3307 * This function returns -1 if it fails. 3308 */ 3309 NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_remote_window_size( 3310 nghttp2_session *session, int32_t stream_id); 3311 3312 /** 3313 * @function 3314 * 3315 * Returns the remote window size for a connection. 3316 * 3317 * This function always succeeds. 3318 */ 3319 NGHTTP2_EXTERN int32_t 3320 nghttp2_session_get_remote_window_size(nghttp2_session *session); 3321 3322 /** 3323 * @function 3324 * 3325 * Returns 1 if local peer half closed the given stream |stream_id|. 3326 * Returns 0 if it did not. Returns -1 if no such stream exists. 3327 */ 3328 NGHTTP2_EXTERN int 3329 nghttp2_session_get_stream_local_close(nghttp2_session *session, 3330 int32_t stream_id); 3331 3332 /** 3333 * @function 3334 * 3335 * Returns 1 if remote peer half closed the given stream |stream_id|. 3336 * Returns 0 if it did not. Returns -1 if no such stream exists. 3337 */ 3338 NGHTTP2_EXTERN int 3339 nghttp2_session_get_stream_remote_close(nghttp2_session *session, 3340 int32_t stream_id); 3341 3342 /** 3343 * @function 3344 * 3345 * Returns the current dynamic table size of HPACK inflater, including 3346 * the overhead 32 bytes per entry described in RFC 7541. 3347 */ 3348 NGHTTP2_EXTERN size_t 3349 nghttp2_session_get_hd_inflate_dynamic_table_size(nghttp2_session *session); 3350 3351 /** 3352 * @function 3353 * 3354 * Returns the current dynamic table size of HPACK deflater including 3355 * the overhead 32 bytes per entry described in RFC 7541. 3356 */ 3357 NGHTTP2_EXTERN size_t 3358 nghttp2_session_get_hd_deflate_dynamic_table_size(nghttp2_session *session); 3359 3360 /** 3361 * @function 3362 * 3363 * Signals the session so that the connection should be terminated. 3364 * 3365 * The last stream ID is the minimum value between the stream ID of a 3366 * stream for which :type:`nghttp2_on_frame_recv_callback` was called 3367 * most recently and the last stream ID we have sent to the peer 3368 * previously. 3369 * 3370 * The |error_code| is the error code of this GOAWAY frame. The 3371 * pre-defined error code is one of :enum:`nghttp2_error_code`. 3372 * 3373 * After the transmission, both `nghttp2_session_want_read()` and 3374 * `nghttp2_session_want_write()` return 0. 3375 * 3376 * This function should be called when the connection should be 3377 * terminated after sending GOAWAY. If the remaining streams should 3378 * be processed after GOAWAY, use `nghttp2_submit_goaway()` instead. 3379 * 3380 * This function returns 0 if it succeeds, or one of the following 3381 * negative error codes: 3382 * 3383 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3384 * Out of memory. 3385 */ 3386 NGHTTP2_EXTERN int nghttp2_session_terminate_session(nghttp2_session *session, 3387 uint32_t error_code); 3388 3389 /** 3390 * @function 3391 * 3392 * Signals the session so that the connection should be terminated. 3393 * 3394 * This function behaves like `nghttp2_session_terminate_session()`, 3395 * but the last stream ID can be specified by the application for fine 3396 * grained control of stream. The HTTP/2 specification does not allow 3397 * last_stream_id to be increased. So the actual value sent as 3398 * last_stream_id is the minimum value between the given 3399 * |last_stream_id| and the last_stream_id we have previously sent to 3400 * the peer. 3401 * 3402 * The |last_stream_id| is peer's stream ID or 0. So if |session| is 3403 * initialized as client, |last_stream_id| must be even or 0. If 3404 * |session| is initialized as server, |last_stream_id| must be odd or 3405 * 0. 3406 * 3407 * This function returns 0 if it succeeds, or one of the following 3408 * negative error codes: 3409 * 3410 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3411 * Out of memory. 3412 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3413 * The |last_stream_id| is invalid. 3414 */ 3415 NGHTTP2_EXTERN int nghttp2_session_terminate_session2(nghttp2_session *session, 3416 int32_t last_stream_id, 3417 uint32_t error_code); 3418 3419 /** 3420 * @function 3421 * 3422 * Signals to the client that the server started graceful shutdown 3423 * procedure. 3424 * 3425 * This function is only usable for server. If this function is 3426 * called with client side session, this function returns 3427 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`. 3428 * 3429 * To gracefully shutdown HTTP/2 session, server should call this 3430 * function to send GOAWAY with last_stream_id (1u << 31) - 1. And 3431 * after some delay (e.g., 1 RTT), send another GOAWAY with the stream 3432 * ID that the server has some processing using 3433 * `nghttp2_submit_goaway()`. See also 3434 * `nghttp2_session_get_last_proc_stream_id()`. 3435 * 3436 * Unlike `nghttp2_submit_goaway()`, this function just sends GOAWAY 3437 * and does nothing more. This is a mere indication to the client 3438 * that session shutdown is imminent. The application should call 3439 * `nghttp2_submit_goaway()` with appropriate last_stream_id after 3440 * this call. 3441 * 3442 * If one or more GOAWAY frame have been already sent by either 3443 * `nghttp2_submit_goaway()` or `nghttp2_session_terminate_session()`, 3444 * this function has no effect. 3445 * 3446 * This function returns 0 if it succeeds, or one of the following 3447 * negative error codes: 3448 * 3449 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3450 * Out of memory. 3451 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` 3452 * The |session| is initialized as client. 3453 */ 3454 NGHTTP2_EXTERN int nghttp2_submit_shutdown_notice(nghttp2_session *session); 3455 3456 /** 3457 * @function 3458 * 3459 * Returns the value of SETTINGS |id| notified by a remote endpoint. 3460 * The |id| must be one of values defined in 3461 * :enum:`nghttp2_settings_id`. 3462 */ 3463 NGHTTP2_EXTERN uint32_t nghttp2_session_get_remote_settings( 3464 nghttp2_session *session, nghttp2_settings_id id); 3465 3466 /** 3467 * @function 3468 * 3469 * Returns the value of SETTINGS |id| of local endpoint acknowledged 3470 * by the remote endpoint. The |id| must be one of the values defined 3471 * in :enum:`nghttp2_settings_id`. 3472 */ 3473 NGHTTP2_EXTERN uint32_t nghttp2_session_get_local_settings( 3474 nghttp2_session *session, nghttp2_settings_id id); 3475 3476 /** 3477 * @function 3478 * 3479 * Tells the |session| that next stream ID is |next_stream_id|. The 3480 * |next_stream_id| must be equal or greater than the value returned 3481 * by `nghttp2_session_get_next_stream_id()`. 3482 * 3483 * This function returns 0 if it succeeds, or one of the following 3484 * negative error codes: 3485 * 3486 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3487 * The |next_stream_id| is strictly less than the value 3488 * `nghttp2_session_get_next_stream_id()` returns; or 3489 * |next_stream_id| is invalid (e.g., even integer for client, or 3490 * odd integer for server). 3491 */ 3492 NGHTTP2_EXTERN int nghttp2_session_set_next_stream_id(nghttp2_session *session, 3493 int32_t next_stream_id); 3494 3495 /** 3496 * @function 3497 * 3498 * Returns the next outgoing stream ID. Notice that return type is 3499 * uint32_t. If we run out of stream ID for this session, this 3500 * function returns 1 << 31. 3501 */ 3502 NGHTTP2_EXTERN uint32_t 3503 nghttp2_session_get_next_stream_id(nghttp2_session *session); 3504 3505 /** 3506 * @function 3507 * 3508 * Tells the |session| that |size| bytes for a stream denoted by 3509 * |stream_id| were consumed by application and are ready to 3510 * WINDOW_UPDATE. The consumed bytes are counted towards both 3511 * connection and stream level WINDOW_UPDATE (see 3512 * `nghttp2_session_consume_connection()` and 3513 * `nghttp2_session_consume_stream()` to update consumption 3514 * independently). This function is intended to be used without 3515 * automatic window update (see 3516 * `nghttp2_option_set_no_auto_window_update()`). 3517 * 3518 * This function returns 0 if it succeeds, or one of the following 3519 * negative error codes: 3520 * 3521 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3522 * Out of memory. 3523 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3524 * The |stream_id| is 0. 3525 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` 3526 * Automatic WINDOW_UPDATE is not disabled. 3527 */ 3528 NGHTTP2_EXTERN int nghttp2_session_consume(nghttp2_session *session, 3529 int32_t stream_id, size_t size); 3530 3531 /** 3532 * @function 3533 * 3534 * Like `nghttp2_session_consume()`, but this only tells library that 3535 * |size| bytes were consumed only for connection level. Note that 3536 * HTTP/2 maintains connection and stream level flow control windows 3537 * independently. 3538 * 3539 * This function returns 0 if it succeeds, or one of the following 3540 * negative error codes: 3541 * 3542 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3543 * Out of memory. 3544 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` 3545 * Automatic WINDOW_UPDATE is not disabled. 3546 */ 3547 NGHTTP2_EXTERN int nghttp2_session_consume_connection(nghttp2_session *session, 3548 size_t size); 3549 3550 /** 3551 * @function 3552 * 3553 * Like `nghttp2_session_consume()`, but this only tells library that 3554 * |size| bytes were consumed only for stream denoted by |stream_id|. 3555 * Note that HTTP/2 maintains connection and stream level flow control 3556 * windows independently. 3557 * 3558 * This function returns 0 if it succeeds, or one of the following 3559 * negative error codes: 3560 * 3561 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3562 * Out of memory. 3563 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3564 * The |stream_id| is 0. 3565 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` 3566 * Automatic WINDOW_UPDATE is not disabled. 3567 */ 3568 NGHTTP2_EXTERN int nghttp2_session_consume_stream(nghttp2_session *session, 3569 int32_t stream_id, 3570 size_t size); 3571 3572 /** 3573 * @function 3574 * 3575 * Changes priority of existing stream denoted by |stream_id|. The 3576 * new priority specification is |pri_spec|. 3577 * 3578 * The priority is changed silently and instantly, and no PRIORITY 3579 * frame will be sent to notify the peer of this change. This 3580 * function may be useful for server to change the priority of pushed 3581 * stream. 3582 * 3583 * If |session| is initialized as server, and ``pri_spec->stream_id`` 3584 * points to the idle stream, the idle stream is created if it does 3585 * not exist. The created idle stream will depend on root stream 3586 * (stream 0) with weight 16. 3587 * 3588 * Otherwise, if stream denoted by ``pri_spec->stream_id`` is not 3589 * found, we use default priority instead of given |pri_spec|. That 3590 * is make stream depend on root stream with weight 16. 3591 * 3592 * This function returns 0 if it succeeds, or one of the following 3593 * negative error codes: 3594 * 3595 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3596 * Out of memory. 3597 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3598 * Attempted to depend on itself; or no stream exist for the given 3599 * |stream_id|; or |stream_id| is 0 3600 */ 3601 NGHTTP2_EXTERN int 3602 nghttp2_session_change_stream_priority(nghttp2_session *session, 3603 int32_t stream_id, 3604 const nghttp2_priority_spec *pri_spec); 3605 3606 /** 3607 * @function 3608 * 3609 * Creates idle stream with the given |stream_id|, and priority 3610 * |pri_spec|. 3611 * 3612 * The stream creation is done without sending PRIORITY frame, which 3613 * means that peer does not know about the existence of this idle 3614 * stream in the local endpoint. 3615 * 3616 * RFC 7540 does not disallow the use of creation of idle stream with 3617 * odd or even stream ID regardless of client or server. So this 3618 * function can create odd or even stream ID regardless of client or 3619 * server. But probably it is a bit safer to use the stream ID the 3620 * local endpoint can initiate (in other words, use odd stream ID for 3621 * client, and even stream ID for server), to avoid potential 3622 * collision from peer's instruction. Also we can use 3623 * `nghttp2_session_set_next_stream_id()` to avoid to open created 3624 * idle streams accidentally if we follow this recommendation. 3625 * 3626 * If |session| is initialized as server, and ``pri_spec->stream_id`` 3627 * points to the idle stream, the idle stream is created if it does 3628 * not exist. The created idle stream will depend on root stream 3629 * (stream 0) with weight 16. 3630 * 3631 * Otherwise, if stream denoted by ``pri_spec->stream_id`` is not 3632 * found, we use default priority instead of given |pri_spec|. That 3633 * is make stream depend on root stream with weight 16. 3634 * 3635 * This function returns 0 if it succeeds, or one of the following 3636 * negative error codes: 3637 * 3638 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3639 * Out of memory. 3640 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3641 * Attempted to depend on itself; or stream denoted by |stream_id| 3642 * already exists; or |stream_id| cannot be used to create idle 3643 * stream (in other words, local endpoint has already opened 3644 * stream ID greater than or equal to the given stream ID; or 3645 * |stream_id| is 0 3646 */ 3647 NGHTTP2_EXTERN int 3648 nghttp2_session_create_idle_stream(nghttp2_session *session, int32_t stream_id, 3649 const nghttp2_priority_spec *pri_spec); 3650 3651 /** 3652 * @function 3653 * 3654 * Performs post-process of HTTP Upgrade request. This function can 3655 * be called from both client and server, but the behavior is very 3656 * different in each other. 3657 * 3658 * .. warning:: 3659 * 3660 * This function is deprecated in favor of 3661 * `nghttp2_session_upgrade2()`, because this function lacks the 3662 * parameter to tell the library the request method used in the 3663 * original HTTP request. This information is required for client 3664 * to validate actual response body length against content-length 3665 * header field (see `nghttp2_option_set_no_http_messaging()`). If 3666 * HEAD is used in request, the length of response body must be 0 3667 * regardless of value included in content-length header field. 3668 * 3669 * If called from client side, the |settings_payload| must be the 3670 * value sent in ``HTTP2-Settings`` header field and must be decoded 3671 * by base64url decoder. The |settings_payloadlen| is the length of 3672 * |settings_payload|. The |settings_payload| is unpacked and its 3673 * setting values will be submitted using `nghttp2_submit_settings()`. 3674 * This means that the client application code does not need to submit 3675 * SETTINGS by itself. The stream with stream ID=1 is opened and the 3676 * |stream_user_data| is used for its stream_user_data. The opened 3677 * stream becomes half-closed (local) state. 3678 * 3679 * If called from server side, the |settings_payload| must be the 3680 * value received in ``HTTP2-Settings`` header field and must be 3681 * decoded by base64url decoder. The |settings_payloadlen| is the 3682 * length of |settings_payload|. It is treated as if the SETTINGS 3683 * frame with that payload is received. Thus, callback functions for 3684 * the reception of SETTINGS frame will be invoked. The stream with 3685 * stream ID=1 is opened. The |stream_user_data| is ignored. The 3686 * opened stream becomes half-closed (remote). 3687 * 3688 * This function returns 0 if it succeeds, or one of the following 3689 * negative error codes: 3690 * 3691 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3692 * Out of memory. 3693 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3694 * The |settings_payload| is badly formed. 3695 * :enum:`nghttp2_error.NGHTTP2_ERR_PROTO` 3696 * The stream ID 1 is already used or closed; or is not available. 3697 */ 3698 NGHTTP2_EXTERN int nghttp2_session_upgrade(nghttp2_session *session, 3699 const uint8_t *settings_payload, 3700 size_t settings_payloadlen, 3701 void *stream_user_data); 3702 3703 /** 3704 * @function 3705 * 3706 * Performs post-process of HTTP Upgrade request. This function can 3707 * be called from both client and server, but the behavior is very 3708 * different in each other. 3709 * 3710 * If called from client side, the |settings_payload| must be the 3711 * value sent in ``HTTP2-Settings`` header field and must be decoded 3712 * by base64url decoder. The |settings_payloadlen| is the length of 3713 * |settings_payload|. The |settings_payload| is unpacked and its 3714 * setting values will be submitted using `nghttp2_submit_settings()`. 3715 * This means that the client application code does not need to submit 3716 * SETTINGS by itself. The stream with stream ID=1 is opened and the 3717 * |stream_user_data| is used for its stream_user_data. The opened 3718 * stream becomes half-closed (local) state. 3719 * 3720 * If called from server side, the |settings_payload| must be the 3721 * value received in ``HTTP2-Settings`` header field and must be 3722 * decoded by base64url decoder. The |settings_payloadlen| is the 3723 * length of |settings_payload|. It is treated as if the SETTINGS 3724 * frame with that payload is received. Thus, callback functions for 3725 * the reception of SETTINGS frame will be invoked. The stream with 3726 * stream ID=1 is opened. The |stream_user_data| is ignored. The 3727 * opened stream becomes half-closed (remote). 3728 * 3729 * If the request method is HEAD, pass nonzero value to 3730 * |head_request|. Otherwise, pass 0. 3731 * 3732 * This function returns 0 if it succeeds, or one of the following 3733 * negative error codes: 3734 * 3735 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3736 * Out of memory. 3737 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3738 * The |settings_payload| is badly formed. 3739 * :enum:`nghttp2_error.NGHTTP2_ERR_PROTO` 3740 * The stream ID 1 is already used or closed; or is not available. 3741 */ 3742 NGHTTP2_EXTERN int nghttp2_session_upgrade2(nghttp2_session *session, 3743 const uint8_t *settings_payload, 3744 size_t settings_payloadlen, 3745 int head_request, 3746 void *stream_user_data); 3747 3748 /** 3749 * @function 3750 * 3751 * Serializes the SETTINGS values |iv| in the |buf|. The size of the 3752 * |buf| is specified by |buflen|. The number of entries in the |iv| 3753 * array is given by |niv|. The required space in |buf| for the |niv| 3754 * entries is ``6*niv`` bytes and if the given buffer is too small, an 3755 * error is returned. This function is used mainly for creating a 3756 * SETTINGS payload to be sent with the ``HTTP2-Settings`` header 3757 * field in an HTTP Upgrade request. The data written in |buf| is NOT 3758 * base64url encoded and the application is responsible for encoding. 3759 * 3760 * This function returns the number of bytes written in |buf|, or one 3761 * of the following negative error codes: 3762 * 3763 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3764 * The |iv| contains duplicate settings ID or invalid value. 3765 * 3766 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE` 3767 * The provided |buflen| size is too small to hold the output. 3768 */ 3769 NGHTTP2_EXTERN ssize_t nghttp2_pack_settings_payload( 3770 uint8_t *buf, size_t buflen, const nghttp2_settings_entry *iv, size_t niv); 3771 3772 /** 3773 * @function 3774 * 3775 * Returns string describing the |lib_error_code|. The 3776 * |lib_error_code| must be one of the :enum:`nghttp2_error`. 3777 */ 3778 NGHTTP2_EXTERN const char *nghttp2_strerror(int lib_error_code); 3779 3780 /** 3781 * @function 3782 * 3783 * Returns string representation of HTTP/2 error code |error_code| 3784 * (e.g., ``PROTOCOL_ERROR`` is returned if ``error_code == 3785 * NGHTTP2_PROTOCOL_ERROR``). If string representation is unknown for 3786 * given |error_code|, this function returns string ``unknown``. 3787 */ 3788 NGHTTP2_EXTERN const char *nghttp2_http2_strerror(uint32_t error_code); 3789 3790 /** 3791 * @function 3792 * 3793 * Initializes |pri_spec| with the |stream_id| of the stream to depend 3794 * on with |weight| and its exclusive flag. If |exclusive| is 3795 * nonzero, exclusive flag is set. 3796 * 3797 * The |weight| must be in [:macro:`NGHTTP2_MIN_WEIGHT`, 3798 * :macro:`NGHTTP2_MAX_WEIGHT`], inclusive. 3799 */ 3800 NGHTTP2_EXTERN void nghttp2_priority_spec_init(nghttp2_priority_spec *pri_spec, 3801 int32_t stream_id, 3802 int32_t weight, int exclusive); 3803 3804 /** 3805 * @function 3806 * 3807 * Initializes |pri_spec| with the default values. The default values 3808 * are: stream_id = 0, weight = :macro:`NGHTTP2_DEFAULT_WEIGHT` and 3809 * exclusive = 0. 3810 */ 3811 NGHTTP2_EXTERN void 3812 nghttp2_priority_spec_default_init(nghttp2_priority_spec *pri_spec); 3813 3814 /** 3815 * @function 3816 * 3817 * Returns nonzero if the |pri_spec| is filled with default values. 3818 */ 3819 NGHTTP2_EXTERN int 3820 nghttp2_priority_spec_check_default(const nghttp2_priority_spec *pri_spec); 3821 3822 /** 3823 * @function 3824 * 3825 * Submits HEADERS frame and optionally one or more DATA frames. 3826 * 3827 * The |pri_spec| is priority specification of this request. ``NULL`` 3828 * means the default priority (see 3829 * `nghttp2_priority_spec_default_init()`). To specify the priority, 3830 * use `nghttp2_priority_spec_init()`. If |pri_spec| is not ``NULL``, 3831 * this function will copy its data members. 3832 * 3833 * The ``pri_spec->weight`` must be in [:macro:`NGHTTP2_MIN_WEIGHT`, 3834 * :macro:`NGHTTP2_MAX_WEIGHT`], inclusive. If ``pri_spec->weight`` 3835 * is strictly less than :macro:`NGHTTP2_MIN_WEIGHT`, it becomes 3836 * :macro:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than 3837 * :macro:`NGHTTP2_MAX_WEIGHT`, it becomes 3838 * :macro:`NGHTTP2_MAX_WEIGHT`. 3839 * 3840 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with 3841 * |nvlen| elements. The application is responsible to include 3842 * required pseudo-header fields (header field whose name starts with 3843 * ":") in |nva| and must place pseudo-headers before regular header 3844 * fields. 3845 * 3846 * This function creates copies of all name/value pairs in |nva|. It 3847 * also lower-cases all names in |nva|. The order of elements in 3848 * |nva| is preserved. For header fields with 3849 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and 3850 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, 3851 * header field name and value are not copied respectively. With 3852 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application 3853 * is responsible to pass header field name in lowercase. The 3854 * application should maintain the references to them until 3855 * :type:`nghttp2_on_frame_send_callback` or 3856 * :type:`nghttp2_on_frame_not_send_callback` is called. 3857 * 3858 * HTTP/2 specification has requirement about header fields in the 3859 * request HEADERS. See the specification for more details. 3860 * 3861 * If |data_prd| is not ``NULL``, it provides data which will be sent 3862 * in subsequent DATA frames. In this case, a method that allows 3863 * request message bodies 3864 * (https://tools.ietf.org/html/rfc7231#section-4) must be specified 3865 * with ``:method`` key in |nva| (e.g. ``POST``). This function does 3866 * not take ownership of the |data_prd|. The function copies the 3867 * members of the |data_prd|. If |data_prd| is ``NULL``, HEADERS have 3868 * END_STREAM set. The |stream_user_data| is data associated to the 3869 * stream opened by this request and can be an arbitrary pointer, 3870 * which can be retrieved later by 3871 * `nghttp2_session_get_stream_user_data()`. 3872 * 3873 * This function returns assigned stream ID if it succeeds, or one of 3874 * the following negative error codes: 3875 * 3876 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3877 * Out of memory. 3878 * :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE` 3879 * No stream ID is available because maximum stream ID was 3880 * reached. 3881 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3882 * Trying to depend on itself (new stream ID equals 3883 * ``pri_spec->stream_id``). 3884 * :enum:`nghttp2_error.NGHTTP2_ERR_PROTO` 3885 * The |session| is server session. 3886 * 3887 * .. warning:: 3888 * 3889 * This function returns assigned stream ID if it succeeds. But 3890 * that stream is not created yet. The application must not submit 3891 * frame to that stream ID before 3892 * :type:`nghttp2_before_frame_send_callback` is called for this 3893 * frame. This means `nghttp2_session_get_stream_user_data()` does 3894 * not work before the callback. But 3895 * `nghttp2_session_set_stream_user_data()` handles this situation 3896 * specially, and it can set data to a stream during this period. 3897 * 3898 */ 3899 NGHTTP2_EXTERN int32_t nghttp2_submit_request( 3900 nghttp2_session *session, const nghttp2_priority_spec *pri_spec, 3901 const nghttp2_nv *nva, size_t nvlen, const nghttp2_data_provider *data_prd, 3902 void *stream_user_data); 3903 3904 /** 3905 * @function 3906 * 3907 * Submits response HEADERS frame and optionally one or more DATA 3908 * frames against the stream |stream_id|. 3909 * 3910 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with 3911 * |nvlen| elements. The application is responsible to include 3912 * required pseudo-header fields (header field whose name starts with 3913 * ":") in |nva| and must place pseudo-headers before regular header 3914 * fields. 3915 * 3916 * This function creates copies of all name/value pairs in |nva|. It 3917 * also lower-cases all names in |nva|. The order of elements in 3918 * |nva| is preserved. For header fields with 3919 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and 3920 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, 3921 * header field name and value are not copied respectively. With 3922 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application 3923 * is responsible to pass header field name in lowercase. The 3924 * application should maintain the references to them until 3925 * :type:`nghttp2_on_frame_send_callback` or 3926 * :type:`nghttp2_on_frame_not_send_callback` is called. 3927 * 3928 * HTTP/2 specification has requirement about header fields in the 3929 * response HEADERS. See the specification for more details. 3930 * 3931 * If |data_prd| is not ``NULL``, it provides data which will be sent 3932 * in subsequent DATA frames. This function does not take ownership 3933 * of the |data_prd|. The function copies the members of the 3934 * |data_prd|. If |data_prd| is ``NULL``, HEADERS will have 3935 * END_STREAM flag set. 3936 * 3937 * This method can be used as normal HTTP response and push response. 3938 * When pushing a resource using this function, the |session| must be 3939 * configured using `nghttp2_session_server_new()` or its variants and 3940 * the target stream denoted by the |stream_id| must be reserved using 3941 * `nghttp2_submit_push_promise()`. 3942 * 3943 * To send non-final response headers (e.g., HTTP status 101), don't 3944 * use this function because this function half-closes the outbound 3945 * stream. Instead, use `nghttp2_submit_headers()` for this purpose. 3946 * 3947 * This function returns 0 if it succeeds, or one of the following 3948 * negative error codes: 3949 * 3950 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 3951 * Out of memory. 3952 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 3953 * The |stream_id| is 0. 3954 * :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST` 3955 * DATA or HEADERS has been already submitted and not fully 3956 * processed yet. Normally, this does not happen, but when 3957 * application wrongly calls `nghttp2_submit_response()` twice, 3958 * this may happen. 3959 * :enum:`nghttp2_error.NGHTTP2_ERR_PROTO` 3960 * The |session| is client session. 3961 * 3962 * .. warning:: 3963 * 3964 * Calling this function twice for the same stream ID may lead to 3965 * program crash. It is generally considered to a programming error 3966 * to commit response twice. 3967 */ 3968 NGHTTP2_EXTERN int 3969 nghttp2_submit_response(nghttp2_session *session, int32_t stream_id, 3970 const nghttp2_nv *nva, size_t nvlen, 3971 const nghttp2_data_provider *data_prd); 3972 3973 /** 3974 * @function 3975 * 3976 * Submits trailer fields HEADERS against the stream |stream_id|. 3977 * 3978 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with 3979 * |nvlen| elements. The application must not include pseudo-header 3980 * fields (headers whose names starts with ":") in |nva|. 3981 * 3982 * This function creates copies of all name/value pairs in |nva|. It 3983 * also lower-cases all names in |nva|. The order of elements in 3984 * |nva| is preserved. For header fields with 3985 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and 3986 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, 3987 * header field name and value are not copied respectively. With 3988 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application 3989 * is responsible to pass header field name in lowercase. The 3990 * application should maintain the references to them until 3991 * :type:`nghttp2_on_frame_send_callback` or 3992 * :type:`nghttp2_on_frame_not_send_callback` is called. 3993 * 3994 * For server, trailer fields must follow response HEADERS or response 3995 * DATA without END_STREAM flat set. The library does not enforce 3996 * this requirement, and applications should do this for themselves. 3997 * If `nghttp2_submit_trailer()` is called before any response HEADERS 3998 * submission (usually by `nghttp2_submit_response()`), the content of 3999 * |nva| will be sent as response headers, which will result in error. 4000 * 4001 * This function has the same effect with `nghttp2_submit_headers()`, 4002 * with flags = :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` and both 4003 * pri_spec and stream_user_data to NULL. 4004 * 4005 * To submit trailer fields after `nghttp2_submit_response()` is 4006 * called, the application has to specify 4007 * :type:`nghttp2_data_provider` to `nghttp2_submit_response()`. 4008 * Inside of :type:`nghttp2_data_source_read_callback`, when setting 4009 * :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF`, also set 4010 * :enum:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_END_STREAM`. After 4011 * that, the application can send trailer fields using 4012 * `nghttp2_submit_trailer()`. `nghttp2_submit_trailer()` can be used 4013 * inside :type:`nghttp2_data_source_read_callback`. 4014 * 4015 * This function returns 0 if it succeeds and |stream_id| is -1. 4016 * Otherwise, this function returns 0 if it succeeds, or one of the 4017 * following negative error codes: 4018 * 4019 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4020 * Out of memory. 4021 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4022 * The |stream_id| is 0. 4023 */ 4024 NGHTTP2_EXTERN int nghttp2_submit_trailer(nghttp2_session *session, 4025 int32_t stream_id, 4026 const nghttp2_nv *nva, size_t nvlen); 4027 4028 /** 4029 * @function 4030 * 4031 * Submits HEADERS frame. The |flags| is bitwise OR of the 4032 * following values: 4033 * 4034 * * :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` 4035 * 4036 * If |flags| includes :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`, 4037 * this frame has END_STREAM flag set. 4038 * 4039 * The library handles the CONTINUATION frame internally and it 4040 * correctly sets END_HEADERS to the last sequence of the PUSH_PROMISE 4041 * or CONTINUATION frame. 4042 * 4043 * If the |stream_id| is -1, this frame is assumed as request (i.e., 4044 * request HEADERS frame which opens new stream). In this case, the 4045 * assigned stream ID will be returned. Otherwise, specify stream ID 4046 * in |stream_id|. 4047 * 4048 * The |pri_spec| is priority specification of this request. ``NULL`` 4049 * means the default priority (see 4050 * `nghttp2_priority_spec_default_init()`). To specify the priority, 4051 * use `nghttp2_priority_spec_init()`. If |pri_spec| is not ``NULL``, 4052 * this function will copy its data members. 4053 * 4054 * The ``pri_spec->weight`` must be in [:macro:`NGHTTP2_MIN_WEIGHT`, 4055 * :macro:`NGHTTP2_MAX_WEIGHT`], inclusive. If ``pri_spec->weight`` 4056 * is strictly less than :macro:`NGHTTP2_MIN_WEIGHT`, it becomes 4057 * :macro:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than 4058 * :macro:`NGHTTP2_MAX_WEIGHT`, it becomes :macro:`NGHTTP2_MAX_WEIGHT`. 4059 * 4060 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with 4061 * |nvlen| elements. The application is responsible to include 4062 * required pseudo-header fields (header field whose name starts with 4063 * ":") in |nva| and must place pseudo-headers before regular header 4064 * fields. 4065 * 4066 * This function creates copies of all name/value pairs in |nva|. It 4067 * also lower-cases all names in |nva|. The order of elements in 4068 * |nva| is preserved. For header fields with 4069 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and 4070 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, 4071 * header field name and value are not copied respectively. With 4072 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application 4073 * is responsible to pass header field name in lowercase. The 4074 * application should maintain the references to them until 4075 * :type:`nghttp2_on_frame_send_callback` or 4076 * :type:`nghttp2_on_frame_not_send_callback` is called. 4077 * 4078 * The |stream_user_data| is a pointer to an arbitrary data which is 4079 * associated to the stream this frame will open. Therefore it is 4080 * only used if this frame opens streams, in other words, it changes 4081 * stream state from idle or reserved to open. 4082 * 4083 * This function is low-level in a sense that the application code can 4084 * specify flags directly. For usual HTTP request, 4085 * `nghttp2_submit_request()` is useful. Likewise, for HTTP response, 4086 * prefer `nghttp2_submit_response()`. 4087 * 4088 * This function returns newly assigned stream ID if it succeeds and 4089 * |stream_id| is -1. Otherwise, this function returns 0 if it 4090 * succeeds, or one of the following negative error codes: 4091 * 4092 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4093 * Out of memory. 4094 * :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE` 4095 * No stream ID is available because maximum stream ID was 4096 * reached. 4097 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4098 * The |stream_id| is 0; or trying to depend on itself (stream ID 4099 * equals ``pri_spec->stream_id``). 4100 * :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST` 4101 * DATA or HEADERS has been already submitted and not fully 4102 * processed yet. This happens if stream denoted by |stream_id| 4103 * is in reserved state. 4104 * :enum:`nghttp2_error.NGHTTP2_ERR_PROTO` 4105 * The |stream_id| is -1, and |session| is server session. 4106 * 4107 * .. warning:: 4108 * 4109 * This function returns assigned stream ID if it succeeds and 4110 * |stream_id| is -1. But that stream is not opened yet. The 4111 * application must not submit frame to that stream ID before 4112 * :type:`nghttp2_before_frame_send_callback` is called for this 4113 * frame. 4114 * 4115 */ 4116 NGHTTP2_EXTERN int32_t nghttp2_submit_headers( 4117 nghttp2_session *session, uint8_t flags, int32_t stream_id, 4118 const nghttp2_priority_spec *pri_spec, const nghttp2_nv *nva, size_t nvlen, 4119 void *stream_user_data); 4120 4121 /** 4122 * @function 4123 * 4124 * Submits one or more DATA frames to the stream |stream_id|. The 4125 * data to be sent are provided by |data_prd|. If |flags| contains 4126 * :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`, the last DATA frame 4127 * has END_STREAM flag set. 4128 * 4129 * This function does not take ownership of the |data_prd|. The 4130 * function copies the members of the |data_prd|. 4131 * 4132 * This function returns 0 if it succeeds, or one of the following 4133 * negative error codes: 4134 * 4135 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4136 * Out of memory. 4137 * :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST` 4138 * DATA or HEADERS has been already submitted and not fully 4139 * processed yet. 4140 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4141 * The |stream_id| is 0. 4142 * :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_CLOSED` 4143 * The stream was already closed; or the |stream_id| is invalid. 4144 * 4145 * .. note:: 4146 * 4147 * Currently, only one DATA or HEADERS is allowed for a stream at a 4148 * time. Submitting these frames more than once before first DATA 4149 * or HEADERS is finished results in 4150 * :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST` error code. The 4151 * earliest callback which tells that previous frame is done is 4152 * :type:`nghttp2_on_frame_send_callback`. In side that callback, 4153 * new data can be submitted using `nghttp2_submit_data()`. Of 4154 * course, all data except for last one must not have 4155 * :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` flag set in |flags|. 4156 * This sounds a bit complicated, and we recommend to use 4157 * `nghttp2_submit_request()` and `nghttp2_submit_response()` to 4158 * avoid this cascading issue. The experience shows that for HTTP 4159 * use, these two functions are enough to implement both client and 4160 * server. 4161 */ 4162 NGHTTP2_EXTERN int nghttp2_submit_data(nghttp2_session *session, uint8_t flags, 4163 int32_t stream_id, 4164 const nghttp2_data_provider *data_prd); 4165 4166 /** 4167 * @function 4168 * 4169 * Submits PRIORITY frame to change the priority of stream |stream_id| 4170 * to the priority specification |pri_spec|. 4171 * 4172 * The |flags| is currently ignored and should be 4173 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4174 * 4175 * The |pri_spec| is priority specification of this request. ``NULL`` 4176 * is not allowed for this function. To specify the priority, use 4177 * `nghttp2_priority_spec_init()`. This function will copy its data 4178 * members. 4179 * 4180 * The ``pri_spec->weight`` must be in [:macro:`NGHTTP2_MIN_WEIGHT`, 4181 * :macro:`NGHTTP2_MAX_WEIGHT`], inclusive. If ``pri_spec->weight`` 4182 * is strictly less than :macro:`NGHTTP2_MIN_WEIGHT`, it becomes 4183 * :macro:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than 4184 * :macro:`NGHTTP2_MAX_WEIGHT`, it becomes 4185 * :macro:`NGHTTP2_MAX_WEIGHT`. 4186 * 4187 * This function returns 0 if it succeeds, or one of the following 4188 * negative error codes: 4189 * 4190 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4191 * Out of memory. 4192 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4193 * The |stream_id| is 0; or the |pri_spec| is NULL; or trying to 4194 * depend on itself. 4195 */ 4196 NGHTTP2_EXTERN int 4197 nghttp2_submit_priority(nghttp2_session *session, uint8_t flags, 4198 int32_t stream_id, 4199 const nghttp2_priority_spec *pri_spec); 4200 4201 /** 4202 * @function 4203 * 4204 * Submits RST_STREAM frame to cancel/reject the stream |stream_id| 4205 * with the error code |error_code|. 4206 * 4207 * The pre-defined error code is one of :enum:`nghttp2_error_code`. 4208 * 4209 * The |flags| is currently ignored and should be 4210 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4211 * 4212 * This function returns 0 if it succeeds, or one of the following 4213 * negative error codes: 4214 * 4215 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4216 * Out of memory. 4217 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4218 * The |stream_id| is 0. 4219 */ 4220 NGHTTP2_EXTERN int nghttp2_submit_rst_stream(nghttp2_session *session, 4221 uint8_t flags, int32_t stream_id, 4222 uint32_t error_code); 4223 4224 /** 4225 * @function 4226 * 4227 * Stores local settings and submits SETTINGS frame. The |iv| is the 4228 * pointer to the array of :type:`nghttp2_settings_entry`. The |niv| 4229 * indicates the number of :type:`nghttp2_settings_entry`. 4230 * 4231 * The |flags| is currently ignored and should be 4232 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4233 * 4234 * This function does not take ownership of the |iv|. This function 4235 * copies all the elements in the |iv|. 4236 * 4237 * While updating individual stream's local window size, if the window 4238 * size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE, 4239 * RST_STREAM is issued against such a stream. 4240 * 4241 * SETTINGS with :enum:`nghttp2_flag.NGHTTP2_FLAG_ACK` is 4242 * automatically submitted by the library and application could not 4243 * send it at its will. 4244 * 4245 * This function returns 0 if it succeeds, or one of the following 4246 * negative error codes: 4247 * 4248 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4249 * The |iv| contains invalid value (e.g., initial window size 4250 * strictly greater than (1 << 31) - 1. 4251 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4252 * Out of memory. 4253 */ 4254 NGHTTP2_EXTERN int nghttp2_submit_settings(nghttp2_session *session, 4255 uint8_t flags, 4256 const nghttp2_settings_entry *iv, 4257 size_t niv); 4258 4259 /** 4260 * @function 4261 * 4262 * Submits PUSH_PROMISE frame. 4263 * 4264 * The |flags| is currently ignored. The library handles the 4265 * CONTINUATION frame internally and it correctly sets END_HEADERS to 4266 * the last sequence of the PUSH_PROMISE or CONTINUATION frame. 4267 * 4268 * The |stream_id| must be client initiated stream ID. 4269 * 4270 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with 4271 * |nvlen| elements. The application is responsible to include 4272 * required pseudo-header fields (header field whose name starts with 4273 * ":") in |nva| and must place pseudo-headers before regular header 4274 * fields. 4275 * 4276 * This function creates copies of all name/value pairs in |nva|. It 4277 * also lower-cases all names in |nva|. The order of elements in 4278 * |nva| is preserved. For header fields with 4279 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and 4280 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, 4281 * header field name and value are not copied respectively. With 4282 * :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application 4283 * is responsible to pass header field name in lowercase. The 4284 * application should maintain the references to them until 4285 * :type:`nghttp2_on_frame_send_callback` or 4286 * :type:`nghttp2_on_frame_not_send_callback` is called. 4287 * 4288 * The |promised_stream_user_data| is a pointer to an arbitrary data 4289 * which is associated to the promised stream this frame will open and 4290 * make it in reserved state. It is available using 4291 * `nghttp2_session_get_stream_user_data()`. The application can 4292 * access it in :type:`nghttp2_before_frame_send_callback` and 4293 * :type:`nghttp2_on_frame_send_callback` of this frame. 4294 * 4295 * The client side is not allowed to use this function. 4296 * 4297 * To submit response headers and data, use 4298 * `nghttp2_submit_response()`. 4299 * 4300 * This function returns assigned promised stream ID if it succeeds, 4301 * or one of the following negative error codes: 4302 * 4303 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4304 * Out of memory. 4305 * :enum:`nghttp2_error.NGHTTP2_ERR_PROTO` 4306 * This function was invoked when |session| is initialized as 4307 * client. 4308 * :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE` 4309 * No stream ID is available because maximum stream ID was 4310 * reached. 4311 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4312 * The |stream_id| is 0; The |stream_id| does not designate stream 4313 * that peer initiated. 4314 * :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_CLOSED` 4315 * The stream was already closed; or the |stream_id| is invalid. 4316 * 4317 * .. warning:: 4318 * 4319 * This function returns assigned promised stream ID if it succeeds. 4320 * As of 1.16.0, stream object for pushed resource is created when 4321 * this function succeeds. In that case, the application can submit 4322 * push response for the promised frame. 4323 * 4324 * In 1.15.0 or prior versions, pushed stream is not opened yet when 4325 * this function succeeds. The application must not submit frame to 4326 * that stream ID before :type:`nghttp2_before_frame_send_callback` 4327 * is called for this frame. 4328 * 4329 */ 4330 NGHTTP2_EXTERN int32_t nghttp2_submit_push_promise( 4331 nghttp2_session *session, uint8_t flags, int32_t stream_id, 4332 const nghttp2_nv *nva, size_t nvlen, void *promised_stream_user_data); 4333 4334 /** 4335 * @function 4336 * 4337 * Submits PING frame. You don't have to send PING back when you 4338 * received PING frame. The library automatically submits PING frame 4339 * in this case. 4340 * 4341 * The |flags| is bitwise OR of 0 or more of the following value. 4342 * 4343 * * :enum:`nghttp2_flag.NGHTTP2_FLAG_ACK` 4344 * 4345 * Unless `nghttp2_option_set_no_auto_ping_ack()` is used, the |flags| 4346 * should be :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4347 * 4348 * If the |opaque_data| is non ``NULL``, then it should point to the 8 4349 * bytes array of memory to specify opaque data to send with PING 4350 * frame. If the |opaque_data| is ``NULL``, zero-cleared 8 bytes will 4351 * be sent as opaque data. 4352 * 4353 * This function returns 0 if it succeeds, or one of the following 4354 * negative error codes: 4355 * 4356 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4357 * Out of memory. 4358 */ 4359 NGHTTP2_EXTERN int nghttp2_submit_ping(nghttp2_session *session, uint8_t flags, 4360 const uint8_t *opaque_data); 4361 4362 /** 4363 * @function 4364 * 4365 * Submits GOAWAY frame with the last stream ID |last_stream_id| and 4366 * the error code |error_code|. 4367 * 4368 * The pre-defined error code is one of :enum:`nghttp2_error_code`. 4369 * 4370 * The |flags| is currently ignored and should be 4371 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4372 * 4373 * The |last_stream_id| is peer's stream ID or 0. So if |session| is 4374 * initialized as client, |last_stream_id| must be even or 0. If 4375 * |session| is initialized as server, |last_stream_id| must be odd or 4376 * 0. 4377 * 4378 * The HTTP/2 specification says last_stream_id must not be increased 4379 * from the value previously sent. So the actual value sent as 4380 * last_stream_id is the minimum value between the given 4381 * |last_stream_id| and the last_stream_id previously sent to the 4382 * peer. 4383 * 4384 * If the |opaque_data| is not ``NULL`` and |opaque_data_len| is not 4385 * zero, those data will be sent as additional debug data. The 4386 * library makes a copy of the memory region pointed by |opaque_data| 4387 * with the length |opaque_data_len|, so the caller does not need to 4388 * keep this memory after the return of this function. If the 4389 * |opaque_data_len| is 0, the |opaque_data| could be ``NULL``. 4390 * 4391 * After successful transmission of GOAWAY, following things happen. 4392 * All incoming streams having strictly more than |last_stream_id| are 4393 * closed. All incoming HEADERS which starts new stream are simply 4394 * ignored. After all active streams are handled, both 4395 * `nghttp2_session_want_read()` and `nghttp2_session_want_write()` 4396 * return 0 and the application can close session. 4397 * 4398 * This function returns 0 if it succeeds, or one of the following 4399 * negative error codes: 4400 * 4401 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4402 * Out of memory. 4403 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4404 * The |opaque_data_len| is too large; the |last_stream_id| is 4405 * invalid. 4406 */ 4407 NGHTTP2_EXTERN int nghttp2_submit_goaway(nghttp2_session *session, 4408 uint8_t flags, int32_t last_stream_id, 4409 uint32_t error_code, 4410 const uint8_t *opaque_data, 4411 size_t opaque_data_len); 4412 4413 /** 4414 * @function 4415 * 4416 * Returns the last stream ID of a stream for which 4417 * :type:`nghttp2_on_frame_recv_callback` was invoked most recently. 4418 * The returned value can be used as last_stream_id parameter for 4419 * `nghttp2_submit_goaway()` and 4420 * `nghttp2_session_terminate_session2()`. 4421 * 4422 * This function always succeeds. 4423 */ 4424 NGHTTP2_EXTERN int32_t 4425 nghttp2_session_get_last_proc_stream_id(nghttp2_session *session); 4426 4427 /** 4428 * @function 4429 * 4430 * Returns nonzero if new request can be sent from local endpoint. 4431 * 4432 * This function return 0 if request is not allowed for this session. 4433 * There are several reasons why request is not allowed. Some of the 4434 * reasons are: session is server; stream ID has been spent; GOAWAY 4435 * has been sent or received. 4436 * 4437 * The application can call `nghttp2_submit_request()` without 4438 * consulting this function. In that case, `nghttp2_submit_request()` 4439 * may return error. Or, request is failed to sent, and 4440 * :type:`nghttp2_on_stream_close_callback` is called. 4441 */ 4442 NGHTTP2_EXTERN int 4443 nghttp2_session_check_request_allowed(nghttp2_session *session); 4444 4445 /** 4446 * @function 4447 * 4448 * Returns nonzero if |session| is initialized as server side session. 4449 */ 4450 NGHTTP2_EXTERN int 4451 nghttp2_session_check_server_session(nghttp2_session *session); 4452 4453 /** 4454 * @function 4455 * 4456 * Submits WINDOW_UPDATE frame. 4457 * 4458 * The |flags| is currently ignored and should be 4459 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4460 * 4461 * The |stream_id| is the stream ID to send this WINDOW_UPDATE. To 4462 * send connection level WINDOW_UPDATE, specify 0 to |stream_id|. 4463 * 4464 * If the |window_size_increment| is positive, the WINDOW_UPDATE with 4465 * that value as window_size_increment is queued. If the 4466 * |window_size_increment| is larger than the received bytes from the 4467 * remote endpoint, the local window size is increased by that 4468 * difference. If the sole purpose is to increase the local window 4469 * size, consider to use `nghttp2_session_set_local_window_size()`. 4470 * 4471 * If the |window_size_increment| is negative, the local window size 4472 * is decreased by -|window_size_increment|. If automatic 4473 * WINDOW_UPDATE is enabled 4474 * (`nghttp2_option_set_no_auto_window_update()`), and the library 4475 * decided that the WINDOW_UPDATE should be submitted, then 4476 * WINDOW_UPDATE is queued with the current received bytes count. If 4477 * the sole purpose is to decrease the local window size, consider to 4478 * use `nghttp2_session_set_local_window_size()`. 4479 * 4480 * If the |window_size_increment| is 0, the function does nothing and 4481 * returns 0. 4482 * 4483 * This function returns 0 if it succeeds, or one of the following 4484 * negative error codes: 4485 * 4486 * :enum:`nghttp2_error.NGHTTP2_ERR_FLOW_CONTROL` 4487 * The local window size overflow or gets negative. 4488 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4489 * Out of memory. 4490 */ 4491 NGHTTP2_EXTERN int nghttp2_submit_window_update(nghttp2_session *session, 4492 uint8_t flags, 4493 int32_t stream_id, 4494 int32_t window_size_increment); 4495 4496 /** 4497 * @function 4498 * 4499 * Set local window size (local endpoints's window size) to the given 4500 * |window_size| for the given stream denoted by |stream_id|. To 4501 * change connection level window size, specify 0 to |stream_id|. To 4502 * increase window size, this function may submit WINDOW_UPDATE frame 4503 * to transmission queue. 4504 * 4505 * The |flags| is currently ignored and should be 4506 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4507 * 4508 * This sounds similar to `nghttp2_submit_window_update()`, but there 4509 * are 2 differences. The first difference is that this function 4510 * takes the absolute value of window size to set, rather than the 4511 * delta. To change the window size, this may be easier to use since 4512 * the application just declares the intended window size, rather than 4513 * calculating delta. The second difference is that 4514 * `nghttp2_submit_window_update()` affects the received bytes count 4515 * which has not acked yet. By the specification of 4516 * `nghttp2_submit_window_update()`, to strictly increase the local 4517 * window size, we have to submit delta including all received bytes 4518 * count, which might not be desirable in some cases. On the other 4519 * hand, this function does not affect the received bytes count. It 4520 * just sets the local window size to the given value. 4521 * 4522 * This function returns 0 if it succeeds, or one of the following 4523 * negative error codes: 4524 * 4525 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4526 * The |stream_id| is negative. 4527 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4528 * Out of memory. 4529 */ 4530 NGHTTP2_EXTERN int 4531 nghttp2_session_set_local_window_size(nghttp2_session *session, uint8_t flags, 4532 int32_t stream_id, int32_t window_size); 4533 4534 /** 4535 * @function 4536 * 4537 * Submits extension frame. 4538 * 4539 * Application can pass arbitrary frame flags and stream ID in |flags| 4540 * and |stream_id| respectively. The |payload| is opaque pointer, and 4541 * it can be accessible though ``frame->ext.payload`` in 4542 * :type:`nghttp2_pack_extension_callback`. The library will not own 4543 * passed |payload| pointer. 4544 * 4545 * The application must set :type:`nghttp2_pack_extension_callback` 4546 * using `nghttp2_session_callbacks_set_pack_extension_callback()`. 4547 * 4548 * The application should retain the memory pointed by |payload| until 4549 * the transmission of extension frame is done (which is indicated by 4550 * :type:`nghttp2_on_frame_send_callback`), or transmission fails 4551 * (which is indicated by :type:`nghttp2_on_frame_not_send_callback`). 4552 * If application does not touch this memory region after packing it 4553 * into a wire format, application can free it inside 4554 * :type:`nghttp2_pack_extension_callback`. 4555 * 4556 * The standard HTTP/2 frame cannot be sent with this function, so 4557 * |type| must be strictly grater than 0x9. Otherwise, this function 4558 * will fail with error code 4559 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`. 4560 * 4561 * This function returns 0 if it succeeds, or one of the following 4562 * negative error codes: 4563 * 4564 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` 4565 * If :type:`nghttp2_pack_extension_callback` is not set. 4566 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4567 * If |type| specifies standard HTTP/2 frame type. The frame 4568 * types in the rage [0x0, 0x9], both inclusive, are standard 4569 * HTTP/2 frame type, and cannot be sent using this function. 4570 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4571 * Out of memory 4572 */ 4573 NGHTTP2_EXTERN int nghttp2_submit_extension(nghttp2_session *session, 4574 uint8_t type, uint8_t flags, 4575 int32_t stream_id, void *payload); 4576 4577 /** 4578 * @struct 4579 * 4580 * The payload of ALTSVC frame. ALTSVC frame is a non-critical 4581 * extension to HTTP/2. If this frame is received, and 4582 * `nghttp2_option_set_user_recv_extension_type()` is not set, and 4583 * `nghttp2_option_set_builtin_recv_extension_type()` is set for 4584 * :enum:`nghttp2_frame_type.NGHTTP2_ALTSVC`, 4585 * ``nghttp2_extension.payload`` will point to this struct. 4586 * 4587 * It has the following members: 4588 */ 4589 typedef struct { 4590 /** 4591 * The pointer to origin which this alternative service is 4592 * associated with. This is not necessarily NULL-terminated. 4593 */ 4594 uint8_t *origin; 4595 /** 4596 * The length of the |origin|. 4597 */ 4598 size_t origin_len; 4599 /** 4600 * The pointer to Alt-Svc field value contained in ALTSVC frame. 4601 * This is not necessarily NULL-terminated. 4602 */ 4603 uint8_t *field_value; 4604 /** 4605 * The length of the |field_value|. 4606 */ 4607 size_t field_value_len; 4608 } nghttp2_ext_altsvc; 4609 4610 /** 4611 * @function 4612 * 4613 * Submits ALTSVC frame. 4614 * 4615 * ALTSVC frame is a non-critical extension to HTTP/2, and defined in 4616 * `RFC 7383 <https://tools.ietf.org/html/rfc7838#section-4>`_. 4617 * 4618 * The |flags| is currently ignored and should be 4619 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4620 * 4621 * The |origin| points to the origin this alternative service is 4622 * associated with. The |origin_len| is the length of the origin. If 4623 * |stream_id| is 0, the origin must be specified. If |stream_id| is 4624 * not zero, the origin must be empty (in other words, |origin_len| 4625 * must be 0). 4626 * 4627 * The ALTSVC frame is only usable from server side. If this function 4628 * is invoked with client side session, this function returns 4629 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`. 4630 * 4631 * This function returns 0 if it succeeds, or one of the following 4632 * negative error codes: 4633 * 4634 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4635 * Out of memory 4636 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` 4637 * The function is called from client side session 4638 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4639 * The sum of |origin_len| and |field_value_len| is larger than 4640 * 16382; or |origin_len| is 0 while |stream_id| is 0; or 4641 * |origin_len| is not 0 while |stream_id| is not 0. 4642 */ 4643 NGHTTP2_EXTERN int nghttp2_submit_altsvc(nghttp2_session *session, 4644 uint8_t flags, int32_t stream_id, 4645 const uint8_t *origin, 4646 size_t origin_len, 4647 const uint8_t *field_value, 4648 size_t field_value_len); 4649 4650 /** 4651 * @struct 4652 * 4653 * The single entry of an origin. 4654 */ 4655 typedef struct { 4656 /** 4657 * The pointer to origin. No validation is made against this field 4658 * by the library. This is not necessarily NULL-terminated. 4659 */ 4660 uint8_t *origin; 4661 /** 4662 * The length of the |origin|. 4663 */ 4664 size_t origin_len; 4665 } nghttp2_origin_entry; 4666 4667 /** 4668 * @struct 4669 * 4670 * The payload of ORIGIN frame. ORIGIN frame is a non-critical 4671 * extension to HTTP/2 and defined by `RFC 8336 4672 * <https://tools.ietf.org/html/rfc8336>`_. 4673 * 4674 * If this frame is received, and 4675 * `nghttp2_option_set_user_recv_extension_type()` is not set, and 4676 * `nghttp2_option_set_builtin_recv_extension_type()` is set for 4677 * :enum:`nghttp2_frame_type.NGHTTP2_ORIGIN`, 4678 * ``nghttp2_extension.payload`` will point to this struct. 4679 * 4680 * It has the following members: 4681 */ 4682 typedef struct { 4683 /** 4684 * The number of origins contained in |ov|. 4685 */ 4686 size_t nov; 4687 /** 4688 * The pointer to the array of origins contained in ORIGIN frame. 4689 */ 4690 nghttp2_origin_entry *ov; 4691 } nghttp2_ext_origin; 4692 4693 /** 4694 * @function 4695 * 4696 * Submits ORIGIN frame. 4697 * 4698 * ORIGIN frame is a non-critical extension to HTTP/2 and defined by 4699 * `RFC 8336 <https://tools.ietf.org/html/rfc8336>`_. 4700 * 4701 * The |flags| is currently ignored and should be 4702 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`. 4703 * 4704 * The |ov| points to the array of origins. The |nov| specifies the 4705 * number of origins included in |ov|. This function creates copies 4706 * of all elements in |ov|. 4707 * 4708 * The ORIGIN frame is only usable by a server. If this function is 4709 * invoked with client side session, this function returns 4710 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`. 4711 * 4712 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4713 * Out of memory 4714 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` 4715 * The function is called from client side session. 4716 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 4717 * There are too many origins, or an origin is too large to fit 4718 * into a default frame payload. 4719 */ 4720 NGHTTP2_EXTERN int nghttp2_submit_origin(nghttp2_session *session, 4721 uint8_t flags, 4722 const nghttp2_origin_entry *ov, 4723 size_t nov); 4724 4725 /** 4726 * @function 4727 * 4728 * Compares ``lhs->name`` of length ``lhs->namelen`` bytes and 4729 * ``rhs->name`` of length ``rhs->namelen`` bytes. Returns negative 4730 * integer if ``lhs->name`` is found to be less than ``rhs->name``; or 4731 * returns positive integer if ``lhs->name`` is found to be greater 4732 * than ``rhs->name``; or returns 0 otherwise. 4733 */ 4734 NGHTTP2_EXTERN int nghttp2_nv_compare_name(const nghttp2_nv *lhs, 4735 const nghttp2_nv *rhs); 4736 4737 /** 4738 * @function 4739 * 4740 * A helper function for dealing with NPN in client side or ALPN in 4741 * server side. The |in| contains peer's protocol list in preferable 4742 * order. The format of |in| is length-prefixed and not 4743 * null-terminated. For example, ``h2`` and 4744 * ``http/1.1`` stored in |in| like this:: 4745 * 4746 * in[0] = 2 4747 * in[1..2] = "h2" 4748 * in[3] = 8 4749 * in[4..11] = "http/1.1" 4750 * inlen = 12 4751 * 4752 * The selection algorithm is as follows: 4753 * 4754 * 1. If peer's list contains HTTP/2 protocol the library supports, 4755 * it is selected and returns 1. The following step is not taken. 4756 * 4757 * 2. If peer's list contains ``http/1.1``, this function selects 4758 * ``http/1.1`` and returns 0. The following step is not taken. 4759 * 4760 * 3. This function selects nothing and returns -1 (So called 4761 * non-overlap case). In this case, |out| and |outlen| are left 4762 * untouched. 4763 * 4764 * Selecting ``h2`` means that ``h2`` is written into |*out| and its 4765 * length (which is 2) is assigned to |*outlen|. 4766 * 4767 * For ALPN, refer to https://tools.ietf.org/html/rfc7301 4768 * 4769 * See http://technotes.googlecode.com/git/nextprotoneg.html for more 4770 * details about NPN. 4771 * 4772 * For NPN, to use this method you should do something like:: 4773 * 4774 * static int select_next_proto_cb(SSL* ssl, 4775 * unsigned char **out, 4776 * unsigned char *outlen, 4777 * const unsigned char *in, 4778 * unsigned int inlen, 4779 * void *arg) 4780 * { 4781 * int rv; 4782 * rv = nghttp2_select_next_protocol(out, outlen, in, inlen); 4783 * if (rv == -1) { 4784 * return SSL_TLSEXT_ERR_NOACK; 4785 * } 4786 * if (rv == 1) { 4787 * ((MyType*)arg)->http2_selected = 1; 4788 * } 4789 * return SSL_TLSEXT_ERR_OK; 4790 * } 4791 * ... 4792 * SSL_CTX_set_next_proto_select_cb(ssl_ctx, select_next_proto_cb, my_obj); 4793 * 4794 */ 4795 NGHTTP2_EXTERN int nghttp2_select_next_protocol(unsigned char **out, 4796 unsigned char *outlen, 4797 const unsigned char *in, 4798 unsigned int inlen); 4799 4800 /** 4801 * @function 4802 * 4803 * Returns a pointer to a nghttp2_info struct with version information 4804 * about the run-time library in use. The |least_version| argument 4805 * can be set to a 24 bit numerical value for the least accepted 4806 * version number and if the condition is not met, this function will 4807 * return a ``NULL``. Pass in 0 to skip the version checking. 4808 */ 4809 NGHTTP2_EXTERN nghttp2_info *nghttp2_version(int least_version); 4810 4811 /** 4812 * @function 4813 * 4814 * Returns nonzero if the :type:`nghttp2_error` library error code 4815 * |lib_error| is fatal. 4816 */ 4817 NGHTTP2_EXTERN int nghttp2_is_fatal(int lib_error_code); 4818 4819 /** 4820 * @function 4821 * 4822 * Returns nonzero if HTTP header field name |name| of length |len| is 4823 * valid according to http://tools.ietf.org/html/rfc7230#section-3.2 4824 * 4825 * Because this is a header field name in HTTP2, the upper cased alphabet 4826 * is treated as error. 4827 */ 4828 NGHTTP2_EXTERN int nghttp2_check_header_name(const uint8_t *name, size_t len); 4829 4830 /** 4831 * @function 4832 * 4833 * Returns nonzero if HTTP header field value |value| of length |len| 4834 * is valid according to 4835 * http://tools.ietf.org/html/rfc7230#section-3.2 4836 */ 4837 NGHTTP2_EXTERN int nghttp2_check_header_value(const uint8_t *value, size_t len); 4838 4839 /** 4840 * @function 4841 * 4842 * Returns nonzero if the |value| which is supposed to be the value of 4843 * the :method header field is valid according to 4844 * https://datatracker.ietf.org/doc/html/rfc7231#section-4 and 4845 * https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6 4846 */ 4847 NGHTTP2_EXTERN int nghttp2_check_method(const uint8_t *value, size_t len); 4848 4849 /** 4850 * @function 4851 * 4852 * Returns nonzero if the |value| which is supposed to be the value of 4853 * the :path header field is valid according to 4854 * https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2.3 4855 * 4856 * |value| is valid if it merely consists of the allowed characters. 4857 * In particular, it does not check whether |value| follows the syntax 4858 * of path. The allowed characters are all characters valid by 4859 * `nghttp2_check_header_value` minus SPC and HT. 4860 */ 4861 NGHTTP2_EXTERN int nghttp2_check_path(const uint8_t *value, size_t len); 4862 4863 /** 4864 * @function 4865 * 4866 * Returns nonzero if the |value| which is supposed to be the value of the 4867 * :authority or host header field is valid according to 4868 * https://tools.ietf.org/html/rfc3986#section-3.2 4869 * 4870 * |value| is valid if it merely consists of the allowed characters. 4871 * In particular, it does not check whether |value| follows the syntax 4872 * of authority. 4873 */ 4874 NGHTTP2_EXTERN int nghttp2_check_authority(const uint8_t *value, size_t len); 4875 4876 /* HPACK API */ 4877 4878 struct nghttp2_hd_deflater; 4879 4880 /** 4881 * @struct 4882 * 4883 * HPACK deflater object. 4884 */ 4885 typedef struct nghttp2_hd_deflater nghttp2_hd_deflater; 4886 4887 /** 4888 * @function 4889 * 4890 * Initializes |*deflater_ptr| for deflating name/values pairs. 4891 * 4892 * The |max_deflate_dynamic_table_size| is the upper bound of header 4893 * table size the deflater will use. 4894 * 4895 * If this function fails, |*deflater_ptr| is left untouched. 4896 * 4897 * This function returns 0 if it succeeds, or one of the following 4898 * negative error codes: 4899 * 4900 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4901 * Out of memory. 4902 */ 4903 NGHTTP2_EXTERN int 4904 nghttp2_hd_deflate_new(nghttp2_hd_deflater **deflater_ptr, 4905 size_t max_deflate_dynamic_table_size); 4906 4907 /** 4908 * @function 4909 * 4910 * Like `nghttp2_hd_deflate_new()`, but with additional custom memory 4911 * allocator specified in the |mem|. 4912 * 4913 * The |mem| can be ``NULL`` and the call is equivalent to 4914 * `nghttp2_hd_deflate_new()`. 4915 * 4916 * This function does not take ownership |mem|. The application is 4917 * responsible for freeing |mem|. 4918 * 4919 * The library code does not refer to |mem| pointer after this 4920 * function returns, so the application can safely free it. 4921 */ 4922 NGHTTP2_EXTERN int 4923 nghttp2_hd_deflate_new2(nghttp2_hd_deflater **deflater_ptr, 4924 size_t max_deflate_dynamic_table_size, 4925 nghttp2_mem *mem); 4926 4927 /** 4928 * @function 4929 * 4930 * Deallocates any resources allocated for |deflater|. 4931 */ 4932 NGHTTP2_EXTERN void nghttp2_hd_deflate_del(nghttp2_hd_deflater *deflater); 4933 4934 /** 4935 * @function 4936 * 4937 * Changes header table size of the |deflater| to 4938 * |settings_max_dynamic_table_size| bytes. This may trigger eviction 4939 * in the dynamic table. 4940 * 4941 * The |settings_max_dynamic_table_size| should be the value received 4942 * in SETTINGS_HEADER_TABLE_SIZE. 4943 * 4944 * The deflater never uses more memory than 4945 * ``max_deflate_dynamic_table_size`` bytes specified in 4946 * `nghttp2_hd_deflate_new()`. Therefore, if 4947 * |settings_max_dynamic_table_size| > 4948 * ``max_deflate_dynamic_table_size``, resulting maximum table size 4949 * becomes ``max_deflate_dynamic_table_size``. 4950 * 4951 * This function returns 0 if it succeeds, or one of the following 4952 * negative error codes: 4953 * 4954 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4955 * Out of memory. 4956 */ 4957 NGHTTP2_EXTERN int 4958 nghttp2_hd_deflate_change_table_size(nghttp2_hd_deflater *deflater, 4959 size_t settings_max_dynamic_table_size); 4960 4961 /** 4962 * @function 4963 * 4964 * Deflates the |nva|, which has the |nvlen| name/value pairs, into 4965 * the |buf| of length |buflen|. 4966 * 4967 * If |buf| is not large enough to store the deflated header block, 4968 * this function fails with 4969 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`. The caller 4970 * should use `nghttp2_hd_deflate_bound()` to know the upper bound of 4971 * buffer size required to deflate given header name/value pairs. 4972 * 4973 * Once this function fails, subsequent call of this function always 4974 * returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`. 4975 * 4976 * After this function returns, it is safe to delete the |nva|. 4977 * 4978 * This function returns the number of bytes written to |buf| if it 4979 * succeeds, or one of the following negative error codes: 4980 * 4981 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 4982 * Out of memory. 4983 * :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP` 4984 * Deflation process has failed. 4985 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE` 4986 * The provided |buflen| size is too small to hold the output. 4987 */ 4988 NGHTTP2_EXTERN ssize_t nghttp2_hd_deflate_hd(nghttp2_hd_deflater *deflater, 4989 uint8_t *buf, size_t buflen, 4990 const nghttp2_nv *nva, 4991 size_t nvlen); 4992 4993 /** 4994 * @function 4995 * 4996 * Deflates the |nva|, which has the |nvlen| name/value pairs, into 4997 * the |veclen| size of buf vector |vec|. The each size of buffer 4998 * must be set in len field of :type:`nghttp2_vec`. If and only if 4999 * one chunk is filled up completely, next chunk will be used. If 5000 * |vec| is not large enough to store the deflated header block, this 5001 * function fails with 5002 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`. The caller 5003 * should use `nghttp2_hd_deflate_bound()` to know the upper bound of 5004 * buffer size required to deflate given header name/value pairs. 5005 * 5006 * Once this function fails, subsequent call of this function always 5007 * returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`. 5008 * 5009 * After this function returns, it is safe to delete the |nva|. 5010 * 5011 * This function returns the number of bytes written to |vec| if it 5012 * succeeds, or one of the following negative error codes: 5013 * 5014 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 5015 * Out of memory. 5016 * :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP` 5017 * Deflation process has failed. 5018 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE` 5019 * The provided |buflen| size is too small to hold the output. 5020 */ 5021 NGHTTP2_EXTERN ssize_t nghttp2_hd_deflate_hd_vec(nghttp2_hd_deflater *deflater, 5022 const nghttp2_vec *vec, 5023 size_t veclen, 5024 const nghttp2_nv *nva, 5025 size_t nvlen); 5026 5027 /** 5028 * @function 5029 * 5030 * Returns an upper bound on the compressed size after deflation of 5031 * |nva| of length |nvlen|. 5032 */ 5033 NGHTTP2_EXTERN size_t nghttp2_hd_deflate_bound(nghttp2_hd_deflater *deflater, 5034 const nghttp2_nv *nva, 5035 size_t nvlen); 5036 5037 /** 5038 * @function 5039 * 5040 * Returns the number of entries that header table of |deflater| 5041 * contains. This is the sum of the number of static table and 5042 * dynamic table, so the return value is at least 61. 5043 */ 5044 NGHTTP2_EXTERN 5045 size_t nghttp2_hd_deflate_get_num_table_entries(nghttp2_hd_deflater *deflater); 5046 5047 /** 5048 * @function 5049 * 5050 * Returns the table entry denoted by |idx| from header table of 5051 * |deflater|. The |idx| is 1-based, and idx=1 returns first entry of 5052 * static table. idx=62 returns first entry of dynamic table if it 5053 * exists. Specifying idx=0 is error, and this function returns NULL. 5054 * If |idx| is strictly greater than the number of entries the tables 5055 * contain, this function returns NULL. 5056 */ 5057 NGHTTP2_EXTERN 5058 const nghttp2_nv * 5059 nghttp2_hd_deflate_get_table_entry(nghttp2_hd_deflater *deflater, size_t idx); 5060 5061 /** 5062 * @function 5063 * 5064 * Returns the used dynamic table size, including the overhead 32 5065 * bytes per entry described in RFC 7541. 5066 */ 5067 NGHTTP2_EXTERN 5068 size_t nghttp2_hd_deflate_get_dynamic_table_size(nghttp2_hd_deflater *deflater); 5069 5070 /** 5071 * @function 5072 * 5073 * Returns the maximum dynamic table size. 5074 */ 5075 NGHTTP2_EXTERN 5076 size_t 5077 nghttp2_hd_deflate_get_max_dynamic_table_size(nghttp2_hd_deflater *deflater); 5078 5079 struct nghttp2_hd_inflater; 5080 5081 /** 5082 * @struct 5083 * 5084 * HPACK inflater object. 5085 */ 5086 typedef struct nghttp2_hd_inflater nghttp2_hd_inflater; 5087 5088 /** 5089 * @function 5090 * 5091 * Initializes |*inflater_ptr| for inflating name/values pairs. 5092 * 5093 * If this function fails, |*inflater_ptr| is left untouched. 5094 * 5095 * This function returns 0 if it succeeds, or one of the following 5096 * negative error codes: 5097 * 5098 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 5099 * Out of memory. 5100 */ 5101 NGHTTP2_EXTERN int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr); 5102 5103 /** 5104 * @function 5105 * 5106 * Like `nghttp2_hd_inflate_new()`, but with additional custom memory 5107 * allocator specified in the |mem|. 5108 * 5109 * The |mem| can be ``NULL`` and the call is equivalent to 5110 * `nghttp2_hd_inflate_new()`. 5111 * 5112 * This function does not take ownership |mem|. The application is 5113 * responsible for freeing |mem|. 5114 * 5115 * The library code does not refer to |mem| pointer after this 5116 * function returns, so the application can safely free it. 5117 */ 5118 NGHTTP2_EXTERN int nghttp2_hd_inflate_new2(nghttp2_hd_inflater **inflater_ptr, 5119 nghttp2_mem *mem); 5120 5121 /** 5122 * @function 5123 * 5124 * Deallocates any resources allocated for |inflater|. 5125 */ 5126 NGHTTP2_EXTERN void nghttp2_hd_inflate_del(nghttp2_hd_inflater *inflater); 5127 5128 /** 5129 * @function 5130 * 5131 * Changes header table size in the |inflater|. This may trigger 5132 * eviction in the dynamic table. 5133 * 5134 * The |settings_max_dynamic_table_size| should be the value 5135 * transmitted in SETTINGS_HEADER_TABLE_SIZE. 5136 * 5137 * This function must not be called while header block is being 5138 * inflated. In other words, this function must be called after 5139 * initialization of |inflater|, but before calling 5140 * `nghttp2_hd_inflate_hd2()`, or after 5141 * `nghttp2_hd_inflate_end_headers()`. Otherwise, 5142 * `NGHTTP2_ERR_INVALID_STATE` was returned. 5143 * 5144 * This function returns 0 if it succeeds, or one of the following 5145 * negative error codes: 5146 * 5147 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 5148 * Out of memory. 5149 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE` 5150 * The function is called while header block is being inflated. 5151 * Probably, application missed to call 5152 * `nghttp2_hd_inflate_end_headers()`. 5153 */ 5154 NGHTTP2_EXTERN int 5155 nghttp2_hd_inflate_change_table_size(nghttp2_hd_inflater *inflater, 5156 size_t settings_max_dynamic_table_size); 5157 5158 /** 5159 * @enum 5160 * 5161 * The flags for header inflation. 5162 */ 5163 typedef enum { 5164 /** 5165 * No flag set. 5166 */ 5167 NGHTTP2_HD_INFLATE_NONE = 0, 5168 /** 5169 * Indicates all headers were inflated. 5170 */ 5171 NGHTTP2_HD_INFLATE_FINAL = 0x01, 5172 /** 5173 * Indicates a header was emitted. 5174 */ 5175 NGHTTP2_HD_INFLATE_EMIT = 0x02 5176 } nghttp2_hd_inflate_flag; 5177 5178 /** 5179 * @function 5180 * 5181 * .. warning:: 5182 * 5183 * Deprecated. Use `nghttp2_hd_inflate_hd2()` instead. 5184 * 5185 * Inflates name/value block stored in |in| with length |inlen|. This 5186 * function performs decompression. For each successful emission of 5187 * header name/value pair, 5188 * :enum:`nghttp2_hd_inflate_flag.NGHTTP2_HD_INFLATE_EMIT` is set in 5189 * |*inflate_flags| and name/value pair is assigned to the |nv_out| 5190 * and the function returns. The caller must not free the members of 5191 * |nv_out|. 5192 * 5193 * The |nv_out| may include pointers to the memory region in the |in|. 5194 * The caller must retain the |in| while the |nv_out| is used. 5195 * 5196 * The application should call this function repeatedly until the 5197 * ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and 5198 * return value is non-negative. This means the all input values are 5199 * processed successfully. Then the application must call 5200 * `nghttp2_hd_inflate_end_headers()` to prepare for the next header 5201 * block input. 5202 * 5203 * The caller can feed complete compressed header block. It also can 5204 * feed it in several chunks. The caller must set |in_final| to 5205 * nonzero if the given input is the last block of the compressed 5206 * header. 5207 * 5208 * This function returns the number of bytes processed if it succeeds, 5209 * or one of the following negative error codes: 5210 * 5211 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 5212 * Out of memory. 5213 * :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP` 5214 * Inflation process has failed. 5215 * :enum:`nghttp2_error.NGHTTP2_ERR_BUFFER_ERROR` 5216 * The header field name or value is too large. 5217 * 5218 * Example follows:: 5219 * 5220 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater, 5221 * uint8_t *in, size_t inlen, int final) 5222 * { 5223 * ssize_t rv; 5224 * 5225 * for(;;) { 5226 * nghttp2_nv nv; 5227 * int inflate_flags = 0; 5228 * 5229 * rv = nghttp2_hd_inflate_hd(hd_inflater, &nv, &inflate_flags, 5230 * in, inlen, final); 5231 * 5232 * if(rv < 0) { 5233 * fprintf(stderr, "inflate failed with error code %zd", rv); 5234 * return -1; 5235 * } 5236 * 5237 * in += rv; 5238 * inlen -= rv; 5239 * 5240 * if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) { 5241 * fwrite(nv.name, nv.namelen, 1, stderr); 5242 * fprintf(stderr, ": "); 5243 * fwrite(nv.value, nv.valuelen, 1, stderr); 5244 * fprintf(stderr, "\n"); 5245 * } 5246 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) { 5247 * nghttp2_hd_inflate_end_headers(hd_inflater); 5248 * break; 5249 * } 5250 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 && 5251 * inlen == 0) { 5252 * break; 5253 * } 5254 * } 5255 * 5256 * return 0; 5257 * } 5258 * 5259 */ 5260 NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd(nghttp2_hd_inflater *inflater, 5261 nghttp2_nv *nv_out, 5262 int *inflate_flags, uint8_t *in, 5263 size_t inlen, int in_final); 5264 5265 /** 5266 * @function 5267 * 5268 * Inflates name/value block stored in |in| with length |inlen|. This 5269 * function performs decompression. For each successful emission of 5270 * header name/value pair, 5271 * :enum:`nghttp2_hd_inflate_flag.NGHTTP2_HD_INFLATE_EMIT` is set in 5272 * |*inflate_flags| and name/value pair is assigned to the |nv_out| 5273 * and the function returns. The caller must not free the members of 5274 * |nv_out|. 5275 * 5276 * The |nv_out| may include pointers to the memory region in the |in|. 5277 * The caller must retain the |in| while the |nv_out| is used. 5278 * 5279 * The application should call this function repeatedly until the 5280 * ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and 5281 * return value is non-negative. If that happens, all given input 5282 * data (|inlen| bytes) are processed successfully. Then the 5283 * application must call `nghttp2_hd_inflate_end_headers()` to prepare 5284 * for the next header block input. 5285 * 5286 * In other words, if |in_final| is nonzero, and this function returns 5287 * |inlen|, you can assert that 5288 * :enum:`nghttp2_hd_inflate_final.NGHTTP2_HD_INFLATE_FINAL` is set in 5289 * |*inflate_flags|. 5290 * 5291 * The caller can feed complete compressed header block. It also can 5292 * feed it in several chunks. The caller must set |in_final| to 5293 * nonzero if the given input is the last block of the compressed 5294 * header. 5295 * 5296 * This function returns the number of bytes processed if it succeeds, 5297 * or one of the following negative error codes: 5298 * 5299 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM` 5300 * Out of memory. 5301 * :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP` 5302 * Inflation process has failed. 5303 * :enum:`nghttp2_error.NGHTTP2_ERR_BUFFER_ERROR` 5304 * The header field name or value is too large. 5305 * 5306 * Example follows:: 5307 * 5308 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater, 5309 * uint8_t *in, size_t inlen, int final) 5310 * { 5311 * ssize_t rv; 5312 * 5313 * for(;;) { 5314 * nghttp2_nv nv; 5315 * int inflate_flags = 0; 5316 * 5317 * rv = nghttp2_hd_inflate_hd2(hd_inflater, &nv, &inflate_flags, 5318 * in, inlen, final); 5319 * 5320 * if(rv < 0) { 5321 * fprintf(stderr, "inflate failed with error code %zd", rv); 5322 * return -1; 5323 * } 5324 * 5325 * in += rv; 5326 * inlen -= rv; 5327 * 5328 * if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) { 5329 * fwrite(nv.name, nv.namelen, 1, stderr); 5330 * fprintf(stderr, ": "); 5331 * fwrite(nv.value, nv.valuelen, 1, stderr); 5332 * fprintf(stderr, "\n"); 5333 * } 5334 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) { 5335 * nghttp2_hd_inflate_end_headers(hd_inflater); 5336 * break; 5337 * } 5338 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 && 5339 * inlen == 0) { 5340 * break; 5341 * } 5342 * } 5343 * 5344 * return 0; 5345 * } 5346 * 5347 */ 5348 NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd2(nghttp2_hd_inflater *inflater, 5349 nghttp2_nv *nv_out, 5350 int *inflate_flags, 5351 const uint8_t *in, size_t inlen, 5352 int in_final); 5353 5354 /** 5355 * @function 5356 * 5357 * Signals the end of decompression for one header block. 5358 * 5359 * This function returns 0 if it succeeds. Currently this function 5360 * always succeeds. 5361 */ 5362 NGHTTP2_EXTERN int 5363 nghttp2_hd_inflate_end_headers(nghttp2_hd_inflater *inflater); 5364 5365 /** 5366 * @function 5367 * 5368 * Returns the number of entries that header table of |inflater| 5369 * contains. This is the sum of the number of static table and 5370 * dynamic table, so the return value is at least 61. 5371 */ 5372 NGHTTP2_EXTERN 5373 size_t nghttp2_hd_inflate_get_num_table_entries(nghttp2_hd_inflater *inflater); 5374 5375 /** 5376 * @function 5377 * 5378 * Returns the table entry denoted by |idx| from header table of 5379 * |inflater|. The |idx| is 1-based, and idx=1 returns first entry of 5380 * static table. idx=62 returns first entry of dynamic table if it 5381 * exists. Specifying idx=0 is error, and this function returns NULL. 5382 * If |idx| is strictly greater than the number of entries the tables 5383 * contain, this function returns NULL. 5384 */ 5385 NGHTTP2_EXTERN 5386 const nghttp2_nv * 5387 nghttp2_hd_inflate_get_table_entry(nghttp2_hd_inflater *inflater, size_t idx); 5388 5389 /** 5390 * @function 5391 * 5392 * Returns the used dynamic table size, including the overhead 32 5393 * bytes per entry described in RFC 7541. 5394 */ 5395 NGHTTP2_EXTERN 5396 size_t nghttp2_hd_inflate_get_dynamic_table_size(nghttp2_hd_inflater *inflater); 5397 5398 /** 5399 * @function 5400 * 5401 * Returns the maximum dynamic table size. 5402 */ 5403 NGHTTP2_EXTERN 5404 size_t 5405 nghttp2_hd_inflate_get_max_dynamic_table_size(nghttp2_hd_inflater *inflater); 5406 5407 struct nghttp2_stream; 5408 5409 /** 5410 * @struct 5411 * 5412 * The structure to represent HTTP/2 stream. The details of this 5413 * structure are intentionally hidden from the public API. 5414 */ 5415 typedef struct nghttp2_stream nghttp2_stream; 5416 5417 /** 5418 * @function 5419 * 5420 * Returns pointer to :type:`nghttp2_stream` object denoted by 5421 * |stream_id|. If stream was not found, returns NULL. 5422 * 5423 * Returns imaginary root stream (see 5424 * `nghttp2_session_get_root_stream()`) if 0 is given in |stream_id|. 5425 * 5426 * Unless |stream_id| == 0, the returned pointer is valid until next 5427 * call of `nghttp2_session_send()`, `nghttp2_session_mem_send()`, 5428 * `nghttp2_session_recv()`, and `nghttp2_session_mem_recv()`. 5429 */ 5430 NGHTTP2_EXTERN nghttp2_stream * 5431 nghttp2_session_find_stream(nghttp2_session *session, int32_t stream_id); 5432 5433 /** 5434 * @enum 5435 * 5436 * State of stream as described in RFC 7540. 5437 */ 5438 typedef enum { 5439 /** 5440 * idle state. 5441 */ 5442 NGHTTP2_STREAM_STATE_IDLE = 1, 5443 /** 5444 * open state. 5445 */ 5446 NGHTTP2_STREAM_STATE_OPEN, 5447 /** 5448 * reserved (local) state. 5449 */ 5450 NGHTTP2_STREAM_STATE_RESERVED_LOCAL, 5451 /** 5452 * reserved (remote) state. 5453 */ 5454 NGHTTP2_STREAM_STATE_RESERVED_REMOTE, 5455 /** 5456 * half closed (local) state. 5457 */ 5458 NGHTTP2_STREAM_STATE_HALF_CLOSED_LOCAL, 5459 /** 5460 * half closed (remote) state. 5461 */ 5462 NGHTTP2_STREAM_STATE_HALF_CLOSED_REMOTE, 5463 /** 5464 * closed state. 5465 */ 5466 NGHTTP2_STREAM_STATE_CLOSED 5467 } nghttp2_stream_proto_state; 5468 5469 /** 5470 * @function 5471 * 5472 * Returns state of |stream|. The root stream retrieved by 5473 * `nghttp2_session_get_root_stream()` will have stream state 5474 * :enum:`nghttp2_stream_proto_state.NGHTTP2_STREAM_STATE_IDLE`. 5475 */ 5476 NGHTTP2_EXTERN nghttp2_stream_proto_state 5477 nghttp2_stream_get_state(nghttp2_stream *stream); 5478 5479 /** 5480 * @function 5481 * 5482 * Returns root of dependency tree, which is imaginary stream with 5483 * stream ID 0. The returned pointer is valid until |session| is 5484 * freed by `nghttp2_session_del()`. 5485 */ 5486 NGHTTP2_EXTERN nghttp2_stream * 5487 nghttp2_session_get_root_stream(nghttp2_session *session); 5488 5489 /** 5490 * @function 5491 * 5492 * Returns the parent stream of |stream| in dependency tree. Returns 5493 * NULL if there is no such stream. 5494 */ 5495 NGHTTP2_EXTERN nghttp2_stream * 5496 nghttp2_stream_get_parent(nghttp2_stream *stream); 5497 5498 NGHTTP2_EXTERN int32_t nghttp2_stream_get_stream_id(nghttp2_stream *stream); 5499 5500 /** 5501 * @function 5502 * 5503 * Returns the next sibling stream of |stream| in dependency tree. 5504 * Returns NULL if there is no such stream. 5505 */ 5506 NGHTTP2_EXTERN nghttp2_stream * 5507 nghttp2_stream_get_next_sibling(nghttp2_stream *stream); 5508 5509 /** 5510 * @function 5511 * 5512 * Returns the previous sibling stream of |stream| in dependency tree. 5513 * Returns NULL if there is no such stream. 5514 */ 5515 NGHTTP2_EXTERN nghttp2_stream * 5516 nghttp2_stream_get_previous_sibling(nghttp2_stream *stream); 5517 5518 /** 5519 * @function 5520 * 5521 * Returns the first child stream of |stream| in dependency tree. 5522 * Returns NULL if there is no such stream. 5523 */ 5524 NGHTTP2_EXTERN nghttp2_stream * 5525 nghttp2_stream_get_first_child(nghttp2_stream *stream); 5526 5527 /** 5528 * @function 5529 * 5530 * Returns dependency weight to the parent stream of |stream|. 5531 */ 5532 NGHTTP2_EXTERN int32_t nghttp2_stream_get_weight(nghttp2_stream *stream); 5533 5534 /** 5535 * @function 5536 * 5537 * Returns the sum of the weight for |stream|'s children. 5538 */ 5539 NGHTTP2_EXTERN int32_t 5540 nghttp2_stream_get_sum_dependency_weight(nghttp2_stream *stream); 5541 5542 /** 5543 * @functypedef 5544 * 5545 * Callback function invoked when the library outputs debug logging. 5546 * The function is called with arguments suitable for ``vfprintf(3)`` 5547 * 5548 * The debug output is only enabled if the library is built with 5549 * ``DEBUGBUILD`` macro defined. 5550 */ 5551 typedef void (*nghttp2_debug_vprintf_callback)(const char *format, 5552 va_list args); 5553 5554 /** 5555 * @function 5556 * 5557 * Sets a debug output callback called by the library when built with 5558 * ``DEBUGBUILD`` macro defined. If this option is not used, debug 5559 * log is written into standard error output. 5560 * 5561 * For builds without ``DEBUGBUILD`` macro defined, this function is 5562 * noop. 5563 * 5564 * Note that building with ``DEBUGBUILD`` may cause significant 5565 * performance penalty to libnghttp2 because of extra processing. It 5566 * should be used for debugging purpose only. 5567 * 5568 * .. Warning:: 5569 * 5570 * Building with ``DEBUGBUILD`` may cause significant performance 5571 * penalty to libnghttp2 because of extra processing. It should be 5572 * used for debugging purpose only. We write this two times because 5573 * this is important. 5574 */ 5575 NGHTTP2_EXTERN void nghttp2_set_debug_vprintf_callback( 5576 nghttp2_debug_vprintf_callback debug_vprintf_callback); 5577 5578 #ifdef __cplusplus 5579 } 5580 #endif 5581 5582 #endif /* NGHTTP2_H */ 5583