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)
39 #if defined(_MSC_VER) && (_MSC_VER < 1800)
40 /* MSVC < 2013 does not have inttypes.h because it is not C99
41 compliant. See compiler macros and version number in
42 https://sourceforge.net/p/predef/wiki/Compilers/ */
44 #else /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */
46 #endif /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */
47 #include <sys/types.h>
49 #include <nghttp2/nghttp2ver.h>
51 #ifdef NGHTTP2_STATICLIB
52 #define NGHTTP2_EXTERN
54 #ifdef BUILDING_NGHTTP2
55 #define NGHTTP2_EXTERN __declspec(dllexport)
56 #else /* !BUILDING_NGHTTP2 */
57 #define NGHTTP2_EXTERN __declspec(dllimport)
58 #endif /* !BUILDING_NGHTTP2 */
59 #else /* !defined(WIN32) */
60 #ifdef BUILDING_NGHTTP2
61 #define NGHTTP2_EXTERN __attribute__((visibility("default")))
62 #else /* !BUILDING_NGHTTP2 */
63 #define NGHTTP2_EXTERN
64 #endif /* !BUILDING_NGHTTP2 */
65 #endif /* !defined(WIN32) */
70 * The protocol version identification string of this library
71 * supports. This identifier is used if HTTP/2 is used over TLS.
73 #define NGHTTP2_PROTO_VERSION_ID "h2"
77 * The length of :macro:`NGHTTP2_PROTO_VERSION_ID`.
79 #define NGHTTP2_PROTO_VERSION_ID_LEN 2
84 * The serialized form of ALPN protocol identifier this library
85 * supports. Notice that first byte is the length of following
86 * protocol identifier. This is the same wire format of `TLS ALPN
87 * extension <https://tools.ietf.org/html/rfc7301>`_. This is useful
88 * to process incoming ALPN tokens in wire format.
90 #define NGHTTP2_PROTO_ALPN "\x2h2"
95 * The length of :macro:`NGHTTP2_PROTO_ALPN`.
97 #define NGHTTP2_PROTO_ALPN_LEN (sizeof(NGHTTP2_PROTO_ALPN) - 1)
102 * The protocol version identification string of this library
103 * supports. This identifier is used if HTTP/2 is used over cleartext
106 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID "h2c"
111 * The length of :macro:`NGHTTP2_CLEARTEXT_PROTO_VERSION_ID`.
113 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN 3
115 struct nghttp2_session;
119 * The primary structure to hold the resources needed for a HTTP/2
120 * session. The details of this structure are intentionally hidden
121 * from the public API.
123 typedef struct nghttp2_session nghttp2_session;
128 * The age of :type:`nghttp2_info`
130 #define NGHTTP2_VERSION_AGE 1
135 * This struct is what `nghttp2_version()` returns. It holds
136 * information about the particular nghttp2 version.
140 * Age of this struct. This instance of nghttp2 sets it to
141 * :macro:`NGHTTP2_VERSION_AGE` but a future version may bump it and
142 * add more struct fields at the bottom
146 * the :macro:`NGHTTP2_VERSION_NUM` number (since age ==1)
150 * points to the :macro:`NGHTTP2_VERSION` string (since age ==1)
152 const char *version_str;
154 * points to the :macro:`NGHTTP2_PROTO_VERSION_ID` string this
155 * instance implements (since age ==1)
157 const char *proto_str;
158 /* -------- the above fields all exist when age == 1 */
164 * The default weight of stream dependency.
166 #define NGHTTP2_DEFAULT_WEIGHT 16
171 * The maximum weight of stream dependency.
173 #define NGHTTP2_MAX_WEIGHT 256
178 * The minimum weight of stream dependency.
180 #define NGHTTP2_MIN_WEIGHT 1
185 * The maximum window size
187 #define NGHTTP2_MAX_WINDOW_SIZE ((int32_t)((1U << 31) - 1))
192 * The initial window size for stream level flow control.
194 #define NGHTTP2_INITIAL_WINDOW_SIZE ((1 << 16) - 1)
198 * The initial window size for connection level flow control.
200 #define NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE ((1 << 16) - 1)
205 * The default header table size.
207 #define NGHTTP2_DEFAULT_HEADER_TABLE_SIZE (1 << 12)
212 * The client magic string, which is the first 24 bytes byte string of
213 * client connection preface.
215 #define NGHTTP2_CLIENT_MAGIC "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
220 * The length of :macro:`NGHTTP2_CLIENT_MAGIC`.
222 #define NGHTTP2_CLIENT_MAGIC_LEN 24
227 * Error codes used in this library. The code range is [-999, -500],
228 * inclusive. The following values are defined:
232 * Invalid argument passed.
234 NGHTTP2_ERR_INVALID_ARGUMENT = -501,
236 * Out of buffer space.
238 NGHTTP2_ERR_BUFFER_ERROR = -502,
240 * The specified protocol version is not supported.
242 NGHTTP2_ERR_UNSUPPORTED_VERSION = -503,
244 * Used as a return value from :type:`nghttp2_send_callback`,
245 * :type:`nghttp2_recv_callback` and
246 * :type:`nghttp2_send_data_callback` to indicate that the operation
249 NGHTTP2_ERR_WOULDBLOCK = -504,
251 * General protocol error
253 NGHTTP2_ERR_PROTO = -505,
255 * The frame is invalid.
257 NGHTTP2_ERR_INVALID_FRAME = -506,
259 * The peer performed a shutdown on the connection.
261 NGHTTP2_ERR_EOF = -507,
263 * Used as a return value from
264 * :func:`nghttp2_data_source_read_callback` to indicate that data
265 * transfer is postponed. See
266 * :func:`nghttp2_data_source_read_callback` for details.
268 NGHTTP2_ERR_DEFERRED = -508,
270 * Stream ID has reached the maximum value. Therefore no stream ID
273 NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE = -509,
275 * The stream is already closed; or the stream ID is invalid.
277 NGHTTP2_ERR_STREAM_CLOSED = -510,
279 * RST_STREAM has been added to the outbound queue. The stream is
282 NGHTTP2_ERR_STREAM_CLOSING = -511,
284 * The transmission is not allowed for this stream (e.g., a frame
285 * with END_STREAM flag set has already sent).
287 NGHTTP2_ERR_STREAM_SHUT_WR = -512,
289 * The stream ID is invalid.
291 NGHTTP2_ERR_INVALID_STREAM_ID = -513,
293 * The state of the stream is not valid (e.g., DATA cannot be sent
294 * to the stream if response HEADERS has not been sent).
296 NGHTTP2_ERR_INVALID_STREAM_STATE = -514,
298 * Another DATA frame has already been deferred.
300 NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515,
302 * Starting new stream is not allowed (e.g., GOAWAY has been sent
305 NGHTTP2_ERR_START_STREAM_NOT_ALLOWED = -516,
307 * GOAWAY has already been sent.
309 NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517,
311 * The received frame contains the invalid header block (e.g., There
312 * are duplicate header names; or the header names are not encoded
313 * in US-ASCII character set and not lower cased; or the header name
314 * is zero-length string; or the header value contains multiple
315 * in-sequence NUL bytes).
317 NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518,
319 * Indicates that the context is not suitable to perform the
320 * requested operation.
322 NGHTTP2_ERR_INVALID_STATE = -519,
324 * The user callback function failed due to the temporal error.
326 NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE = -521,
328 * The length of the frame is invalid, either too large or too small.
330 NGHTTP2_ERR_FRAME_SIZE_ERROR = -522,
332 * Header block inflate/deflate error.
334 NGHTTP2_ERR_HEADER_COMP = -523,
338 NGHTTP2_ERR_FLOW_CONTROL = -524,
340 * Insufficient buffer size given to function.
342 NGHTTP2_ERR_INSUFF_BUFSIZE = -525,
344 * Callback was paused by the application
346 NGHTTP2_ERR_PAUSE = -526,
348 * There are too many in-flight SETTING frame and no more
349 * transmission of SETTINGS is allowed.
351 NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGS = -527,
353 * The server push is disabled.
355 NGHTTP2_ERR_PUSH_DISABLED = -528,
357 * DATA or HEADERS frame for a given stream has been already
358 * submitted and has not been fully processed yet. Application
359 * should wait for the transmission of the previously submitted
360 * frame before submitting another.
362 NGHTTP2_ERR_DATA_EXIST = -529,
364 * The current session is closing due to a connection error or
365 * `nghttp2_session_terminate_session()` is called.
367 NGHTTP2_ERR_SESSION_CLOSING = -530,
369 * Invalid HTTP header field was received and stream is going to be
372 NGHTTP2_ERR_HTTP_HEADER = -531,
374 * Violation in HTTP messaging rule.
376 NGHTTP2_ERR_HTTP_MESSAGING = -532,
378 * Stream was refused.
380 NGHTTP2_ERR_REFUSED_STREAM = -533,
382 * Unexpected internal error, but recovered.
384 NGHTTP2_ERR_INTERNAL = -534,
386 * Indicates that a processing was canceled.
388 NGHTTP2_ERR_CANCEL = -535,
390 * The errors < :enum:`NGHTTP2_ERR_FATAL` mean that the library is
391 * under unexpected condition and processing was terminated (e.g.,
392 * out of memory). If application receives this error code, it must
393 * stop using that :type:`nghttp2_session` object and only allowed
394 * operation for that object is deallocate it using
395 * `nghttp2_session_del()`.
397 NGHTTP2_ERR_FATAL = -900,
399 * Out of memory. This is a fatal error.
401 NGHTTP2_ERR_NOMEM = -901,
403 * The user callback function failed. This is a fatal error.
405 NGHTTP2_ERR_CALLBACK_FAILURE = -902,
407 * Invalid client magic (see :macro:`NGHTTP2_CLIENT_MAGIC`) was
408 * received and further processing is not possible.
410 NGHTTP2_ERR_BAD_CLIENT_MAGIC = -903,
412 * Possible flooding by peer was detected in this HTTP/2 session.
413 * Flooding is measured by how many PING and SETTINGS frames with
414 * ACK flag set are queued for transmission. These frames are
415 * response for the peer initiated frames, and peer can cause memory
416 * exhaustion on server side to send these frames forever and does
419 NGHTTP2_ERR_FLOODED = -904
425 * The object representing single contiguous buffer.
429 * The pointer to the buffer.
433 * The length of the buffer.
438 struct nghttp2_rcbuf;
443 * The object representing reference counted buffer. The details of
444 * this structure are intentionally hidden from the public API.
446 typedef struct nghttp2_rcbuf nghttp2_rcbuf;
451 * Increments the reference count of |rcbuf| by 1.
453 NGHTTP2_EXTERN void nghttp2_rcbuf_incref(nghttp2_rcbuf *rcbuf);
458 * Decrements the reference count of |rcbuf| by 1. If the reference
459 * count becomes zero, the object pointed by |rcbuf| will be freed.
460 * In this case, application must not use |rcbuf| again.
462 NGHTTP2_EXTERN void nghttp2_rcbuf_decref(nghttp2_rcbuf *rcbuf);
467 * Returns the underlying buffer managed by |rcbuf|.
469 NGHTTP2_EXTERN nghttp2_vec nghttp2_rcbuf_get_buf(nghttp2_rcbuf *rcbuf);
474 * The flags for header field name/value pair.
480 NGHTTP2_NV_FLAG_NONE = 0,
482 * Indicates that this name/value pair must not be indexed ("Literal
483 * Header Field never Indexed" representation must be used in HPACK
484 * encoding). Other implementation calls this bit as "sensitive".
486 NGHTTP2_NV_FLAG_NO_INDEX = 0x01,
488 * This flag is set solely by application. If this flag is set, the
489 * library does not make a copy of header field name. This could
490 * improve performance.
492 NGHTTP2_NV_FLAG_NO_COPY_NAME = 0x02,
494 * This flag is set solely by application. If this flag is set, the
495 * library does not make a copy of header field value. This could
496 * improve performance.
498 NGHTTP2_NV_FLAG_NO_COPY_VALUE = 0x04
504 * The name/value pair, which mainly used to represent header fields.
508 * The |name| byte string. If this struct is presented from library
509 * (e.g., :type:`nghttp2_on_frame_recv_callback`), |name| is
510 * guaranteed to be NULL-terminated. For some callbacks
511 * (:type:`nghttp2_before_frame_send_callback`,
512 * :type:`nghttp2_on_frame_send_callback`, and
513 * :type:`nghttp2_on_frame_not_send_callback`), it may not be
514 * NULL-terminated if header field is passed from application with
515 * the flag :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME`). When application
516 * is constructing this struct, |name| is not required to be
521 * The |value| byte string. If this struct is presented from
522 * library (e.g., :type:`nghttp2_on_frame_recv_callback`), |value|
523 * is guaranteed to be NULL-terminated. For some callbacks
524 * (:type:`nghttp2_before_frame_send_callback`,
525 * :type:`nghttp2_on_frame_send_callback`, and
526 * :type:`nghttp2_on_frame_not_send_callback`), it may not be
527 * NULL-terminated if header field is passed from application with
528 * the flag :enum:`NGHTTP2_NV_FLAG_NO_COPY_VALUE`). When
529 * application is constructing this struct, |value| is not required
530 * to be NULL-terminated.
534 * The length of the |name|, excluding terminating NULL.
538 * The length of the |value|, excluding terminating NULL.
542 * Bitwise OR of one or more of :type:`nghttp2_nv_flag`.
550 * The frame types in HTTP/2 specification.
560 NGHTTP2_HEADERS = 0x01,
562 * The PRIORITY frame.
564 NGHTTP2_PRIORITY = 0x02,
566 * The RST_STREAM frame.
568 NGHTTP2_RST_STREAM = 0x03,
570 * The SETTINGS frame.
572 NGHTTP2_SETTINGS = 0x04,
574 * The PUSH_PROMISE frame.
576 NGHTTP2_PUSH_PROMISE = 0x05,
584 NGHTTP2_GOAWAY = 0x07,
586 * The WINDOW_UPDATE frame.
588 NGHTTP2_WINDOW_UPDATE = 0x08,
590 * The CONTINUATION frame. This frame type won't be passed to any
591 * callbacks because the library processes this frame type and its
592 * preceding HEADERS/PUSH_PROMISE as a single frame.
594 NGHTTP2_CONTINUATION = 0x09,
596 * The ALTSVC frame, which is defined in `RFC 7383
597 * <https://tools.ietf.org/html/rfc7838#section-4>`_.
599 NGHTTP2_ALTSVC = 0x0a
600 } nghttp2_frame_type;
605 * The flags for HTTP/2 frames. This enum defines all flags for all
612 NGHTTP2_FLAG_NONE = 0,
614 * The END_STREAM flag.
616 NGHTTP2_FLAG_END_STREAM = 0x01,
618 * The END_HEADERS flag.
620 NGHTTP2_FLAG_END_HEADERS = 0x04,
624 NGHTTP2_FLAG_ACK = 0x01,
628 NGHTTP2_FLAG_PADDED = 0x08,
632 NGHTTP2_FLAG_PRIORITY = 0x20
641 * SETTINGS_HEADER_TABLE_SIZE
643 NGHTTP2_SETTINGS_HEADER_TABLE_SIZE = 0x01,
645 * SETTINGS_ENABLE_PUSH
647 NGHTTP2_SETTINGS_ENABLE_PUSH = 0x02,
649 * SETTINGS_MAX_CONCURRENT_STREAMS
651 NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS = 0x03,
653 * SETTINGS_INITIAL_WINDOW_SIZE
655 NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE = 0x04,
657 * SETTINGS_MAX_FRAME_SIZE
659 NGHTTP2_SETTINGS_MAX_FRAME_SIZE = 0x05,
661 * SETTINGS_MAX_HEADER_LIST_SIZE
663 NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE = 0x06
664 } nghttp2_settings_id;
665 /* Note: If we add SETTINGS, update the capacity of
666 NGHTTP2_INBOUND_NUM_IV as well */
673 * Deprecated. The initial max concurrent streams is 0xffffffffu.
675 * Default maximum number of incoming concurrent streams. Use
676 * `nghttp2_submit_settings()` with
677 * :enum:`NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS` to change the
678 * maximum number of incoming concurrent streams.
682 * The maximum number of outgoing concurrent streams is 100 by
685 #define NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS ((1U << 31) - 1)
689 * The status codes for the RST_STREAM and GOAWAY frames.
695 NGHTTP2_NO_ERROR = 0x00,
699 NGHTTP2_PROTOCOL_ERROR = 0x01,
703 NGHTTP2_INTERNAL_ERROR = 0x02,
707 NGHTTP2_FLOW_CONTROL_ERROR = 0x03,
711 NGHTTP2_SETTINGS_TIMEOUT = 0x04,
715 NGHTTP2_STREAM_CLOSED = 0x05,
719 NGHTTP2_FRAME_SIZE_ERROR = 0x06,
723 NGHTTP2_REFUSED_STREAM = 0x07,
727 NGHTTP2_CANCEL = 0x08,
731 NGHTTP2_COMPRESSION_ERROR = 0x09,
735 NGHTTP2_CONNECT_ERROR = 0x0a,
739 NGHTTP2_ENHANCE_YOUR_CALM = 0x0b,
741 * INADEQUATE_SECURITY
743 NGHTTP2_INADEQUATE_SECURITY = 0x0c,
747 NGHTTP2_HTTP_1_1_REQUIRED = 0x0d
748 } nghttp2_error_code;
756 * The length field of this frame, excluding frame header.
760 * The stream identifier (aka, stream ID)
764 * The type of this frame. See `nghttp2_frame_type`.
772 * Reserved bit in frame header. Currently, this is always set to 0
773 * and application should not expect something useful in here.
781 * This union represents the some kind of data source passed to
782 * :type:`nghttp2_data_source_read_callback`.
786 * The integer field, suitable for a file descriptor.
790 * The pointer to an arbitrary object.
793 } nghttp2_data_source;
798 * The flags used to set in |data_flags| output parameter in
799 * :type:`nghttp2_data_source_read_callback`.
805 NGHTTP2_DATA_FLAG_NONE = 0,
807 * Indicates EOF was sensed.
809 NGHTTP2_DATA_FLAG_EOF = 0x01,
811 * Indicates that END_STREAM flag must not be set even if
812 * NGHTTP2_DATA_FLAG_EOF is set. Usually this flag is used to send
813 * trailer fields with `nghttp2_submit_request()` or
814 * `nghttp2_submit_response()`.
816 NGHTTP2_DATA_FLAG_NO_END_STREAM = 0x02,
818 * Indicates that application will send complete DATA frame in
819 * :type:`nghttp2_send_data_callback`.
821 NGHTTP2_DATA_FLAG_NO_COPY = 0x04
827 * Callback function invoked when the library wants to read data from
828 * the |source|. The read data is sent in the stream |stream_id|.
829 * The implementation of this function must read at most |length|
830 * bytes of data from |source| (or possibly other places) and store
831 * them in |buf| and return number of data stored in |buf|. If EOF is
832 * reached, set :enum:`NGHTTP2_DATA_FLAG_EOF` flag in |*data_flags|.
834 * Sometime it is desirable to avoid copying data into |buf| and let
835 * application to send data directly. To achieve this, set
836 * :enum:`NGHTTP2_DATA_FLAG_NO_COPY` to |*data_flags| (and possibly
837 * other flags, just like when we do copy), and return the number of
838 * bytes to send without copying data into |buf|. The library, seeing
839 * :enum:`NGHTTP2_DATA_FLAG_NO_COPY`, will invoke
840 * :type:`nghttp2_send_data_callback`. The application must send
841 * complete DATA frame in that callback.
843 * If this callback is set by `nghttp2_submit_request()`,
844 * `nghttp2_submit_response()` or `nghttp2_submit_headers()` and
845 * `nghttp2_submit_data()` with flag parameter
846 * :enum:`NGHTTP2_FLAG_END_STREAM` set, and
847 * :enum:`NGHTTP2_DATA_FLAG_EOF` flag is set to |*data_flags|, DATA
848 * frame will have END_STREAM flag set. Usually, this is expected
849 * behaviour and all are fine. One exception is send trailer fields.
850 * You cannot send trailer fields after sending frame with END_STREAM
851 * set. To avoid this problem, one can set
852 * :enum:`NGHTTP2_DATA_FLAG_NO_END_STREAM` along with
853 * :enum:`NGHTTP2_DATA_FLAG_EOF` to signal the library not to set
854 * END_STREAM in DATA frame. Then application can use
855 * `nghttp2_submit_trailer()` to send trailer fields.
856 * `nghttp2_submit_trailer()` can be called inside this callback.
858 * If the application wants to postpone DATA frames (e.g.,
859 * asynchronous I/O, or reading data blocks for long time), it is
860 * achieved by returning :enum:`NGHTTP2_ERR_DEFERRED` without reading
861 * any data in this invocation. The library removes DATA frame from
862 * the outgoing queue temporarily. To move back deferred DATA frame
863 * to outgoing queue, call `nghttp2_session_resume_data()`. In case
864 * of error, there are 2 choices. Returning
865 * :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close the stream
866 * by issuing RST_STREAM with :enum:`NGHTTP2_INTERNAL_ERROR`. If a
867 * different error code is desirable, use
868 * `nghttp2_submit_rst_stream()` with a desired error code and then
869 * return :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. Returning
870 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session
873 typedef ssize_t (*nghttp2_data_source_read_callback)(
874 nghttp2_session *session, int32_t stream_id, uint8_t *buf, size_t length,
875 uint32_t *data_flags, nghttp2_data_source *source, void *user_data);
880 * This struct represents the data source and the way to read a chunk
887 nghttp2_data_source source;
889 * The callback function to read a chunk of data from the |source|.
891 nghttp2_data_source_read_callback read_callback;
892 } nghttp2_data_provider;
897 * The DATA frame. The received data is delivered via
898 * :type:`nghttp2_on_data_chunk_recv_callback`.
903 * The length of the padding in this frame. This includes PAD_HIGH
912 * The category of HEADERS, which indicates the role of the frame. In
913 * HTTP/2 spec, request, response, push response and other arbitrary
914 * headers (e.g., trailer fields) are all called just HEADERS. To
915 * give the application the role of incoming HEADERS frame, we define
916 * several categories.
920 * The HEADERS frame is opening new stream, which is analogous to
921 * SYN_STREAM in SPDY.
923 NGHTTP2_HCAT_REQUEST = 0,
925 * The HEADERS frame is the first response headers, which is
926 * analogous to SYN_REPLY in SPDY.
928 NGHTTP2_HCAT_RESPONSE = 1,
930 * The HEADERS frame is the first headers sent against reserved
933 NGHTTP2_HCAT_PUSH_RESPONSE = 2,
935 * The HEADERS frame which does not apply for the above categories,
936 * which is analogous to HEADERS in SPDY. If non-final response
937 * (e.g., status 1xx) is used, final response HEADERS frame will be
940 NGHTTP2_HCAT_HEADERS = 3
941 } nghttp2_headers_category;
946 * The structure to specify stream dependency.
950 * The stream ID of the stream to depend on. Specifying 0 makes
951 * stream not depend any other stream.
955 * The weight of this dependency.
959 * nonzero means exclusive dependency
962 } nghttp2_priority_spec;
967 * The HEADERS frame. It has the following members:
975 * The length of the padding in this frame. This includes PAD_HIGH
980 * The priority specification
982 nghttp2_priority_spec pri_spec;
984 * The name/value pairs.
988 * The number of name/value pairs in |nva|.
992 * The category of this HEADERS frame.
994 nghttp2_headers_category cat;
1000 * The PRIORITY frame. It has the following members:
1006 nghttp2_frame_hd hd;
1008 * The priority specification.
1010 nghttp2_priority_spec pri_spec;
1016 * The RST_STREAM frame. It has the following members:
1022 nghttp2_frame_hd hd;
1024 * The error code. See :type:`nghttp2_error_code`.
1026 uint32_t error_code;
1027 } nghttp2_rst_stream;
1032 * The SETTINGS ID/Value pair. It has the following members:
1036 * The SETTINGS ID. See :type:`nghttp2_settings_id`.
1038 int32_t settings_id;
1040 * The value of this entry.
1043 } nghttp2_settings_entry;
1048 * The SETTINGS frame. It has the following members:
1054 nghttp2_frame_hd hd;
1056 * The number of SETTINGS ID/Value pairs in |iv|.
1060 * The pointer to the array of SETTINGS ID/Value pair.
1062 nghttp2_settings_entry *iv;
1068 * The PUSH_PROMISE frame. It has the following members:
1074 nghttp2_frame_hd hd;
1076 * The length of the padding in this frame. This includes PAD_HIGH
1081 * The name/value pairs.
1085 * The number of name/value pairs in |nva|.
1089 * The promised stream ID
1091 int32_t promised_stream_id;
1093 * Reserved bit. Currently this is always set to 0 and application
1094 * should not expect something useful in here.
1097 } nghttp2_push_promise;
1102 * The PING frame. It has the following members:
1108 nghttp2_frame_hd hd;
1112 uint8_t opaque_data[8];
1118 * The GOAWAY frame. It has the following members:
1124 nghttp2_frame_hd hd;
1126 * The last stream stream ID.
1128 int32_t last_stream_id;
1130 * The error code. See :type:`nghttp2_error_code`.
1132 uint32_t error_code;
1134 * The additional debug data
1136 uint8_t *opaque_data;
1138 * The length of |opaque_data| member.
1140 size_t opaque_data_len;
1142 * Reserved bit. Currently this is always set to 0 and application
1143 * should not expect something useful in here.
1151 * The WINDOW_UPDATE frame. It has the following members:
1157 nghttp2_frame_hd hd;
1159 * The window size increment.
1161 int32_t window_size_increment;
1163 * Reserved bit. Currently this is always set to 0 and application
1164 * should not expect something useful in here.
1167 } nghttp2_window_update;
1172 * The extension frame. It has following members:
1178 nghttp2_frame_hd hd;
1180 * The pointer to extension payload. The exact pointer type is
1181 * determined by hd.type.
1183 * Currently, no extension is supported. This is a place holder for
1184 * the future extensions.
1187 } nghttp2_extension;
1192 * This union includes all frames to pass them to various function
1193 * calls as nghttp2_frame type. The CONTINUATION frame is omitted
1194 * from here because the library deals with it internally.
1198 * The frame header, which is convenient to inspect frame header.
1200 nghttp2_frame_hd hd;
1206 * The HEADERS frame.
1208 nghttp2_headers headers;
1210 * The PRIORITY frame.
1212 nghttp2_priority priority;
1214 * The RST_STREAM frame.
1216 nghttp2_rst_stream rst_stream;
1218 * The SETTINGS frame.
1220 nghttp2_settings settings;
1222 * The PUSH_PROMISE frame.
1224 nghttp2_push_promise push_promise;
1232 nghttp2_goaway goaway;
1234 * The WINDOW_UPDATE frame.
1236 nghttp2_window_update window_update;
1238 * The extension frame.
1240 nghttp2_extension ext;
1246 * Callback function invoked when |session| wants to send data to the
1247 * remote peer. The implementation of this function must send at most
1248 * |length| bytes of data stored in |data|. The |flags| is currently
1249 * not used and always 0. It must return the number of bytes sent if
1250 * it succeeds. If it cannot send any single byte without blocking,
1251 * it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. For other errors,
1252 * it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. The
1253 * |user_data| pointer is the third argument passed in to the call to
1254 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
1256 * This callback is required if the application uses
1257 * `nghttp2_session_send()` to send data to the remote endpoint. If
1258 * the application uses solely `nghttp2_session_mem_send()` instead,
1259 * this callback function is unnecessary.
1261 * To set this callback to :type:`nghttp2_session_callbacks`, use
1262 * `nghttp2_session_callbacks_set_send_callback()`.
1266 * The |length| may be very small. If that is the case, and
1267 * application disables Nagle algorithm (``TCP_NODELAY``), then just
1268 * writing |data| to the network stack leads to very small packet,
1269 * and it is very inefficient. An application should be responsible
1270 * to buffer up small chunks of data as necessary to avoid this
1273 typedef ssize_t (*nghttp2_send_callback)(nghttp2_session *session,
1274 const uint8_t *data, size_t length,
1275 int flags, void *user_data);
1280 * Callback function invoked when :enum:`NGHTTP2_DATA_FLAG_NO_COPY` is
1281 * used in :type:`nghttp2_data_source_read_callback` to send complete
1284 * The |frame| is a DATA frame to send. The |framehd| is the
1285 * serialized frame header (9 bytes). The |length| is the length of
1286 * application data to send (this does not include padding). The
1287 * |source| is the same pointer passed to
1288 * :type:`nghttp2_data_source_read_callback`.
1290 * The application first must send frame header |framehd| of length 9
1291 * bytes. If ``frame->data.padlen > 0``, send 1 byte of value
1292 * ``frame->data.padlen - 1``. Then send exactly |length| bytes of
1293 * application data. Finally, if ``frame->data.padlen > 1``, send
1294 * ``frame->data.padlen - 1`` bytes of zero as padding.
1296 * The application has to send complete DATA frame in this callback.
1297 * If all data were written successfully, return 0.
1299 * If it cannot send any data at all, just return
1300 * :enum:`NGHTTP2_ERR_WOULDBLOCK`; the library will call this callback
1301 * with the same parameters later (It is recommended to send complete
1302 * DATA frame at once in this function to deal with error; if partial
1303 * frame data has already sent, it is impossible to send another data
1304 * in that state, and all we can do is tear down connection). When
1305 * data is fully processed, but application wants to make
1306 * `nghttp2_session_mem_send()` or `nghttp2_session_send()` return
1307 * immediately without processing next frames, return
1308 * :enum:`NGHTTP2_ERR_PAUSE`. If application decided to reset this
1309 * stream, return :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`, then
1310 * the library will send RST_STREAM with INTERNAL_ERROR as error code.
1311 * The application can also return
1312 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`, which will result in
1313 * connection closure. Returning any other value is treated as
1314 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned.
1316 typedef int (*nghttp2_send_data_callback)(nghttp2_session *session,
1317 nghttp2_frame *frame,
1318 const uint8_t *framehd, size_t length,
1319 nghttp2_data_source *source,
1325 * Callback function invoked when |session| wants to receive data from
1326 * the remote peer. The implementation of this function must read at
1327 * most |length| bytes of data and store it in |buf|. The |flags| is
1328 * currently not used and always 0. It must return the number of
1329 * bytes written in |buf| if it succeeds. If it cannot read any
1330 * single byte without blocking, it must return
1331 * :enum:`NGHTTP2_ERR_WOULDBLOCK`. If it gets EOF before it reads any
1332 * single byte, it must return :enum:`NGHTTP2_ERR_EOF`. For other
1333 * errors, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1334 * Returning 0 is treated as :enum:`NGHTTP2_ERR_WOULDBLOCK`. The
1335 * |user_data| pointer is the third argument passed in to the call to
1336 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
1338 * This callback is required if the application uses
1339 * `nghttp2_session_recv()` to receive data from the remote endpoint.
1340 * If the application uses solely `nghttp2_session_mem_recv()`
1341 * instead, this callback function is unnecessary.
1343 * To set this callback to :type:`nghttp2_session_callbacks`, use
1344 * `nghttp2_session_callbacks_set_recv_callback()`.
1346 typedef ssize_t (*nghttp2_recv_callback)(nghttp2_session *session, uint8_t *buf,
1347 size_t length, int flags,
1353 * Callback function invoked by `nghttp2_session_recv()` and
1354 * `nghttp2_session_mem_recv()` when a frame is received. The
1355 * |user_data| pointer is the third argument passed in to the call to
1356 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
1358 * If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
1359 * member of their data structure are always ``NULL`` and 0
1360 * respectively. The header name/value pairs are emitted via
1361 * :type:`nghttp2_on_header_callback`.
1363 * For HEADERS, PUSH_PROMISE and DATA frames, this callback may be
1364 * called after stream is closed (see
1365 * :type:`nghttp2_on_stream_close_callback`). The application should
1366 * check that stream is still alive using its own stream management or
1367 * :func:`nghttp2_session_get_stream_user_data()`.
1369 * Only HEADERS and DATA frame can signal the end of incoming data.
1370 * If ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
1371 * |frame| is the last frame from the remote peer in this stream.
1373 * This callback won't be called for CONTINUATION frames.
1374 * HEADERS/PUSH_PROMISE + CONTINUATIONs are treated as single frame.
1376 * The implementation of this function must return 0 if it succeeds.
1377 * If nonzero value is returned, it is treated as fatal error and
1378 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1379 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1381 * To set this callback to :type:`nghttp2_session_callbacks`, use
1382 * `nghttp2_session_callbacks_set_on_frame_recv_callback()`.
1384 typedef int (*nghttp2_on_frame_recv_callback)(nghttp2_session *session,
1385 const nghttp2_frame *frame,
1391 * Callback function invoked by `nghttp2_session_recv()` and
1392 * `nghttp2_session_mem_recv()` when an invalid non-DATA frame is
1393 * received. The error is indicated by the |lib_error_code|, which is
1394 * one of the values defined in :type:`nghttp2_error`. When this
1395 * callback function is invoked, the library automatically submits
1396 * either RST_STREAM or GOAWAY frame. The |user_data| pointer is the
1397 * third argument passed in to the call to
1398 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
1400 * If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
1401 * member of their data structure are always ``NULL`` and 0
1404 * The implementation of this function must return 0 if it succeeds.
1405 * If nonzero is returned, it is treated as fatal error and
1406 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1407 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1409 * To set this callback to :type:`nghttp2_session_callbacks`, use
1410 * `nghttp2_session_callbacks_set_on_invalid_frame_recv_callback()`.
1412 typedef int (*nghttp2_on_invalid_frame_recv_callback)(
1413 nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code,
1419 * Callback function invoked when a chunk of data in DATA frame is
1420 * received. The |stream_id| is the stream ID this DATA frame belongs
1421 * to. The |flags| is the flags of DATA frame which this data chunk
1422 * is contained. ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
1423 * necessarily mean this chunk of data is the last one in the stream.
1424 * You should use :type:`nghttp2_on_frame_recv_callback` to know all
1425 * data frames are received. The |user_data| pointer is the third
1426 * argument passed in to the call to `nghttp2_session_client_new()` or
1427 * `nghttp2_session_server_new()`.
1429 * If the application uses `nghttp2_session_mem_recv()`, it can return
1430 * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
1431 * return without processing further input bytes. The memory by
1432 * pointed by the |data| is retained until
1433 * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
1434 * The application must retain the input bytes which was used to
1435 * produce the |data| parameter, because it may refer to the memory
1436 * region included in the input bytes.
1438 * The implementation of this function must return 0 if it succeeds.
1439 * If nonzero is returned, it is treated as fatal error, and
1440 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1441 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1443 * To set this callback to :type:`nghttp2_session_callbacks`, use
1444 * `nghttp2_session_callbacks_set_on_data_chunk_recv_callback()`.
1446 typedef int (*nghttp2_on_data_chunk_recv_callback)(nghttp2_session *session,
1449 const uint8_t *data,
1450 size_t len, void *user_data);
1455 * Callback function invoked just before the non-DATA frame |frame| is
1456 * sent. The |user_data| pointer is the third argument passed in to
1457 * the call to `nghttp2_session_client_new()` or
1458 * `nghttp2_session_server_new()`.
1460 * The implementation of this function must return 0 if it succeeds.
1461 * It can also return :enum:`NGHTTP2_ERR_CANCEL` to cancel the
1462 * transmission of the given frame.
1464 * If there is a fatal error while executing this callback, the
1465 * implementation should return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`,
1466 * which makes `nghttp2_session_send()` and
1467 * `nghttp2_session_mem_send()` functions immediately return
1468 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1470 * If the other value is returned, it is treated as if
1471 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned. But the
1472 * implementation should not rely on this since the library may define
1473 * new return value to extend its capability.
1475 * To set this callback to :type:`nghttp2_session_callbacks`, use
1476 * `nghttp2_session_callbacks_set_before_frame_send_callback()`.
1478 typedef int (*nghttp2_before_frame_send_callback)(nghttp2_session *session,
1479 const nghttp2_frame *frame,
1485 * Callback function invoked after the frame |frame| is sent. The
1486 * |user_data| pointer is the third argument passed in to the call to
1487 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
1489 * The implementation of this function must return 0 if it succeeds.
1490 * If nonzero is returned, it is treated as fatal error and
1491 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
1492 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1494 * To set this callback to :type:`nghttp2_session_callbacks`, use
1495 * `nghttp2_session_callbacks_set_on_frame_send_callback()`.
1497 typedef int (*nghttp2_on_frame_send_callback)(nghttp2_session *session,
1498 const nghttp2_frame *frame,
1504 * Callback function invoked after the non-DATA frame |frame| is not
1505 * sent because of the error. The error is indicated by the
1506 * |lib_error_code|, which is one of the values defined in
1507 * :type:`nghttp2_error`. The |user_data| pointer is the third
1508 * argument passed in to the call to `nghttp2_session_client_new()` or
1509 * `nghttp2_session_server_new()`.
1511 * The implementation of this function must return 0 if it succeeds.
1512 * If nonzero is returned, it is treated as fatal error and
1513 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
1514 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1516 * `nghttp2_session_get_stream_user_data()` can be used to get
1519 * To set this callback to :type:`nghttp2_session_callbacks`, use
1520 * `nghttp2_session_callbacks_set_on_frame_not_send_callback()`.
1522 typedef int (*nghttp2_on_frame_not_send_callback)(nghttp2_session *session,
1523 const nghttp2_frame *frame,
1530 * Callback function invoked when the stream |stream_id| is closed.
1531 * The reason of closure is indicated by the |error_code|. The
1532 * |error_code| is usually one of :enum:`nghttp2_error_code`, but that
1533 * is not guaranteed. The stream_user_data, which was specified in
1534 * `nghttp2_submit_request()` or `nghttp2_submit_headers()`, is still
1535 * available in this function. The |user_data| pointer is the third
1536 * argument passed in to the call to `nghttp2_session_client_new()` or
1537 * `nghttp2_session_server_new()`.
1539 * This function is also called for a stream in reserved state.
1541 * The implementation of this function must return 0 if it succeeds.
1542 * If nonzero is returned, it is treated as fatal error and
1543 * `nghttp2_session_recv()`, `nghttp2_session_mem_recv()`,
1544 * `nghttp2_session_send()`, and `nghttp2_session_mem_send()`
1545 * functions immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1547 * To set this callback to :type:`nghttp2_session_callbacks`, use
1548 * `nghttp2_session_callbacks_set_on_stream_close_callback()`.
1550 typedef int (*nghttp2_on_stream_close_callback)(nghttp2_session *session,
1552 uint32_t error_code,
1558 * Callback function invoked when the reception of header block in
1559 * HEADERS or PUSH_PROMISE is started. Each header name/value pair
1560 * will be emitted by :type:`nghttp2_on_header_callback`.
1562 * The ``frame->hd.flags`` may not have
1563 * :enum:`NGHTTP2_FLAG_END_HEADERS` flag set, which indicates that one
1564 * or more CONTINUATION frames are involved. But the application does
1565 * not need to care about that because the header name/value pairs are
1566 * emitted transparently regardless of CONTINUATION frames.
1568 * The server applications probably create an object to store
1569 * information about new stream if ``frame->hd.type ==
1570 * NGHTTP2_HEADERS`` and ``frame->headers.cat ==
1571 * NGHTTP2_HCAT_REQUEST``. If |session| is configured as server side,
1572 * ``frame->headers.cat`` is either ``NGHTTP2_HCAT_REQUEST``
1573 * containing request headers or ``NGHTTP2_HCAT_HEADERS`` containing
1574 * trailer fields and never get PUSH_PROMISE in this callback.
1576 * For the client applications, ``frame->hd.type`` is either
1577 * ``NGHTTP2_HEADERS`` or ``NGHTTP2_PUSH_PROMISE``. In case of
1578 * ``NGHTTP2_HEADERS``, ``frame->headers.cat ==
1579 * NGHTTP2_HCAT_RESPONSE`` means that it is the first response
1580 * headers, but it may be non-final response which is indicated by 1xx
1581 * status code. In this case, there may be zero or more HEADERS frame
1582 * with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS`` which has
1583 * non-final response code and finally client gets exactly one HEADERS
1584 * frame with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS``
1585 * containing final response headers (non-1xx status code). The
1586 * trailer fields also has ``frame->headers.cat ==
1587 * NGHTTP2_HCAT_HEADERS`` which does not contain any status code.
1589 * Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close
1590 * the stream (promised stream if frame is PUSH_PROMISE) by issuing
1591 * RST_STREAM with :enum:`NGHTTP2_INTERNAL_ERROR`. In this case,
1592 * :type:`nghttp2_on_header_callback` and
1593 * :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a
1594 * different error code is desirable, use
1595 * `nghttp2_submit_rst_stream()` with a desired error code and then
1596 * return :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. Again, use
1597 * ``frame->push_promise.promised_stream_id`` as stream_id parameter
1598 * in `nghttp2_submit_rst_stream()` if frame is PUSH_PROMISE.
1600 * The implementation of this function must return 0 if it succeeds.
1601 * It can return :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` to
1602 * reset the stream (promised stream if frame is PUSH_PROMISE). For
1603 * critical errors, it must return
1604 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If the other value is
1605 * returned, it is treated as if :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
1606 * is returned. If :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
1607 * `nghttp2_session_mem_recv()` function will immediately return
1608 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1610 * To set this callback to :type:`nghttp2_session_callbacks`, use
1611 * `nghttp2_session_callbacks_set_on_begin_headers_callback()`.
1613 typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session,
1614 const nghttp2_frame *frame,
1620 * Callback function invoked when a header name/value pair is received
1621 * for the |frame|. The |name| of length |namelen| is header name.
1622 * The |value| of length |valuelen| is header value. The |flags| is
1623 * bitwise OR of one or more of :type:`nghttp2_nv_flag`.
1625 * If :enum:`NGHTTP2_NV_FLAG_NO_INDEX` is set in |flags|, the receiver
1626 * must not index this name/value pair when forwarding it to the next
1627 * hop. More specifically, "Literal Header Field never Indexed"
1628 * representation must be used in HPACK encoding.
1630 * When this callback is invoked, ``frame->hd.type`` is either
1631 * :enum:`NGHTTP2_HEADERS` or :enum:`NGHTTP2_PUSH_PROMISE`. After all
1632 * header name/value pairs are processed with this callback, and no
1633 * error has been detected, :type:`nghttp2_on_frame_recv_callback`
1634 * will be invoked. If there is an error in decompression,
1635 * :type:`nghttp2_on_frame_recv_callback` for the |frame| will not be
1638 * Both |name| and |value| are guaranteed to be NULL-terminated. The
1639 * |namelen| and |valuelen| do not include terminal NULL. If
1640 * `nghttp2_option_set_no_http_messaging()` is used with nonzero
1641 * value, NULL character may be included in |name| or |value| before
1644 * Please note that unless `nghttp2_option_set_no_http_messaging()` is
1645 * used, nghttp2 library does perform validation against the |name|
1646 * and the |value| using `nghttp2_check_header_name()` and
1647 * `nghttp2_check_header_value()`. In addition to this, nghttp2
1648 * performs validation based on HTTP Messaging rule, which is briefly
1649 * explained in :ref:`http-messaging` section.
1651 * If the application uses `nghttp2_session_mem_recv()`, it can return
1652 * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
1653 * return without processing further input bytes. The memory pointed
1654 * by |frame|, |name| and |value| parameters are retained until
1655 * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
1656 * The application must retain the input bytes which was used to
1657 * produce these parameters, because it may refer to the memory region
1658 * included in the input bytes.
1660 * Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close
1661 * the stream (promised stream if frame is PUSH_PROMISE) by issuing
1662 * RST_STREAM with :enum:`NGHTTP2_INTERNAL_ERROR`. In this case,
1663 * :type:`nghttp2_on_header_callback` and
1664 * :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a
1665 * different error code is desirable, use
1666 * `nghttp2_submit_rst_stream()` with a desired error code and then
1667 * return :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. Again, use
1668 * ``frame->push_promise.promised_stream_id`` as stream_id parameter
1669 * in `nghttp2_submit_rst_stream()` if frame is PUSH_PROMISE.
1671 * The implementation of this function must return 0 if it succeeds.
1672 * It may return :enum:`NGHTTP2_ERR_PAUSE` or
1673 * :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. For other critical
1674 * failures, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If
1675 * the other nonzero value is returned, it is treated as
1676 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If
1677 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
1678 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1679 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1681 * To set this callback to :type:`nghttp2_session_callbacks`, use
1682 * `nghttp2_session_callbacks_set_on_header_callback()`.
1686 * Application should properly limit the total buffer size to store
1687 * incoming header fields. Without it, peer may send large number
1688 * of header fields or large header fields to cause out of memory in
1689 * local endpoint. Due to how HPACK works, peer can do this
1690 * effectively without using much memory on their own.
1692 typedef int (*nghttp2_on_header_callback)(nghttp2_session *session,
1693 const nghttp2_frame *frame,
1694 const uint8_t *name, size_t namelen,
1695 const uint8_t *value, size_t valuelen,
1696 uint8_t flags, void *user_data);
1701 * Callback function invoked when a header name/value pair is received
1702 * for the |frame|. The |name| is header name. The |value| is header
1703 * value. The |flags| is bitwise OR of one or more of
1704 * :type:`nghttp2_nv_flag`.
1706 * This callback behaves like :type:`nghttp2_on_header_callback`,
1707 * except that |name| and |value| are stored in reference counted
1708 * buffer. If application wishes to keep these references without
1709 * copying them, use `nghttp2_rcbuf_incref()` to increment their
1710 * reference count. It is the application's responsibility to call
1711 * `nghttp2_rcbuf_decref()` if they called `nghttp2_rcbuf_incref()` so
1712 * as not to leak memory. If the |session| is created by
1713 * `nghttp2_session_server_new3()` or `nghttp2_session_client_new3()`,
1714 * the function to free memory is the one belongs to the mem
1715 * parameter. As long as this free function alives, |name| and
1716 * |value| can live after |session| was destroyed.
1718 typedef int (*nghttp2_on_header_callback2)(nghttp2_session *session,
1719 const nghttp2_frame *frame,
1720 nghttp2_rcbuf *name,
1721 nghttp2_rcbuf *value, uint8_t flags,
1727 * Callback function invoked when the library asks application how
1728 * many padding bytes are required for the transmission of the
1729 * |frame|. The application must choose the total length of payload
1730 * including padded bytes in range [frame->hd.length, max_payloadlen],
1731 * inclusive. Choosing number not in this range will be treated as
1732 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. Returning
1733 * ``frame->hd.length`` means no padding is added. Returning
1734 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will make
1735 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
1736 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1738 * To set this callback to :type:`nghttp2_session_callbacks`, use
1739 * `nghttp2_session_callbacks_set_select_padding_callback()`.
1741 typedef ssize_t (*nghttp2_select_padding_callback)(nghttp2_session *session,
1742 const nghttp2_frame *frame,
1743 size_t max_payloadlen,
1749 * Callback function invoked when library wants to get max length of
1750 * data to send data to the remote peer. The implementation of this
1751 * function should return a value in the following range. [1,
1752 * min(|session_remote_window_size|, |stream_remote_window_size|,
1753 * |remote_max_frame_size|)]. If a value greater than this range is
1754 * returned than the max allow value will be used. Returning a value
1755 * smaller than this range is treated as
1756 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. The |frame_type| is provided
1757 * for future extensibility and identifies the type of frame (see
1758 * :type:`nghttp2_frame_type`) for which to get the length for.
1759 * Currently supported frame types are: :enum:`NGHTTP2_DATA`.
1761 * This callback can be used to control the length in bytes for which
1762 * :type:`nghttp2_data_source_read_callback` is allowed to send to the
1763 * remote endpoint. This callback is optional. Returning
1764 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session
1767 * To set this callback to :type:`nghttp2_session_callbacks`, use
1768 * `nghttp2_session_callbacks_set_data_source_read_length_callback()`.
1770 typedef ssize_t (*nghttp2_data_source_read_length_callback)(
1771 nghttp2_session *session, uint8_t frame_type, int32_t stream_id,
1772 int32_t session_remote_window_size, int32_t stream_remote_window_size,
1773 uint32_t remote_max_frame_size, void *user_data);
1778 * Callback function invoked when a frame header is received. The
1779 * |hd| points to received frame header.
1781 * Unlike :type:`nghttp2_on_frame_recv_callback`, this callback will
1782 * also be called when frame header of CONTINUATION frame is received.
1784 * If both :type:`nghttp2_on_begin_frame_callback` and
1785 * :type:`nghttp2_on_begin_headers_callback` are set and HEADERS or
1786 * PUSH_PROMISE is received, :type:`nghttp2_on_begin_frame_callback`
1787 * will be called first.
1789 * The implementation of this function must return 0 if it succeeds.
1790 * If nonzero value is returned, it is treated as fatal error and
1791 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1792 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1794 * To set this callback to :type:`nghttp2_session_callbacks`, use
1795 * `nghttp2_session_callbacks_set_on_begin_frame_callback()`.
1797 typedef int (*nghttp2_on_begin_frame_callback)(nghttp2_session *session,
1798 const nghttp2_frame_hd *hd,
1804 * Callback function invoked when chunk of extension frame payload is
1805 * received. The |hd| points to frame header. The received
1806 * chunk is |data| of length |len|.
1808 * The implementation of this function must return 0 if it succeeds.
1810 * To abort processing this extension frame, return
1811 * :enum:`NGHTTP2_ERR_CANCEL`.
1813 * If fatal error occurred, application should return
1814 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
1815 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1816 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If the
1817 * other values are returned, currently they are treated as
1818 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1820 typedef int (*nghttp2_on_extension_chunk_recv_callback)(
1821 nghttp2_session *session, const nghttp2_frame_hd *hd, const uint8_t *data,
1822 size_t len, void *user_data);
1827 * Callback function invoked when library asks the application to
1828 * unpack extension payload from its wire format. The extension
1829 * payload has been passed to the application using
1830 * :type:`nghttp2_on_extension_chunk_recv_callback`. The frame header
1831 * is already unpacked by the library and provided as |hd|.
1833 * To receive extension frames, the application must tell desired
1834 * extension frame type to the library using
1835 * `nghttp2_option_set_user_recv_extension_type()`.
1837 * The implementation of this function may store the pointer to the
1838 * created object as a result of unpacking in |*payload|, and returns
1839 * 0. The pointer stored in |*payload| is opaque to the library, and
1840 * the library does not own its pointer. |*payload| is initialized as
1841 * ``NULL``. The |*payload| is available as ``frame->ext.payload`` in
1842 * :type:`nghttp2_on_frame_recv_callback`. Therefore if application
1843 * can free that memory inside :type:`nghttp2_on_frame_recv_callback`
1844 * callback. Of course, application has a liberty not ot use
1845 * |*payload|, and do its own mechanism to process extension frames.
1847 * To abort processing this extension frame, return
1848 * :enum:`NGHTTP2_ERR_CANCEL`.
1850 * If fatal error occurred, application should return
1851 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
1852 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1853 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If the
1854 * other values are returned, currently they are treated as
1855 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1857 typedef int (*nghttp2_unpack_extension_callback)(nghttp2_session *session,
1859 const nghttp2_frame_hd *hd,
1865 * Callback function invoked when library asks the application to pack
1866 * extension payload in its wire format. The frame header will be
1867 * packed by library. Application must pack payload only.
1868 * ``frame->ext.payload`` is the object passed to
1869 * `nghttp2_submit_extension()` as payload parameter. Application
1870 * must pack extension payload to the |buf| of its capacity |len|
1871 * bytes. The |len| is at least 16KiB.
1873 * The implementation of this function should return the number of
1874 * bytes written into |buf| when it succeeds.
1876 * To abort processing this extension frame, return
1877 * :enum:`NGHTTP2_ERR_CANCEL`, and
1878 * :type:`nghttp2_on_frame_not_send_callback` will be invoked.
1880 * If fatal error occurred, application should return
1881 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
1882 * `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
1883 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If the
1884 * other values are returned, currently they are treated as
1885 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If the return value is
1886 * strictly larger than |len|, it is treated as
1887 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1889 typedef ssize_t (*nghttp2_pack_extension_callback)(nghttp2_session *session,
1890 uint8_t *buf, size_t len,
1891 const nghttp2_frame *frame,
1897 * Callback function invoked when library provides the error message
1898 * intended for human consumption. This callback is solely for
1899 * debugging purpose. The |msg| is typically NULL-terminated string
1900 * of length |len|. |len| does not include the sentinel NULL
1903 * The format of error message may change between nghttp2 library
1904 * versions. The application should not depend on the particular
1907 * Normally, application should return 0 from this callback. If fatal
1908 * error occurred while doing something in this callback, application
1909 * should return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
1910 * library will return immediately with return value
1911 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. Currently, if nonzero value
1912 * is returned from this callback, they are treated as
1913 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`, but application should not
1914 * rely on this details.
1916 typedef int (*nghttp2_error_callback)(nghttp2_session *session, const char *msg,
1917 size_t len, void *user_data);
1919 struct nghttp2_session_callbacks;
1924 * Callback functions for :type:`nghttp2_session`. The details of
1925 * this structure are intentionally hidden from the public API.
1927 typedef struct nghttp2_session_callbacks nghttp2_session_callbacks;
1932 * Initializes |*callbacks_ptr| with NULL values.
1934 * The initialized object can be used when initializing multiple
1935 * :type:`nghttp2_session` objects.
1937 * When the application finished using this object, it can use
1938 * `nghttp2_session_callbacks_del()` to free its memory.
1940 * This function returns 0 if it succeeds, or one of the following
1941 * negative error codes:
1943 * :enum:`NGHTTP2_ERR_NOMEM`
1947 nghttp2_session_callbacks_new(nghttp2_session_callbacks **callbacks_ptr);
1952 * Frees any resources allocated for |callbacks|. If |callbacks| is
1953 * ``NULL``, this function does nothing.
1956 nghttp2_session_callbacks_del(nghttp2_session_callbacks *callbacks);
1961 * Sets callback function invoked when a session wants to send data to
1962 * the remote peer. This callback is not necessary if the application
1963 * uses solely `nghttp2_session_mem_send()` to serialize data to
1966 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_callback(
1967 nghttp2_session_callbacks *cbs, nghttp2_send_callback send_callback);
1972 * Sets callback function invoked when the a session wants to receive
1973 * data from the remote peer. This callback is not necessary if the
1974 * application uses solely `nghttp2_session_mem_recv()` to process
1977 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_recv_callback(
1978 nghttp2_session_callbacks *cbs, nghttp2_recv_callback recv_callback);
1983 * Sets callback function invoked by `nghttp2_session_recv()` and
1984 * `nghttp2_session_mem_recv()` when a frame is received.
1986 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_recv_callback(
1987 nghttp2_session_callbacks *cbs,
1988 nghttp2_on_frame_recv_callback on_frame_recv_callback);
1993 * Sets callback function invoked by `nghttp2_session_recv()` and
1994 * `nghttp2_session_mem_recv()` when an invalid non-DATA frame is
1998 nghttp2_session_callbacks_set_on_invalid_frame_recv_callback(
1999 nghttp2_session_callbacks *cbs,
2000 nghttp2_on_invalid_frame_recv_callback on_invalid_frame_recv_callback);
2005 * Sets callback function invoked when a chunk of data in DATA frame
2008 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_data_chunk_recv_callback(
2009 nghttp2_session_callbacks *cbs,
2010 nghttp2_on_data_chunk_recv_callback on_data_chunk_recv_callback);
2015 * Sets callback function invoked before a non-DATA frame is sent.
2017 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_before_frame_send_callback(
2018 nghttp2_session_callbacks *cbs,
2019 nghttp2_before_frame_send_callback before_frame_send_callback);
2024 * Sets callback function invoked after a frame is sent.
2026 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_send_callback(
2027 nghttp2_session_callbacks *cbs,
2028 nghttp2_on_frame_send_callback on_frame_send_callback);
2033 * Sets callback function invoked when a non-DATA frame is not sent
2034 * because of an error.
2036 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_frame_not_send_callback(
2037 nghttp2_session_callbacks *cbs,
2038 nghttp2_on_frame_not_send_callback on_frame_not_send_callback);
2043 * Sets callback function invoked when the stream is closed.
2045 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_stream_close_callback(
2046 nghttp2_session_callbacks *cbs,
2047 nghttp2_on_stream_close_callback on_stream_close_callback);
2052 * Sets callback function invoked when the reception of header block
2053 * in HEADERS or PUSH_PROMISE is started.
2055 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_begin_headers_callback(
2056 nghttp2_session_callbacks *cbs,
2057 nghttp2_on_begin_headers_callback on_begin_headers_callback);
2062 * Sets callback function invoked when a header name/value pair is
2064 * `nghttp2_session_callbacks_set_on_header_callback()` and
2065 * `nghttp2_session_callbacks_set_on_header_callback2()` are used to
2066 * set callbacks, the latter has the precedence.
2068 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_header_callback(
2069 nghttp2_session_callbacks *cbs,
2070 nghttp2_on_header_callback on_header_callback);
2075 * Sets callback function invoked when a header name/value pair is
2078 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_header_callback2(
2079 nghttp2_session_callbacks *cbs,
2080 nghttp2_on_header_callback2 on_header_callback2);
2085 * Sets callback function invoked when the library asks application
2086 * how many padding bytes are required for the transmission of the
2089 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_select_padding_callback(
2090 nghttp2_session_callbacks *cbs,
2091 nghttp2_select_padding_callback select_padding_callback);
2096 * Sets callback function determine the length allowed in
2097 * :type:`nghttp2_data_source_read_callback`.
2100 nghttp2_session_callbacks_set_data_source_read_length_callback(
2101 nghttp2_session_callbacks *cbs,
2102 nghttp2_data_source_read_length_callback data_source_read_length_callback);
2107 * Sets callback function invoked when a frame header is received.
2109 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_on_begin_frame_callback(
2110 nghttp2_session_callbacks *cbs,
2111 nghttp2_on_begin_frame_callback on_begin_frame_callback);
2116 * Sets callback function invoked when
2117 * :enum:`NGHTTP2_DATA_FLAG_NO_COPY` is used in
2118 * :type:`nghttp2_data_source_read_callback` to avoid data copy.
2120 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_send_data_callback(
2121 nghttp2_session_callbacks *cbs,
2122 nghttp2_send_data_callback send_data_callback);
2127 * Sets callback function invoked when the library asks the
2128 * application to pack extension frame payload in wire format.
2130 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_pack_extension_callback(
2131 nghttp2_session_callbacks *cbs,
2132 nghttp2_pack_extension_callback pack_extension_callback);
2137 * Sets callback function invoked when the library asks the
2138 * application to unpack extension frame payload from wire format.
2140 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_unpack_extension_callback(
2141 nghttp2_session_callbacks *cbs,
2142 nghttp2_unpack_extension_callback unpack_extension_callback);
2147 * Sets callback function invoked when chunk of extension frame
2148 * payload is received.
2151 nghttp2_session_callbacks_set_on_extension_chunk_recv_callback(
2152 nghttp2_session_callbacks *cbs,
2153 nghttp2_on_extension_chunk_recv_callback on_extension_chunk_recv_callback);
2158 * Sets callback function invoked when library tells error message to
2161 NGHTTP2_EXTERN void nghttp2_session_callbacks_set_error_callback(
2162 nghttp2_session_callbacks *cbs, nghttp2_error_callback error_callback);
2167 * Custom memory allocator to replace malloc(). The |mem_user_data|
2168 * is the mem_user_data member of :type:`nghttp2_mem` structure.
2170 typedef void *(*nghttp2_malloc)(size_t size, void *mem_user_data);
2175 * Custom memory allocator to replace free(). The |mem_user_data| is
2176 * the mem_user_data member of :type:`nghttp2_mem` structure.
2178 typedef void (*nghttp2_free)(void *ptr, void *mem_user_data);
2183 * Custom memory allocator to replace calloc(). The |mem_user_data|
2184 * is the mem_user_data member of :type:`nghttp2_mem` structure.
2186 typedef void *(*nghttp2_calloc)(size_t nmemb, size_t size, void *mem_user_data);
2191 * Custom memory allocator to replace realloc(). The |mem_user_data|
2192 * is the mem_user_data member of :type:`nghttp2_mem` structure.
2194 typedef void *(*nghttp2_realloc)(void *ptr, size_t size, void *mem_user_data);
2199 * Custom memory allocator functions and user defined pointer. The
2200 * |mem_user_data| member is passed to each allocator function. This
2201 * can be used, for example, to achieve per-session memory pool.
2203 * In the following example code, ``my_malloc``, ``my_free``,
2204 * ``my_calloc`` and ``my_realloc`` are the replacement of the
2205 * standard allocators ``malloc``, ``free``, ``calloc`` and
2206 * ``realloc`` respectively::
2208 * void *my_malloc_cb(size_t size, void *mem_user_data) {
2209 * return my_malloc(size);
2212 * void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); }
2214 * void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) {
2215 * return my_calloc(nmemb, size);
2218 * void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) {
2219 * return my_realloc(ptr, size);
2222 * void session_new() {
2223 * nghttp2_session *session;
2224 * nghttp2_session_callbacks *callbacks;
2225 * nghttp2_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb,
2230 * nghttp2_session_client_new3(&session, callbacks, NULL, NULL, &mem);
2237 * An arbitrary user supplied data. This is passed to each
2238 * allocator function.
2240 void *mem_user_data;
2242 * Custom allocator function to replace malloc().
2244 nghttp2_malloc malloc;
2246 * Custom allocator function to replace free().
2250 * Custom allocator function to replace calloc().
2252 nghttp2_calloc calloc;
2254 * Custom allocator function to replace realloc().
2256 nghttp2_realloc realloc;
2259 struct nghttp2_option;
2264 * Configuration options for :type:`nghttp2_session`. The details of
2265 * this structure are intentionally hidden from the public API.
2267 typedef struct nghttp2_option nghttp2_option;
2272 * Initializes |*option_ptr| with default values.
2274 * When the application finished using this object, it can use
2275 * `nghttp2_option_del()` to free its memory.
2277 * This function returns 0 if it succeeds, or one of the following
2278 * negative error codes:
2280 * :enum:`NGHTTP2_ERR_NOMEM`
2283 NGHTTP2_EXTERN int nghttp2_option_new(nghttp2_option **option_ptr);
2288 * Frees any resources allocated for |option|. If |option| is
2289 * ``NULL``, this function does nothing.
2291 NGHTTP2_EXTERN void nghttp2_option_del(nghttp2_option *option);
2296 * This option prevents the library from sending WINDOW_UPDATE for a
2297 * connection automatically. If this option is set to nonzero, the
2298 * library won't send WINDOW_UPDATE for DATA until application calls
2299 * `nghttp2_session_consume()` to indicate the consumed amount of
2300 * data. Don't use `nghttp2_submit_window_update()` for this purpose.
2301 * By default, this option is set to zero.
2304 nghttp2_option_set_no_auto_window_update(nghttp2_option *option, int val);
2309 * This option sets the SETTINGS_MAX_CONCURRENT_STREAMS value of
2310 * remote endpoint as if it is received in SETTINGS frame. Without
2311 * specifying this option, before the local endpoint receives
2312 * SETTINGS_MAX_CONCURRENT_STREAMS in SETTINGS frame from remote
2313 * endpoint, SETTINGS_MAX_CONCURRENT_STREAMS is unlimited. This may
2314 * cause problem if local endpoint submits lots of requests initially
2315 * and sending them at once to the remote peer may lead to the
2316 * rejection of some requests. Specifying this option to the sensible
2317 * value, say 100, may avoid this kind of issue. This value will be
2318 * overwritten if the local endpoint receives
2319 * SETTINGS_MAX_CONCURRENT_STREAMS from the remote endpoint.
2322 nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
2328 * By default, nghttp2 library, if configured as server, requires
2329 * first 24 bytes of client magic byte string (MAGIC). In most cases,
2330 * this will simplify the implementation of server. But sometimes
2331 * server may want to detect the application protocol based on first
2332 * few bytes on clear text communication.
2334 * If this option is used with nonzero |val|, nghttp2 library does not
2335 * handle MAGIC. It still checks following SETTINGS frame. This
2336 * means that applications should deal with MAGIC by themselves.
2338 * If this option is not used or used with zero value, if MAGIC does
2339 * not match :macro:`NGHTTP2_CLIENT_MAGIC`, `nghttp2_session_recv()`
2340 * and `nghttp2_session_mem_recv()` will return error
2341 * :enum:`NGHTTP2_ERR_BAD_CLIENT_MAGIC`, which is fatal error.
2344 nghttp2_option_set_no_recv_client_magic(nghttp2_option *option, int val);
2349 * By default, nghttp2 library enforces subset of HTTP Messaging rules
2350 * described in `HTTP/2 specification, section 8
2351 * <https://tools.ietf.org/html/rfc7540#section-8>`_. See
2352 * :ref:`http-messaging` section for details. For those applications
2353 * who use nghttp2 library as non-HTTP use, give nonzero to |val| to
2354 * disable this enforcement.
2356 NGHTTP2_EXTERN void nghttp2_option_set_no_http_messaging(nghttp2_option *option,
2362 * RFC 7540 does not enforce any limit on the number of incoming
2363 * reserved streams (in RFC 7540 terms, streams in reserved (remote)
2364 * state). This only affects client side, since only server can push
2365 * streams. Malicious server can push arbitrary number of streams,
2366 * and make client's memory exhausted. This option can set the
2367 * maximum number of such incoming streams to avoid possible memory
2368 * exhaustion. If this option is set, and pushed streams are
2369 * automatically closed on reception, without calling user provided
2370 * callback, if they exceed the given limit. The default value is
2371 * 200. If session is configured as server side, this option has no
2372 * effect. Server can control the number of streams to push.
2375 nghttp2_option_set_max_reserved_remote_streams(nghttp2_option *option,
2381 * Sets extension frame type the application is willing to handle with
2382 * user defined callbacks (see
2383 * :type:`nghttp2_on_extension_chunk_recv_callback` and
2384 * :type:`nghttp2_unpack_extension_callback`). The |type| is
2385 * extension frame type, and must be strictly greater than 0x9.
2386 * Otherwise, this function does nothing. The application can call
2387 * this function multiple times to set more than one frame type to
2388 * receive. The application does not have to call this function if it
2389 * just sends extension frames.
2392 nghttp2_option_set_user_recv_extension_type(nghttp2_option *option,
2398 * Sets extension frame type the application is willing to receive
2399 * using builtin handler. The |type| is the extension frame type to
2400 * receive, and must be strictly greater than 0x9. Otherwise, this
2401 * function does nothing. The application can call this function
2402 * multiple times to set more than one frame type to receive. The
2403 * application does not have to call this function if it just sends
2406 * If same frame type is passed to both
2407 * `nghttp2_option_set_builtin_recv_extension_type()` and
2408 * `nghttp2_option_set_user_recv_extension_type()`, the latter takes
2412 nghttp2_option_set_builtin_recv_extension_type(nghttp2_option *option,
2418 * This option prevents the library from sending PING frame with ACK
2419 * flag set automatically when PING frame without ACK flag set is
2420 * received. If this option is set to nonzero, the library won't send
2421 * PING frame with ACK flag set in the response for incoming PING
2422 * frame. The application can send PING frame with ACK flag set using
2423 * `nghttp2_submit_ping()` with :enum:`NGHTTP2_FLAG_ACK` as flags
2426 NGHTTP2_EXTERN void nghttp2_option_set_no_auto_ping_ack(nghttp2_option *option,
2432 * This option sets the maximum length of header block (a set of
2433 * header fields per one HEADERS frame) to send. The length of a
2434 * given set of header fields is calculated using
2435 * `nghttp2_hd_deflate_bound()`. The default value is 64KiB. If
2436 * application attempts to send header fields larger than this limit,
2437 * the transmission of the frame fails with error code
2438 * :enum:`NGHTTP2_ERR_FRAME_SIZE_ERROR`.
2441 nghttp2_option_set_max_send_header_block_length(nghttp2_option *option,
2447 * Initializes |*session_ptr| for client use. The all members of
2448 * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
2449 * does not store |callbacks|. The |user_data| is an arbitrary user
2450 * supplied data, which will be passed to the callback functions.
2452 * The :type:`nghttp2_send_callback` must be specified. If the
2453 * application code uses `nghttp2_session_recv()`, the
2454 * :type:`nghttp2_recv_callback` must be specified. The other members
2455 * of |callbacks| can be ``NULL``.
2457 * If this function fails, |*session_ptr| is left untouched.
2459 * This function returns 0 if it succeeds, or one of the following
2460 * negative error codes:
2462 * :enum:`NGHTTP2_ERR_NOMEM`
2466 nghttp2_session_client_new(nghttp2_session **session_ptr,
2467 const nghttp2_session_callbacks *callbacks,
2473 * Initializes |*session_ptr| for server use. The all members of
2474 * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
2475 * does not store |callbacks|. The |user_data| is an arbitrary user
2476 * supplied data, which will be passed to the callback functions.
2478 * The :type:`nghttp2_send_callback` must be specified. If the
2479 * application code uses `nghttp2_session_recv()`, the
2480 * :type:`nghttp2_recv_callback` must be specified. The other members
2481 * of |callbacks| can be ``NULL``.
2483 * If this function fails, |*session_ptr| is left untouched.
2485 * This function returns 0 if it succeeds, or one of the following
2486 * negative error codes:
2488 * :enum:`NGHTTP2_ERR_NOMEM`
2492 nghttp2_session_server_new(nghttp2_session **session_ptr,
2493 const nghttp2_session_callbacks *callbacks,
2499 * Like `nghttp2_session_client_new()`, but with additional options
2500 * specified in the |option|.
2502 * The |option| can be ``NULL`` and the call is equivalent to
2503 * `nghttp2_session_client_new()`.
2505 * This function does not take ownership |option|. The application is
2506 * responsible for freeing |option| if it finishes using the object.
2508 * The library code does not refer to |option| after this function
2511 * This function returns 0 if it succeeds, or one of the following
2512 * negative error codes:
2514 * :enum:`NGHTTP2_ERR_NOMEM`
2518 nghttp2_session_client_new2(nghttp2_session **session_ptr,
2519 const nghttp2_session_callbacks *callbacks,
2520 void *user_data, const nghttp2_option *option);
2525 * Like `nghttp2_session_server_new()`, but with additional options
2526 * specified in the |option|.
2528 * The |option| can be ``NULL`` and the call is equivalent to
2529 * `nghttp2_session_server_new()`.
2531 * This function does not take ownership |option|. The application is
2532 * responsible for freeing |option| if it finishes using the object.
2534 * The library code does not refer to |option| after this function
2537 * This function returns 0 if it succeeds, or one of the following
2538 * negative error codes:
2540 * :enum:`NGHTTP2_ERR_NOMEM`
2544 nghttp2_session_server_new2(nghttp2_session **session_ptr,
2545 const nghttp2_session_callbacks *callbacks,
2546 void *user_data, const nghttp2_option *option);
2551 * Like `nghttp2_session_client_new2()`, but with additional custom
2552 * memory allocator specified in the |mem|.
2554 * The |mem| can be ``NULL`` and the call is equivalent to
2555 * `nghttp2_session_client_new2()`.
2557 * This function does not take ownership |mem|. The application is
2558 * responsible for freeing |mem|.
2560 * The library code does not refer to |mem| pointer after this
2561 * function returns, so the application can safely free it.
2563 * This function returns 0 if it succeeds, or one of the following
2564 * negative error codes:
2566 * :enum:`NGHTTP2_ERR_NOMEM`
2569 NGHTTP2_EXTERN int nghttp2_session_client_new3(
2570 nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks,
2571 void *user_data, const nghttp2_option *option, nghttp2_mem *mem);
2576 * Like `nghttp2_session_server_new2()`, but with additional custom
2577 * memory allocator specified in the |mem|.
2579 * The |mem| can be ``NULL`` and the call is equivalent to
2580 * `nghttp2_session_server_new2()`.
2582 * This function does not take ownership |mem|. The application is
2583 * responsible for freeing |mem|.
2585 * The library code does not refer to |mem| pointer after this
2586 * function returns, so the application can safely free it.
2588 * This function returns 0 if it succeeds, or one of the following
2589 * negative error codes:
2591 * :enum:`NGHTTP2_ERR_NOMEM`
2594 NGHTTP2_EXTERN int nghttp2_session_server_new3(
2595 nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks,
2596 void *user_data, const nghttp2_option *option, nghttp2_mem *mem);
2601 * Frees any resources allocated for |session|. If |session| is
2602 * ``NULL``, this function does nothing.
2604 NGHTTP2_EXTERN void nghttp2_session_del(nghttp2_session *session);
2609 * Sends pending frames to the remote peer.
2611 * This function retrieves the highest prioritized frame from the
2612 * outbound queue and sends it to the remote peer. It does this as
2613 * many as possible until the user callback
2614 * :type:`nghttp2_send_callback` returns
2615 * :enum:`NGHTTP2_ERR_WOULDBLOCK` or the outbound queue becomes empty.
2616 * This function calls several callback functions which are passed
2617 * when initializing the |session|. Here is the simple time chart
2618 * which tells when each callback is invoked:
2620 * 1. Get the next frame to send from outbound queue.
2622 * 2. Prepare transmission of the frame.
2624 * 3. If the control frame cannot be sent because some preconditions
2625 * are not met (e.g., request HEADERS cannot be sent after GOAWAY),
2626 * :type:`nghttp2_on_frame_not_send_callback` is invoked. Abort
2627 * the following steps.
2629 * 4. If the frame is HEADERS, PUSH_PROMISE or DATA,
2630 * :type:`nghttp2_select_padding_callback` is invoked.
2632 * 5. If the frame is request HEADERS, the stream is opened here.
2634 * 6. :type:`nghttp2_before_frame_send_callback` is invoked.
2636 * 7. If :enum:`NGHTTP2_ERR_CANCEL` is returned from
2637 * :type:`nghttp2_before_frame_send_callback`, the current frame
2638 * transmission is canceled, and
2639 * :type:`nghttp2_on_frame_not_send_callback` is invoked. Abort
2640 * the following steps.
2642 * 8. :type:`nghttp2_send_callback` is invoked one or more times to
2645 * 9. :type:`nghttp2_on_frame_send_callback` is invoked.
2647 * 10. If the transmission of the frame triggers closure of the
2648 * stream, the stream is closed and
2649 * :type:`nghttp2_on_stream_close_callback` is invoked.
2651 * This function returns 0 if it succeeds, or one of the following
2652 * negative error codes:
2654 * :enum:`NGHTTP2_ERR_NOMEM`
2656 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
2657 * The callback function failed.
2659 NGHTTP2_EXTERN int nghttp2_session_send(nghttp2_session *session);
2664 * Returns the serialized data to send.
2666 * This function behaves like `nghttp2_session_send()` except that it
2667 * does not use :type:`nghttp2_send_callback` to transmit data.
2668 * Instead, it assigns the pointer to the serialized data to the
2669 * |*data_ptr| and returns its length. The other callbacks are called
2670 * in the same way as they are in `nghttp2_session_send()`.
2672 * If no data is available to send, this function returns 0.
2674 * This function may not return all serialized data in one invocation.
2675 * To get all data, call this function repeatedly until it returns 0
2676 * or one of negative error codes.
2678 * The assigned |*data_ptr| is valid until the next call of
2679 * `nghttp2_session_mem_send()` or `nghttp2_session_send()`.
2681 * The caller must send all data before sending the next chunk of
2684 * This function returns the length of the data pointed by the
2685 * |*data_ptr| if it succeeds, or one of the following negative error
2688 * :enum:`NGHTTP2_ERR_NOMEM`
2693 * This function may produce very small byte string. If that is the
2694 * case, and application disables Nagle algorithm (``TCP_NODELAY``),
2695 * then writing this small chunk leads to very small packet, and it
2696 * is very inefficient. An application should be responsible to
2697 * buffer up small chunks of data as necessary to avoid this
2700 NGHTTP2_EXTERN ssize_t
2701 nghttp2_session_mem_send(nghttp2_session *session, const uint8_t **data_ptr);
2706 * Receives frames from the remote peer.
2708 * This function receives as many frames as possible until the user
2709 * callback :type:`nghttp2_recv_callback` returns
2710 * :enum:`NGHTTP2_ERR_WOULDBLOCK`. This function calls several
2711 * callback functions which are passed when initializing the
2712 * |session|. Here is the simple time chart which tells when each
2713 * callback is invoked:
2715 * 1. :type:`nghttp2_recv_callback` is invoked one or more times to
2716 * receive frame header.
2718 * 2. When frame header is received,
2719 * :type:`nghttp2_on_begin_frame_callback` is invoked.
2721 * 3. If the frame is DATA frame:
2723 * 1. :type:`nghttp2_recv_callback` is invoked to receive DATA
2724 * payload. For each chunk of data,
2725 * :type:`nghttp2_on_data_chunk_recv_callback` is invoked.
2727 * 2. If one DATA frame is completely received,
2728 * :type:`nghttp2_on_frame_recv_callback` is invoked. If the
2729 * reception of the frame triggers the closure of the stream,
2730 * :type:`nghttp2_on_stream_close_callback` is invoked.
2732 * 4. If the frame is the control frame:
2734 * 1. :type:`nghttp2_recv_callback` is invoked one or more times to
2735 * receive whole frame.
2737 * 2. If the received frame is valid, then following actions are
2738 * taken. If the frame is either HEADERS or PUSH_PROMISE,
2739 * :type:`nghttp2_on_begin_headers_callback` is invoked. Then
2740 * :type:`nghttp2_on_header_callback` is invoked for each header
2741 * name/value pair. After all name/value pairs are emitted
2742 * successfully, :type:`nghttp2_on_frame_recv_callback` is
2743 * invoked. For other frames,
2744 * :type:`nghttp2_on_frame_recv_callback` is invoked. If the
2745 * reception of the frame triggers the closure of the stream,
2746 * :type:`nghttp2_on_stream_close_callback` is invoked.
2748 * 3. If the received frame is unpacked but is interpreted as
2749 * invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is
2752 * This function returns 0 if it succeeds, or one of the following
2753 * negative error codes:
2755 * :enum:`NGHTTP2_ERR_EOF`
2756 * The remote peer did shutdown on the connection.
2757 * :enum:`NGHTTP2_ERR_NOMEM`
2759 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
2760 * The callback function failed.
2761 * :enum:`NGHTTP2_ERR_BAD_CLIENT_MAGIC`
2762 * Invalid client magic was detected. This error only returns
2763 * when |session| was configured as server and
2764 * `nghttp2_option_set_no_recv_client_magic()` is not used with
2766 * :enum:`NGHTTP2_ERR_FLOODED`
2767 * Flooding was detected in this HTTP/2 session, and it must be
2768 * closed. This is most likely caused by misbehaviour of peer.
2770 NGHTTP2_EXTERN int nghttp2_session_recv(nghttp2_session *session);
2775 * Processes data |in| as an input from the remote endpoint. The
2776 * |inlen| indicates the number of bytes in the |in|.
2778 * This function behaves like `nghttp2_session_recv()` except that it
2779 * does not use :type:`nghttp2_recv_callback` to receive data; the
2780 * |in| is the only data for the invocation of this function. If all
2781 * bytes are processed, this function returns. The other callbacks
2782 * are called in the same way as they are in `nghttp2_session_recv()`.
2784 * In the current implementation, this function always tries to
2785 * processes all input data unless either an error occurs or
2786 * :enum:`NGHTTP2_ERR_PAUSE` is returned from
2787 * :type:`nghttp2_on_header_callback` or
2788 * :type:`nghttp2_on_data_chunk_recv_callback`. If
2789 * :enum:`NGHTTP2_ERR_PAUSE` is used, the return value includes the
2790 * number of bytes which was used to produce the data or frame for the
2793 * This function returns the number of processed bytes, or one of the
2794 * following negative error codes:
2796 * :enum:`NGHTTP2_ERR_NOMEM`
2798 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
2799 * The callback function failed.
2800 * :enum:`NGHTTP2_ERR_BAD_CLIENT_MAGIC`
2801 * Invalid client magic was detected. This error only returns
2802 * when |session| was configured as server and
2803 * `nghttp2_option_set_no_recv_client_magic()` is not used with
2805 * :enum:`NGHTTP2_ERR_FLOODED`
2806 * Flooding was detected in this HTTP/2 session, and it must be
2807 * closed. This is most likely caused by misbehaviour of peer.
2809 NGHTTP2_EXTERN ssize_t nghttp2_session_mem_recv(nghttp2_session *session,
2816 * Puts back previously deferred DATA frame in the stream |stream_id|
2817 * to the outbound queue.
2819 * This function returns 0 if it succeeds, or one of the following
2820 * negative error codes:
2822 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2823 * The stream does not exist; or no deferred data exist.
2824 * :enum:`NGHTTP2_ERR_NOMEM`
2827 NGHTTP2_EXTERN int nghttp2_session_resume_data(nghttp2_session *session,
2833 * Returns nonzero value if |session| wants to receive data from the
2836 * If both `nghttp2_session_want_read()` and
2837 * `nghttp2_session_want_write()` return 0, the application should
2838 * drop the connection.
2840 NGHTTP2_EXTERN int nghttp2_session_want_read(nghttp2_session *session);
2845 * Returns nonzero value if |session| wants to send data to the remote
2848 * If both `nghttp2_session_want_read()` and
2849 * `nghttp2_session_want_write()` return 0, the application should
2850 * drop the connection.
2852 NGHTTP2_EXTERN int nghttp2_session_want_write(nghttp2_session *session);
2857 * Returns stream_user_data for the stream |stream_id|. The
2858 * stream_user_data is provided by `nghttp2_submit_request()`,
2859 * `nghttp2_submit_headers()` or
2860 * `nghttp2_session_set_stream_user_data()`. Unless it is set using
2861 * `nghttp2_session_set_stream_user_data()`, if the stream is
2862 * initiated by the remote endpoint, stream_user_data is always
2863 * ``NULL``. If the stream does not exist, this function returns
2866 NGHTTP2_EXTERN void *
2867 nghttp2_session_get_stream_user_data(nghttp2_session *session,
2873 * Sets the |stream_user_data| to the stream denoted by the
2874 * |stream_id|. If a stream user data is already set to the stream,
2875 * it is replaced with the |stream_user_data|. It is valid to specify
2876 * ``NULL`` in the |stream_user_data|, which nullifies the associated
2879 * It is valid to set the |stream_user_data| to the stream reserved by
2880 * PUSH_PROMISE frame.
2882 * This function returns 0 if it succeeds, or one of following
2883 * negative error codes:
2885 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2886 * The stream does not exist
2889 nghttp2_session_set_stream_user_data(nghttp2_session *session,
2890 int32_t stream_id, void *stream_user_data);
2895 * Returns the number of frames in the outbound queue. This does not
2896 * include the deferred DATA frames.
2898 NGHTTP2_EXTERN size_t
2899 nghttp2_session_get_outbound_queue_size(nghttp2_session *session);
2904 * Returns the number of DATA payload in bytes received without
2905 * WINDOW_UPDATE transmission for the stream |stream_id|. The local
2906 * (receive) window size can be adjusted by
2907 * `nghttp2_submit_window_update()`. This function takes into account
2908 * that and returns effective data length. In particular, if the
2909 * local window size is reduced by submitting negative
2910 * window_size_increment with `nghttp2_submit_window_update()`, this
2911 * function returns the number of bytes less than actually received.
2913 * This function returns -1 if it fails.
2915 NGHTTP2_EXTERN int32_t
2916 nghttp2_session_get_stream_effective_recv_data_length(nghttp2_session *session,
2922 * Returns the local (receive) window size for the stream |stream_id|.
2923 * The local window size can be adjusted by
2924 * `nghttp2_submit_window_update()`. This function takes into account
2925 * that and returns effective window size.
2927 * This function returns -1 if it fails.
2929 NGHTTP2_EXTERN int32_t
2930 nghttp2_session_get_stream_effective_local_window_size(nghttp2_session *session,
2936 * Returns the number of DATA payload in bytes received without
2937 * WINDOW_UPDATE transmission for a connection. The local (receive)
2938 * window size can be adjusted by `nghttp2_submit_window_update()`.
2939 * This function takes into account that and returns effective data
2940 * length. In particular, if the local window size is reduced by
2941 * submitting negative window_size_increment with
2942 * `nghttp2_submit_window_update()`, this function returns the number
2943 * of bytes less than actually received.
2945 * This function returns -1 if it fails.
2947 NGHTTP2_EXTERN int32_t
2948 nghttp2_session_get_effective_recv_data_length(nghttp2_session *session);
2953 * Returns the local (receive) window size for a connection. The
2954 * local window size can be adjusted by
2955 * `nghttp2_submit_window_update()`. This function takes into account
2956 * that and returns effective window size.
2958 * This function returns -1 if it fails.
2960 NGHTTP2_EXTERN int32_t
2961 nghttp2_session_get_effective_local_window_size(nghttp2_session *session);
2966 * Returns the remote window size for a given stream |stream_id|.
2968 * This is the amount of flow-controlled payload (e.g., DATA) that the
2969 * local endpoint can send without stream level WINDOW_UPDATE. There
2970 * is also connection level flow control, so the effective size of
2971 * payload that the local endpoint can actually send is
2972 * min(`nghttp2_session_get_stream_remote_window_size()`,
2973 * `nghttp2_session_get_remote_window_size()`).
2975 * This function returns -1 if it fails.
2977 NGHTTP2_EXTERN int32_t
2978 nghttp2_session_get_stream_remote_window_size(nghttp2_session *session,
2984 * Returns the remote window size for a connection.
2986 * This function always succeeds.
2988 NGHTTP2_EXTERN int32_t
2989 nghttp2_session_get_remote_window_size(nghttp2_session *session);
2994 * Returns 1 if local peer half closed the given stream |stream_id|.
2995 * Returns 0 if it did not. Returns -1 if no such stream exists.
2998 nghttp2_session_get_stream_local_close(nghttp2_session *session,
3004 * Returns 1 if remote peer half closed the given stream |stream_id|.
3005 * Returns 0 if it did not. Returns -1 if no such stream exists.
3008 nghttp2_session_get_stream_remote_close(nghttp2_session *session,
3014 * Signals the session so that the connection should be terminated.
3016 * The last stream ID is the minimum value between the stream ID of a
3017 * stream for which :type:`nghttp2_on_frame_recv_callback` was called
3018 * most recently and the last stream ID we have sent to the peer
3021 * The |error_code| is the error code of this GOAWAY frame. The
3022 * pre-defined error code is one of :enum:`nghttp2_error_code`.
3024 * After the transmission, both `nghttp2_session_want_read()` and
3025 * `nghttp2_session_want_write()` return 0.
3027 * This function should be called when the connection should be
3028 * terminated after sending GOAWAY. If the remaining streams should
3029 * be processed after GOAWAY, use `nghttp2_submit_goaway()` instead.
3031 * This function returns 0 if it succeeds, or one of the following
3032 * negative error codes:
3034 * :enum:`NGHTTP2_ERR_NOMEM`
3037 NGHTTP2_EXTERN int nghttp2_session_terminate_session(nghttp2_session *session,
3038 uint32_t error_code);
3043 * Signals the session so that the connection should be terminated.
3045 * This function behaves like `nghttp2_session_terminate_session()`,
3046 * but the last stream ID can be specified by the application for fine
3047 * grained control of stream. The HTTP/2 specification does not allow
3048 * last_stream_id to be increased. So the actual value sent as
3049 * last_stream_id is the minimum value between the given
3050 * |last_stream_id| and the last_stream_id we have previously sent to
3053 * The |last_stream_id| is peer's stream ID or 0. So if |session| is
3054 * initialized as client, |last_stream_id| must be even or 0. If
3055 * |session| is initialized as server, |last_stream_id| must be odd or
3058 * This function returns 0 if it succeeds, or one of the following
3059 * negative error codes:
3061 * :enum:`NGHTTP2_ERR_NOMEM`
3063 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3064 * The |last_stream_id| is invalid.
3066 NGHTTP2_EXTERN int nghttp2_session_terminate_session2(nghttp2_session *session,
3067 int32_t last_stream_id,
3068 uint32_t error_code);
3073 * Signals to the client that the server started graceful shutdown
3076 * This function is only usable for server. If this function is
3077 * called with client side session, this function returns
3078 * :enum:`NGHTTP2_ERR_INVALID_STATE`.
3080 * To gracefully shutdown HTTP/2 session, server should call this
3081 * function to send GOAWAY with last_stream_id (1u << 31) - 1. And
3082 * after some delay (e.g., 1 RTT), send another GOAWAY with the stream
3083 * ID that the server has some processing using
3084 * `nghttp2_submit_goaway()`. See also
3085 * `nghttp2_session_get_last_proc_stream_id()`.
3087 * Unlike `nghttp2_submit_goaway()`, this function just sends GOAWAY
3088 * and does nothing more. This is a mere indication to the client
3089 * that session shutdown is imminent. The application should call
3090 * `nghttp2_submit_goaway()` with appropriate last_stream_id after
3093 * If one or more GOAWAY frame have been already sent by either
3094 * `nghttp2_submit_goaway()` or `nghttp2_session_terminate_session()`,
3095 * this function has no effect.
3097 * This function returns 0 if it succeeds, or one of the following
3098 * negative error codes:
3100 * :enum:`NGHTTP2_ERR_NOMEM`
3102 * :enum:`NGHTTP2_ERR_INVALID_STATE`
3103 * The |session| is initialized as client.
3105 NGHTTP2_EXTERN int nghttp2_submit_shutdown_notice(nghttp2_session *session);
3110 * Returns the value of SETTINGS |id| notified by a remote endpoint.
3111 * The |id| must be one of values defined in
3112 * :enum:`nghttp2_settings_id`.
3114 NGHTTP2_EXTERN uint32_t
3115 nghttp2_session_get_remote_settings(nghttp2_session *session,
3116 nghttp2_settings_id id);
3121 * Tells the |session| that next stream ID is |next_stream_id|. The
3122 * |next_stream_id| must be equal or greater than the value returned
3123 * by `nghttp2_session_get_next_stream_id()`.
3125 * This function returns 0 if it succeeds, or one of the following
3126 * negative error codes:
3128 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3129 * The |next_stream_id| is strictly less than the value
3130 * `nghttp2_session_get_next_stream_id()` returns; or
3131 * |next_stream_id| is invalid (e.g., even integer for client, or
3132 * odd integer for server).
3134 NGHTTP2_EXTERN int nghttp2_session_set_next_stream_id(nghttp2_session *session,
3135 int32_t next_stream_id);
3140 * Returns the next outgoing stream ID. Notice that return type is
3141 * uint32_t. If we run out of stream ID for this session, this
3142 * function returns 1 << 31.
3144 NGHTTP2_EXTERN uint32_t
3145 nghttp2_session_get_next_stream_id(nghttp2_session *session);
3150 * Tells the |session| that |size| bytes for a stream denoted by
3151 * |stream_id| were consumed by application and are ready to
3152 * WINDOW_UPDATE. The consumed bytes are counted towards both
3153 * connection and stream level WINDOW_UPDATE (see
3154 * `nghttp2_session_consume_connection()` and
3155 * `nghttp2_session_consume_stream()` to update consumption
3156 * independently). This function is intended to be used without
3157 * automatic window update (see
3158 * `nghttp2_option_set_no_auto_window_update()`).
3160 * This function returns 0 if it succeeds, or one of the following
3161 * negative error codes:
3163 * :enum:`NGHTTP2_ERR_NOMEM`
3165 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3166 * The |stream_id| is 0.
3167 * :enum:`NGHTTP2_ERR_INVALID_STATE`
3168 * Automatic WINDOW_UPDATE is not disabled.
3170 NGHTTP2_EXTERN int nghttp2_session_consume(nghttp2_session *session,
3171 int32_t stream_id, size_t size);
3176 * Like `nghttp2_session_consume()`, but this only tells library that
3177 * |size| bytes were consumed only for connection level. Note that
3178 * HTTP/2 maintains connection and stream level flow control windows
3181 * This function returns 0 if it succeeds, or one of the following
3182 * negative error codes:
3184 * :enum:`NGHTTP2_ERR_NOMEM`
3186 * :enum:`NGHTTP2_ERR_INVALID_STATE`
3187 * Automatic WINDOW_UPDATE is not disabled.
3189 NGHTTP2_EXTERN int nghttp2_session_consume_connection(nghttp2_session *session,
3195 * Like `nghttp2_session_consume()`, but this only tells library that
3196 * |size| bytes were consumed only for stream denoted by |stream_id|.
3197 * Note that HTTP/2 maintains connection and stream level flow control
3198 * windows independently.
3200 * This function returns 0 if it succeeds, or one of the following
3201 * negative error codes:
3203 * :enum:`NGHTTP2_ERR_NOMEM`
3205 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3206 * The |stream_id| is 0.
3207 * :enum:`NGHTTP2_ERR_INVALID_STATE`
3208 * Automatic WINDOW_UPDATE is not disabled.
3210 NGHTTP2_EXTERN int nghttp2_session_consume_stream(nghttp2_session *session,
3217 * Changes priority of existing stream denoted by |stream_id|. The
3218 * new priority specification is |pri_spec|.
3220 * The priority is changed silently and instantly, and no PRIORITY
3221 * frame will be sent to notify the peer of this change. This
3222 * function may be useful for server to change the priority of pushed
3225 * If |session| is initialized as server, and ``pri_spec->stream_id``
3226 * points to the idle stream, the idle stream is created if it does
3227 * not exist. The created idle stream will depend on root stream
3228 * (stream 0) with weight 16.
3230 * Otherwise, if stream denoted by ``pri_spec->stream_id`` is not
3231 * found, we use default priority instead of given |pri_spec|. That
3232 * is make stream depend on root stream with weight 16.
3234 * This function returns 0 if it succeeds, or one of the following
3235 * negative error codes:
3237 * :enum:`NGHTTP2_ERR_NOMEM`
3239 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3240 * Attempted to depend on itself; or no stream exist for the given
3241 * |stream_id|; or |stream_id| is 0
3244 nghttp2_session_change_stream_priority(nghttp2_session *session,
3246 const nghttp2_priority_spec *pri_spec);
3251 * Creates idle stream with the given |stream_id|, and priority
3254 * The stream creation is done without sending PRIORITY frame, which
3255 * means that peer does not know about the existence of this idle
3256 * stream in the local endpoint.
3258 * RFC 7540 does not disallow the use of creation of idle stream with
3259 * odd or even stream ID regardless of client or server. So this
3260 * function can create odd or even stream ID regardless of client or
3261 * server. But probably it is a bit safer to use the stream ID the
3262 * local endpoint can initiate (in other words, use odd stream ID for
3263 * client, and even stream ID for server), to avoid potential
3264 * collision from peer's instruction. Also we can use
3265 * `nghttp2_session_set_next_stream_id()` to avoid to open created
3266 * idle streams accidentally if we follow this recommendation.
3268 * If |session| is initialized as server, and ``pri_spec->stream_id``
3269 * points to the idle stream, the idle stream is created if it does
3270 * not exist. The created idle stream will depend on root stream
3271 * (stream 0) with weight 16.
3273 * Otherwise, if stream denoted by ``pri_spec->stream_id`` is not
3274 * found, we use default priority instead of given |pri_spec|. That
3275 * is make stream depend on root stream with weight 16.
3277 * This function returns 0 if it succeeds, or one of the following
3278 * negative error codes:
3280 * :enum:`NGHTTP2_ERR_NOMEM`
3282 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3283 * Attempted to depend on itself; or stream denoted by |stream_id|
3284 * already exists; or |stream_id| cannot be used to create idle
3285 * stream (in other words, local endpoint has already opened
3286 * stream ID greater than or equal to the given stream ID; or
3290 nghttp2_session_create_idle_stream(nghttp2_session *session, int32_t stream_id,
3291 const nghttp2_priority_spec *pri_spec);
3296 * Performs post-process of HTTP Upgrade request. This function can
3297 * be called from both client and server, but the behavior is very
3298 * different in each other.
3302 * This function is deprecated in favor of
3303 * `nghttp2_session_upgrade2()`, because this function lacks the
3304 * parameter to tell the library the request method used in the
3305 * original HTTP request. This information is required for client
3306 * to validate actual response body length against content-length
3307 * header field (see `nghttp2_option_set_no_http_messaging()`). If
3308 * HEAD is used in request, the length of response body must be 0
3309 * regardless of value included in content-length header field.
3311 * If called from client side, the |settings_payload| must be the
3312 * value sent in ``HTTP2-Settings`` header field and must be decoded
3313 * by base64url decoder. The |settings_payloadlen| is the length of
3314 * |settings_payload|. The |settings_payload| is unpacked and its
3315 * setting values will be submitted using `nghttp2_submit_settings()`.
3316 * This means that the client application code does not need to submit
3317 * SETTINGS by itself. The stream with stream ID=1 is opened and the
3318 * |stream_user_data| is used for its stream_user_data. The opened
3319 * stream becomes half-closed (local) state.
3321 * If called from server side, the |settings_payload| must be the
3322 * value received in ``HTTP2-Settings`` header field and must be
3323 * decoded by base64url decoder. The |settings_payloadlen| is the
3324 * length of |settings_payload|. It is treated as if the SETTINGS
3325 * frame with that payload is received. Thus, callback functions for
3326 * the reception of SETTINGS frame will be invoked. The stream with
3327 * stream ID=1 is opened. The |stream_user_data| is ignored. The
3328 * opened stream becomes half-closed (remote).
3330 * This function returns 0 if it succeeds, or one of the following
3331 * negative error codes:
3333 * :enum:`NGHTTP2_ERR_NOMEM`
3335 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3336 * The |settings_payload| is badly formed.
3337 * :enum:`NGHTTP2_ERR_PROTO`
3338 * The stream ID 1 is already used or closed; or is not available.
3340 NGHTTP2_EXTERN int nghttp2_session_upgrade(nghttp2_session *session,
3341 const uint8_t *settings_payload,
3342 size_t settings_payloadlen,
3343 void *stream_user_data);
3348 * Performs post-process of HTTP Upgrade request. This function can
3349 * be called from both client and server, but the behavior is very
3350 * different in each other.
3352 * If called from client side, the |settings_payload| must be the
3353 * value sent in ``HTTP2-Settings`` header field and must be decoded
3354 * by base64url decoder. The |settings_payloadlen| is the length of
3355 * |settings_payload|. The |settings_payload| is unpacked and its
3356 * setting values will be submitted using `nghttp2_submit_settings()`.
3357 * This means that the client application code does not need to submit
3358 * SETTINGS by itself. The stream with stream ID=1 is opened and the
3359 * |stream_user_data| is used for its stream_user_data. The opened
3360 * stream becomes half-closed (local) state.
3362 * If called from server side, the |settings_payload| must be the
3363 * value received in ``HTTP2-Settings`` header field and must be
3364 * decoded by base64url decoder. The |settings_payloadlen| is the
3365 * length of |settings_payload|. It is treated as if the SETTINGS
3366 * frame with that payload is received. Thus, callback functions for
3367 * the reception of SETTINGS frame will be invoked. The stream with
3368 * stream ID=1 is opened. The |stream_user_data| is ignored. The
3369 * opened stream becomes half-closed (remote).
3371 * If the request method is HEAD, pass nonzero value to
3372 * |head_request|. Otherwise, pass 0.
3374 * This function returns 0 if it succeeds, or one of the following
3375 * negative error codes:
3377 * :enum:`NGHTTP2_ERR_NOMEM`
3379 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3380 * The |settings_payload| is badly formed.
3381 * :enum:`NGHTTP2_ERR_PROTO`
3382 * The stream ID 1 is already used or closed; or is not available.
3384 NGHTTP2_EXTERN int nghttp2_session_upgrade2(nghttp2_session *session,
3385 const uint8_t *settings_payload,
3386 size_t settings_payloadlen,
3388 void *stream_user_data);
3393 * Serializes the SETTINGS values |iv| in the |buf|. The size of the
3394 * |buf| is specified by |buflen|. The number of entries in the |iv|
3395 * array is given by |niv|. The required space in |buf| for the |niv|
3396 * entries is ``8*niv`` bytes and if the given buffer is too small, an
3397 * error is returned. This function is used mainly for creating a
3398 * SETTINGS payload to be sent with the ``HTTP2-Settings`` header
3399 * field in an HTTP Upgrade request. The data written in |buf| is NOT
3400 * base64url encoded and the application is responsible for encoding.
3402 * This function returns the number of bytes written in |buf|, or one
3403 * of the following negative error codes:
3405 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3406 * The |iv| contains duplicate settings ID or invalid value.
3408 * :enum:`NGHTTP2_ERR_INSUFF_BUFSIZE`
3409 * The provided |buflen| size is too small to hold the output.
3411 NGHTTP2_EXTERN ssize_t
3412 nghttp2_pack_settings_payload(uint8_t *buf, size_t buflen,
3413 const nghttp2_settings_entry *iv, size_t niv);
3418 * Returns string describing the |lib_error_code|. The
3419 * |lib_error_code| must be one of the :enum:`nghttp2_error`.
3421 NGHTTP2_EXTERN const char *nghttp2_strerror(int lib_error_code);
3426 * Returns string representation of HTTP/2 error code |error_code|
3427 * (e.g., ``PROTOCOL_ERROR`` is returned if ``error_code ==
3428 * NGHTTP2_PROTOCOL_ERROR``). If string representation is unknown for
3429 * given |error_code|, this function returns string ``unknown``.
3431 NGHTTP2_EXTERN const char *nghttp2_http2_strerror(uint32_t error_code);
3436 * Initializes |pri_spec| with the |stream_id| of the stream to depend
3437 * on with |weight| and its exclusive flag. If |exclusive| is
3438 * nonzero, exclusive flag is set.
3440 * The |weight| must be in [:enum:`NGHTTP2_MIN_WEIGHT`,
3441 * :enum:`NGHTTP2_MAX_WEIGHT`], inclusive.
3443 NGHTTP2_EXTERN void nghttp2_priority_spec_init(nghttp2_priority_spec *pri_spec,
3445 int32_t weight, int exclusive);
3450 * Initializes |pri_spec| with the default values. The default values
3451 * are: stream_id = 0, weight = :macro:`NGHTTP2_DEFAULT_WEIGHT` and
3455 nghttp2_priority_spec_default_init(nghttp2_priority_spec *pri_spec);
3460 * Returns nonzero if the |pri_spec| is filled with default values.
3463 nghttp2_priority_spec_check_default(const nghttp2_priority_spec *pri_spec);
3468 * Submits HEADERS frame and optionally one or more DATA frames.
3470 * The |pri_spec| is priority specification of this request. ``NULL``
3471 * means the default priority (see
3472 * `nghttp2_priority_spec_default_init()`). To specify the priority,
3473 * use `nghttp2_priority_spec_init()`. If |pri_spec| is not ``NULL``,
3474 * this function will copy its data members.
3476 * The ``pri_spec->weight`` must be in [:enum:`NGHTTP2_MIN_WEIGHT`,
3477 * :enum:`NGHTTP2_MAX_WEIGHT`], inclusive. If ``pri_spec->weight`` is
3478 * strictly less than :enum:`NGHTTP2_MIN_WEIGHT`, it becomes
3479 * :enum:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than
3480 * :enum:`NGHTTP2_MAX_WEIGHT`, it becomes :enum:`NGHTTP2_MAX_WEIGHT`.
3482 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with
3483 * |nvlen| elements. The application is responsible to include
3484 * required pseudo-header fields (header field whose name starts with
3485 * ":") in |nva| and must place pseudo-headers before regular header
3488 * This function creates copies of all name/value pairs in |nva|. It
3489 * also lower-cases all names in |nva|. The order of elements in
3490 * |nva| is preserved. For header fields with
3491 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME` and
3492 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, header field name
3493 * and value are not copied respectively. With
3494 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME`, application is responsible to
3495 * pass header field name in lowercase. The application should
3496 * maintain the references to them until
3497 * :type:`nghttp2_on_frame_send_callback` or
3498 * :type:`nghttp2_on_frame_not_send_callback` is called.
3500 * HTTP/2 specification has requirement about header fields in the
3501 * request HEADERS. See the specification for more details.
3503 * If |data_prd| is not ``NULL``, it provides data which will be sent
3504 * in subsequent DATA frames. In this case, a method that allows
3505 * request message bodies
3506 * (https://tools.ietf.org/html/rfc7231#section-4) must be specified
3507 * with ``:method`` key in |nva| (e.g. ``POST``). This function does
3508 * not take ownership of the |data_prd|. The function copies the
3509 * members of the |data_prd|. If |data_prd| is ``NULL``, HEADERS have
3510 * END_STREAM set. The |stream_user_data| is data associated to the
3511 * stream opened by this request and can be an arbitrary pointer,
3512 * which can be retrieved later by
3513 * `nghttp2_session_get_stream_user_data()`.
3515 * This function returns assigned stream ID if it succeeds, or one of
3516 * the following negative error codes:
3518 * :enum:`NGHTTP2_ERR_NOMEM`
3520 * :enum:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
3521 * No stream ID is available because maximum stream ID was
3523 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3524 * Trying to depend on itself (new stream ID equals
3525 * ``pri_spec->stream_id``).
3526 * :enum:`NGHTTP2_ERR_PROTO`
3527 * The |session| is server session.
3531 * This function returns assigned stream ID if it succeeds. But
3532 * that stream is not opened yet. The application must not submit
3533 * frame to that stream ID before
3534 * :type:`nghttp2_before_frame_send_callback` is called for this
3538 NGHTTP2_EXTERN int32_t
3539 nghttp2_submit_request(nghttp2_session *session,
3540 const nghttp2_priority_spec *pri_spec,
3541 const nghttp2_nv *nva, size_t nvlen,
3542 const nghttp2_data_provider *data_prd,
3543 void *stream_user_data);
3548 * Submits response HEADERS frame and optionally one or more DATA
3549 * frames against the stream |stream_id|.
3551 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with
3552 * |nvlen| elements. The application is responsible to include
3553 * required pseudo-header fields (header field whose name starts with
3554 * ":") in |nva| and must place pseudo-headers before regular header
3557 * This function creates copies of all name/value pairs in |nva|. It
3558 * also lower-cases all names in |nva|. The order of elements in
3559 * |nva| is preserved. For header fields with
3560 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME` and
3561 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, header field name
3562 * and value are not copied respectively. With
3563 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME`, application is responsible to
3564 * pass header field name in lowercase. The application should
3565 * maintain the references to them until
3566 * :type:`nghttp2_on_frame_send_callback` or
3567 * :type:`nghttp2_on_frame_not_send_callback` is called.
3569 * HTTP/2 specification has requirement about header fields in the
3570 * response HEADERS. See the specification for more details.
3572 * If |data_prd| is not ``NULL``, it provides data which will be sent
3573 * in subsequent DATA frames. This function does not take ownership
3574 * of the |data_prd|. The function copies the members of the
3575 * |data_prd|. If |data_prd| is ``NULL``, HEADERS will have
3576 * END_STREAM flag set.
3578 * This method can be used as normal HTTP response and push response.
3579 * When pushing a resource using this function, the |session| must be
3580 * configured using `nghttp2_session_server_new()` or its variants and
3581 * the target stream denoted by the |stream_id| must be reserved using
3582 * `nghttp2_submit_push_promise()`.
3584 * To send non-final response headers (e.g., HTTP status 101), don't
3585 * use this function because this function half-closes the outbound
3586 * stream. Instead, use `nghttp2_submit_headers()` for this purpose.
3588 * This function returns 0 if it succeeds, or one of the following
3589 * negative error codes:
3591 * :enum:`NGHTTP2_ERR_NOMEM`
3593 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3594 * The |stream_id| is 0.
3595 * :enum:`NGHTTP2_ERR_DATA_EXIST`
3596 * DATA or HEADERS has been already submitted and not fully
3597 * processed yet. Normally, this does not happen, but when
3598 * application wrongly calls `nghttp2_submit_response()` twice,
3600 * :enum:`NGHTTP2_ERR_PROTO`
3601 * The |session| is client session.
3605 * Calling this function twice for the same stream ID may lead to
3606 * program crash. It is generally considered to a programming error
3607 * to commit response twice.
3610 nghttp2_submit_response(nghttp2_session *session, int32_t stream_id,
3611 const nghttp2_nv *nva, size_t nvlen,
3612 const nghttp2_data_provider *data_prd);
3617 * Submits trailer fields HEADERS against the stream |stream_id|.
3619 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with
3620 * |nvlen| elements. The application is responsible not to include
3621 * pseudo-header fields (header field whose name starts with ":") in
3624 * This function creates copies of all name/value pairs in |nva|. It
3625 * also lower-cases all names in |nva|. The order of elements in
3626 * |nva| is preserved. For header fields with
3627 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME` and
3628 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, header field name
3629 * and value are not copied respectively. With
3630 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME`, application is responsible to
3631 * pass header field name in lowercase. The application should
3632 * maintain the references to them until
3633 * :type:`nghttp2_on_frame_send_callback` or
3634 * :type:`nghttp2_on_frame_not_send_callback` is called.
3636 * For server, trailer fields must follow response HEADERS or response
3637 * DATA without END_STREAM flat set. The library does not enforce
3638 * this requirement, and applications should do this for themselves.
3639 * If `nghttp2_submit_trailer()` is called before any response HEADERS
3640 * submission (usually by `nghttp2_submit_response()`), the content of
3641 * |nva| will be sent as response headers, which will result in error.
3643 * This function has the same effect with `nghttp2_submit_headers()`,
3644 * with flags = :enum:`NGHTTP2_FLAG_END_STREAM` and both pri_spec and
3645 * stream_user_data to NULL.
3647 * To submit trailer fields after `nghttp2_submit_response()` is
3648 * called, the application has to specify
3649 * :type:`nghttp2_data_provider` to `nghttp2_submit_response()`.
3650 * Inside of :type:`nghttp2_data_source_read_callback`, when setting
3651 * :enum:`NGHTTP2_DATA_FLAG_EOF`, also set
3652 * :enum:`NGHTTP2_DATA_FLAG_NO_END_STREAM`. After that, the
3653 * application can send trailer fields using
3654 * `nghttp2_submit_trailer()`. `nghttp2_submit_trailer()` can be used
3655 * inside :type:`nghttp2_data_source_read_callback`.
3657 * This function returns 0 if it succeeds and |stream_id| is -1.
3658 * Otherwise, this function returns 0 if it succeeds, or one of the
3659 * following negative error codes:
3661 * :enum:`NGHTTP2_ERR_NOMEM`
3663 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3664 * The |stream_id| is 0.
3666 NGHTTP2_EXTERN int nghttp2_submit_trailer(nghttp2_session *session,
3668 const nghttp2_nv *nva, size_t nvlen);
3673 * Submits HEADERS frame. The |flags| is bitwise OR of the
3676 * * :enum:`NGHTTP2_FLAG_END_STREAM`
3678 * If |flags| includes :enum:`NGHTTP2_FLAG_END_STREAM`, this frame has
3679 * END_STREAM flag set.
3681 * The library handles the CONTINUATION frame internally and it
3682 * correctly sets END_HEADERS to the last sequence of the PUSH_PROMISE
3683 * or CONTINUATION frame.
3685 * If the |stream_id| is -1, this frame is assumed as request (i.e.,
3686 * request HEADERS frame which opens new stream). In this case, the
3687 * assigned stream ID will be returned. Otherwise, specify stream ID
3690 * The |pri_spec| is priority specification of this request. ``NULL``
3691 * means the default priority (see
3692 * `nghttp2_priority_spec_default_init()`). To specify the priority,
3693 * use `nghttp2_priority_spec_init()`. If |pri_spec| is not ``NULL``,
3694 * this function will copy its data members.
3696 * The ``pri_spec->weight`` must be in [:enum:`NGHTTP2_MIN_WEIGHT`,
3697 * :enum:`NGHTTP2_MAX_WEIGHT`], inclusive. If ``pri_spec->weight`` is
3698 * strictly less than :enum:`NGHTTP2_MIN_WEIGHT`, it becomes
3699 * :enum:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than
3700 * :enum:`NGHTTP2_MAX_WEIGHT`, it becomes :enum:`NGHTTP2_MAX_WEIGHT`.
3702 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with
3703 * |nvlen| elements. The application is responsible to include
3704 * required pseudo-header fields (header field whose name starts with
3705 * ":") in |nva| and must place pseudo-headers before regular header
3708 * This function creates copies of all name/value pairs in |nva|. It
3709 * also lower-cases all names in |nva|. The order of elements in
3710 * |nva| is preserved. For header fields with
3711 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME` and
3712 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, header field name
3713 * and value are not copied respectively. With
3714 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME`, application is responsible to
3715 * pass header field name in lowercase. The application should
3716 * maintain the references to them until
3717 * :type:`nghttp2_on_frame_send_callback` or
3718 * :type:`nghttp2_on_frame_not_send_callback` is called.
3720 * The |stream_user_data| is a pointer to an arbitrary data which is
3721 * associated to the stream this frame will open. Therefore it is
3722 * only used if this frame opens streams, in other words, it changes
3723 * stream state from idle or reserved to open.
3725 * This function is low-level in a sense that the application code can
3726 * specify flags directly. For usual HTTP request,
3727 * `nghttp2_submit_request()` is useful. Likewise, for HTTP response,
3728 * prefer `nghttp2_submit_response()`.
3730 * This function returns newly assigned stream ID if it succeeds and
3731 * |stream_id| is -1. Otherwise, this function returns 0 if it
3732 * succeeds, or one of the following negative error codes:
3734 * :enum:`NGHTTP2_ERR_NOMEM`
3736 * :enum:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
3737 * No stream ID is available because maximum stream ID was
3739 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3740 * The |stream_id| is 0; or trying to depend on itself (stream ID
3741 * equals ``pri_spec->stream_id``).
3742 * :enum:`NGHTTP2_ERR_DATA_EXIST`
3743 * DATA or HEADERS has been already submitted and not fully
3744 * processed yet. This happens if stream denoted by |stream_id|
3745 * is in reserved state.
3746 * :enum:`NGHTTP2_ERR_PROTO`
3747 * The |stream_id| is -1, and |session| is server session.
3751 * This function returns assigned stream ID if it succeeds and
3752 * |stream_id| is -1. But that stream is not opened yet. The
3753 * application must not submit frame to that stream ID before
3754 * :type:`nghttp2_before_frame_send_callback` is called for this
3758 NGHTTP2_EXTERN int32_t
3759 nghttp2_submit_headers(nghttp2_session *session, uint8_t flags,
3760 int32_t stream_id, const nghttp2_priority_spec *pri_spec,
3761 const nghttp2_nv *nva, size_t nvlen,
3762 void *stream_user_data);
3767 * Submits one or more DATA frames to the stream |stream_id|. The
3768 * data to be sent are provided by |data_prd|. If |flags| contains
3769 * :enum:`NGHTTP2_FLAG_END_STREAM`, the last DATA frame has END_STREAM
3772 * This function does not take ownership of the |data_prd|. The
3773 * function copies the members of the |data_prd|.
3775 * This function returns 0 if it succeeds, or one of the following
3776 * negative error codes:
3778 * :enum:`NGHTTP2_ERR_NOMEM`
3780 * :enum:`NGHTTP2_ERR_DATA_EXIST`
3781 * DATA or HEADERS has been already submitted and not fully
3783 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3784 * The |stream_id| is 0.
3785 * :enum:`NGHTTP2_ERR_STREAM_CLOSED`
3786 * The stream was already closed; or the |stream_id| is invalid.
3790 * Currently, only one DATA or HEADERS is allowed for a stream at a
3791 * time. Submitting these frames more than once before first DATA
3792 * or HEADERS is finished results in :enum:`NGHTTP2_ERR_DATA_EXIST`
3793 * error code. The earliest callback which tells that previous
3794 * frame is done is :type:`nghttp2_on_frame_send_callback`. In side
3795 * that callback, new data can be submitted using
3796 * `nghttp2_submit_data()`. Of course, all data except for last one
3797 * must not have :enum:`NGHTTP2_FLAG_END_STREAM` flag set in
3798 * |flags|. This sounds a bit complicated, and we recommend to use
3799 * `nghttp2_submit_request()` and `nghttp2_submit_response()` to
3800 * avoid this cascading issue. The experience shows that for HTTP
3801 * use, these two functions are enough to implement both client and
3804 NGHTTP2_EXTERN int nghttp2_submit_data(nghttp2_session *session, uint8_t flags,
3806 const nghttp2_data_provider *data_prd);
3811 * Submits PRIORITY frame to change the priority of stream |stream_id|
3812 * to the priority specification |pri_spec|.
3814 * The |flags| is currently ignored and should be
3815 * :enum:`NGHTTP2_FLAG_NONE`.
3817 * The |pri_spec| is priority specification of this request. ``NULL``
3818 * is not allowed for this function. To specify the priority, use
3819 * `nghttp2_priority_spec_init()`. This function will copy its data
3822 * The ``pri_spec->weight`` must be in [:enum:`NGHTTP2_MIN_WEIGHT`,
3823 * :enum:`NGHTTP2_MAX_WEIGHT`], inclusive. If ``pri_spec->weight`` is
3824 * strictly less than :enum:`NGHTTP2_MIN_WEIGHT`, it becomes
3825 * :enum:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than
3826 * :enum:`NGHTTP2_MAX_WEIGHT`, it becomes :enum:`NGHTTP2_MAX_WEIGHT`.
3828 * This function returns 0 if it succeeds, or one of the following
3829 * negative error codes:
3831 * :enum:`NGHTTP2_ERR_NOMEM`
3833 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3834 * The |stream_id| is 0; or the |pri_spec| is NULL; or trying to
3838 nghttp2_submit_priority(nghttp2_session *session, uint8_t flags,
3840 const nghttp2_priority_spec *pri_spec);
3845 * Submits RST_STREAM frame to cancel/reject the stream |stream_id|
3846 * with the error code |error_code|.
3848 * The pre-defined error code is one of :enum:`nghttp2_error_code`.
3850 * The |flags| is currently ignored and should be
3851 * :enum:`NGHTTP2_FLAG_NONE`.
3853 * This function returns 0 if it succeeds, or one of the following
3854 * negative error codes:
3856 * :enum:`NGHTTP2_ERR_NOMEM`
3858 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3859 * The |stream_id| is 0.
3861 NGHTTP2_EXTERN int nghttp2_submit_rst_stream(nghttp2_session *session,
3862 uint8_t flags, int32_t stream_id,
3863 uint32_t error_code);
3868 * Stores local settings and submits SETTINGS frame. The |iv| is the
3869 * pointer to the array of :type:`nghttp2_settings_entry`. The |niv|
3870 * indicates the number of :type:`nghttp2_settings_entry`.
3872 * The |flags| is currently ignored and should be
3873 * :enum:`NGHTTP2_FLAG_NONE`.
3875 * This function does not take ownership of the |iv|. This function
3876 * copies all the elements in the |iv|.
3878 * While updating individual stream's local window size, if the window
3879 * size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE,
3880 * RST_STREAM is issued against such a stream.
3882 * SETTINGS with :enum:`NGHTTP2_FLAG_ACK` is automatically submitted
3883 * by the library and application could not send it at its will.
3885 * This function returns 0 if it succeeds, or one of the following
3886 * negative error codes:
3888 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3889 * The |iv| contains invalid value (e.g., initial window size
3890 * strictly greater than (1 << 31) - 1.
3891 * :enum:`NGHTTP2_ERR_NOMEM`
3894 NGHTTP2_EXTERN int nghttp2_submit_settings(nghttp2_session *session,
3896 const nghttp2_settings_entry *iv,
3902 * Submits PUSH_PROMISE frame.
3904 * The |flags| is currently ignored. The library handles the
3905 * CONTINUATION frame internally and it correctly sets END_HEADERS to
3906 * the last sequence of the PUSH_PROMISE or CONTINUATION frame.
3908 * The |stream_id| must be client initiated 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_NO_COPY_NAME` and
3920 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, header field name
3921 * and value are not copied respectively. With
3922 * :enum:`NGHTTP2_NV_FLAG_NO_COPY_NAME`, application is responsible to
3923 * pass header field name in lowercase. The application should
3924 * 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 * The |promised_stream_user_data| is a pointer to an arbitrary data
3929 * which is associated to the promised stream this frame will open and
3930 * make it in reserved state. It is available using
3931 * `nghttp2_session_get_stream_user_data()`. The application can
3932 * access it in :type:`nghttp2_before_frame_send_callback` and
3933 * :type:`nghttp2_on_frame_send_callback` of this frame.
3935 * The client side is not allowed to use this function.
3937 * To submit response headers and data, use
3938 * `nghttp2_submit_response()`.
3940 * This function returns assigned promised stream ID if it succeeds,
3941 * or one of the following negative error codes:
3943 * :enum:`NGHTTP2_ERR_NOMEM`
3945 * :enum:`NGHTTP2_ERR_PROTO`
3946 * This function was invoked when |session| is initialized as
3948 * :enum:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
3949 * No stream ID is available because maximum stream ID was
3951 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3952 * The |stream_id| is 0; The |stream_id| does not designate stream
3953 * that peer initiated.
3954 * :enum:`NGHTTP2_ERR_STREAM_CLOSED`
3955 * The stream was already closed; or the |stream_id| is invalid.
3959 * This function returns assigned promised stream ID if it succeeds.
3960 * As of 1.16.0, stream object for pushed resource is created when
3961 * this function succeeds. In that case, the application can submit
3962 * push response for the promised frame.
3964 * In 1.15.0 or prior versions, pushed stream is not opened yet when
3965 * this function succeeds. The application must not submit frame to
3966 * that stream ID before :type:`nghttp2_before_frame_send_callback`
3967 * is called for this frame.
3970 NGHTTP2_EXTERN int32_t
3971 nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags,
3972 int32_t stream_id, const nghttp2_nv *nva,
3973 size_t nvlen, void *promised_stream_user_data);
3978 * Submits PING frame. You don't have to send PING back when you
3979 * received PING frame. The library automatically submits PING frame
3982 * The |flags| is bitwise OR of 0 or more of the following value.
3984 * * :enum:`NGHTTP2_FLAG_ACK`
3986 * Unless `nghttp2_option_set_no_auto_ping_ack()` is used, the |flags|
3987 * should be :enum:`NGHTTP2_FLAG_NONE`.
3989 * If the |opaque_data| is non ``NULL``, then it should point to the 8
3990 * bytes array of memory to specify opaque data to send with PING
3991 * frame. If the |opaque_data| is ``NULL``, zero-cleared 8 bytes will
3992 * be sent as opaque data.
3994 * This function returns 0 if it succeeds, or one of the following
3995 * negative error codes:
3997 * :enum:`NGHTTP2_ERR_NOMEM`
4000 NGHTTP2_EXTERN int nghttp2_submit_ping(nghttp2_session *session, uint8_t flags,
4001 const uint8_t *opaque_data);
4006 * Submits GOAWAY frame with the last stream ID |last_stream_id| and
4007 * the error code |error_code|.
4009 * The pre-defined error code is one of :enum:`nghttp2_error_code`.
4011 * The |flags| is currently ignored and should be
4012 * :enum:`NGHTTP2_FLAG_NONE`.
4014 * The |last_stream_id| is peer's stream ID or 0. So if |session| is
4015 * initialized as client, |last_stream_id| must be even or 0. If
4016 * |session| is initialized as server, |last_stream_id| must be odd or
4019 * The HTTP/2 specification says last_stream_id must not be increased
4020 * from the value previously sent. So the actual value sent as
4021 * last_stream_id is the minimum value between the given
4022 * |last_stream_id| and the last_stream_id previously sent to the
4025 * If the |opaque_data| is not ``NULL`` and |opaque_data_len| is not
4026 * zero, those data will be sent as additional debug data. The
4027 * library makes a copy of the memory region pointed by |opaque_data|
4028 * with the length |opaque_data_len|, so the caller does not need to
4029 * keep this memory after the return of this function. If the
4030 * |opaque_data_len| is 0, the |opaque_data| could be ``NULL``.
4032 * After successful transmission of GOAWAY, following things happen.
4033 * All incoming streams having strictly more than |last_stream_id| are
4034 * closed. All incoming HEADERS which starts new stream are simply
4035 * ignored. After all active streams are handled, both
4036 * `nghttp2_session_want_read()` and `nghttp2_session_want_write()`
4037 * return 0 and the application can close session.
4039 * This function returns 0 if it succeeds, or one of the following
4040 * negative error codes:
4042 * :enum:`NGHTTP2_ERR_NOMEM`
4044 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
4045 * The |opaque_data_len| is too large; the |last_stream_id| is
4048 NGHTTP2_EXTERN int nghttp2_submit_goaway(nghttp2_session *session,
4049 uint8_t flags, int32_t last_stream_id,
4050 uint32_t error_code,
4051 const uint8_t *opaque_data,
4052 size_t opaque_data_len);
4057 * Returns the last stream ID of a stream for which
4058 * :type:`nghttp2_on_frame_recv_callback` was invoked most recently.
4059 * The returned value can be used as last_stream_id parameter for
4060 * `nghttp2_submit_goaway()` and
4061 * `nghttp2_session_terminate_session2()`.
4063 * This function always succeeds.
4065 NGHTTP2_EXTERN int32_t
4066 nghttp2_session_get_last_proc_stream_id(nghttp2_session *session);
4071 * Returns nonzero if new request can be sent from local endpoint.
4073 * This function return 0 if request is not allowed for this session.
4074 * There are several reasons why request is not allowed. Some of the
4075 * reasons are: session is server; stream ID has been spent; GOAWAY
4076 * has been sent or received.
4078 * The application can call `nghttp2_submit_request()` without
4079 * consulting this function. In that case, `nghttp2_submit_request()`
4080 * may return error. Or, request is failed to sent, and
4081 * :type:`nghttp2_on_stream_close_callback` is called.
4084 nghttp2_session_check_request_allowed(nghttp2_session *session);
4089 * Returns nonzero if |session| is initialized as server side session.
4092 nghttp2_session_check_server_session(nghttp2_session *session);
4097 * Submits WINDOW_UPDATE frame.
4099 * The |flags| is currently ignored and should be
4100 * :enum:`NGHTTP2_FLAG_NONE`.
4102 * The |stream_id| is the stream ID to send this WINDOW_UPDATE. To
4103 * send connection level WINDOW_UPDATE, specify 0 to |stream_id|.
4105 * If the |window_size_increment| is positive, the WINDOW_UPDATE with
4106 * that value as window_size_increment is queued. If the
4107 * |window_size_increment| is larger than the received bytes from the
4108 * remote endpoint, the local window size is increased by that
4109 * difference. If the sole purpose is to increase the local window
4110 * size, consider to use `nghttp2_session_set_local_window_size()`.
4112 * If the |window_size_increment| is negative, the local window size
4113 * is decreased by -|window_size_increment|. If automatic
4114 * WINDOW_UPDATE is enabled
4115 * (`nghttp2_option_set_no_auto_window_update()`), and the library
4116 * decided that the WINDOW_UPDATE should be submitted, then
4117 * WINDOW_UPDATE is queued with the current received bytes count. If
4118 * the sole purpose is to decrease the local window size, consider to
4119 * use `nghttp2_session_set_local_window_size()`.
4121 * If the |window_size_increment| is 0, the function does nothing and
4124 * This function returns 0 if it succeeds, or one of the following
4125 * negative error codes:
4127 * :enum:`NGHTTP2_ERR_FLOW_CONTROL`
4128 * The local window size overflow or gets negative.
4129 * :enum:`NGHTTP2_ERR_NOMEM`
4132 NGHTTP2_EXTERN int nghttp2_submit_window_update(nghttp2_session *session,
4135 int32_t window_size_increment);
4140 * Set local window size (local endpoints's window size) to the given
4141 * |window_size| for the given stream denoted by |stream_id|. To
4142 * change connection level window size, specify 0 to |stream_id|. To
4143 * increase window size, this function may submit WINDOW_UPDATE frame
4144 * to transmission queue.
4146 * The |flags| is currently ignored and should be
4147 * :enum:`NGHTTP2_FLAG_NONE`.
4149 * This sounds similar to `nghttp2_submit_window_update()`, but there
4150 * are 2 differences. The first difference is that this function
4151 * takes the absolute value of window size to set, rather than the
4152 * delta. To change the window size, this may be easier to use since
4153 * the application just declares the intended window size, rather than
4154 * calculating delta. The second difference is that
4155 * `nghttp2_submit_window_update()` affects the received bytes count
4156 * which has not acked yet. By the specification of
4157 * `nghttp2_submit_window_update()`, to strictly increase the local
4158 * window size, we have to submit delta including all received bytes
4159 * count, which might not be desirable in some cases. On the other
4160 * hand, this function does not affect the received bytes count. It
4161 * just sets the local window size to the given value.
4163 * This function returns 0 if it succeeds, or one of the following
4164 * negative error codes:
4166 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
4167 * The |stream_id| is negative.
4168 * :enum:`NGHTTP2_ERR_NOMEM`
4172 nghttp2_session_set_local_window_size(nghttp2_session *session, uint8_t flags,
4173 int32_t stream_id, int32_t window_size);
4178 * Submits extension frame.
4180 * Application can pass arbitrary frame flags and stream ID in |flags|
4181 * and |stream_id| respectively. The |payload| is opaque pointer, and
4182 * it can be accessible though ``frame->ext.payload`` in
4183 * :type:`nghttp2_pack_extension_callback`. The library will not own
4184 * passed |payload| pointer.
4186 * The application must set :type:`nghttp2_pack_extension_callback`
4187 * using `nghttp2_session_callbacks_set_pack_extension_callback()`.
4189 * The application should retain the memory pointed by |payload| until
4190 * the transmission of extension frame is done (which is indicated by
4191 * :type:`nghttp2_on_frame_send_callback`), or transmission fails
4192 * (which is indicated by :type:`nghttp2_on_frame_not_send_callback`).
4193 * If application does not touch this memory region after packing it
4194 * into a wire format, application can free it inside
4195 * :type:`nghttp2_pack_extension_callback`.
4197 * The standard HTTP/2 frame cannot be sent with this function, so
4198 * |type| must be strictly grater than 0x9. Otherwise, this function
4199 * will fail with error code :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`.
4201 * This function returns 0 if it succeeds, or one of the following
4202 * negative error codes:
4204 * :enum:`NGHTTP2_ERR_INVALID_STATE`
4205 * If :type:`nghttp2_pack_extension_callback` is not set.
4206 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
4207 * If |type| specifies standard HTTP/2 frame type. The frame
4208 * types in the rage [0x0, 0x9], both inclusive, are standard
4209 * HTTP/2 frame type, and cannot be sent using this function.
4210 * :enum:`NGHTTP2_ERR_NOMEM`
4213 NGHTTP2_EXTERN int nghttp2_submit_extension(nghttp2_session *session,
4214 uint8_t type, uint8_t flags,
4215 int32_t stream_id, void *payload);
4220 * The payload of ALTSVC frame. ALTSVC frame is a non-critical
4221 * extension to HTTP/2. If this frame is received, and
4222 * `nghttp2_option_set_user_recv_extension_type()` is not set, and
4223 * `nghttp2_option_set_builtin_recv_extension_type()` is set for
4224 * :enum:`NGHTTP2_ALTSVC`, ``nghttp2_extension.payload`` will point to
4227 * It has the following members:
4231 * The pointer to origin which this alternative service is
4232 * associated with. This is not necessarily NULL-terminated.
4236 * The length of the |origin|.
4240 * The pointer to Alt-Svc field value contained in ALTSVC frame.
4241 * This is not necessarily NULL-terminated.
4243 uint8_t *field_value;
4245 * The length of the |field_value|.
4247 size_t field_value_len;
4248 } nghttp2_ext_altsvc;
4253 * Submits ALTSVC frame.
4255 * ALTSVC frame is a non-critical extension to HTTP/2, and defined in
4256 * is defined in `RFC 7383
4257 * <https://tools.ietf.org/html/rfc7838#section-4>`_.
4259 * The |flags| is currently ignored and should be
4260 * :enum:`NGHTTP2_FLAG_NONE`.
4262 * The |origin| points to the origin this alternative service is
4263 * associated with. The |origin_len| is the length of the origin. If
4264 * |stream_id| is 0, the origin must be specified. If |stream_id| is
4265 * not zero, the origin must be empty (in other words, |origin_len|
4268 * The ALTSVC frame is only usable from server side. If this function
4269 * is invoked with client side session, this function returns
4270 * :enum:`NGHTTP2_ERR_INVALID_STATE`.
4272 * This function returns 0 if it succeeds, or one of the following
4273 * negative error codes:
4275 * :enum:`NGHTTP2_ERR_NOMEM`
4277 * :enum:`NGHTTP2_ERR_INVALID_STATE`
4278 * The function is called from client side session
4279 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
4280 * The sum of |origin_len| and |field_value_len| is larger than
4281 * 16382; or |origin_len| is 0 while |stream_id| is 0; or
4282 * |origin_len| is not 0 while |stream_id| is not 0.
4284 NGHTTP2_EXTERN int nghttp2_submit_altsvc(nghttp2_session *session,
4285 uint8_t flags, int32_t stream_id,
4286 const uint8_t *origin,
4288 const uint8_t *field_value,
4289 size_t field_value_len);
4294 * Compares ``lhs->name`` of length ``lhs->namelen`` bytes and
4295 * ``rhs->name`` of length ``rhs->namelen`` bytes. Returns negative
4296 * integer if ``lhs->name`` is found to be less than ``rhs->name``; or
4297 * returns positive integer if ``lhs->name`` is found to be greater
4298 * than ``rhs->name``; or returns 0 otherwise.
4300 NGHTTP2_EXTERN int nghttp2_nv_compare_name(const nghttp2_nv *lhs,
4301 const nghttp2_nv *rhs);
4306 * A helper function for dealing with NPN in client side or ALPN in
4307 * server side. The |in| contains peer's protocol list in preferable
4308 * order. The format of |in| is length-prefixed and not
4309 * null-terminated. For example, ``h2`` and
4310 * ``http/1.1`` stored in |in| like this::
4315 * in[4..11] = "http/1.1"
4318 * The selection algorithm is as follows:
4320 * 1. If peer's list contains HTTP/2 protocol the library supports,
4321 * it is selected and returns 1. The following step is not taken.
4323 * 2. If peer's list contains ``http/1.1``, this function selects
4324 * ``http/1.1`` and returns 0. The following step is not taken.
4326 * 3. This function selects nothing and returns -1 (So called
4327 * non-overlap case). In this case, |out| and |outlen| are left
4330 * Selecting ``h2`` means that ``h2`` is written into |*out| and its
4331 * length (which is 2) is assigned to |*outlen|.
4333 * For ALPN, refer to https://tools.ietf.org/html/rfc7301
4335 * See http://technotes.googlecode.com/git/nextprotoneg.html for more
4336 * details about NPN.
4338 * For NPN, to use this method you should do something like::
4340 * static int select_next_proto_cb(SSL* ssl,
4341 * unsigned char **out,
4342 * unsigned char *outlen,
4343 * const unsigned char *in,
4344 * unsigned int inlen,
4348 * rv = nghttp2_select_next_protocol(out, outlen, in, inlen);
4350 * return SSL_TLSEXT_ERR_NOACK;
4353 * ((MyType*)arg)->http2_selected = 1;
4355 * return SSL_TLSEXT_ERR_OK;
4358 * SSL_CTX_set_next_proto_select_cb(ssl_ctx, select_next_proto_cb, my_obj);
4361 NGHTTP2_EXTERN int nghttp2_select_next_protocol(unsigned char **out,
4362 unsigned char *outlen,
4363 const unsigned char *in,
4364 unsigned int inlen);
4369 * Returns a pointer to a nghttp2_info struct with version information
4370 * about the run-time library in use. The |least_version| argument
4371 * can be set to a 24 bit numerical value for the least accepted
4372 * version number and if the condition is not met, this function will
4373 * return a ``NULL``. Pass in 0 to skip the version checking.
4375 NGHTTP2_EXTERN nghttp2_info *nghttp2_version(int least_version);
4380 * Returns nonzero if the :type:`nghttp2_error` library error code
4381 * |lib_error| is fatal.
4383 NGHTTP2_EXTERN int nghttp2_is_fatal(int lib_error_code);
4388 * Returns nonzero if HTTP header field name |name| of length |len| is
4389 * valid according to http://tools.ietf.org/html/rfc7230#section-3.2
4391 * Because this is a header field name in HTTP2, the upper cased alphabet
4392 * is treated as error.
4394 NGHTTP2_EXTERN int nghttp2_check_header_name(const uint8_t *name, size_t len);
4399 * Returns nonzero if HTTP header field value |value| of length |len|
4400 * is valid according to
4401 * http://tools.ietf.org/html/rfc7230#section-3.2
4403 NGHTTP2_EXTERN int nghttp2_check_header_value(const uint8_t *value, size_t len);
4407 struct nghttp2_hd_deflater;
4412 * HPACK deflater object.
4414 typedef struct nghttp2_hd_deflater nghttp2_hd_deflater;
4419 * Initializes |*deflater_ptr| for deflating name/values pairs.
4421 * The |deflate_hd_table_bufsize_max| is the upper bound of header
4422 * table size the deflater will use.
4424 * If this function fails, |*deflater_ptr| is left untouched.
4426 * This function returns 0 if it succeeds, or one of the following
4427 * negative error codes:
4429 * :enum:`NGHTTP2_ERR_NOMEM`
4432 NGHTTP2_EXTERN int nghttp2_hd_deflate_new(nghttp2_hd_deflater **deflater_ptr,
4433 size_t deflate_hd_table_bufsize_max);
4438 * Like `nghttp2_hd_deflate_new()`, but with additional custom memory
4439 * allocator specified in the |mem|.
4441 * The |mem| can be ``NULL`` and the call is equivalent to
4442 * `nghttp2_hd_deflate_new()`.
4444 * This function does not take ownership |mem|. The application is
4445 * responsible for freeing |mem|.
4447 * The library code does not refer to |mem| pointer after this
4448 * function returns, so the application can safely free it.
4450 NGHTTP2_EXTERN int nghttp2_hd_deflate_new2(nghttp2_hd_deflater **deflater_ptr,
4451 size_t deflate_hd_table_bufsize_max,
4457 * Deallocates any resources allocated for |deflater|.
4459 NGHTTP2_EXTERN void nghttp2_hd_deflate_del(nghttp2_hd_deflater *deflater);
4464 * Changes header table size of the |deflater| to
4465 * |settings_hd_table_bufsize_max| bytes. This may trigger eviction
4466 * in the dynamic table.
4468 * The |settings_hd_table_bufsize_max| should be the value received in
4469 * SETTINGS_HEADER_TABLE_SIZE.
4471 * The deflater never uses more memory than
4472 * ``deflate_hd_table_bufsize_max`` bytes specified in
4473 * `nghttp2_hd_deflate_new()`. Therefore, if
4474 * |settings_hd_table_bufsize_max| > ``deflate_hd_table_bufsize_max``,
4475 * resulting maximum table size becomes
4476 * ``deflate_hd_table_bufsize_max``.
4478 * This function returns 0 if it succeeds, or one of the following
4479 * negative error codes:
4481 * :enum:`NGHTTP2_ERR_NOMEM`
4485 nghttp2_hd_deflate_change_table_size(nghttp2_hd_deflater *deflater,
4486 size_t settings_hd_table_bufsize_max);
4491 * Deflates the |nva|, which has the |nvlen| name/value pairs, into
4492 * the |buf| of length |buflen|.
4494 * If |buf| is not large enough to store the deflated header block,
4495 * this function fails with :enum:`NGHTTP2_ERR_INSUFF_BUFSIZE`. The
4496 * caller should use `nghttp2_hd_deflate_bound()` to know the upper
4497 * bound of buffer size required to deflate given header name/value
4500 * Once this function fails, subsequent call of this function always
4501 * returns :enum:`NGHTTP2_ERR_HEADER_COMP`.
4503 * After this function returns, it is safe to delete the |nva|.
4505 * This function returns 0 if it succeeds, or one of the following
4506 * negative error codes:
4508 * :enum:`NGHTTP2_ERR_NOMEM`
4510 * :enum:`NGHTTP2_ERR_HEADER_COMP`
4511 * Deflation process has failed.
4512 * :enum:`NGHTTP2_ERR_INSUFF_BUFSIZE`
4513 * The provided |buflen| size is too small to hold the output.
4515 NGHTTP2_EXTERN ssize_t
4516 nghttp2_hd_deflate_hd(nghttp2_hd_deflater *deflater, uint8_t *buf,
4517 size_t buflen, const nghttp2_nv *nva, size_t nvlen);
4522 * Returns an upper bound on the compressed size after deflation of
4523 * |nva| of length |nvlen|.
4525 NGHTTP2_EXTERN size_t nghttp2_hd_deflate_bound(nghttp2_hd_deflater *deflater,
4526 const nghttp2_nv *nva,
4532 * Returns the number of entries that header table of |deflater|
4533 * contains. This is the sum of the number of static table and
4534 * dynamic table, so the return value is at least 61.
4537 size_t nghttp2_hd_deflate_get_num_table_entries(nghttp2_hd_deflater *deflater);
4542 * Returns the table entry denoted by |idx| from header table of
4543 * |deflater|. The |idx| is 1-based, and idx=1 returns first entry of
4544 * static table. idx=62 returns first entry of dynamic table if it
4545 * exists. Specifying idx=0 is error, and this function returns NULL.
4546 * If |idx| is strictly greater than the number of entries the tables
4547 * contain, this function returns NULL.
4551 nghttp2_hd_deflate_get_table_entry(nghttp2_hd_deflater *deflater, size_t idx);
4556 * Returns the used dynamic table size, including the overhead 32
4557 * bytes per entry described in RFC 7541.
4560 size_t nghttp2_hd_deflate_get_dynamic_table_size(nghttp2_hd_deflater *deflater);
4565 * Returns the maximum dynamic table size.
4569 nghttp2_hd_deflate_get_max_dynamic_table_size(nghttp2_hd_deflater *deflater);
4571 struct nghttp2_hd_inflater;
4576 * HPACK inflater object.
4578 typedef struct nghttp2_hd_inflater nghttp2_hd_inflater;
4583 * Initializes |*inflater_ptr| for inflating name/values pairs.
4585 * If this function fails, |*inflater_ptr| is left untouched.
4587 * This function returns 0 if it succeeds, or one of the following
4588 * negative error codes:
4590 * :enum:`NGHTTP2_ERR_NOMEM`
4593 NGHTTP2_EXTERN int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr);
4598 * Like `nghttp2_hd_inflate_new()`, but with additional custom memory
4599 * allocator specified in the |mem|.
4601 * The |mem| can be ``NULL`` and the call is equivalent to
4602 * `nghttp2_hd_inflate_new()`.
4604 * This function does not take ownership |mem|. The application is
4605 * responsible for freeing |mem|.
4607 * The library code does not refer to |mem| pointer after this
4608 * function returns, so the application can safely free it.
4610 NGHTTP2_EXTERN int nghttp2_hd_inflate_new2(nghttp2_hd_inflater **inflater_ptr,
4616 * Deallocates any resources allocated for |inflater|.
4618 NGHTTP2_EXTERN void nghttp2_hd_inflate_del(nghttp2_hd_inflater *inflater);
4623 * Changes header table size in the |inflater|. This may trigger
4624 * eviction in the dynamic table.
4626 * The |settings_hd_table_bufsize_max| should be the value transmitted
4627 * in SETTINGS_HEADER_TABLE_SIZE.
4629 * This function must not be called while header block is being
4630 * inflated. In other words, this function must be called after
4631 * initialization of |inflater|, but before calling
4632 * `nghttp2_hd_inflate_hd2()`, or after
4633 * `nghttp2_hd_inflate_end_headers()`. Otherwise,
4634 * `NGHTTP2_ERR_INVALID_STATE` was returned.
4636 * This function returns 0 if it succeeds, or one of the following
4637 * negative error codes:
4639 * :enum:`NGHTTP2_ERR_NOMEM`
4641 * :enum:`NGHTTP2_ERR_INVALID_STATE`
4642 * The function is called while header block is being inflated.
4643 * Probably, application missed to call
4644 * `nghttp2_hd_inflate_end_headers()`.
4647 nghttp2_hd_inflate_change_table_size(nghttp2_hd_inflater *inflater,
4648 size_t settings_hd_table_bufsize_max);
4653 * The flags for header inflation.
4659 NGHTTP2_HD_INFLATE_NONE = 0,
4661 * Indicates all headers were inflated.
4663 NGHTTP2_HD_INFLATE_FINAL = 0x01,
4665 * Indicates a header was emitted.
4667 NGHTTP2_HD_INFLATE_EMIT = 0x02
4668 } nghttp2_hd_inflate_flag;
4675 * Deprecated. Use `nghttp2_hd_inflate_hd2()` instead.
4677 * Inflates name/value block stored in |in| with length |inlen|. This
4678 * function performs decompression. For each successful emission of
4679 * header name/value pair, :enum:`NGHTTP2_HD_INFLATE_EMIT` is set in
4680 * |*inflate_flags| and name/value pair is assigned to the |nv_out|
4681 * and the function returns. The caller must not free the members of
4684 * The |nv_out| may include pointers to the memory region in the |in|.
4685 * The caller must retain the |in| while the |nv_out| is used.
4687 * The application should call this function repeatedly until the
4688 * ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
4689 * return value is non-negative. This means the all input values are
4690 * processed successfully. Then the application must call
4691 * `nghttp2_hd_inflate_end_headers()` to prepare for the next header
4694 * The caller can feed complete compressed header block. It also can
4695 * feed it in several chunks. The caller must set |in_final| to
4696 * nonzero if the given input is the last block of the compressed
4699 * This function returns the number of bytes processed if it succeeds,
4700 * or one of the following negative error codes:
4702 * :enum:`NGHTTP2_ERR_NOMEM`
4704 * :enum:`NGHTTP2_ERR_HEADER_COMP`
4705 * Inflation process has failed.
4706 * :enum:`NGHTTP2_ERR_BUFFER_ERROR`
4707 * The header field name or value is too large.
4711 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
4712 * uint8_t *in, size_t inlen, int final)
4718 * int inflate_flags = 0;
4720 * rv = nghttp2_hd_inflate_hd(hd_inflater, &nv, &inflate_flags,
4721 * in, inlen, final);
4724 * fprintf(stderr, "inflate failed with error code %zd", rv);
4731 * if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
4732 * fwrite(nv.name, nv.namelen, 1, stderr);
4733 * fprintf(stderr, ": ");
4734 * fwrite(nv.value, nv.valuelen, 1, stderr);
4735 * fprintf(stderr, "\n");
4737 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
4738 * nghttp2_hd_inflate_end_headers(hd_inflater);
4741 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
4751 NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd(nghttp2_hd_inflater *inflater,
4753 int *inflate_flags, uint8_t *in,
4754 size_t inlen, int in_final);
4759 * Inflates name/value block stored in |in| with length |inlen|. This
4760 * function performs decompression. For each successful emission of
4761 * header name/value pair, :enum:`NGHTTP2_HD_INFLATE_EMIT` is set in
4762 * |*inflate_flags| and name/value pair is assigned to the |nv_out|
4763 * and the function returns. The caller must not free the members of
4766 * The |nv_out| may include pointers to the memory region in the |in|.
4767 * The caller must retain the |in| while the |nv_out| is used.
4769 * The application should call this function repeatedly until the
4770 * ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
4771 * return value is non-negative. This means the all input values are
4772 * processed successfully. Then the application must call
4773 * `nghttp2_hd_inflate_end_headers()` to prepare for the next header
4776 * The caller can feed complete compressed header block. It also can
4777 * feed it in several chunks. The caller must set |in_final| to
4778 * nonzero if the given input is the last block of the compressed
4781 * This function returns the number of bytes processed if it succeeds,
4782 * or one of the following negative error codes:
4784 * :enum:`NGHTTP2_ERR_NOMEM`
4786 * :enum:`NGHTTP2_ERR_HEADER_COMP`
4787 * Inflation process has failed.
4788 * :enum:`NGHTTP2_ERR_BUFFER_ERROR`
4789 * The header field name or value is too large.
4793 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
4794 * uint8_t *in, size_t inlen, int final)
4800 * int inflate_flags = 0;
4802 * rv = nghttp2_hd_inflate_hd2(hd_inflater, &nv, &inflate_flags,
4803 * in, inlen, final);
4806 * fprintf(stderr, "inflate failed with error code %zd", rv);
4813 * if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
4814 * fwrite(nv.name, nv.namelen, 1, stderr);
4815 * fprintf(stderr, ": ");
4816 * fwrite(nv.value, nv.valuelen, 1, stderr);
4817 * fprintf(stderr, "\n");
4819 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
4820 * nghttp2_hd_inflate_end_headers(hd_inflater);
4823 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
4833 NGHTTP2_EXTERN ssize_t
4834 nghttp2_hd_inflate_hd2(nghttp2_hd_inflater *inflater, nghttp2_nv *nv_out,
4835 int *inflate_flags, const uint8_t *in, size_t inlen,
4841 * Signals the end of decompression for one header block.
4843 * This function returns 0 if it succeeds. Currently this function
4847 nghttp2_hd_inflate_end_headers(nghttp2_hd_inflater *inflater);
4852 * Returns the number of entries that header table of |inflater|
4853 * contains. This is the sum of the number of static table and
4854 * dynamic table, so the return value is at least 61.
4857 size_t nghttp2_hd_inflate_get_num_table_entries(nghttp2_hd_inflater *inflater);
4862 * Returns the table entry denoted by |idx| from header table of
4863 * |inflater|. The |idx| is 1-based, and idx=1 returns first entry of
4864 * static table. idx=62 returns first entry of dynamic table if it
4865 * exists. Specifying idx=0 is error, and this function returns NULL.
4866 * If |idx| is strictly greater than the number of entries the tables
4867 * contain, this function returns NULL.
4871 nghttp2_hd_inflate_get_table_entry(nghttp2_hd_inflater *inflater, size_t idx);
4876 * Returns the used dynamic table size, including the overhead 32
4877 * bytes per entry described in RFC 7541.
4880 size_t nghttp2_hd_inflate_get_dynamic_table_size(nghttp2_hd_inflater *inflater);
4885 * Returns the maximum dynamic table size.
4889 nghttp2_hd_inflate_get_max_dynamic_table_size(nghttp2_hd_inflater *inflater);
4891 struct nghttp2_stream;
4896 * The structure to represent HTTP/2 stream. The details of this
4897 * structure are intentionally hidden from the public API.
4899 typedef struct nghttp2_stream nghttp2_stream;
4904 * Returns pointer to :type:`nghttp2_stream` object denoted by
4905 * |stream_id|. If stream was not found, returns NULL.
4907 * Returns imaginary root stream (see
4908 * `nghttp2_session_get_root_stream()`) if 0 is given in |stream_id|.
4910 * Unless |stream_id| == 0, the returned pointer is valid until next
4911 * call of `nghttp2_session_send()`, `nghttp2_session_mem_send()`,
4912 * `nghttp2_session_recv()`, and `nghttp2_session_mem_recv()`.
4914 NGHTTP2_EXTERN nghttp2_stream *
4915 nghttp2_session_find_stream(nghttp2_session *session, int32_t stream_id);
4920 * State of stream as described in RFC 7540.
4926 NGHTTP2_STREAM_STATE_IDLE = 1,
4930 NGHTTP2_STREAM_STATE_OPEN,
4932 * reserved (local) state.
4934 NGHTTP2_STREAM_STATE_RESERVED_LOCAL,
4936 * reserved (remote) state.
4938 NGHTTP2_STREAM_STATE_RESERVED_REMOTE,
4940 * half closed (local) state.
4942 NGHTTP2_STREAM_STATE_HALF_CLOSED_LOCAL,
4944 * half closed (remote) state.
4946 NGHTTP2_STREAM_STATE_HALF_CLOSED_REMOTE,
4950 NGHTTP2_STREAM_STATE_CLOSED
4951 } nghttp2_stream_proto_state;
4956 * Returns state of |stream|. The root stream retrieved by
4957 * `nghttp2_session_get_root_stream()` will have stream state
4958 * :enum:`NGHTTP2_STREAM_STATE_IDLE`.
4960 NGHTTP2_EXTERN nghttp2_stream_proto_state
4961 nghttp2_stream_get_state(nghttp2_stream *stream);
4966 * Returns root of dependency tree, which is imaginary stream with
4967 * stream ID 0. The returned pointer is valid until |session| is
4968 * freed by `nghttp2_session_del()`.
4970 NGHTTP2_EXTERN nghttp2_stream *
4971 nghttp2_session_get_root_stream(nghttp2_session *session);
4976 * Returns the parent stream of |stream| in dependency tree. Returns
4977 * NULL if there is no such stream.
4979 NGHTTP2_EXTERN nghttp2_stream *
4980 nghttp2_stream_get_parent(nghttp2_stream *stream);
4982 NGHTTP2_EXTERN int32_t nghttp2_stream_get_stream_id(nghttp2_stream *stream);
4987 * Returns the next sibling stream of |stream| in dependency tree.
4988 * Returns NULL if there is no such stream.
4990 NGHTTP2_EXTERN nghttp2_stream *
4991 nghttp2_stream_get_next_sibling(nghttp2_stream *stream);
4996 * Returns the previous sibling stream of |stream| in dependency tree.
4997 * Returns NULL if there is no such stream.
4999 NGHTTP2_EXTERN nghttp2_stream *
5000 nghttp2_stream_get_previous_sibling(nghttp2_stream *stream);
5005 * Returns the first child stream of |stream| in dependency tree.
5006 * Returns NULL if there is no such stream.
5008 NGHTTP2_EXTERN nghttp2_stream *
5009 nghttp2_stream_get_first_child(nghttp2_stream *stream);
5014 * Returns dependency weight to the parent stream of |stream|.
5016 NGHTTP2_EXTERN int32_t nghttp2_stream_get_weight(nghttp2_stream *stream);
5021 * Returns the sum of the weight for |stream|'s children.
5023 NGHTTP2_EXTERN int32_t
5024 nghttp2_stream_get_sum_dependency_weight(nghttp2_stream *stream);
5030 #endif /* NGHTTP2_H */