2 * nghttp2 - HTTP/2 C Library
4 * Copyright (c) 2013, 2014 Tatsuhiro Tsujikawa
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:
14 * The above copyright notice and this permission notice shall be
15 * included in all copies or substantial portions of the Software.
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.
28 /* Define WIN32 when build target is Win32 API (borrowed from
30 #if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32)
34 /* Compatibility for non-Clang compilers */
35 #ifndef __has_declspec_attribute
36 # define __has_declspec_attribute(x) 0
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/ */
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>
55 #include <nghttp2/nghttp2ver.h>
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) */
77 * The protocol version identification string of this library
78 * supports. This identifier is used if HTTP/2 is used over TLS.
80 #define NGHTTP2_PROTO_VERSION_ID "h2"
84 * The length of :macro:`NGHTTP2_PROTO_VERSION_ID`.
86 #define NGHTTP2_PROTO_VERSION_ID_LEN 2
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.
97 #define NGHTTP2_PROTO_ALPN "\x2h2"
102 * The length of :macro:`NGHTTP2_PROTO_ALPN`.
104 #define NGHTTP2_PROTO_ALPN_LEN (sizeof(NGHTTP2_PROTO_ALPN) - 1)
109 * The protocol version identification string of this library
110 * supports. This identifier is used if HTTP/2 is used over cleartext
113 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID "h2c"
118 * The length of :macro:`NGHTTP2_CLEARTEXT_PROTO_VERSION_ID`.
120 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN 3
122 struct nghttp2_session;
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.
130 typedef struct nghttp2_session nghttp2_session;
135 * The age of :type:`nghttp2_info`
137 #define NGHTTP2_VERSION_AGE 1
142 * This struct is what `nghttp2_version()` returns. It holds
143 * information about the particular nghttp2 version.
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
153 * the :macro:`NGHTTP2_VERSION_NUM` number (since age ==1)
157 * points to the :macro:`NGHTTP2_VERSION` string (since age ==1)
159 const char *version_str;
161 * points to the :macro:`NGHTTP2_PROTO_VERSION_ID` string this
162 * instance implements (since age ==1)
164 const char *proto_str;
165 /* -------- the above fields all exist when age == 1 */
171 * The default weight of stream dependency.
173 #define NGHTTP2_DEFAULT_WEIGHT 16
178 * The maximum weight of stream dependency.
180 #define NGHTTP2_MAX_WEIGHT 256
185 * The minimum weight of stream dependency.
187 #define NGHTTP2_MIN_WEIGHT 1
192 * The maximum window size
194 #define NGHTTP2_MAX_WINDOW_SIZE ((int32_t)((1U << 31) - 1))
199 * The initial window size for stream level flow control.
201 #define NGHTTP2_INITIAL_WINDOW_SIZE ((1 << 16) - 1)
205 * The initial window size for connection level flow control.
207 #define NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE ((1 << 16) - 1)
212 * The default header table size.
214 #define NGHTTP2_DEFAULT_HEADER_TABLE_SIZE (1 << 12)
219 * The client magic string, which is the first 24 bytes byte string of
220 * client connection preface.
222 #define NGHTTP2_CLIENT_MAGIC "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
227 * The length of :macro:`NGHTTP2_CLIENT_MAGIC`.
229 #define NGHTTP2_CLIENT_MAGIC_LEN 24
234 * The default max number of settings per SETTINGS frame
236 #define NGHTTP2_DEFAULT_MAX_SETTINGS 32
241 * Error codes used in this library. The code range is [-999, -500],
242 * inclusive. The following values are defined:
246 * Invalid argument passed.
248 NGHTTP2_ERR_INVALID_ARGUMENT = -501,
250 * Out of buffer space.
252 NGHTTP2_ERR_BUFFER_ERROR = -502,
254 * The specified protocol version is not supported.
256 NGHTTP2_ERR_UNSUPPORTED_VERSION = -503,
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
263 NGHTTP2_ERR_WOULDBLOCK = -504,
265 * General protocol error
267 NGHTTP2_ERR_PROTO = -505,
269 * The frame is invalid.
271 NGHTTP2_ERR_INVALID_FRAME = -506,
273 * The peer performed a shutdown on the connection.
275 NGHTTP2_ERR_EOF = -507,
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.
282 NGHTTP2_ERR_DEFERRED = -508,
284 * Stream ID has reached the maximum value. Therefore no stream ID
287 NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE = -509,
289 * The stream is already closed; or the stream ID is invalid.
291 NGHTTP2_ERR_STREAM_CLOSED = -510,
293 * RST_STREAM has been added to the outbound queue. The stream is
296 NGHTTP2_ERR_STREAM_CLOSING = -511,
298 * The transmission is not allowed for this stream (e.g., a frame
299 * with END_STREAM flag set has already sent).
301 NGHTTP2_ERR_STREAM_SHUT_WR = -512,
303 * The stream ID is invalid.
305 NGHTTP2_ERR_INVALID_STREAM_ID = -513,
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).
310 NGHTTP2_ERR_INVALID_STREAM_STATE = -514,
312 * Another DATA frame has already been deferred.
314 NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515,
316 * Starting new stream is not allowed (e.g., GOAWAY has been sent
319 NGHTTP2_ERR_START_STREAM_NOT_ALLOWED = -516,
321 * GOAWAY has already been sent.
323 NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517,
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).
331 NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518,
333 * Indicates that the context is not suitable to perform the
334 * requested operation.
336 NGHTTP2_ERR_INVALID_STATE = -519,
338 * The user callback function failed due to the temporal error.
340 NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE = -521,
342 * The length of the frame is invalid, either too large or too small.
344 NGHTTP2_ERR_FRAME_SIZE_ERROR = -522,
346 * Header block inflate/deflate error.
348 NGHTTP2_ERR_HEADER_COMP = -523,
352 NGHTTP2_ERR_FLOW_CONTROL = -524,
354 * Insufficient buffer size given to function.
356 NGHTTP2_ERR_INSUFF_BUFSIZE = -525,
358 * Callback was paused by the application
360 NGHTTP2_ERR_PAUSE = -526,
362 * There are too many in-flight SETTING frame and no more
363 * transmission of SETTINGS is allowed.
365 NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGS = -527,
367 * The server push is disabled.
369 NGHTTP2_ERR_PUSH_DISABLED = -528,
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.
376 NGHTTP2_ERR_DATA_EXIST = -529,
378 * The current session is closing due to a connection error or
379 * `nghttp2_session_terminate_session()` is called.
381 NGHTTP2_ERR_SESSION_CLOSING = -530,
383 * Invalid HTTP header field was received and stream is going to be
386 NGHTTP2_ERR_HTTP_HEADER = -531,
388 * Violation in HTTP messaging rule.
390 NGHTTP2_ERR_HTTP_MESSAGING = -532,
392 * Stream was refused.
394 NGHTTP2_ERR_REFUSED_STREAM = -533,
396 * Unexpected internal error, but recovered.
398 NGHTTP2_ERR_INTERNAL = -534,
400 * Indicates that a processing was canceled.
402 NGHTTP2_ERR_CANCEL = -535,
404 * When a local endpoint expects to receive SETTINGS frame, it
405 * receives an other type of frame.
407 NGHTTP2_ERR_SETTINGS_EXPECTED = -536,
409 * When a local endpoint receives too many settings entries
410 * in a single SETTINGS frame.
412 NGHTTP2_ERR_TOO_MANY_SETTINGS = -537,
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()`.
421 NGHTTP2_ERR_FATAL = -900,
423 * Out of memory. This is a fatal error.
425 NGHTTP2_ERR_NOMEM = -901,
427 * The user callback function failed. This is a fatal error.
429 NGHTTP2_ERR_CALLBACK_FAILURE = -902,
431 * Invalid client magic (see :macro:`NGHTTP2_CLIENT_MAGIC`) was
432 * received and further processing is not possible.
434 NGHTTP2_ERR_BAD_CLIENT_MAGIC = -903,
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
443 NGHTTP2_ERR_FLOODED = -904
449 * The object representing single contiguous buffer.
453 * The pointer to the buffer.
457 * The length of the buffer.
462 struct nghttp2_rcbuf;
467 * The object representing reference counted buffer. The details of
468 * this structure are intentionally hidden from the public API.
470 typedef struct nghttp2_rcbuf nghttp2_rcbuf;
475 * Increments the reference count of |rcbuf| by 1.
477 NGHTTP2_EXTERN void nghttp2_rcbuf_incref(nghttp2_rcbuf *rcbuf);
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.
486 NGHTTP2_EXTERN void nghttp2_rcbuf_decref(nghttp2_rcbuf *rcbuf);
491 * Returns the underlying buffer managed by |rcbuf|.
493 NGHTTP2_EXTERN nghttp2_vec nghttp2_rcbuf_get_buf(nghttp2_rcbuf *rcbuf);
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.
502 NGHTTP2_EXTERN int nghttp2_rcbuf_is_static(const nghttp2_rcbuf *rcbuf);
507 * The flags for header field name/value pair.
513 NGHTTP2_NV_FLAG_NONE = 0,
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".
519 NGHTTP2_NV_FLAG_NO_INDEX = 0x01,
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.
525 NGHTTP2_NV_FLAG_NO_COPY_NAME = 0x02,
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.
531 NGHTTP2_NV_FLAG_NO_COPY_VALUE = 0x04
537 * The name/value pair, which mainly used to represent header fields.
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.
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.
567 * The length of the |name|, excluding terminating NULL.
571 * The length of the |value|, excluding terminating NULL.
575 * Bitwise OR of one or more of :type:`nghttp2_nv_flag`.
583 * The frame types in HTTP/2 specification.
593 NGHTTP2_HEADERS = 0x01,
595 * The PRIORITY frame.
597 NGHTTP2_PRIORITY = 0x02,
599 * The RST_STREAM frame.
601 NGHTTP2_RST_STREAM = 0x03,
603 * The SETTINGS frame.
605 NGHTTP2_SETTINGS = 0x04,
607 * The PUSH_PROMISE frame.
609 NGHTTP2_PUSH_PROMISE = 0x05,
617 NGHTTP2_GOAWAY = 0x07,
619 * The WINDOW_UPDATE frame.
621 NGHTTP2_WINDOW_UPDATE = 0x08,
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.
627 NGHTTP2_CONTINUATION = 0x09,
629 * The ALTSVC frame, which is defined in `RFC 7383
630 * <https://tools.ietf.org/html/rfc7838#section-4>`_.
632 NGHTTP2_ALTSVC = 0x0a,
634 * The ORIGIN frame, which is defined by `RFC 8336
635 * <https://tools.ietf.org/html/rfc8336>`_.
637 NGHTTP2_ORIGIN = 0x0c
638 } nghttp2_frame_type;
643 * The flags for HTTP/2 frames. This enum defines all flags for all
650 NGHTTP2_FLAG_NONE = 0,
652 * The END_STREAM flag.
654 NGHTTP2_FLAG_END_STREAM = 0x01,
656 * The END_HEADERS flag.
658 NGHTTP2_FLAG_END_HEADERS = 0x04,
662 NGHTTP2_FLAG_ACK = 0x01,
666 NGHTTP2_FLAG_PADDED = 0x08,
670 NGHTTP2_FLAG_PRIORITY = 0x20
679 * SETTINGS_HEADER_TABLE_SIZE
681 NGHTTP2_SETTINGS_HEADER_TABLE_SIZE = 0x01,
683 * SETTINGS_ENABLE_PUSH
685 NGHTTP2_SETTINGS_ENABLE_PUSH = 0x02,
687 * SETTINGS_MAX_CONCURRENT_STREAMS
689 NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS = 0x03,
691 * SETTINGS_INITIAL_WINDOW_SIZE
693 NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE = 0x04,
695 * SETTINGS_MAX_FRAME_SIZE
697 NGHTTP2_SETTINGS_MAX_FRAME_SIZE = 0x05,
699 * SETTINGS_MAX_HEADER_LIST_SIZE
701 NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE = 0x06,
703 * SETTINGS_ENABLE_CONNECT_PROTOCOL
704 * (`RFC 8441 <https://tools.ietf.org/html/rfc8441>`_)
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 */
716 * Deprecated. The initial max concurrent streams is 0xffffffffu.
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.
725 * The maximum number of outgoing concurrent streams is 100 by
728 #define NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS ((1U << 31) - 1)
732 * The status codes for the RST_STREAM and GOAWAY frames.
738 NGHTTP2_NO_ERROR = 0x00,
742 NGHTTP2_PROTOCOL_ERROR = 0x01,
746 NGHTTP2_INTERNAL_ERROR = 0x02,
750 NGHTTP2_FLOW_CONTROL_ERROR = 0x03,
754 NGHTTP2_SETTINGS_TIMEOUT = 0x04,
758 NGHTTP2_STREAM_CLOSED = 0x05,
762 NGHTTP2_FRAME_SIZE_ERROR = 0x06,
766 NGHTTP2_REFUSED_STREAM = 0x07,
770 NGHTTP2_CANCEL = 0x08,
774 NGHTTP2_COMPRESSION_ERROR = 0x09,
778 NGHTTP2_CONNECT_ERROR = 0x0a,
782 NGHTTP2_ENHANCE_YOUR_CALM = 0x0b,
784 * INADEQUATE_SECURITY
786 NGHTTP2_INADEQUATE_SECURITY = 0x0c,
790 NGHTTP2_HTTP_1_1_REQUIRED = 0x0d
791 } nghttp2_error_code;
799 * The length field of this frame, excluding frame header.
803 * The stream identifier (aka, stream ID)
807 * The type of this frame. See `nghttp2_frame_type`.
815 * Reserved bit in frame header. Currently, this is always set to 0
816 * and application should not expect something useful in here.
824 * This union represents the some kind of data source passed to
825 * :type:`nghttp2_data_source_read_callback`.
829 * The integer field, suitable for a file descriptor.
833 * The pointer to an arbitrary object.
836 } nghttp2_data_source;
841 * The flags used to set in |data_flags| output parameter in
842 * :type:`nghttp2_data_source_read_callback`.
848 NGHTTP2_DATA_FLAG_NONE = 0,
850 * Indicates EOF was sensed.
852 NGHTTP2_DATA_FLAG_EOF = 0x01,
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()`.
859 NGHTTP2_DATA_FLAG_NO_END_STREAM = 0x02,
861 * Indicates that application will send complete DATA frame in
862 * :type:`nghttp2_send_data_callback`.
864 NGHTTP2_DATA_FLAG_NO_COPY = 0x04
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
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.
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.
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()`.
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
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`.
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.
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);
937 * This struct represents the data source and the way to read a chunk
944 nghttp2_data_source source;
946 * The callback function to read a chunk of data from the |source|.
948 nghttp2_data_source_read_callback read_callback;
949 } nghttp2_data_provider;
954 * The DATA frame. The received data is delivered via
955 * :type:`nghttp2_on_data_chunk_recv_callback`.
960 * The length of the padding in this frame. This includes PAD_HIGH
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.
977 * The HEADERS frame is opening new stream, which is analogous to
978 * SYN_STREAM in SPDY.
980 NGHTTP2_HCAT_REQUEST = 0,
982 * The HEADERS frame is the first response headers, which is
983 * analogous to SYN_REPLY in SPDY.
985 NGHTTP2_HCAT_RESPONSE = 1,
987 * The HEADERS frame is the first headers sent against reserved
990 NGHTTP2_HCAT_PUSH_RESPONSE = 2,
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
997 NGHTTP2_HCAT_HEADERS = 3
998 } nghttp2_headers_category;
1003 * The structure to specify stream dependency.
1007 * The stream ID of the stream to depend on. Specifying 0 makes
1008 * stream not depend any other stream.
1012 * The weight of this dependency.
1016 * nonzero means exclusive dependency
1019 } nghttp2_priority_spec;
1024 * The HEADERS frame. It has the following members:
1030 nghttp2_frame_hd hd;
1032 * The length of the padding in this frame. This includes PAD_HIGH
1037 * The priority specification
1039 nghttp2_priority_spec pri_spec;
1041 * The name/value pairs.
1045 * The number of name/value pairs in |nva|.
1049 * The category of this HEADERS frame.
1051 nghttp2_headers_category cat;
1057 * The PRIORITY frame. It has the following members:
1063 nghttp2_frame_hd hd;
1065 * The priority specification.
1067 nghttp2_priority_spec pri_spec;
1073 * The RST_STREAM frame. It has the following members:
1079 nghttp2_frame_hd hd;
1081 * The error code. See :type:`nghttp2_error_code`.
1083 uint32_t error_code;
1084 } nghttp2_rst_stream;
1089 * The SETTINGS ID/Value pair. It has the following members:
1093 * The SETTINGS ID. See :type:`nghttp2_settings_id`.
1095 int32_t settings_id;
1097 * The value of this entry.
1100 } nghttp2_settings_entry;
1105 * The SETTINGS frame. It has the following members:
1111 nghttp2_frame_hd hd;
1113 * The number of SETTINGS ID/Value pairs in |iv|.
1117 * The pointer to the array of SETTINGS ID/Value pair.
1119 nghttp2_settings_entry *iv;
1125 * The PUSH_PROMISE frame. It has the following members:
1131 nghttp2_frame_hd hd;
1133 * The length of the padding in this frame. This includes PAD_HIGH
1138 * The name/value pairs.
1142 * The number of name/value pairs in |nva|.
1146 * The promised stream ID
1148 int32_t promised_stream_id;
1150 * Reserved bit. Currently this is always set to 0 and application
1151 * should not expect something useful in here.
1154 } nghttp2_push_promise;
1159 * The PING frame. It has the following members:
1165 nghttp2_frame_hd hd;
1169 uint8_t opaque_data[8];
1175 * The GOAWAY frame. It has the following members:
1181 nghttp2_frame_hd hd;
1183 * The last stream stream ID.
1185 int32_t last_stream_id;
1187 * The error code. See :type:`nghttp2_error_code`.
1189 uint32_t error_code;
1191 * The additional debug data
1193 uint8_t *opaque_data;
1195 * The length of |opaque_data| member.
1197 size_t opaque_data_len;
1199 * Reserved bit. Currently this is always set to 0 and application
1200 * should not expect something useful in here.
1208 * The WINDOW_UPDATE frame. It has the following members:
1214 nghttp2_frame_hd hd;
1216 * The window size increment.
1218 int32_t window_size_increment;
1220 * Reserved bit. Currently this is always set to 0 and application
1221 * should not expect something useful in here.
1224 } nghttp2_window_update;
1229 * The extension frame. It has following members:
1235 nghttp2_frame_hd hd;
1237 * The pointer to extension payload. The exact pointer type is
1238 * determined by hd.type.
1240 * Currently, no extension is supported. This is a place holder for
1241 * the future extensions.
1244 } nghttp2_extension;
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.
1255 * The frame header, which is convenient to inspect frame header.
1257 nghttp2_frame_hd hd;
1263 * The HEADERS frame.
1265 nghttp2_headers headers;
1267 * The PRIORITY frame.
1269 nghttp2_priority priority;
1271 * The RST_STREAM frame.
1273 nghttp2_rst_stream rst_stream;
1275 * The SETTINGS frame.
1277 nghttp2_settings settings;
1279 * The PUSH_PROMISE frame.
1281 nghttp2_push_promise push_promise;
1289 nghttp2_goaway goaway;
1291 * The WINDOW_UPDATE frame.
1293 nghttp2_window_update window_update;
1295 * The extension frame.
1297 nghttp2_extension ext;
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()`.
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.
1319 * To set this callback to :type:`nghttp2_session_callbacks`, use
1320 * `nghttp2_session_callbacks_set_send_callback()`.
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
1331 typedef ssize_t (*nghttp2_send_callback)(nghttp2_session *session,
1332 const uint8_t *data, size_t length,
1333 int flags, void *user_data);
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
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`.
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.
1355 * The application has to send complete DATA frame in this callback.
1356 * If all data were written successfully, return 0.
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.
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,
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()`.
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.
1405 * To set this callback to :type:`nghttp2_session_callbacks`, use
1406 * `nghttp2_session_callbacks_set_recv_callback()`.
1408 typedef ssize_t (*nghttp2_recv_callback)(nghttp2_session *session, uint8_t *buf,
1409 size_t length, int flags,
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()`.
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`.
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()`.
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.
1435 * This callback won't be called for CONTINUATION frames.
1436 * HEADERS/PUSH_PROMISE + CONTINUATIONs are treated as single frame.
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`.
1444 * To set this callback to :type:`nghttp2_session_callbacks`, use
1445 * `nghttp2_session_callbacks_set_on_frame_recv_callback()`.
1447 typedef int (*nghttp2_on_frame_recv_callback)(nghttp2_session *session,
1448 const nghttp2_frame *frame,
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()`.
1463 * If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
1464 * member of their data structure are always ``NULL`` and 0
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`.
1473 * To set this callback to :type:`nghttp2_session_callbacks`, use
1474 * `nghttp2_session_callbacks_set_on_invalid_frame_recv_callback()`.
1476 typedef int (*nghttp2_on_invalid_frame_recv_callback)(
1477 nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code,
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()`.
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.
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`.
1508 * To set this callback to :type:`nghttp2_session_callbacks`, use
1509 * `nghttp2_session_callbacks_set_on_data_chunk_recv_callback()`.
1511 typedef int (*nghttp2_on_data_chunk_recv_callback)(nghttp2_session *session,
1514 const uint8_t *data,
1515 size_t len, void *user_data);
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()`.
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.
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`.
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.
1541 * To set this callback to :type:`nghttp2_session_callbacks`, use
1542 * `nghttp2_session_callbacks_set_before_frame_send_callback()`.
1544 typedef int (*nghttp2_before_frame_send_callback)(nghttp2_session *session,
1545 const nghttp2_frame *frame,
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()`.
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`.
1561 * To set this callback to :type:`nghttp2_session_callbacks`, use
1562 * `nghttp2_session_callbacks_set_on_frame_send_callback()`.
1564 typedef int (*nghttp2_on_frame_send_callback)(nghttp2_session *session,
1565 const nghttp2_frame *frame,
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()`.
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`.
1584 * `nghttp2_session_get_stream_user_data()` can be used to get
1587 * To set this callback to :type:`nghttp2_session_callbacks`, use
1588 * `nghttp2_session_callbacks_set_on_frame_not_send_callback()`.
1590 typedef int (*nghttp2_on_frame_not_send_callback)(nghttp2_session *session,
1591 const nghttp2_frame *frame,
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()`.
1607 * This function is also called for a stream in reserved state.
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`.
1616 * To set this callback to :type:`nghttp2_session_callbacks`, use
1617 * `nghttp2_session_callbacks_set_on_stream_close_callback()`.
1619 typedef int (*nghttp2_on_stream_close_callback)(nghttp2_session *session,
1621 uint32_t error_code,
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`.
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.
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.
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.
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
1673 * The implementation of this function must return 0 if it succeeds.
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`.
1685 * To set this callback to :type:`nghttp2_session_callbacks`, use
1686 * `nghttp2_session_callbacks_set_on_begin_headers_callback()`.
1688 typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session,
1689 const nghttp2_frame *frame,
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`.
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.
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
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
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.
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.
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
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`.
1762 * To set this callback to :type:`nghttp2_session_callbacks`, use
1763 * `nghttp2_session_callbacks_set_on_header_callback()`.
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.
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);
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`.
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.
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,
1808 * Callback function invoked when a invalid header name/value pair is
1809 * received for the |frame|.
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
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()`).
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`.
1834 * If 0 is returned, the header field is ignored, and the stream is
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,
1845 * Callback function invoked when a invalid header name/value pair is
1846 * received for the |frame|.
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.
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()`).
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`.
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);
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`.
1889 * To set this callback to :type:`nghttp2_session_callbacks`, use
1890 * `nghttp2_session_callbacks_set_select_padding_callback()`.
1892 typedef ssize_t (*nghttp2_select_padding_callback)(nghttp2_session *session,
1893 const nghttp2_frame *frame,
1894 size_t max_payloadlen,
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`.
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.
1919 * To set this callback to :type:`nghttp2_session_callbacks`, use
1920 * `nghttp2_session_callbacks_set_data_source_read_length_callback()`.
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);
1930 * Callback function invoked when a frame header is received. The
1931 * |hd| points to received frame header.
1933 * Unlike :type:`nghttp2_on_frame_recv_callback`, this callback will
1934 * also be called when frame header of CONTINUATION frame is received.
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.
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`.
1947 * To set this callback to :type:`nghttp2_session_callbacks`, use
1948 * `nghttp2_session_callbacks_set_on_begin_frame_callback()`.
1950 typedef int (*nghttp2_on_begin_frame_callback)(nghttp2_session *session,
1951 const nghttp2_frame_hd *hd,
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|.
1961 * The implementation of this function must return 0 if it succeeds.
1963 * To abort processing this extension frame, return
1964 * :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`.
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`.
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);
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|.
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()`.
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.
2001 * To abort processing this extension frame, return
2002 * :enum:`nghttp2_error.NGHTTP2_ERR_CANCEL`.
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`.
2012 typedef int (*nghttp2_unpack_extension_callback)(nghttp2_session *session,
2014 const nghttp2_frame_hd *hd,
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.
2028 * The implementation of this function should return the number of
2029 * bytes written into |buf| when it succeeds.
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.
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`.
2045 typedef ssize_t (*nghttp2_pack_extension_callback)(nghttp2_session *session,
2046 uint8_t *buf, size_t len,
2047 const nghttp2_frame *frame,
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
2059 * This function is deprecated. The new application should use
2060 * :type:`nghttp2_error_callback2`.
2062 * The format of error message may change between nghttp2 library
2063 * versions. The application should not depend on the particular
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.
2075 typedef int (*nghttp2_error_callback)(nghttp2_session *session, const char *msg,
2076 size_t len, void *user_data);
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.
2088 * The format of error message may change between nghttp2 library
2089 * versions. The application should not depend on the particular
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.
2101 typedef int (*nghttp2_error_callback2)(nghttp2_session *session,
2102 int lib_error_code, const char *msg,
2103 size_t len, void *user_data);
2105 struct nghttp2_session_callbacks;
2110 * Callback functions for :type:`nghttp2_session`. The details of
2111 * this structure are intentionally hidden from the public API.
2113 typedef struct nghttp2_session_callbacks nghttp2_session_callbacks;
2118 * Initializes |*callbacks_ptr| with NULL values.
2120 * The initialized object can be used when initializing multiple
2121 * :type:`nghttp2_session` objects.
2123 * When the application finished using this object, it can use
2124 * `nghttp2_session_callbacks_del()` to free its memory.
2126 * This function returns 0 if it succeeds, or one of the following
2127 * negative error codes:
2129 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
2133 nghttp2_session_callbacks_new(nghttp2_session_callbacks **callbacks_ptr);
2138 * Frees any resources allocated for |callbacks|. If |callbacks| is
2139 * ``NULL``, this function does nothing.
2142 nghttp2_session_callbacks_del(nghttp2_session_callbacks *callbacks);
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
2152 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_callback(
2153 nghttp2_session_callbacks *cbs, nghttp2_send_callback send_callback);
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
2163 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_recv_callback(
2164 nghttp2_session_callbacks *cbs, nghttp2_recv_callback recv_callback);
2169 * Sets callback function invoked by `nghttp2_session_recv()` and
2170 * `nghttp2_session_mem_recv()` when a frame is received.
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);
2179 * Sets callback function invoked by `nghttp2_session_recv()` and
2180 * `nghttp2_session_mem_recv()` when an invalid non-DATA frame is
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);
2191 * Sets callback function invoked when a chunk of data in DATA frame
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);
2201 * Sets callback function invoked before a non-DATA frame is sent.
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);
2210 * Sets callback function invoked after a frame is sent.
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);
2219 * Sets callback function invoked when a non-DATA frame is not sent
2220 * because of an error.
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);
2229 * Sets callback function invoked when the stream is closed.
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);
2238 * Sets callback function invoked when the reception of header block
2239 * in HEADERS or PUSH_PROMISE is started.
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);
2248 * Sets callback function invoked when a header name/value pair is
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.
2254 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_header_callback(
2255 nghttp2_session_callbacks *cbs,
2256 nghttp2_on_header_callback on_header_callback);
2261 * Sets callback function invoked when a header name/value pair is
2264 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_header_callback2(
2265 nghttp2_session_callbacks *cbs,
2266 nghttp2_on_header_callback2 on_header_callback2);
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.
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);
2284 * Sets callback function invoked when a invalid header name/value
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);
2294 * Sets callback function invoked when the library asks application
2295 * how many padding bytes are required for the transmission of the
2298 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_select_padding_callback(
2299 nghttp2_session_callbacks *cbs,
2300 nghttp2_select_padding_callback select_padding_callback);
2305 * Sets callback function determine the length allowed in
2306 * :type:`nghttp2_data_source_read_callback`.
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);
2316 * Sets callback function invoked when a frame header is received.
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);
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.
2329 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_data_callback(
2330 nghttp2_session_callbacks *cbs,
2331 nghttp2_send_data_callback send_data_callback);
2336 * Sets callback function invoked when the library asks the
2337 * application to pack extension frame payload in wire format.
2339 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_pack_extension_callback(
2340 nghttp2_session_callbacks *cbs,
2341 nghttp2_pack_extension_callback pack_extension_callback);
2346 * Sets callback function invoked when the library asks the
2347 * application to unpack extension frame payload from wire format.
2349 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_unpack_extension_callback(
2350 nghttp2_session_callbacks *cbs,
2351 nghttp2_unpack_extension_callback unpack_extension_callback);
2356 * Sets callback function invoked when chunk of extension frame
2357 * payload is received.
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);
2367 * Sets callback function invoked when library tells error message to
2370 * This function is deprecated. The new application should use
2371 * `nghttp2_session_callbacks_set_error_callback2()`.
2373 * If both :type:`nghttp2_error_callback` and
2374 * :type:`nghttp2_error_callback2` are set, the latter takes
2377 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_error_callback(
2378 nghttp2_session_callbacks *cbs, nghttp2_error_callback error_callback);
2383 * Sets callback function invoked when library tells error code, and
2384 * message to the application.
2386 * If both :type:`nghttp2_error_callback` and
2387 * :type:`nghttp2_error_callback2` are set, the latter takes
2390 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_error_callback2(
2391 nghttp2_session_callbacks *cbs, nghttp2_error_callback2 error_callback2);
2396 * Custom memory allocator to replace malloc(). The |mem_user_data|
2397 * is the mem_user_data member of :type:`nghttp2_mem` structure.
2399 typedef void *(*nghttp2_malloc)(size_t size, void *mem_user_data);
2404 * Custom memory allocator to replace free(). The |mem_user_data| is
2405 * the mem_user_data member of :type:`nghttp2_mem` structure.
2407 typedef void (*nghttp2_free)(void *ptr, void *mem_user_data);
2412 * Custom memory allocator to replace calloc(). The |mem_user_data|
2413 * is the mem_user_data member of :type:`nghttp2_mem` structure.
2415 typedef void *(*nghttp2_calloc)(size_t nmemb, size_t size, void *mem_user_data);
2420 * Custom memory allocator to replace realloc(). The |mem_user_data|
2421 * is the mem_user_data member of :type:`nghttp2_mem` structure.
2423 typedef void *(*nghttp2_realloc)(void *ptr, size_t size, void *mem_user_data);
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.
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::
2437 * void *my_malloc_cb(size_t size, void *mem_user_data) {
2438 * return my_malloc(size);
2441 * void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); }
2443 * void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) {
2444 * return my_calloc(nmemb, size);
2447 * void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) {
2448 * return my_realloc(ptr, size);
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,
2459 * nghttp2_session_client_new3(&session, callbacks, NULL, NULL, &mem);
2466 * An arbitrary user supplied data. This is passed to each
2467 * allocator function.
2469 void *mem_user_data;
2471 * Custom allocator function to replace malloc().
2473 nghttp2_malloc malloc;
2475 * Custom allocator function to replace free().
2479 * Custom allocator function to replace calloc().
2481 nghttp2_calloc calloc;
2483 * Custom allocator function to replace realloc().
2485 nghttp2_realloc realloc;
2488 struct nghttp2_option;
2493 * Configuration options for :type:`nghttp2_session`. The details of
2494 * this structure are intentionally hidden from the public API.
2496 typedef struct nghttp2_option nghttp2_option;
2501 * Initializes |*option_ptr| with default values.
2503 * When the application finished using this object, it can use
2504 * `nghttp2_option_del()` to free its memory.
2506 * This function returns 0 if it succeeds, or one of the following
2507 * negative error codes:
2509 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
2512 NGHTTP2_EXTERN int nghttp2_option_new(nghttp2_option **option_ptr);
2517 * Frees any resources allocated for |option|. If |option| is
2518 * ``NULL``, this function does nothing.
2520 NGHTTP2_EXTERN void nghttp2_option_del(nghttp2_option *option);
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.
2533 nghttp2_option_set_no_auto_window_update(nghttp2_option *option, int val);
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.
2551 nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
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.
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.
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
2574 nghttp2_option_set_no_recv_client_magic(nghttp2_option *option, int val);
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
2589 NGHTTP2_EXTERN void nghttp2_option_set_no_http_messaging(nghttp2_option *option,
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.
2608 nghttp2_option_set_max_reserved_remote_streams(nghttp2_option *option,
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.
2625 nghttp2_option_set_user_recv_extension_type(nghttp2_option *option,
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
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
2645 nghttp2_option_set_builtin_recv_extension_type(nghttp2_option *option,
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.
2659 NGHTTP2_EXTERN void nghttp2_option_set_no_auto_ping_ack(nghttp2_option *option,
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`.
2674 nghttp2_option_set_max_send_header_block_length(nghttp2_option *option,
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.
2687 nghttp2_option_set_max_deflate_dynamic_table_size(nghttp2_option *option,
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.
2697 NGHTTP2_EXTERN void nghttp2_option_set_no_closed_streams(nghttp2_option *option,
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.
2708 NGHTTP2_EXTERN void nghttp2_option_set_max_outbound_ack(nghttp2_option *option,
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.
2719 NGHTTP2_EXTERN void nghttp2_option_set_max_settings(nghttp2_option *option,
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.
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``.
2735 * If this function fails, |*session_ptr| is left untouched.
2737 * This function returns 0 if it succeeds, or one of the following
2738 * negative error codes:
2740 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
2744 nghttp2_session_client_new(nghttp2_session **session_ptr,
2745 const nghttp2_session_callbacks *callbacks,
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.
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``.
2761 * If this function fails, |*session_ptr| is left untouched.
2763 * This function returns 0 if it succeeds, or one of the following
2764 * negative error codes:
2766 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
2770 nghttp2_session_server_new(nghttp2_session **session_ptr,
2771 const nghttp2_session_callbacks *callbacks,
2777 * Like `nghttp2_session_client_new()`, but with additional options
2778 * specified in the |option|.
2780 * The |option| can be ``NULL`` and the call is equivalent to
2781 * `nghttp2_session_client_new()`.
2783 * This function does not take ownership |option|. The application is
2784 * responsible for freeing |option| if it finishes using the object.
2786 * The library code does not refer to |option| after this function
2789 * This function returns 0 if it succeeds, or one of the following
2790 * negative error codes:
2792 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
2796 nghttp2_session_client_new2(nghttp2_session **session_ptr,
2797 const nghttp2_session_callbacks *callbacks,
2798 void *user_data, const nghttp2_option *option);
2803 * Like `nghttp2_session_server_new()`, but with additional options
2804 * specified in the |option|.
2806 * The |option| can be ``NULL`` and the call is equivalent to
2807 * `nghttp2_session_server_new()`.
2809 * This function does not take ownership |option|. The application is
2810 * responsible for freeing |option| if it finishes using the object.
2812 * The library code does not refer to |option| after this function
2815 * This function returns 0 if it succeeds, or one of the following
2816 * negative error codes:
2818 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
2822 nghttp2_session_server_new2(nghttp2_session **session_ptr,
2823 const nghttp2_session_callbacks *callbacks,
2824 void *user_data, const nghttp2_option *option);
2829 * Like `nghttp2_session_client_new2()`, but with additional custom
2830 * memory allocator specified in the |mem|.
2832 * The |mem| can be ``NULL`` and the call is equivalent to
2833 * `nghttp2_session_client_new2()`.
2835 * This function does not take ownership |mem|. The application is
2836 * responsible for freeing |mem|.
2838 * The library code does not refer to |mem| pointer after this
2839 * function returns, so the application can safely free it.
2841 * This function returns 0 if it succeeds, or one of the following
2842 * negative error codes:
2844 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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);
2854 * Like `nghttp2_session_server_new2()`, but with additional custom
2855 * memory allocator specified in the |mem|.
2857 * The |mem| can be ``NULL`` and the call is equivalent to
2858 * `nghttp2_session_server_new2()`.
2860 * This function does not take ownership |mem|. The application is
2861 * responsible for freeing |mem|.
2863 * The library code does not refer to |mem| pointer after this
2864 * function returns, so the application can safely free it.
2866 * This function returns 0 if it succeeds, or one of the following
2867 * negative error codes:
2869 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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);
2879 * Frees any resources allocated for |session|. If |session| is
2880 * ``NULL``, this function does nothing.
2882 NGHTTP2_EXTERN void nghttp2_session_del(nghttp2_session *session);
2887 * Sends pending frames to the remote peer.
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:
2900 * 1. Get the next frame to send from outbound queue.
2902 * 2. Prepare transmission of the frame.
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.
2909 * 4. If the frame is HEADERS, PUSH_PROMISE or DATA,
2910 * :type:`nghttp2_select_padding_callback` is invoked.
2912 * 5. If the frame is request HEADERS, the stream is opened here.
2914 * 6. :type:`nghttp2_before_frame_send_callback` is invoked.
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.
2922 * 8. :type:`nghttp2_send_callback` is invoked one or more times to
2925 * 9. :type:`nghttp2_on_frame_send_callback` is invoked.
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.
2931 * This function returns 0 if it succeeds, or one of the following
2932 * negative error codes:
2934 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
2936 * :enum:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`
2937 * The callback function failed.
2939 NGHTTP2_EXTERN int nghttp2_session_send(nghttp2_session *session);
2944 * Returns the serialized data to send.
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()`.
2952 * If no data is available to send, this function returns 0.
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.
2958 * The assigned |*data_ptr| is valid until the next call of
2959 * `nghttp2_session_mem_send()` or `nghttp2_session_send()`.
2961 * The caller must send all data before sending the next chunk of
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
2968 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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
2980 NGHTTP2_EXTERN ssize_t nghttp2_session_mem_send(nghttp2_session *session,
2981 const uint8_t **data_ptr);
2986 * Receives frames from the remote peer.
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:
2995 * 1. :type:`nghttp2_recv_callback` is invoked one or more times to
2996 * receive frame header.
2998 * 2. When frame header is received,
2999 * :type:`nghttp2_on_begin_frame_callback` is invoked.
3001 * 3. If the frame is DATA frame:
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.
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.
3012 * 4. If the frame is the control frame:
3014 * 1. :type:`nghttp2_recv_callback` is invoked one or more times to
3015 * receive whole frame.
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.
3029 * 3. If the received frame is unpacked but is interpreted as
3030 * invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is
3033 * This function returns 0 if it succeeds, or one of the following
3034 * negative error codes:
3036 * :enum:`nghttp2_error.NGHTTP2_ERR_EOF`
3037 * The remote peer did shutdown on the connection.
3038 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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
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.
3051 NGHTTP2_EXTERN int nghttp2_session_recv(nghttp2_session *session);
3056 * Processes data |in| as an input from the remote endpoint. The
3057 * |inlen| indicates the number of bytes to receive in the |in|.
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()`.
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.
3074 * This function returns the number of processed bytes, or one of the
3075 * following negative error codes:
3077 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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
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.
3090 NGHTTP2_EXTERN ssize_t nghttp2_session_mem_recv(nghttp2_session *session,
3097 * Puts back previously deferred DATA frame in the stream |stream_id|
3098 * to the outbound queue.
3100 * This function returns 0 if it succeeds, or one of the following
3101 * negative error codes:
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`
3108 NGHTTP2_EXTERN int nghttp2_session_resume_data(nghttp2_session *session,
3114 * Returns nonzero value if |session| wants to receive data from the
3117 * If both `nghttp2_session_want_read()` and
3118 * `nghttp2_session_want_write()` return 0, the application should
3119 * drop the connection.
3121 NGHTTP2_EXTERN int nghttp2_session_want_read(nghttp2_session *session);
3126 * Returns nonzero value if |session| wants to send data to the remote
3129 * If both `nghttp2_session_want_read()` and
3130 * `nghttp2_session_want_write()` return 0, the application should
3131 * drop the connection.
3133 NGHTTP2_EXTERN int nghttp2_session_want_write(nghttp2_session *session);
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
3147 NGHTTP2_EXTERN void *
3148 nghttp2_session_get_stream_user_data(nghttp2_session *session,
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
3160 * It is valid to set the |stream_user_data| to the stream reserved by
3161 * PUSH_PROMISE frame.
3163 * This function returns 0 if it succeeds, or one of following
3164 * negative error codes:
3166 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
3167 * The stream does not exist
3170 nghttp2_session_set_stream_user_data(nghttp2_session *session,
3171 int32_t stream_id, void *stream_user_data);
3176 * Sets |user_data| to |session|, overwriting the existing user data
3177 * specified in `nghttp2_session_client_new()`, or
3178 * `nghttp2_session_server_new()`.
3180 NGHTTP2_EXTERN void nghttp2_session_set_user_data(nghttp2_session *session,
3186 * Returns the number of frames in the outbound queue. This does not
3187 * include the deferred DATA frames.
3189 NGHTTP2_EXTERN size_t
3190 nghttp2_session_get_outbound_queue_size(nghttp2_session *session);
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.
3204 * This function returns -1 if it fails.
3206 NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_effective_recv_data_length(
3207 nghttp2_session *session, int32_t stream_id);
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.
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.
3224 * This function returns -1 if it fails.
3226 NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_effective_local_window_size(
3227 nghttp2_session *session, int32_t stream_id);
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()`).
3239 * This function returns -1 if it fails.
3241 NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_local_window_size(
3242 nghttp2_session *session, int32_t stream_id);
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.
3256 * This function returns -1 if it fails.
3258 NGHTTP2_EXTERN int32_t
3259 nghttp2_session_get_effective_recv_data_length(nghttp2_session *session);
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.
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.
3276 * This function returns -1 if it fails.
3278 NGHTTP2_EXTERN int32_t
3279 nghttp2_session_get_effective_local_window_size(nghttp2_session *session);
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()`).
3290 * This function returns -1 if it fails.
3292 NGHTTP2_EXTERN int32_t
3293 nghttp2_session_get_local_window_size(nghttp2_session *session);
3298 * Returns the remote window size for a given stream |stream_id|.
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()`).
3307 * This function returns -1 if it fails.
3309 NGHTTP2_EXTERN int32_t nghttp2_session_get_stream_remote_window_size(
3310 nghttp2_session *session, int32_t stream_id);
3315 * Returns the remote window size for a connection.
3317 * This function always succeeds.
3319 NGHTTP2_EXTERN int32_t
3320 nghttp2_session_get_remote_window_size(nghttp2_session *session);
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.
3329 nghttp2_session_get_stream_local_close(nghttp2_session *session,
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.
3339 nghttp2_session_get_stream_remote_close(nghttp2_session *session,
3345 * Returns the current dynamic table size of HPACK inflater, including
3346 * the overhead 32 bytes per entry described in RFC 7541.
3348 NGHTTP2_EXTERN size_t
3349 nghttp2_session_get_hd_inflate_dynamic_table_size(nghttp2_session *session);
3354 * Returns the current dynamic table size of HPACK deflater including
3355 * the overhead 32 bytes per entry described in RFC 7541.
3357 NGHTTP2_EXTERN size_t
3358 nghttp2_session_get_hd_deflate_dynamic_table_size(nghttp2_session *session);
3363 * Signals the session so that the connection should be terminated.
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
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`.
3373 * After the transmission, both `nghttp2_session_want_read()` and
3374 * `nghttp2_session_want_write()` return 0.
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.
3380 * This function returns 0 if it succeeds, or one of the following
3381 * negative error codes:
3383 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
3386 NGHTTP2_EXTERN int nghttp2_session_terminate_session(nghttp2_session *session,
3387 uint32_t error_code);
3392 * Signals the session so that the connection should be terminated.
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
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
3407 * This function returns 0 if it succeeds, or one of the following
3408 * negative error codes:
3410 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
3412 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
3413 * The |last_stream_id| is invalid.
3415 NGHTTP2_EXTERN int nghttp2_session_terminate_session2(nghttp2_session *session,
3416 int32_t last_stream_id,
3417 uint32_t error_code);
3422 * Signals to the client that the server started graceful shutdown
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`.
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()`.
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
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.
3446 * This function returns 0 if it succeeds, or one of the following
3447 * negative error codes:
3449 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
3451 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
3452 * The |session| is initialized as client.
3454 NGHTTP2_EXTERN int nghttp2_submit_shutdown_notice(nghttp2_session *session);
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`.
3463 NGHTTP2_EXTERN uint32_t nghttp2_session_get_remote_settings(
3464 nghttp2_session *session, nghttp2_settings_id id);
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`.
3473 NGHTTP2_EXTERN uint32_t nghttp2_session_get_local_settings(
3474 nghttp2_session *session, nghttp2_settings_id id);
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()`.
3483 * This function returns 0 if it succeeds, or one of the following
3484 * negative error codes:
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).
3492 NGHTTP2_EXTERN int nghttp2_session_set_next_stream_id(nghttp2_session *session,
3493 int32_t next_stream_id);
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.
3502 NGHTTP2_EXTERN uint32_t
3503 nghttp2_session_get_next_stream_id(nghttp2_session *session);
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()`).
3518 * This function returns 0 if it succeeds, or one of the following
3519 * negative error codes:
3521 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
3528 NGHTTP2_EXTERN int nghttp2_session_consume(nghttp2_session *session,
3529 int32_t stream_id, size_t size);
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
3539 * This function returns 0 if it succeeds, or one of the following
3540 * negative error codes:
3542 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
3544 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
3545 * Automatic WINDOW_UPDATE is not disabled.
3547 NGHTTP2_EXTERN int nghttp2_session_consume_connection(nghttp2_session *session,
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.
3558 * This function returns 0 if it succeeds, or one of the following
3559 * negative error codes:
3561 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
3568 NGHTTP2_EXTERN int nghttp2_session_consume_stream(nghttp2_session *session,
3575 * Changes priority of existing stream denoted by |stream_id|. The
3576 * new priority specification is |pri_spec|.
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
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.
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.
3592 * This function returns 0 if it succeeds, or one of the following
3593 * negative error codes:
3595 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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
3602 nghttp2_session_change_stream_priority(nghttp2_session *session,
3604 const nghttp2_priority_spec *pri_spec);
3609 * Creates idle stream with the given |stream_id|, and priority
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.
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.
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.
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.
3635 * This function returns 0 if it succeeds, or one of the following
3636 * negative error codes:
3638 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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
3648 nghttp2_session_create_idle_stream(nghttp2_session *session, int32_t stream_id,
3649 const nghttp2_priority_spec *pri_spec);
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.
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.
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.
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).
3688 * This function returns 0 if it succeeds, or one of the following
3689 * negative error codes:
3691 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
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);
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.
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.
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).
3729 * If the request method is HEAD, pass nonzero value to
3730 * |head_request|. Otherwise, pass 0.
3732 * This function returns 0 if it succeeds, or one of the following
3733 * negative error codes:
3735 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
3742 NGHTTP2_EXTERN int nghttp2_session_upgrade2(nghttp2_session *session,
3743 const uint8_t *settings_payload,
3744 size_t settings_payloadlen,
3746 void *stream_user_data);
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.
3760 * This function returns the number of bytes written in |buf|, or one
3761 * of the following negative error codes:
3763 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
3764 * The |iv| contains duplicate settings ID or invalid value.
3766 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
3767 * The provided |buflen| size is too small to hold the output.
3769 NGHTTP2_EXTERN ssize_t nghttp2_pack_settings_payload(
3770 uint8_t *buf, size_t buflen, const nghttp2_settings_entry *iv, size_t niv);
3775 * Returns string describing the |lib_error_code|. The
3776 * |lib_error_code| must be one of the :enum:`nghttp2_error`.
3778 NGHTTP2_EXTERN const char *nghttp2_strerror(int lib_error_code);
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``.
3788 NGHTTP2_EXTERN const char *nghttp2_http2_strerror(uint32_t error_code);
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.
3797 * The |weight| must be in [:macro:`NGHTTP2_MIN_WEIGHT`,
3798 * :macro:`NGHTTP2_MAX_WEIGHT`], inclusive.
3800 NGHTTP2_EXTERN void nghttp2_priority_spec_init(nghttp2_priority_spec *pri_spec,
3802 int32_t weight, int exclusive);
3807 * Initializes |pri_spec| with the default values. The default values
3808 * are: stream_id = 0, weight = :macro:`NGHTTP2_DEFAULT_WEIGHT` and
3812 nghttp2_priority_spec_default_init(nghttp2_priority_spec *pri_spec);
3817 * Returns nonzero if the |pri_spec| is filled with default values.
3820 nghttp2_priority_spec_check_default(const nghttp2_priority_spec *pri_spec);
3825 * Submits HEADERS frame and optionally one or more DATA frames.
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.
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`.
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
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.
3858 * HTTP/2 specification has requirement about header fields in the
3859 * request HEADERS. See the specification for more details.
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()`.
3873 * This function returns assigned stream ID if it succeeds, or one of
3874 * the following negative error codes:
3876 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
3878 * :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
3879 * No stream ID is available because maximum stream ID was
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.
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.
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);
3907 * Submits response HEADERS frame and optionally one or more DATA
3908 * frames against the stream |stream_id|.
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
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.
3928 * HTTP/2 specification has requirement about header fields in the
3929 * response HEADERS. See the specification for more details.
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.
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()`.
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.
3947 * This function returns 0 if it succeeds, or one of the following
3948 * negative error codes:
3950 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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,
3959 * :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
3960 * The |session| is client session.
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.
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);
3976 * Submits trailer fields HEADERS against the stream |stream_id|.
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|.
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.
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.
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.
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`.
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:
4019 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4021 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
4022 * The |stream_id| is 0.
4024 NGHTTP2_EXTERN int nghttp2_submit_trailer(nghttp2_session *session,
4026 const nghttp2_nv *nva, size_t nvlen);
4031 * Submits HEADERS frame. The |flags| is bitwise OR of the
4034 * * :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`
4036 * If |flags| includes :enum:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`,
4037 * this frame has END_STREAM flag set.
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.
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
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.
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`.
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
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.
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.
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()`.
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:
4092 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4094 * :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
4095 * No stream ID is available because maximum stream ID was
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.
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
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);
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.
4129 * This function does not take ownership of the |data_prd|. The
4130 * function copies the members of the |data_prd|.
4132 * This function returns 0 if it succeeds, or one of the following
4133 * negative error codes:
4135 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4137 * :enum:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
4138 * DATA or HEADERS has been already submitted and not fully
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.
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
4162 NGHTTP2_EXTERN int nghttp2_submit_data(nghttp2_session *session, uint8_t flags,
4164 const nghttp2_data_provider *data_prd);
4169 * Submits PRIORITY frame to change the priority of stream |stream_id|
4170 * to the priority specification |pri_spec|.
4172 * The |flags| is currently ignored and should be
4173 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
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
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`.
4187 * This function returns 0 if it succeeds, or one of the following
4188 * negative error codes:
4190 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4192 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
4193 * The |stream_id| is 0; or the |pri_spec| is NULL; or trying to
4197 nghttp2_submit_priority(nghttp2_session *session, uint8_t flags,
4199 const nghttp2_priority_spec *pri_spec);
4204 * Submits RST_STREAM frame to cancel/reject the stream |stream_id|
4205 * with the error code |error_code|.
4207 * The pre-defined error code is one of :enum:`nghttp2_error_code`.
4209 * The |flags| is currently ignored and should be
4210 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
4212 * This function returns 0 if it succeeds, or one of the following
4213 * negative error codes:
4215 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4217 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
4218 * The |stream_id| is 0.
4220 NGHTTP2_EXTERN int nghttp2_submit_rst_stream(nghttp2_session *session,
4221 uint8_t flags, int32_t stream_id,
4222 uint32_t error_code);
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`.
4231 * The |flags| is currently ignored and should be
4232 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
4234 * This function does not take ownership of the |iv|. This function
4235 * copies all the elements in the |iv|.
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.
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.
4245 * This function returns 0 if it succeeds, or one of the following
4246 * negative error codes:
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`
4254 NGHTTP2_EXTERN int nghttp2_submit_settings(nghttp2_session *session,
4256 const nghttp2_settings_entry *iv,
4262 * Submits PUSH_PROMISE frame.
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.
4268 * The |stream_id| must be client initiated stream ID.
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
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.
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.
4295 * The client side is not allowed to use this function.
4297 * To submit response headers and data, use
4298 * `nghttp2_submit_response()`.
4300 * This function returns assigned promised stream ID if it succeeds,
4301 * or one of the following negative error codes:
4303 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4305 * :enum:`nghttp2_error.NGHTTP2_ERR_PROTO`
4306 * This function was invoked when |session| is initialized as
4308 * :enum:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
4309 * No stream ID is available because maximum stream ID was
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.
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.
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.
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);
4337 * Submits PING frame. You don't have to send PING back when you
4338 * received PING frame. The library automatically submits PING frame
4341 * The |flags| is bitwise OR of 0 or more of the following value.
4343 * * :enum:`nghttp2_flag.NGHTTP2_FLAG_ACK`
4345 * Unless `nghttp2_option_set_no_auto_ping_ack()` is used, the |flags|
4346 * should be :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
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.
4353 * This function returns 0 if it succeeds, or one of the following
4354 * negative error codes:
4356 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4359 NGHTTP2_EXTERN int nghttp2_submit_ping(nghttp2_session *session, uint8_t flags,
4360 const uint8_t *opaque_data);
4365 * Submits GOAWAY frame with the last stream ID |last_stream_id| and
4366 * the error code |error_code|.
4368 * The pre-defined error code is one of :enum:`nghttp2_error_code`.
4370 * The |flags| is currently ignored and should be
4371 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
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
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
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``.
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.
4398 * This function returns 0 if it succeeds, or one of the following
4399 * negative error codes:
4401 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4403 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
4404 * The |opaque_data_len| is too large; the |last_stream_id| is
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);
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()`.
4422 * This function always succeeds.
4424 NGHTTP2_EXTERN int32_t
4425 nghttp2_session_get_last_proc_stream_id(nghttp2_session *session);
4430 * Returns nonzero if new request can be sent from local endpoint.
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.
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.
4443 nghttp2_session_check_request_allowed(nghttp2_session *session);
4448 * Returns nonzero if |session| is initialized as server side session.
4451 nghttp2_session_check_server_session(nghttp2_session *session);
4456 * Submits WINDOW_UPDATE frame.
4458 * The |flags| is currently ignored and should be
4459 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
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|.
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()`.
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()`.
4480 * If the |window_size_increment| is 0, the function does nothing and
4483 * This function returns 0 if it succeeds, or one of the following
4484 * negative error codes:
4486 * :enum:`nghttp2_error.NGHTTP2_ERR_FLOW_CONTROL`
4487 * The local window size overflow or gets negative.
4488 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4491 NGHTTP2_EXTERN int nghttp2_submit_window_update(nghttp2_session *session,
4494 int32_t window_size_increment);
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.
4505 * The |flags| is currently ignored and should be
4506 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
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.
4522 * This function returns 0 if it succeeds, or one of the following
4523 * negative error codes:
4525 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
4526 * The |stream_id| is negative.
4527 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4531 nghttp2_session_set_local_window_size(nghttp2_session *session, uint8_t flags,
4532 int32_t stream_id, int32_t window_size);
4537 * Submits extension frame.
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.
4545 * The application must set :type:`nghttp2_pack_extension_callback`
4546 * using `nghttp2_session_callbacks_set_pack_extension_callback()`.
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`.
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`.
4561 * This function returns 0 if it succeeds, or one of the following
4562 * negative error codes:
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`
4573 NGHTTP2_EXTERN int nghttp2_submit_extension(nghttp2_session *session,
4574 uint8_t type, uint8_t flags,
4575 int32_t stream_id, void *payload);
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.
4587 * It has the following members:
4591 * The pointer to origin which this alternative service is
4592 * associated with. This is not necessarily NULL-terminated.
4596 * The length of the |origin|.
4600 * The pointer to Alt-Svc field value contained in ALTSVC frame.
4601 * This is not necessarily NULL-terminated.
4603 uint8_t *field_value;
4605 * The length of the |field_value|.
4607 size_t field_value_len;
4608 } nghttp2_ext_altsvc;
4613 * Submits ALTSVC frame.
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>`_.
4618 * The |flags| is currently ignored and should be
4619 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
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|
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`.
4631 * This function returns 0 if it succeeds, or one of the following
4632 * negative error codes:
4634 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
4643 NGHTTP2_EXTERN int nghttp2_submit_altsvc(nghttp2_session *session,
4644 uint8_t flags, int32_t stream_id,
4645 const uint8_t *origin,
4647 const uint8_t *field_value,
4648 size_t field_value_len);
4653 * The single entry of an origin.
4657 * The pointer to origin. No validation is made against this field
4658 * by the library. This is not necessarily NULL-terminated.
4662 * The length of the |origin|.
4665 } nghttp2_origin_entry;
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>`_.
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.
4680 * It has the following members:
4684 * The number of origins contained in |ov|.
4688 * The pointer to the array of origins contained in ORIGIN frame.
4690 nghttp2_origin_entry *ov;
4691 } nghttp2_ext_origin;
4696 * Submits ORIGIN frame.
4698 * ORIGIN frame is a non-critical extension to HTTP/2 and defined by
4699 * `RFC 8336 <https://tools.ietf.org/html/rfc8336>`_.
4701 * The |flags| is currently ignored and should be
4702 * :enum:`nghttp2_flag.NGHTTP2_FLAG_NONE`.
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|.
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`.
4712 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
4720 NGHTTP2_EXTERN int nghttp2_submit_origin(nghttp2_session *session,
4722 const nghttp2_origin_entry *ov,
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.
4734 NGHTTP2_EXTERN int nghttp2_nv_compare_name(const nghttp2_nv *lhs,
4735 const nghttp2_nv *rhs);
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::
4749 * in[4..11] = "http/1.1"
4752 * The selection algorithm is as follows:
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.
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.
4760 * 3. This function selects nothing and returns -1 (So called
4761 * non-overlap case). In this case, |out| and |outlen| are left
4764 * Selecting ``h2`` means that ``h2`` is written into |*out| and its
4765 * length (which is 2) is assigned to |*outlen|.
4767 * For ALPN, refer to https://tools.ietf.org/html/rfc7301
4769 * See http://technotes.googlecode.com/git/nextprotoneg.html for more
4770 * details about NPN.
4772 * For NPN, to use this method you should do something like::
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,
4782 * rv = nghttp2_select_next_protocol(out, outlen, in, inlen);
4784 * return SSL_TLSEXT_ERR_NOACK;
4787 * ((MyType*)arg)->http2_selected = 1;
4789 * return SSL_TLSEXT_ERR_OK;
4792 * SSL_CTX_set_next_proto_select_cb(ssl_ctx, select_next_proto_cb, my_obj);
4795 NGHTTP2_EXTERN int nghttp2_select_next_protocol(unsigned char **out,
4796 unsigned char *outlen,
4797 const unsigned char *in,
4798 unsigned int inlen);
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.
4809 NGHTTP2_EXTERN nghttp2_info *nghttp2_version(int least_version);
4814 * Returns nonzero if the :type:`nghttp2_error` library error code
4815 * |lib_error| is fatal.
4817 NGHTTP2_EXTERN int nghttp2_is_fatal(int lib_error_code);
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
4825 * Because this is a header field name in HTTP2, the upper cased alphabet
4826 * is treated as error.
4828 NGHTTP2_EXTERN int nghttp2_check_header_name(const uint8_t *name, size_t len);
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
4837 NGHTTP2_EXTERN int nghttp2_check_header_value(const uint8_t *value, size_t len);
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
4847 NGHTTP2_EXTERN int nghttp2_check_method(const uint8_t *value, size_t len);
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
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.
4861 NGHTTP2_EXTERN int nghttp2_check_path(const uint8_t *value, size_t len);
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
4870 * |value| is valid if it merely consists of the allowed characters.
4871 * In particular, it does not check whether |value| follows the syntax
4874 NGHTTP2_EXTERN int nghttp2_check_authority(const uint8_t *value, size_t len);
4878 struct nghttp2_hd_deflater;
4883 * HPACK deflater object.
4885 typedef struct nghttp2_hd_deflater nghttp2_hd_deflater;
4890 * Initializes |*deflater_ptr| for deflating name/values pairs.
4892 * The |max_deflate_dynamic_table_size| is the upper bound of header
4893 * table size the deflater will use.
4895 * If this function fails, |*deflater_ptr| is left untouched.
4897 * This function returns 0 if it succeeds, or one of the following
4898 * negative error codes:
4900 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4904 nghttp2_hd_deflate_new(nghttp2_hd_deflater **deflater_ptr,
4905 size_t max_deflate_dynamic_table_size);
4910 * Like `nghttp2_hd_deflate_new()`, but with additional custom memory
4911 * allocator specified in the |mem|.
4913 * The |mem| can be ``NULL`` and the call is equivalent to
4914 * `nghttp2_hd_deflate_new()`.
4916 * This function does not take ownership |mem|. The application is
4917 * responsible for freeing |mem|.
4919 * The library code does not refer to |mem| pointer after this
4920 * function returns, so the application can safely free it.
4923 nghttp2_hd_deflate_new2(nghttp2_hd_deflater **deflater_ptr,
4924 size_t max_deflate_dynamic_table_size,
4930 * Deallocates any resources allocated for |deflater|.
4932 NGHTTP2_EXTERN void nghttp2_hd_deflate_del(nghttp2_hd_deflater *deflater);
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.
4941 * The |settings_max_dynamic_table_size| should be the value received
4942 * in SETTINGS_HEADER_TABLE_SIZE.
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``.
4951 * This function returns 0 if it succeeds, or one of the following
4952 * negative error codes:
4954 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
4958 nghttp2_hd_deflate_change_table_size(nghttp2_hd_deflater *deflater,
4959 size_t settings_max_dynamic_table_size);
4964 * Deflates the |nva|, which has the |nvlen| name/value pairs, into
4965 * the |buf| of length |buflen|.
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.
4973 * Once this function fails, subsequent call of this function always
4974 * returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`.
4976 * After this function returns, it is safe to delete the |nva|.
4978 * This function returns the number of bytes written to |buf| if it
4979 * succeeds, or one of the following negative error codes:
4981 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
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,
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.
5006 * Once this function fails, subsequent call of this function always
5007 * returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`.
5009 * After this function returns, it is safe to delete the |nva|.
5011 * This function returns the number of bytes written to |vec| if it
5012 * succeeds, or one of the following negative error codes:
5014 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
5021 NGHTTP2_EXTERN ssize_t nghttp2_hd_deflate_hd_vec(nghttp2_hd_deflater *deflater,
5022 const nghttp2_vec *vec,
5024 const nghttp2_nv *nva,
5030 * Returns an upper bound on the compressed size after deflation of
5031 * |nva| of length |nvlen|.
5033 NGHTTP2_EXTERN size_t nghttp2_hd_deflate_bound(nghttp2_hd_deflater *deflater,
5034 const nghttp2_nv *nva,
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.
5045 size_t nghttp2_hd_deflate_get_num_table_entries(nghttp2_hd_deflater *deflater);
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.
5059 nghttp2_hd_deflate_get_table_entry(nghttp2_hd_deflater *deflater, size_t idx);
5064 * Returns the used dynamic table size, including the overhead 32
5065 * bytes per entry described in RFC 7541.
5068 size_t nghttp2_hd_deflate_get_dynamic_table_size(nghttp2_hd_deflater *deflater);
5073 * Returns the maximum dynamic table size.
5077 nghttp2_hd_deflate_get_max_dynamic_table_size(nghttp2_hd_deflater *deflater);
5079 struct nghttp2_hd_inflater;
5084 * HPACK inflater object.
5086 typedef struct nghttp2_hd_inflater nghttp2_hd_inflater;
5091 * Initializes |*inflater_ptr| for inflating name/values pairs.
5093 * If this function fails, |*inflater_ptr| is left untouched.
5095 * This function returns 0 if it succeeds, or one of the following
5096 * negative error codes:
5098 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
5101 NGHTTP2_EXTERN int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr);
5106 * Like `nghttp2_hd_inflate_new()`, but with additional custom memory
5107 * allocator specified in the |mem|.
5109 * The |mem| can be ``NULL`` and the call is equivalent to
5110 * `nghttp2_hd_inflate_new()`.
5112 * This function does not take ownership |mem|. The application is
5113 * responsible for freeing |mem|.
5115 * The library code does not refer to |mem| pointer after this
5116 * function returns, so the application can safely free it.
5118 NGHTTP2_EXTERN int nghttp2_hd_inflate_new2(nghttp2_hd_inflater **inflater_ptr,
5124 * Deallocates any resources allocated for |inflater|.
5126 NGHTTP2_EXTERN void nghttp2_hd_inflate_del(nghttp2_hd_inflater *inflater);
5131 * Changes header table size in the |inflater|. This may trigger
5132 * eviction in the dynamic table.
5134 * The |settings_max_dynamic_table_size| should be the value
5135 * transmitted in SETTINGS_HEADER_TABLE_SIZE.
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.
5144 * This function returns 0 if it succeeds, or one of the following
5145 * negative error codes:
5147 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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()`.
5155 nghttp2_hd_inflate_change_table_size(nghttp2_hd_inflater *inflater,
5156 size_t settings_max_dynamic_table_size);
5161 * The flags for header inflation.
5167 NGHTTP2_HD_INFLATE_NONE = 0,
5169 * Indicates all headers were inflated.
5171 NGHTTP2_HD_INFLATE_FINAL = 0x01,
5173 * Indicates a header was emitted.
5175 NGHTTP2_HD_INFLATE_EMIT = 0x02
5176 } nghttp2_hd_inflate_flag;
5183 * Deprecated. Use `nghttp2_hd_inflate_hd2()` instead.
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
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.
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
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
5208 * This function returns the number of bytes processed if it succeeds,
5209 * or one of the following negative error codes:
5211 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
5220 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
5221 * uint8_t *in, size_t inlen, int final)
5227 * int inflate_flags = 0;
5229 * rv = nghttp2_hd_inflate_hd(hd_inflater, &nv, &inflate_flags,
5230 * in, inlen, final);
5233 * fprintf(stderr, "inflate failed with error code %zd", rv);
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");
5246 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
5247 * nghttp2_hd_inflate_end_headers(hd_inflater);
5250 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
5260 NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd(nghttp2_hd_inflater *inflater,
5262 int *inflate_flags, uint8_t *in,
5263 size_t inlen, int in_final);
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
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.
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.
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
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
5296 * This function returns the number of bytes processed if it succeeds,
5297 * or one of the following negative error codes:
5299 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
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.
5308 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
5309 * uint8_t *in, size_t inlen, int final)
5315 * int inflate_flags = 0;
5317 * rv = nghttp2_hd_inflate_hd2(hd_inflater, &nv, &inflate_flags,
5318 * in, inlen, final);
5321 * fprintf(stderr, "inflate failed with error code %zd", rv);
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");
5334 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
5335 * nghttp2_hd_inflate_end_headers(hd_inflater);
5338 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
5348 NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd2(nghttp2_hd_inflater *inflater,
5351 const uint8_t *in, size_t inlen,
5357 * Signals the end of decompression for one header block.
5359 * This function returns 0 if it succeeds. Currently this function
5363 nghttp2_hd_inflate_end_headers(nghttp2_hd_inflater *inflater);
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.
5373 size_t nghttp2_hd_inflate_get_num_table_entries(nghttp2_hd_inflater *inflater);
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.
5387 nghttp2_hd_inflate_get_table_entry(nghttp2_hd_inflater *inflater, size_t idx);
5392 * Returns the used dynamic table size, including the overhead 32
5393 * bytes per entry described in RFC 7541.
5396 size_t nghttp2_hd_inflate_get_dynamic_table_size(nghttp2_hd_inflater *inflater);
5401 * Returns the maximum dynamic table size.
5405 nghttp2_hd_inflate_get_max_dynamic_table_size(nghttp2_hd_inflater *inflater);
5407 struct nghttp2_stream;
5412 * The structure to represent HTTP/2 stream. The details of this
5413 * structure are intentionally hidden from the public API.
5415 typedef struct nghttp2_stream nghttp2_stream;
5420 * Returns pointer to :type:`nghttp2_stream` object denoted by
5421 * |stream_id|. If stream was not found, returns NULL.
5423 * Returns imaginary root stream (see
5424 * `nghttp2_session_get_root_stream()`) if 0 is given in |stream_id|.
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()`.
5430 NGHTTP2_EXTERN nghttp2_stream *
5431 nghttp2_session_find_stream(nghttp2_session *session, int32_t stream_id);
5436 * State of stream as described in RFC 7540.
5442 NGHTTP2_STREAM_STATE_IDLE = 1,
5446 NGHTTP2_STREAM_STATE_OPEN,
5448 * reserved (local) state.
5450 NGHTTP2_STREAM_STATE_RESERVED_LOCAL,
5452 * reserved (remote) state.
5454 NGHTTP2_STREAM_STATE_RESERVED_REMOTE,
5456 * half closed (local) state.
5458 NGHTTP2_STREAM_STATE_HALF_CLOSED_LOCAL,
5460 * half closed (remote) state.
5462 NGHTTP2_STREAM_STATE_HALF_CLOSED_REMOTE,
5466 NGHTTP2_STREAM_STATE_CLOSED
5467 } nghttp2_stream_proto_state;
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`.
5476 NGHTTP2_EXTERN nghttp2_stream_proto_state
5477 nghttp2_stream_get_state(nghttp2_stream *stream);
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()`.
5486 NGHTTP2_EXTERN nghttp2_stream *
5487 nghttp2_session_get_root_stream(nghttp2_session *session);
5492 * Returns the parent stream of |stream| in dependency tree. Returns
5493 * NULL if there is no such stream.
5495 NGHTTP2_EXTERN nghttp2_stream *
5496 nghttp2_stream_get_parent(nghttp2_stream *stream);
5498 NGHTTP2_EXTERN int32_t nghttp2_stream_get_stream_id(nghttp2_stream *stream);
5503 * Returns the next sibling stream of |stream| in dependency tree.
5504 * Returns NULL if there is no such stream.
5506 NGHTTP2_EXTERN nghttp2_stream *
5507 nghttp2_stream_get_next_sibling(nghttp2_stream *stream);
5512 * Returns the previous sibling stream of |stream| in dependency tree.
5513 * Returns NULL if there is no such stream.
5515 NGHTTP2_EXTERN nghttp2_stream *
5516 nghttp2_stream_get_previous_sibling(nghttp2_stream *stream);
5521 * Returns the first child stream of |stream| in dependency tree.
5522 * Returns NULL if there is no such stream.
5524 NGHTTP2_EXTERN nghttp2_stream *
5525 nghttp2_stream_get_first_child(nghttp2_stream *stream);
5530 * Returns dependency weight to the parent stream of |stream|.
5532 NGHTTP2_EXTERN int32_t nghttp2_stream_get_weight(nghttp2_stream *stream);
5537 * Returns the sum of the weight for |stream|'s children.
5539 NGHTTP2_EXTERN int32_t
5540 nghttp2_stream_get_sum_dependency_weight(nghttp2_stream *stream);
5545 * Callback function invoked when the library outputs debug logging.
5546 * The function is called with arguments suitable for ``vfprintf(3)``
5548 * The debug output is only enabled if the library is built with
5549 * ``DEBUGBUILD`` macro defined.
5551 typedef void (*nghttp2_debug_vprintf_callback)(const char *format,
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.
5561 * For builds without ``DEBUGBUILD`` macro defined, this function is
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.
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.
5575 NGHTTP2_EXTERN void nghttp2_set_debug_vprintf_callback(
5576 nghttp2_debug_vprintf_callback debug_vprintf_callback);
5582 #endif /* NGHTTP2_H */