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.
34 #include <sys/types.h>
36 #include <nghttp2/nghttp2ver.h>
41 * The protocol version identification string of this library
42 * supports. This identifier is used if HTTP/2 is used over TLS.
44 #define NGHTTP2_PROTO_VERSION_ID "h2-14"
48 * The length of :macro:`NGHTTP2_PROTO_VERSION_ID`.
50 #define NGHTTP2_PROTO_VERSION_ID_LEN 5
55 * The seriazlied form of ALPN protocol identifier this library
56 * supports. Notice that first byte is the length of following
57 * protocol identifier. This is the same wire format of `TLS ALPN
58 * extension <https://tools.ietf.org/html/rfc7301>`_. This is useful
59 * to process incoming ALPN tokens in wire format.
61 #define NGHTTP2_PROTO_ALPN "\x5h2-14"
66 * The length of :macro:`NGHTTP2_PROTO_ALPN`.
68 #define NGHTTP2_PROTO_ALPN_LEN (sizeof(NGHTTP2_PROTO_ALPN) - 1)
73 * The protocol version identification string of this library
74 * supports. This identifier is used if HTTP/2 is used over cleartext
77 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID "h2c-14"
82 * The length of :macro:`NGHTTP2_CLEARTEXT_PROTO_VERSION_ID`.
84 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN 6
86 struct nghttp2_session;
90 * The primary structure to hold the resources needed for a HTTP/2
91 * session. The details of this structure are intentionally hidden
92 * from the public API.
94 typedef struct nghttp2_session nghttp2_session;
99 * The age of :type:`nghttp2_info`
101 #define NGHTTP2_VERSION_AGE 1
106 * This struct is what `nghttp2_version()` returns. It holds
107 * information about the particular nghttp2 version.
111 * Age of this struct. This instance of nghttp2 sets it to
112 * :macro:`NGHTTP2_VERSION_AGE` but a future version may bump it and
113 * add more struct fields at the bottom
117 * the :macro:`NGHTTP2_VERSION_NUM` number (since age ==1)
121 * points to the :macro:`NGHTTP2_VERSION` string (since age ==1)
123 const char *version_str;
125 * points to the :macro:`NGHTTP2_PROTO_VERSION_ID` string this
126 * instance implements (since age ==1)
128 const char *proto_str;
129 /* -------- the above fields all exist when age == 1 */
135 * The default weight of stream dependency.
137 #define NGHTTP2_DEFAULT_WEIGHT 16
142 * The maximum weight of stream dependency.
144 #define NGHTTP2_MAX_WEIGHT 256
149 * The minimum weight of stream dependency.
151 #define NGHTTP2_MIN_WEIGHT 1
156 * The maximum window size
158 #define NGHTTP2_MAX_WINDOW_SIZE ((int32_t)((1U << 31) - 1))
163 * The initial window size for stream level flow control.
165 #define NGHTTP2_INITIAL_WINDOW_SIZE ((1 << 16) - 1)
169 * The initial window size for connection level flow control.
171 #define NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE ((1 << 16) - 1)
176 * The default header table size.
178 #define NGHTTP2_DEFAULT_HEADER_TABLE_SIZE (1 << 12)
183 * The client connection preface.
185 #define NGHTTP2_CLIENT_CONNECTION_PREFACE "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
190 * The length of :macro:`NGHTTP2_CLIENT_CONNECTION_PREFACE`.
192 #define NGHTTP2_CLIENT_CONNECTION_PREFACE_LEN 24
197 * The client connection header. This macro is obsoleted by
198 * NGHTTP2_CLIENT_CONNECTION_PREFACE.
200 #define NGHTTP2_CLIENT_CONNECTION_HEADER NGHTTP2_CLIENT_CONNECTION_PREFACE
205 * The length of :macro:`NGHTTP2_CLIENT_CONNECTION_HEADER`.
207 #define NGHTTP2_CLIENT_CONNECTION_HEADER_LEN \
208 NGHTTP2_CLIENT_CONNECTION_PREFACE_LEN
213 * Error codes used in this library. The code range is [-999, -500],
214 * inclusive. The following values are defined:
218 * Invalid argument passed.
220 NGHTTP2_ERR_INVALID_ARGUMENT = -501,
222 * Out of buffer space.
224 NGHTTP2_ERR_BUFFER_ERROR = -502,
226 * The specified protocol version is not supported.
228 NGHTTP2_ERR_UNSUPPORTED_VERSION = -503,
230 * Used as a return value from :type:`nghttp2_send_callback` and
231 * :type:`nghttp2_recv_callback` to indicate that the operation
234 NGHTTP2_ERR_WOULDBLOCK = -504,
236 * General protocol error
238 NGHTTP2_ERR_PROTO = -505,
240 * The frame is invalid.
242 NGHTTP2_ERR_INVALID_FRAME = -506,
244 * The peer performed a shutdown on the connection.
246 NGHTTP2_ERR_EOF = -507,
248 * Used as a return value from
249 * :func:`nghttp2_data_source_read_callback` to indicate that data
250 * transfer is postponed. See
251 * :func:`nghttp2_data_source_read_callback` for details.
253 NGHTTP2_ERR_DEFERRED = -508,
255 * Stream ID has reached the maximum value. Therefore no stream ID
258 NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE = -509,
260 * The stream is already closed; or the stream ID is invalid.
262 NGHTTP2_ERR_STREAM_CLOSED = -510,
264 * RST_STREAM has been added to the outbound queue. The stream is
267 NGHTTP2_ERR_STREAM_CLOSING = -511,
269 * The transmission is not allowed for this stream (e.g., a frame
270 * with END_STREAM flag set has already sent).
272 NGHTTP2_ERR_STREAM_SHUT_WR = -512,
274 * The stream ID is invalid.
276 NGHTTP2_ERR_INVALID_STREAM_ID = -513,
278 * The state of the stream is not valid (e.g., DATA cannot be sent
279 * to the stream if response HEADERS has not been sent).
281 NGHTTP2_ERR_INVALID_STREAM_STATE = -514,
283 * Another DATA frame has already been deferred.
285 NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515,
287 * Starting new stream is not allowed (e.g., GOAWAY has been sent
290 NGHTTP2_ERR_START_STREAM_NOT_ALLOWED = -516,
292 * GOAWAY has already been sent.
294 NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517,
296 * The received frame contains the invalid header block (e.g., There
297 * are duplicate header names; or the header names are not encoded
298 * in US-ASCII character set and not lower cased; or the header name
299 * is zero-length string; or the header value contains multiple
300 * in-sequence NUL bytes).
302 NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518,
304 * Indicates that the context is not suitable to perform the
305 * requested operation.
307 NGHTTP2_ERR_INVALID_STATE = -519,
309 * The user callback function failed due to the temporal error.
311 NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE = -521,
313 * The length of the frame is invalid, either too large or too small.
315 NGHTTP2_ERR_FRAME_SIZE_ERROR = -522,
317 * Header block inflate/deflate error.
319 NGHTTP2_ERR_HEADER_COMP = -523,
323 NGHTTP2_ERR_FLOW_CONTROL = -524,
325 * Insufficient buffer size given to function.
327 NGHTTP2_ERR_INSUFF_BUFSIZE = -525,
329 * Callback was paused by the application
331 NGHTTP2_ERR_PAUSE = -526,
333 * There are too many in-flight SETTING frame and no more
334 * transmission of SETTINGS is allowed.
336 NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGS = -527,
338 * The server push is disabled.
340 NGHTTP2_ERR_PUSH_DISABLED = -528,
342 * DATA frame for a given stream has been already submitted and has
343 * not been fully processed yet.
345 NGHTTP2_ERR_DATA_EXIST = -529,
347 * The current session is closing due to a connection error or
348 * `nghttp2_session_terminate_session()` is called.
350 NGHTTP2_ERR_SESSION_CLOSING = -530,
352 * The errors < :enum:`NGHTTP2_ERR_FATAL` mean that the library is
353 * under unexpected condition and processing was terminated (e.g.,
354 * out of memory). If application receives this error code, it must
355 * stop using that :type:`nghttp2_session` object and only allowed
356 * operation for that object is deallocate it using
357 * `nghttp2_session_del()`.
359 NGHTTP2_ERR_FATAL = -900,
361 * Out of memory. This is a fatal error.
363 NGHTTP2_ERR_NOMEM = -901,
365 * The user callback function failed. This is a fatal error.
367 NGHTTP2_ERR_CALLBACK_FAILURE = -902,
369 * Invalid connection preface was received and further processing is
372 NGHTTP2_ERR_BAD_PREFACE = -903
378 * The flags for header field name/value pair.
384 NGHTTP2_NV_FLAG_NONE = 0,
386 * Indicates that this name/value pair must not be indexed.
388 NGHTTP2_NV_FLAG_NO_INDEX = 0x01
394 * The name/value pair, which mainly used to represent header fields.
398 * The |name| byte string, which is not necessarily ``NULL``
403 * The |value| byte string, which is not necessarily ``NULL``
408 * The length of the |name|.
412 * The length of the |value|.
416 * Bitwise OR of one or more of :type:`nghttp2_nv_flag`.
424 * The frame types in HTTP/2 specification.
434 NGHTTP2_HEADERS = 0x01,
436 * The PRIORITY frame.
438 NGHTTP2_PRIORITY = 0x02,
440 * The RST_STREAM frame.
442 NGHTTP2_RST_STREAM = 0x03,
444 * The SETTINGS frame.
446 NGHTTP2_SETTINGS = 0x04,
448 * The PUSH_PROMISE frame.
450 NGHTTP2_PUSH_PROMISE = 0x05,
458 NGHTTP2_GOAWAY = 0x07,
460 * The WINDOW_UPDATE frame.
462 NGHTTP2_WINDOW_UPDATE = 0x08,
464 * The CONTINUATION frame.
466 NGHTTP2_CONTINUATION = 0x09
467 } nghttp2_frame_type;
472 * The extension frame types.
474 * TODO: The assigned frame types were carried from draft-12, and now
479 * The ALTSVC extension frame.
481 NGHTTP2_EXT_ALTSVC = 0x0a
482 } nghttp2_ext_frame_type;
487 * The flags for HTTP/2 frames. This enum defines all flags for all
494 NGHTTP2_FLAG_NONE = 0,
496 * The END_STREAM flag.
498 NGHTTP2_FLAG_END_STREAM = 0x01,
500 * The END_HEADERS flag.
502 NGHTTP2_FLAG_END_HEADERS = 0x04,
506 NGHTTP2_FLAG_ACK = 0x01,
510 NGHTTP2_FLAG_PADDED = 0x08,
514 NGHTTP2_FLAG_PRIORITY = 0x20
523 * SETTINGS_HEADER_TABLE_SIZE
525 NGHTTP2_SETTINGS_HEADER_TABLE_SIZE = 0x01,
527 * SETTINGS_ENABLE_PUSH
529 NGHTTP2_SETTINGS_ENABLE_PUSH = 0x02,
531 * SETTINGS_MAX_CONCURRENT_STREAMS
533 NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS = 0x03,
535 * SETTINGS_INITIAL_WINDOW_SIZE
537 NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE = 0x04,
539 * SETTINGS_MAX_FRAME_SIZE
541 NGHTTP2_SETTINGS_MAX_FRAME_SIZE = 0x05,
543 * SETTINGS_MAX_HEADER_LIST_SIZE
545 NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE = 0x06
546 } nghttp2_settings_id;
547 /* Note: If we add SETTINGS, update the capacity of
548 NGHTTP2_INBOUND_NUM_IV as well */
552 * Default maximum concurrent streams.
554 #define NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS ((1U << 31) - 1)
558 * The status codes for the RST_STREAM and GOAWAY frames.
564 NGHTTP2_NO_ERROR = 0x00,
568 NGHTTP2_PROTOCOL_ERROR = 0x01,
572 NGHTTP2_INTERNAL_ERROR = 0x02,
576 NGHTTP2_FLOW_CONTROL_ERROR = 0x03,
580 NGHTTP2_SETTINGS_TIMEOUT = 0x04,
584 NGHTTP2_STREAM_CLOSED = 0x05,
588 NGHTTP2_FRAME_SIZE_ERROR = 0x06,
592 NGHTTP2_REFUSED_STREAM = 0x07,
596 NGHTTP2_CANCEL = 0x08,
600 NGHTTP2_COMPRESSION_ERROR = 0x09,
604 NGHTTP2_CONNECT_ERROR = 0x0a,
608 NGHTTP2_ENHANCE_YOUR_CALM = 0x0b,
610 * INADEQUATE_SECURITY
612 NGHTTP2_INADEQUATE_SECURITY = 0x0c,
616 NGHTTP2_HTTP_1_1_REQUIRED = 0x0d
617 } nghttp2_error_code;
625 * The length field of this frame, excluding frame header.
629 * The stream identifier (aka, stream ID)
633 * The type of this frame. See `nghttp2_frame_type`.
641 * Reserved bit in frame header. Currently, this is always set to 0
642 * and application should not expect something useful in here.
650 * This union represents the some kind of data source passed to
651 * :type:`nghttp2_data_source_read_callback`.
655 * The integer field, suitable for a file descriptor.
659 * The pointer to an arbitrary object.
662 } nghttp2_data_source;
667 * The flags used to set in |data_flags| output parameter in
668 * :type:`nghttp2_data_source_read_callback`.
674 NGHTTP2_DATA_FLAG_NONE = 0,
676 * Indicates EOF was sensed.
678 NGHTTP2_DATA_FLAG_EOF = 0x01
684 * Callback function invoked when the library wants to read data from
685 * the |source|. The read data is sent in the stream |stream_id|.
686 * The implementation of this function must read at most |length|
687 * bytes of data from |source| (or possibly other places) and store
688 * them in |buf| and return number of data stored in |buf|. If EOF is
689 * reached, set :enum:`NGHTTP2_DATA_FLAG_EOF` flag in |*data_flags|.
691 * If the application wants to postpone DATA frames (e.g.,
692 * asynchronous I/O, or reading data blocks for long time), it is
693 * achieved by returning :enum:`NGHTTP2_ERR_DEFERRED` without reading
694 * any data in this invocation. The library removes DATA frame from
695 * the outgoing queue temporarily. To move back deferred DATA frame
696 * to outgoing queue, call `nghttp2_session_resume_data()`. In case
697 * of error, there are 2 choices. Returning
698 * :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close the stream
699 * by issuing RST_STREAM with :enum:`NGHTTP2_INTERNAL_ERROR`. If a
700 * different error code is desirable, use
701 * `nghttp2_submit_rst_stream()` with a desired error code and then
702 * return :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. Returning
703 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session
706 typedef ssize_t (*nghttp2_data_source_read_callback)(
707 nghttp2_session *session, int32_t stream_id, uint8_t *buf, size_t length,
708 uint32_t *data_flags, nghttp2_data_source *source, void *user_data);
713 * This struct represents the data source and the way to read a chunk
720 nghttp2_data_source source;
722 * The callback function to read a chunk of data from the |source|.
724 nghttp2_data_source_read_callback read_callback;
725 } nghttp2_data_provider;
730 * The DATA frame. The received data is delivered via
731 * :type:`nghttp2_on_data_chunk_recv_callback`.
736 * The length of the padding in this frame. This includes PAD_HIGH
745 * The category of HEADERS, which indicates the role of the frame. In
746 * HTTP/2 spec, request, response, push response and other arbitrary
747 * headers (e.g., trailers) are all called just HEADERS. To give the
748 * application the role of incoming HEADERS frame, we define several
753 * The HEADERS frame is opening new stream, which is analogous to
754 * SYN_STREAM in SPDY.
756 NGHTTP2_HCAT_REQUEST = 0,
758 * The HEADERS frame is the first response headers, which is
759 * analogous to SYN_REPLY in SPDY.
761 NGHTTP2_HCAT_RESPONSE = 1,
763 * The HEADERS frame is the first headers sent against reserved
766 NGHTTP2_HCAT_PUSH_RESPONSE = 2,
768 * The HEADERS frame which does not apply for the above categories,
769 * which is analogous to HEADERS in SPDY. If non-final response
770 * (e.g., status 1xx) is used, final response HEADERS frame will be
773 NGHTTP2_HCAT_HEADERS = 3
774 } nghttp2_headers_category;
779 * The structure to specify stream dependency.
783 * The stream ID of the stream to depend on. Specifying 0 makes
784 * stream not depend any other stream.
788 * The weight of this dependency.
792 * nonzero means exclusive dependency
795 } nghttp2_priority_spec;
800 * The HEADERS frame. It has the following members:
808 * The length of the padding in this frame. This includes PAD_HIGH
813 * The priority specification
815 nghttp2_priority_spec pri_spec;
817 * The name/value pairs.
821 * The number of name/value pairs in |nva|.
825 * The category of this HEADERS frame.
827 nghttp2_headers_category cat;
833 * The PRIORITY frame. It has the following members:
841 * The priority specification.
843 nghttp2_priority_spec pri_spec;
849 * The RST_STREAM frame. It has the following members:
857 * The error code. See :type:`nghttp2_error_code`.
860 } nghttp2_rst_stream;
865 * The SETTINGS ID/Value pair. It has the following members:
869 * The SETTINGS ID. See :type:`nghttp2_settings_id`.
873 * The value of this entry.
876 } nghttp2_settings_entry;
881 * The SETTINGS frame. It has the following members:
889 * The number of SETTINGS ID/Value pairs in |iv|.
893 * The pointer to the array of SETTINGS ID/Value pair.
895 nghttp2_settings_entry *iv;
901 * The PUSH_PROMISE frame. It has the following members:
909 * The length of the padding in this frame. This includes PAD_HIGH
914 * The name/value pairs.
918 * The number of name/value pairs in |nva|.
922 * The promised stream ID
924 int32_t promised_stream_id;
926 * Reserved bit. Currently this is always set to 0 and application
927 * should not expect something useful in here.
930 } nghttp2_push_promise;
935 * The PING frame. It has the following members:
945 uint8_t opaque_data[8];
951 * The GOAWAY frame. It has the following members:
959 * The last stream stream ID.
961 int32_t last_stream_id;
963 * The error code. See :type:`nghttp2_error_code`.
967 * The additional debug data
969 uint8_t *opaque_data;
971 * The length of |opaque_data| member.
973 size_t opaque_data_len;
975 * Reserved bit. Currently this is always set to 0 and application
976 * should not expect something useful in here.
984 * The WINDOW_UPDATE frame. It has the following members:
992 * The window size increment.
994 int32_t window_size_increment;
996 * Reserved bit. Currently this is always set to 0 and application
997 * should not expect something useful in here.
1000 } nghttp2_window_update;
1005 * The extension frame. It has following members:
1011 nghttp2_frame_hd hd;
1013 * The pointer to extension payload. The exact pointer type is
1014 * determined by hd.type.
1016 * If hd.type == :enum:`NGHTTP2_EXT_ALTSVC`, it is a pointer to
1017 * :type:`nghttp2_ext_altsvc`.
1020 } nghttp2_extension;
1025 * The ALTSVC extension frame payload. It has following members:
1031 uint8_t *protocol_id;
1041 * The length of |protocol_id|
1043 size_t protocol_id_len;
1045 * The length of |host|
1049 * The length of |origin|
1060 } nghttp2_ext_altsvc;
1065 * This union includes all frames to pass them to various function
1066 * calls as nghttp2_frame type. The CONTINUATION frame is omitted
1067 * from here because the library deals with it internally.
1071 * The frame header, which is convenient to inspect frame header.
1073 nghttp2_frame_hd hd;
1079 * The HEADERS frame.
1081 nghttp2_headers headers;
1083 * The PRIORITY frame.
1085 nghttp2_priority priority;
1087 * The RST_STREAM frame.
1089 nghttp2_rst_stream rst_stream;
1091 * The SETTINGS frame.
1093 nghttp2_settings settings;
1095 * The PUSH_PROMISE frame.
1097 nghttp2_push_promise push_promise;
1105 nghttp2_goaway goaway;
1107 * The WINDOW_UPDATE frame.
1109 nghttp2_window_update window_update;
1111 * The extension frame.
1113 nghttp2_extension ext;
1119 * Callback function invoked when |session| wants to send data to the
1120 * remote peer. The implementation of this function must send at most
1121 * |length| bytes of data stored in |data|. The |flags| is currently
1122 * not used and always 0. It must return the number of bytes sent if
1123 * it succeeds. If it cannot send any single byte without blocking,
1124 * it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. For other errors,
1125 * it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. The
1126 * |user_data| pointer is the third argument passed in to the call to
1127 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
1129 * This callback is required if the application uses
1130 * `nghttp2_session_send()` to send data to the remote endpoint. If
1131 * the application uses solely `nghttp2_session_mem_send()` instead,
1132 * this callback function is unnecessary.
1134 * To set this callback to :type:`nghttp2_session_callbacks`, use
1135 * `nghttp2_session_callbacks_set_send_callback()`.
1137 typedef ssize_t (*nghttp2_send_callback)(nghttp2_session *session,
1138 const uint8_t *data, size_t length,
1139 int flags, void *user_data);
1144 * Callback function invoked when |session| wants to receive data from
1145 * the remote peer. The implementation of this function must read at
1146 * most |length| bytes of data and store it in |buf|. The |flags| is
1147 * currently not used and always 0. It must return the number of
1148 * bytes written in |buf| if it succeeds. If it cannot read any
1149 * single byte without blocking, it must return
1150 * :enum:`NGHTTP2_ERR_WOULDBLOCK`. If it gets EOF before it reads any
1151 * single byte, it must return :enum:`NGHTTP2_ERR_EOF`. For other
1152 * errors, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1153 * Returning 0 is treated as :enum:`NGHTTP2_ERR_WOULDBLOCK`. The
1154 * |user_data| pointer is the third argument passed in to the call to
1155 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
1157 * This callback is required if the application uses
1158 * `nghttp2_session_recv()` to receive data from the remote endpoint.
1159 * If the application uses solely `nghttp2_session_mem_recv()`
1160 * instead, this callback function is unnecessary.
1162 * To set this callback to :type:`nghttp2_session_callbacks`, use
1163 * `nghttp2_session_callbacks_set_recv_callback()`.
1165 typedef ssize_t (*nghttp2_recv_callback)(nghttp2_session *session, uint8_t *buf,
1166 size_t length, int flags,
1172 * Callback function invoked by `nghttp2_session_recv()` when a frame
1173 * is received. The |user_data| pointer is the third argument passed
1174 * in to the call to `nghttp2_session_client_new()` or
1175 * `nghttp2_session_server_new()`.
1177 * If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
1178 * member of their data structure are always ``NULL`` and 0
1179 * respectively. The header name/value pairs are emitted via
1180 * :type:`nghttp2_on_header_callback`.
1182 * For HEADERS, PUSH_PROMISE and DATA frames, this callback may be
1183 * called after stream is closed (see
1184 * :type:`nghttp2_on_stream_close_callback`). The application should
1185 * check that stream is still alive using its own stream management or
1186 * :func:`nghttp2_session_get_stream_user_data()`.
1188 * Only HEADERS and DATA frame can signal the end of incoming data.
1189 * If ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
1190 * |frame| is the last frame from the remote peer in this stream.
1192 * This callback won't be called for CONTINUATION frames.
1193 * HEADERS/PUSH_PROMISE + CONTINUATIONs are treated as single frame.
1195 * The implementation of this function must return 0 if it succeeds.
1196 * If nonzero value is returned, it is treated as fatal error and
1197 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1198 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1200 * To set this callback to :type:`nghttp2_session_callbacks`, use
1201 * `nghttp2_session_callbacks_set_on_frame_recv_callback()`.
1203 typedef int (*nghttp2_on_frame_recv_callback)(nghttp2_session *session,
1204 const nghttp2_frame *frame,
1210 * Callback function invoked by `nghttp2_session_recv()` when an
1211 * invalid non-DATA frame is received. The |error_code| indicates the
1212 * error. It is usually one of the :enum:`nghttp2_error_code` but
1213 * that is not guaranteed. When this callback function is invoked,
1214 * the library automatically submits either RST_STREAM or GOAWAY
1215 * frame. The |user_data| pointer is the third argument passed in to
1216 * the call to `nghttp2_session_client_new()` or
1217 * `nghttp2_session_server_new()`.
1219 * If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
1220 * member of their data structure are always ``NULL`` and 0
1223 * The implementation of this function must return 0 if it succeeds.
1224 * If nonzero is returned, it is treated as fatal error and
1225 * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
1226 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1228 * To set this callback to :type:`nghttp2_session_callbacks`, use
1229 * `nghttp2_session_callbacks_set_on_invalid_frame_recv_callback()`.
1231 typedef int (*nghttp2_on_invalid_frame_recv_callback)(
1232 nghttp2_session *session, const nghttp2_frame *frame, uint32_t error_code,
1238 * Callback function invoked when a chunk of data in DATA frame is
1239 * received. The |stream_id| is the stream ID this DATA frame belongs
1240 * to. The |flags| is the flags of DATA frame which this data chunk
1241 * is contained. ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
1242 * necessarily mean this chunk of data is the last one in the stream.
1243 * You should use :type:`nghttp2_on_frame_recv_callback` to know all
1244 * data frames are received. The |user_data| pointer is the third
1245 * argument passed in to the call to `nghttp2_session_client_new()` or
1246 * `nghttp2_session_server_new()`.
1248 * If the application uses `nghttp2_session_mem_recv()`, it can return
1249 * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
1250 * return without processing further input bytes. The memory by
1251 * pointed by the |data| is retained until
1252 * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
1253 * The application must retain the input bytes which was used to
1254 * produce the |data| parameter, because it may refer to the memory
1255 * region included in the input bytes.
1257 * The implementation of this function must return 0 if it succeeds.
1258 * If nonzero is returned, it is treated as fatal error and
1259 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1260 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1262 * To set this callback to :type:`nghttp2_session_callbacks`, use
1263 * `nghttp2_session_callbacks_set_on_data_chunk_recv_callback()`.
1265 typedef int (*nghttp2_on_data_chunk_recv_callback)(nghttp2_session *session,
1268 const uint8_t *data,
1269 size_t len, void *user_data);
1274 * Callback function invoked just before the non-DATA frame |frame| is
1275 * sent. The |user_data| pointer is the third argument passed in to
1276 * the call to `nghttp2_session_client_new()` or
1277 * `nghttp2_session_server_new()`.
1279 * The implementation of this function must return 0 if it succeeds.
1280 * If nonzero is returned, it is treated as fatal error and
1281 * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
1282 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1284 * To set this callback to :type:`nghttp2_session_callbacks`, use
1285 * `nghttp2_session_callbacks_set_before_frame_send_callback()`.
1287 typedef int (*nghttp2_before_frame_send_callback)(nghttp2_session *session,
1288 const nghttp2_frame *frame,
1294 * Callback function invoked after the frame |frame| is sent. The
1295 * |user_data| pointer is the third argument passed in to the call to
1296 * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
1298 * The implementation of this function must return 0 if it succeeds.
1299 * If nonzero is returned, it is treated as fatal error and
1300 * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
1301 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1303 * To set this callback to :type:`nghttp2_session_callbacks`, use
1304 * `nghttp2_session_callbacks_set_on_frame_send_callback()`.
1306 typedef int (*nghttp2_on_frame_send_callback)(nghttp2_session *session,
1307 const nghttp2_frame *frame,
1313 * Callback function invoked after the non-DATA frame |frame| is not
1314 * sent because of the error. The error is indicated by the
1315 * |lib_error_code|, which is one of the values defined in
1316 * :type:`nghttp2_error`. The |user_data| pointer is the third
1317 * argument passed in to the call to `nghttp2_session_client_new()` or
1318 * `nghttp2_session_server_new()`.
1320 * The implementation of this function must return 0 if it succeeds.
1321 * If nonzero is returned, it is treated as fatal error and
1322 * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
1323 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1325 * To set this callback to :type:`nghttp2_session_callbacks`, use
1326 * `nghttp2_session_callbacks_set_on_frame_not_send_callback()`.
1328 typedef int (*nghttp2_on_frame_not_send_callback)(nghttp2_session *session,
1329 const nghttp2_frame *frame,
1336 * Callback function invoked when the stream |stream_id| is closed.
1337 * The reason of closure is indicated by the |error_code|. The
1338 * |error_code| is usually one of :enum:`nghttp2_error_code`, but that
1339 * is not guaranteed. The stream_user_data, which was specified in
1340 * `nghttp2_submit_request()` or `nghttp2_submit_headers()`, is still
1341 * available in this function. The |user_data| pointer is the third
1342 * argument passed in to the call to `nghttp2_session_client_new()` or
1343 * `nghttp2_session_server_new()`.
1345 * This function is also called for a stream in reserved state.
1347 * The implementation of this function must return 0 if it succeeds.
1348 * If nonzero is returned, it is treated as fatal error and
1349 * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
1350 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1352 * To set this callback to :type:`nghttp2_session_callbacks`, use
1353 * `nghttp2_session_callbacks_set_on_stream_close_callback()`.
1355 typedef int (*nghttp2_on_stream_close_callback)(nghttp2_session *session,
1357 uint32_t error_code,
1363 * Callback function invoked when the reception of header block in
1364 * HEADERS or PUSH_PROMISE is started. Each header name/value pair
1365 * will be emitted by :type:`nghttp2_on_header_callback`.
1367 * The ``frame->hd.flags`` may not have
1368 * :enum:`NGHTTP2_FLAG_END_HEADERS` flag set, which indicates that one
1369 * or more CONTINUATION frames are involved. But the application does
1370 * not need to care about that because the header name/value pairs are
1371 * emitted transparently regardless of CONTINUATION frames.
1373 * The implementation of this function must return 0 if it succeeds or
1374 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If nonzero value other than
1375 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned, it is treated as
1376 * if :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned. If
1377 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
1378 * `nghttp2_session_mem_recv()` function will immediately return
1379 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1381 * To set this callback to :type:`nghttp2_session_callbacks`, use
1382 * `nghttp2_session_callbacks_set_on_begin_headers_callback()`.
1384 typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session,
1385 const nghttp2_frame *frame,
1391 * Callback function invoked when a header name/value pair is received
1392 * for the |frame|. The |name| of length |namelen| is header name.
1393 * The |value| of length |valuelen| is header value. The |flags| is
1394 * bitwise OR of one or more of :type:`nghttp2_nv_flag`.
1396 * If :enum:`NGHTTP2_NV_FLAG_NO_INDEX` is set in |flags|, the receiver
1397 * must not index this name/value pair when forwarding it to the next
1400 * When this callback is invoked, ``frame->hd.type`` is either
1401 * :enum:`NGHTTP2_HEADERS` or :enum:`NGHTTP2_PUSH_PROMISE`. After all
1402 * header name/value pairs are processed with this callback, and no
1403 * error has been detected, :type:`nghttp2_on_frame_recv_callback`
1404 * will be invoked. If there is an error in decompression,
1405 * :type:`nghttp2_on_frame_recv_callback` for the |frame| will not be
1408 * The |name| may be ``NULL`` if the |namelen| is 0. The same thing
1409 * can be said about the |value|.
1411 * Please note that nghttp2 library does not perform any validity
1412 * check against the |name| and the |value|. For example, the
1413 * |namelen| could be 0, and/or the |value| contains ``0x0a`` or
1414 * ``0x0d``. The application must check them if it matters. The
1415 * helper function `nghttp2_check_header_name()` and
1416 * `nghttp2_check_header_value()` provide simple validation against
1417 * HTTP2 header field construction rule.
1419 * HTTP/2 specification requires that pseudo header fields (header
1420 * field starting with ':') must appear in front of regular header
1421 * fields. The library does not validate this requirement. The
1422 * application must check them if it matters.
1424 * If the application uses `nghttp2_session_mem_recv()`, it can return
1425 * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
1426 * return without processing further input bytes. The memory pointed
1427 * by |frame|, |name| and |value| parameters are retained until
1428 * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
1429 * The application must retain the input bytes which was used to
1430 * produce these parameters, because it may refer to the memory region
1431 * included in the input bytes.
1433 * Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close
1434 * the stream by issuing RST_STREAM with
1435 * :enum:`NGHTTP2_INTERNAL_ERROR`. In this case,
1436 * :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a
1437 * different error code is desirable, use
1438 * `nghttp2_submit_rst_stream()` with a desired error code and then
1439 * return :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
1441 * The implementation of this function must return 0 if it succeeds.
1442 * It may return :enum:`NGHTTP2_ERR_PAUSE` or
1443 * :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. For other critical
1444 * failures, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If
1445 * the other nonzero value is returned, it is treated as
1446 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If
1447 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
1448 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1449 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1451 * To set this callback to :type:`nghttp2_session_callbacks`, use
1452 * `nghttp2_session_callbacks_set_on_header_callback()`.
1454 typedef int (*nghttp2_on_header_callback)(nghttp2_session *session,
1455 const nghttp2_frame *frame,
1456 const uint8_t *name, size_t namelen,
1457 const uint8_t *value, size_t valuelen,
1458 uint8_t flags, void *user_data);
1463 * Callback function invoked when the library asks application how
1464 * many padding bytes are required for the transmission of the
1465 * |frame|. The application must choose the total length of payload
1466 * including padded bytes in range [frame->hd.length, max_payloadlen],
1467 * inclusive. Choosing number not in this range will be treated as
1468 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. Returning
1469 * ``frame->hd.length`` means no padding is added. Returning
1470 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will make
1471 * `nghttp2_session_send()` function immediately return
1472 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1474 * To set this callback to :type:`nghttp2_session_callbacks`, use
1475 * `nghttp2_session_callbacks_set_select_padding_callback()`.
1477 typedef ssize_t (*nghttp2_select_padding_callback)(nghttp2_session *session,
1478 const nghttp2_frame *frame,
1479 size_t max_payloadlen,
1485 * Callback function invoked when library wants to get max length of
1486 * data to send data to the remote peer. The implementation of this
1487 * function should return a value in the following range. [1,
1488 * min(|session_remote_window_size|, |stream_remote_window_size|,
1489 * |remote_max_frame_size|)]. If a value greater than this range is
1490 * returned than the max allow value will be used. Returning a value
1491 * smaller than this range is treated as
1492 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. The |frame_type| is provided
1493 * for future extensibility and identifies the type of frame (see
1494 * :type:`nghttp2_frame_type`) for which to get the length for.
1495 * Currently supported frame types are: :enum:`NGHTTP2_DATA`.
1497 * This callback can be used to control the length in bytes for which
1498 * :type:`nghttp2_data_source_read_callback` is allowed to send to the
1499 * remote endpoint. This callback is optional. Returning
1500 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session
1503 * To set this callback to :type:`nghttp2_session_callbacks`, use
1504 * `nghttp2_session_callbacks_set_data_source_read_length_callback()`.
1506 typedef ssize_t (*nghttp2_data_source_read_length_callback)(
1507 nghttp2_session *session, uint8_t frame_type, int32_t stream_id,
1508 int32_t session_remote_window_size, int32_t stream_remote_window_size,
1509 uint32_t remote_max_frame_size, void *user_data);
1514 * Callback function invoked when a frame header is received. The
1515 * |hd| points to received frame header.
1517 * Unlike :type:`nghttp2_on_frame_recv_callback`, this callback will
1518 * also be called when frame header of CONTINUATION frame is received.
1520 * If both :type:`nghttp2_on_begin_frame_callback` and
1521 * :type:`nghttp2_on_begin_headers_callback` are set and HEADERS or
1522 * PUSH_PROMISE is received, :type:`nghttp2_on_begin_frame_callback`
1523 * will be called first.
1525 * The implementation of this function must return 0 if it succeeds.
1526 * If nonzero value is returned, it is treated as fatal error and
1527 * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1528 * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
1530 * To set this callback to :type:`nghttp2_session_callbacks`, use
1531 * `nghttp2_session_callbacks_set_on_begin_frame_callback()`.
1533 typedef int (*nghttp2_on_begin_frame_callback)(nghttp2_session *session,
1534 const nghttp2_frame_hd *hd,
1537 struct nghttp2_session_callbacks;
1542 * Callback functions for :type:`nghttp2_session`. The details of
1543 * this structure are intentionally hidden from the public API.
1545 typedef struct nghttp2_session_callbacks nghttp2_session_callbacks;
1550 * Initializes |*callbacks_ptr| with NULL values.
1552 * The initialized object can be used when initializing multiple
1553 * :type:`nghttp2_session` objects.
1555 * When the application finished using this object, it can use
1556 * `nghttp2_session_callbacks_del()` to free its memory.
1558 * This function returns 0 if it succeeds, or one of the following
1559 * negative error codes:
1561 * :enum:`NGHTTP2_ERR_NOMEM`
1564 int nghttp2_session_callbacks_new(nghttp2_session_callbacks **callbacks_ptr);
1569 * Frees any resources allocated for |callbacks|. If |callbacks| is
1570 * ``NULL``, this function does nothing.
1572 void nghttp2_session_callbacks_del(nghttp2_session_callbacks *callbacks);
1577 * Sets callback function invoked when a session wants to send data to
1578 * the remote peer. This callback is not necessary if the application
1579 * uses solely `nghttp2_session_mem_send()` to serialize data to
1582 void nghttp2_session_callbacks_set_send_callback(
1583 nghttp2_session_callbacks *cbs, nghttp2_send_callback send_callback);
1588 * Sets callback function invoked when the a session wants to receive
1589 * data from the remote peer. This callback is not necessary if the
1590 * application uses solely `nghttp2_session_mem_recv()` to process
1593 void nghttp2_session_callbacks_set_recv_callback(
1594 nghttp2_session_callbacks *cbs, nghttp2_recv_callback recv_callback);
1599 * Sets callback function invoked by `nghttp2_session_recv()` when a
1600 * frame is received.
1602 void nghttp2_session_callbacks_set_on_frame_recv_callback(
1603 nghttp2_session_callbacks *cbs,
1604 nghttp2_on_frame_recv_callback on_frame_recv_callback);
1609 * Sets callback function invoked by `nghttp2_session_recv()` when an
1610 * invalid non-DATA frame is received.
1612 void nghttp2_session_callbacks_set_on_invalid_frame_recv_callback(
1613 nghttp2_session_callbacks *cbs,
1614 nghttp2_on_invalid_frame_recv_callback on_invalid_frame_recv_callback);
1619 * Sets callback function invoked when a chunk of data in DATA frame
1622 void nghttp2_session_callbacks_set_on_data_chunk_recv_callback(
1623 nghttp2_session_callbacks *cbs,
1624 nghttp2_on_data_chunk_recv_callback on_data_chunk_recv_callback);
1629 * Sets callback function invoked before a non-DATA frame is sent.
1631 void nghttp2_session_callbacks_set_before_frame_send_callback(
1632 nghttp2_session_callbacks *cbs,
1633 nghttp2_before_frame_send_callback before_frame_send_callback);
1638 * Sets callback function invoked after a frame is sent.
1640 void nghttp2_session_callbacks_set_on_frame_send_callback(
1641 nghttp2_session_callbacks *cbs,
1642 nghttp2_on_frame_send_callback on_frame_send_callback);
1647 * Sets callback function invoked when a non-DATA frame is not sent
1648 * because of an error.
1650 void nghttp2_session_callbacks_set_on_frame_not_send_callback(
1651 nghttp2_session_callbacks *cbs,
1652 nghttp2_on_frame_not_send_callback on_frame_not_send_callback);
1657 * Sets callback function invoked when the stream is closed.
1659 void nghttp2_session_callbacks_set_on_stream_close_callback(
1660 nghttp2_session_callbacks *cbs,
1661 nghttp2_on_stream_close_callback on_stream_close_callback);
1666 * Sets callback function invoked when the reception of header block
1667 * in HEADERS or PUSH_PROMISE is started.
1669 void nghttp2_session_callbacks_set_on_begin_headers_callback(
1670 nghttp2_session_callbacks *cbs,
1671 nghttp2_on_begin_headers_callback on_begin_headers_callback);
1676 * Sets callback function invoked when a header name/value pair is
1679 void nghttp2_session_callbacks_set_on_header_callback(
1680 nghttp2_session_callbacks *cbs,
1681 nghttp2_on_header_callback on_header_callback);
1686 * Sets callback function invoked when the library asks application
1687 * how many padding bytes are required for the transmission of the
1690 void nghttp2_session_callbacks_set_select_padding_callback(
1691 nghttp2_session_callbacks *cbs,
1692 nghttp2_select_padding_callback select_padding_callback);
1697 * Sets callback function determine the length allowed in
1698 * :type:`nghttp2_data_source_read_callback`.
1700 void nghttp2_session_callbacks_set_data_source_read_length_callback(
1701 nghttp2_session_callbacks *cbs,
1702 nghttp2_data_source_read_length_callback data_source_read_length_callback);
1707 * Sets callback function invoked when a frame header is received.
1709 void nghttp2_session_callbacks_set_on_begin_frame_callback(
1710 nghttp2_session_callbacks *cbs,
1711 nghttp2_on_begin_frame_callback on_begin_frame_callback);
1716 * Custom memory allocator to replace malloc(). The |mem_user_data|
1717 * is the mem_user_data member of :type:`nghttp2_mem` structure.
1719 typedef void *(*nghttp2_malloc)(size_t size, void *mem_user_data);
1724 * Custom memory allocator to replace free(). The |mem_user_data| is
1725 * the mem_user_data member of :type:`nghttp2_mem` structure.
1727 typedef void (*nghttp2_free)(void *ptr, void *mem_user_data);
1732 * Custom memory allocator to replace calloc(). The |mem_user_data|
1733 * is the mem_user_data member of :type:`nghttp2_mem` structure.
1735 typedef void *(*nghttp2_calloc)(size_t nmemb, size_t size, void *mem_user_data);
1740 * Custom memory allocator to replace realloc(). The |mem_user_data|
1741 * is the mem_user_data member of :type:`nghttp2_mem` structure.
1743 typedef void *(*nghttp2_realloc)(void *ptr, size_t size, void *mem_user_data);
1748 * Custom memory allocator functions and user defined pointer. The
1749 * |mem_user_data| member is passed to each allocator function. This
1750 * can be used, for example, to achieve per-session memory pool.
1752 * In the following example code, ``my_malloc``, ``my_free``,
1753 * ``my_calloc`` and ``my_realloc`` are the replacement of the
1754 * standard allocators ``malloc``, ``free``, ``calloc`` and
1755 * ``realloc`` respectively::
1757 * void *my_malloc_cb(size_t size, void *mem_user_data) {
1758 * return my_malloc(size);
1761 * void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); }
1763 * void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) {
1764 * return my_calloc(nmemb, size);
1767 * void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) {
1768 * return my_realloc(ptr, size);
1771 * void session_new() {
1772 * nghttp2_session *session;
1773 * nghttp2_session_callbacks *callbacks;
1774 * nghttp2_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb,
1779 * nghttp2_session_client_new3(&session, callbacks, NULL, NULL, &mem);
1786 * An arbitrary user supplied data. This is passed to each
1787 * allocator function.
1789 void *mem_user_data;
1791 * Custom allocator function to replace malloc().
1793 nghttp2_malloc malloc;
1795 * Custom allocator function to replace free().
1799 * Custom allocator function to replace calloc().
1801 nghttp2_calloc calloc;
1803 * Custom allocator function to replace realloc().
1805 nghttp2_realloc realloc;
1808 struct nghttp2_option;
1813 * Configuration options for :type:`nghttp2_session`. The details of
1814 * this structure are intentionally hidden from the public API.
1816 typedef struct nghttp2_option nghttp2_option;
1821 * Initializes |*option_ptr| with default values.
1823 * When the application finished using this object, it can use
1824 * `nghttp2_option_del()` to free its memory.
1826 * This function returns 0 if it succeeds, or one of the following
1827 * negative error codes:
1829 * :enum:`NGHTTP2_ERR_NOMEM`
1832 int nghttp2_option_new(nghttp2_option **option_ptr);
1837 * Frees any resources allocated for |option|. If |option| is
1838 * ``NULL``, this function does nothing.
1840 void nghttp2_option_del(nghttp2_option *option);
1845 * This option prevents the library from sending WINDOW_UPDATE for a
1846 * connection automatically. If this option is set to nonzero, the
1847 * library won't send WINDOW_UPDATE for DATA until application calls
1848 * `nghttp2_session_consume()` to indicate the consumed amount of
1849 * data. Don't use `nghttp2_submit_window_update()` for this purpose.
1850 * By default, this option is set to zero.
1852 void nghttp2_option_set_no_auto_window_update(nghttp2_option *option, int val);
1857 * This option sets the SETTINGS_MAX_CONCURRENT_STREAMS value of
1858 * remote endpoint as if it is received in SETTINGS frame. Without
1859 * specifying this option, before the local endpoint receives
1860 * SETTINGS_MAX_CONCURRENT_STREAMS in SETTINGS frame from remote
1861 * endpoint, SETTINGS_MAX_CONCURRENT_STREAMS is unlimited. This may
1862 * cause problem if local endpoint submits lots of requests initially
1863 * and sending them at once to the remote peer may lead to the
1864 * rejection of some requests. Specifying this option to the sensible
1865 * value, say 100, may avoid this kind of issue. This value will be
1866 * overwritten if the local endpoint receives
1867 * SETTINGS_MAX_CONCURRENT_STREAMS from the remote endpoint.
1869 void nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
1875 * By default, nghttp2 library only handles HTTP/2 frames and does not
1876 * recognize first 24 bytes of client connection preface. This design
1877 * choice is done due to the fact that server may want to detect the
1878 * application protocol based on first few bytes on clear text
1879 * communication. But for simple servers which only speak HTTP/2, it
1880 * is easier for developers if nghttp2 library takes care of client
1881 * connection preface.
1883 * If this option is used with nonzero |val|, nghttp2 library checks
1884 * first 24 bytes client connection preface. If it is not a valid
1885 * one, `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` will
1886 * return error :enum:`NGHTTP2_ERR_BAD_PREFACE`, which is fatal error.
1888 void nghttp2_option_set_recv_client_preface(nghttp2_option *option, int val);
1893 * Initializes |*session_ptr| for client use. The all members of
1894 * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
1895 * does not store |callbacks|. The |user_data| is an arbitrary user
1896 * supplied data, which will be passed to the callback functions.
1898 * The :type:`nghttp2_send_callback` must be specified. If the
1899 * application code uses `nghttp2_session_recv()`, the
1900 * :type:`nghttp2_recv_callback` must be specified. The other members
1901 * of |callbacks| can be ``NULL``.
1903 * If this function fails, |*session_ptr| is left untouched.
1905 * This function returns 0 if it succeeds, or one of the following
1906 * negative error codes:
1908 * :enum:`NGHTTP2_ERR_NOMEM`
1911 int nghttp2_session_client_new(nghttp2_session **session_ptr,
1912 const nghttp2_session_callbacks *callbacks,
1918 * Initializes |*session_ptr| for server use. The all members of
1919 * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
1920 * does not store |callbacks|. The |user_data| is an arbitrary user
1921 * supplied data, which will be passed to the callback functions.
1923 * The :type:`nghttp2_send_callback` must be specified. If the
1924 * application code uses `nghttp2_session_recv()`, the
1925 * :type:`nghttp2_recv_callback` must be specified. The other members
1926 * of |callbacks| can be ``NULL``.
1928 * If this function fails, |*session_ptr| is left untouched.
1930 * This function returns 0 if it succeeds, or one of the following
1931 * negative error codes:
1933 * :enum:`NGHTTP2_ERR_NOMEM`
1936 int nghttp2_session_server_new(nghttp2_session **session_ptr,
1937 const nghttp2_session_callbacks *callbacks,
1943 * Like `nghttp2_session_client_new()`, but with additional options
1944 * specified in the |option|.
1946 * The |option| can be ``NULL`` and the call is equivalent to
1947 * `nghttp2_session_client_new()`.
1949 * This function does not take ownership |option|. The application is
1950 * responsible for freeing |option| if it finishes using the object.
1952 * The library code does not refer to |option| after this function
1955 * This function returns 0 if it succeeds, or one of the following
1956 * negative error codes:
1958 * :enum:`NGHTTP2_ERR_NOMEM`
1961 int nghttp2_session_client_new2(nghttp2_session **session_ptr,
1962 const nghttp2_session_callbacks *callbacks,
1963 void *user_data, const nghttp2_option *option);
1968 * Like `nghttp2_session_server_new()`, but with additional options
1969 * specified in the |option|.
1971 * The |option| can be ``NULL`` and the call is equivalent to
1972 * `nghttp2_session_server_new()`.
1974 * This function does not take ownership |option|. The application is
1975 * responsible for freeing |option| if it finishes using the object.
1977 * The library code does not refer to |option| after this function
1980 * This function returns 0 if it succeeds, or one of the following
1981 * negative error codes:
1983 * :enum:`NGHTTP2_ERR_NOMEM`
1986 int nghttp2_session_server_new2(nghttp2_session **session_ptr,
1987 const nghttp2_session_callbacks *callbacks,
1988 void *user_data, const nghttp2_option *option);
1993 * Like `nghttp2_session_client_new2()`, but with additional custom
1994 * memory allocator specified in the |mem|.
1996 * The |mem| can be ``NULL`` and the call is equivalent to
1997 * `nghttp2_session_client_new2()`.
1999 * This function does not take ownership |mem|. The application is
2000 * responsible for freeing |mem|.
2002 * The library code does not refer to |mem| pointer after this
2003 * function returns, so the application can safely free it.
2005 * This function returns 0 if it succeeds, or one of the following
2006 * negative error codes:
2008 * :enum:`NGHTTP2_ERR_NOMEM`
2011 int nghttp2_session_client_new3(nghttp2_session **session_ptr,
2012 const nghttp2_session_callbacks *callbacks,
2013 void *user_data, const nghttp2_option *option,
2019 * Like `nghttp2_session_server_new2()`, but with additional custom
2020 * memory allocator specified in the |mem|.
2022 * The |mem| can be ``NULL`` and the call is equivalent to
2023 * `nghttp2_session_server_new2()`.
2025 * This function does not take ownership |mem|. The application is
2026 * responsible for freeing |mem|.
2028 * The library code does not refer to |mem| pointer after this
2029 * function returns, so the application can safely free it.
2031 * This function returns 0 if it succeeds, or one of the following
2032 * negative error codes:
2034 * :enum:`NGHTTP2_ERR_NOMEM`
2037 int nghttp2_session_server_new3(nghttp2_session **session_ptr,
2038 const nghttp2_session_callbacks *callbacks,
2039 void *user_data, const nghttp2_option *option,
2045 * Frees any resources allocated for |session|. If |session| is
2046 * ``NULL``, this function does nothing.
2048 void nghttp2_session_del(nghttp2_session *session);
2053 * Sends pending frames to the remote peer.
2055 * This function retrieves the highest prioritized frame from the
2056 * outbound queue and sends it to the remote peer. It does this as
2057 * many as possible until the user callback
2058 * :type:`nghttp2_send_callback` returns
2059 * :enum:`NGHTTP2_ERR_WOULDBLOCK` or the outbound queue becomes empty.
2060 * This function calls several callback functions which are passed
2061 * when initializing the |session|. Here is the simple time chart
2062 * which tells when each callback is invoked:
2064 * 1. Get the next frame to send from outbound queue.
2066 * 2. Prepare transmission of the frame.
2068 * 3. If the control frame cannot be sent because some preconditions
2069 * are not met (e.g., request HEADERS cannot be sent after GOAWAY),
2070 * :type:`nghttp2_on_frame_not_send_callback` is invoked. Abort
2071 * the following steps.
2073 * 4. If the frame is HEADERS, PUSH_PROMISE or DATA,
2074 * :type:`nghttp2_select_padding_callback` is invoked.
2076 * 5. If the frame is request HEADERS, the stream is opened here.
2078 * 6. :type:`nghttp2_before_frame_send_callback` is invoked.
2080 * 7. :type:`nghttp2_send_callback` is invoked one or more times to
2083 * 8. :type:`nghttp2_on_frame_send_callback` is invoked.
2085 * 9. If the transmission of the frame triggers closure of the stream,
2086 * the stream is closed and
2087 * :type:`nghttp2_on_stream_close_callback` is invoked.
2089 * This function returns 0 if it succeeds, or one of the following
2090 * negative error codes:
2092 * :enum:`NGHTTP2_ERR_NOMEM`
2094 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
2095 * The callback function failed.
2097 int nghttp2_session_send(nghttp2_session *session);
2102 * Returns the serialized data to send.
2104 * This function behaves like `nghttp2_session_send()` except that it
2105 * does not use :type:`nghttp2_send_callback` to transmit data.
2106 * Instead, it assigns the pointer to the serialized data to the
2107 * |*data_ptr| and returns its length. The other callbacks are called
2108 * in the same way as they are in `nghttp2_session_send()`.
2110 * If no data is available to send, this function returns 0.
2112 * This function may not return all serialized data in one invocation.
2113 * To get all data, call this function repeatedly until it returns 0
2114 * or one of negative error codes.
2116 * The assigned |*data_ptr| is valid until the next call of
2117 * `nghttp2_session_mem_send()` or `nghttp2_session_send()`.
2119 * The caller must send all data before sending the next chunk of
2122 * This function returns the length of the data pointed by the
2123 * |*data_ptr| if it succeeds, or one of the following negative error
2126 * :enum:`NGHTTP2_ERR_NOMEM`
2129 ssize_t nghttp2_session_mem_send(nghttp2_session *session,
2130 const uint8_t **data_ptr);
2135 * Receives frames from the remote peer.
2137 * This function receives as many frames as possible until the user
2138 * callback :type:`nghttp2_recv_callback` returns
2139 * :enum:`NGHTTP2_ERR_WOULDBLOCK`. This function calls several
2140 * callback functions which are passed when initializing the
2141 * |session|. Here is the simple time chart which tells when each
2142 * callback is invoked:
2144 * 1. :type:`nghttp2_recv_callback` is invoked one or more times to
2145 * receive frame header.
2147 * 2. When frame header is received,
2148 * :type:`nghttp2_on_begin_frame_callback` is invoked.
2150 * 3. If the frame is DATA frame:
2152 * 1. :type:`nghttp2_recv_callback` is invoked to receive DATA
2153 * payload. For each chunk of data,
2154 * :type:`nghttp2_on_data_chunk_recv_callback` is invoked.
2156 * 2. If one DATA frame is completely received,
2157 * :type:`nghttp2_on_frame_recv_callback` is invoked. If the
2158 * reception of the frame triggers the closure of the stream,
2159 * :type:`nghttp2_on_stream_close_callback` is invoked.
2161 * 4. If the frame is the control frame:
2163 * 1. :type:`nghttp2_recv_callback` is invoked one or more times to
2164 * receive whole frame.
2166 * 2. If the received frame is valid, then following actions are
2167 * taken. If the frame is either HEADERS or PUSH_PROMISE,
2168 * :type:`nghttp2_on_begin_headers_callback` is invoked. Then
2169 * :type:`nghttp2_on_header_callback` is invoked for each header
2170 * name/value pair. After all name/value pairs are emitted
2171 * successfully, :type:`nghttp2_on_frame_recv_callback` is
2172 * invoked. For other frames,
2173 * :type:`nghttp2_on_frame_recv_callback` is invoked. If the
2174 * reception of the frame triggers the closure of the stream,
2175 * :type:`nghttp2_on_stream_close_callback` is invoked.
2177 * 3. If the received frame is unpacked but is interpreted as
2178 * invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is
2181 * This function returns 0 if it succeeds, or one of the following
2182 * negative error codes:
2184 * :enum:`NGHTTP2_ERR_EOF`
2185 * The remote peer did shutdown on the connection.
2186 * :enum:`NGHTTP2_ERR_NOMEM`
2188 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
2189 * The callback function failed.
2190 * :enum:`NGHTTP2_ERR_BAD_PREFACE`
2191 * Invalid client preface was detected. This error only returns
2192 * when |session| was configured as server and
2193 * `nghttp2_option_set_recv_client_preface()` is used.
2195 int nghttp2_session_recv(nghttp2_session *session);
2200 * Processes data |in| as an input from the remote endpoint. The
2201 * |inlen| indicates the number of bytes in the |in|.
2203 * This function behaves like `nghttp2_session_recv()` except that it
2204 * does not use :type:`nghttp2_recv_callback` to receive data; the
2205 * |in| is the only data for the invocation of this function. If all
2206 * bytes are processed, this function returns. The other callbacks
2207 * are called in the same way as they are in `nghttp2_session_recv()`.
2209 * In the current implementation, this function always tries to
2210 * processes all input data unless either an error occurs or
2211 * :enum:`NGHTTP2_ERR_PAUSE` is returned from
2212 * :type:`nghttp2_on_header_callback` or
2213 * :type:`nghttp2_on_data_chunk_recv_callback`. If
2214 * :enum:`NGHTTP2_ERR_PAUSE` is used, the return value includes the
2215 * number of bytes which was used to produce the data or frame for the
2218 * This function returns the number of processed bytes, or one of the
2219 * following negative error codes:
2221 * :enum:`NGHTTP2_ERR_NOMEM`
2223 * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
2224 * The callback function failed.
2225 * :enum:`NGHTTP2_ERR_BAD_PREFACE`
2226 * Invalid client preface was detected. This error only returns
2227 * when |session| was configured as server and
2228 * `nghttp2_option_set_recv_client_preface()` is used.
2230 ssize_t nghttp2_session_mem_recv(nghttp2_session *session, const uint8_t *in,
2236 * Puts back previously deferred DATA frame in the stream |stream_id|
2237 * to the outbound queue.
2239 * This function returns 0 if it succeeds, or one of the following
2240 * negative error codes:
2242 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2243 * The stream does not exist; or no deferred data exist.
2244 * :enum:`NGHTTP2_ERR_NOMEM`
2247 int nghttp2_session_resume_data(nghttp2_session *session, int32_t stream_id);
2252 * Returns nonzero value if |session| wants to receive data from the
2255 * If both `nghttp2_session_want_read()` and
2256 * `nghttp2_session_want_write()` return 0, the application should
2257 * drop the connection.
2259 int nghttp2_session_want_read(nghttp2_session *session);
2264 * Returns nonzero value if |session| wants to send data to the remote
2267 * If both `nghttp2_session_want_read()` and
2268 * `nghttp2_session_want_write()` return 0, the application should
2269 * drop the connection.
2271 int nghttp2_session_want_write(nghttp2_session *session);
2276 * Returns stream_user_data for the stream |stream_id|. The
2277 * stream_user_data is provided by `nghttp2_submit_request()`,
2278 * `nghttp2_submit_headers()` or
2279 * `nghttp2_session_set_stream_user_data()`. Unless it is set using
2280 * `nghttp2_session_set_stream_user_data()`, if the stream is
2281 * initiated by the remote endpoint, stream_user_data is always
2282 * ``NULL``. If the stream does not exist, this function returns
2285 void *nghttp2_session_get_stream_user_data(nghttp2_session *session,
2291 * Sets the |stream_user_data| to the stream denoted by the
2292 * |stream_id|. If a stream user data is already set to the stream,
2293 * it is replaced with the |stream_user_data|. It is valid to specify
2294 * ``NULL`` in the |stream_user_data|, which nullifies the associated
2297 * It is valid to set the |stream_user_data| to the stream reserved by
2298 * PUSH_PROMISE frame.
2300 * This function returns 0 if it succeeds, or one of following
2301 * negative error codes:
2303 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2304 * The stream does not exist
2306 int nghttp2_session_set_stream_user_data(nghttp2_session *session,
2308 void *stream_user_data);
2313 * Returns the number of frames in the outbound queue. This does not
2314 * include the deferred DATA frames.
2316 size_t nghttp2_session_get_outbound_queue_size(nghttp2_session *session);
2321 * Returns the number of DATA payload in bytes received without
2322 * WINDOW_UPDATE transmission for the stream |stream_id|. The local
2323 * (receive) window size can be adjusted by
2324 * `nghttp2_submit_window_update()`. This function takes into account
2325 * that and returns effective data length. In particular, if the
2326 * local window size is reduced by submitting negative
2327 * window_size_increment with `nghttp2_submit_window_update()`, this
2328 * function returns the number of bytes less than actually received.
2330 * This function returns -1 if it fails.
2333 nghttp2_session_get_stream_effective_recv_data_length(nghttp2_session *session,
2339 * Returns the local (receive) window size for the stream |stream_id|.
2340 * The local window size can be adjusted by
2341 * `nghttp2_submit_window_update()`. This function takes into account
2342 * that and returns effective window size.
2344 * This function returns -1 if it fails.
2347 nghttp2_session_get_stream_effective_local_window_size(nghttp2_session *session,
2353 * Returns the number of DATA payload in bytes received without
2354 * WINDOW_UPDATE transmission for a connection. The local (receive)
2355 * window size can be adjusted by `nghttp2_submit_window_update()`.
2356 * This function takes into account that and returns effective data
2357 * length. In particular, if the local window size is reduced by
2358 * submitting negative window_size_increment with
2359 * `nghttp2_submit_window_update()`, this function returns the number
2360 * of bytes less than actually received.
2362 * This function returns -1 if it fails.
2365 nghttp2_session_get_effective_recv_data_length(nghttp2_session *session);
2370 * Returns the local (receive) window size for a connection. The
2371 * local window size can be adjusted by
2372 * `nghttp2_submit_window_update()`. This function takes into account
2373 * that and returns effective window size.
2375 * This function returns -1 if it fails.
2378 nghttp2_session_get_effective_local_window_size(nghttp2_session *session);
2383 * Returns the remote window size for a given stream |stream_id|.
2385 * This is the amount of flow-controlled payload (e.g., DATA) that the
2386 * local endpoint can send without stream level WINDOW_UPDATE. There
2387 * is also connection level flow control, so the effective size of
2388 * payload that the local endpoint can actually send is
2389 * min(`nghttp2_session_get_stream_remote_window_size()`,
2390 * `nghttp2_session_get_remote_window_size()`).
2392 * This function returns -1 if it fails.
2394 int32_t nghttp2_session_get_stream_remote_window_size(nghttp2_session *session,
2400 * Returns the remote window size for a connection.
2402 * This function always succeeds.
2404 int32_t nghttp2_session_get_remote_window_size(nghttp2_session *session);
2409 * Returns 1 if local peer half closed the given stream |stream_id|.
2410 * Returns 0 if it did not. Returns -1 if no such stream exists.
2412 int nghttp2_session_get_stream_local_close(nghttp2_session *session,
2418 * Returns 1 if remote peer half closed the given stream |stream_id|.
2419 * Returns 0 if it did not. Returns -1 if no such stream exists.
2421 int nghttp2_session_get_stream_remote_close(nghttp2_session *session,
2427 * Signals the session so that the connection should be terminated.
2429 * The last stream ID is the minimum value between the stream ID of a
2430 * stream for which :type:`nghttp2_on_frame_recv_callback` was called
2431 * most recently and the last stream ID we have sent to the peer
2434 * The |error_code| is the error code of this GOAWAY frame. The
2435 * pre-defined error code is one of :enum:`nghttp2_error_code`.
2437 * After the transmission, both `nghttp2_session_want_read()` and
2438 * `nghttp2_session_want_write()` return 0.
2440 * This function should be called when the connection should be
2441 * terminated after sending GOAWAY. If the remaining streams should
2442 * be processed after GOAWAY, use `nghttp2_submit_goaway()` instead.
2444 * This function returns 0 if it succeeds, or one of the following
2445 * negative error codes:
2447 * :enum:`NGHTTP2_ERR_NOMEM`
2450 int nghttp2_session_terminate_session(nghttp2_session *session,
2451 uint32_t error_code);
2456 * Signals the session so that the connection should be terminated.
2458 * This function behaves like `nghttp2_session_terminate_session()`,
2459 * but the last stream ID can be specified by the application for fine
2460 * grained control of stream. The HTTP/2 specification does not allow
2461 * last_stream_id to be increased. So the actual value sent as
2462 * last_stream_id is the minimum value between the given
2463 * |last_stream_id| and the last_stream_id we have previously sent to
2466 * The |last_stream_id| is peer's stream ID or 0. So if |session| is
2467 * initialized as client, |last_stream_id| must be even or 0. If
2468 * |session| is initialized as server, |last_stream_id| must be odd or
2471 * This function returns 0 if it succeeds, or one of the following
2472 * negative error codes:
2474 * :enum:`NGHTTP2_ERR_NOMEM`
2476 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2477 * The |last_stream_id| is invalid.
2479 int nghttp2_session_terminate_session2(nghttp2_session *session,
2480 int32_t last_stream_id,
2481 uint32_t error_code);
2486 * Signals to the client that the server started graceful shutdown
2489 * This function is only usable for server. If this function is
2490 * called with client side session, this function returns
2491 * :enum:`NGHTTP2_ERR_INVALID_STATE`.
2493 * To gracefully shutdown HTTP/2 session, server should call this
2494 * function to send GOAWAY with last_stream_id (1u << 31) - 1. And
2495 * after some delay (e.g., 1 RTT), send another GOAWAY with the stream
2496 * ID that the server has some processing using
2497 * `nghttp2_submit_goaway()`. See also
2498 * `nghttp2_session_get_last_proc_stream_id()`.
2500 * Unlike `nghttp2_submit_goaway()`, this function just sends GOAWAY
2501 * and does nothing more. This is a mere indication to the client
2502 * that session shutdown is imminent. The application should call
2503 * `nghttp2_submit_goaway()` with appropriate last_stream_id after
2506 * If one or more GOAWAY frame have been already sent by either
2507 * `nghttp2_submit_goaway()` or `nghttp2_session_terminate_session()`,
2508 * this function has no effect.
2510 * This function returns 0 if it succeeds, or one of the following
2511 * negative error codes:
2513 * :enum:`NGHTTP2_ERR_NOMEM`
2515 * :enum:`NGHTTP2_ERR_INVALID_STATE`
2516 * The |session| is initialized as client.
2518 int nghttp2_submit_shutdown_notice(nghttp2_session *session);
2523 * Returns the value of SETTINGS |id| notified by a remote endpoint.
2524 * The |id| must be one of values defined in
2525 * :enum:`nghttp2_settings_id`.
2527 uint32_t nghttp2_session_get_remote_settings(nghttp2_session *session,
2528 nghttp2_settings_id id);
2533 * Tells the |session| that next stream ID is |next_stream_id|. The
2534 * |next_stream_id| must be equal or greater than the value returned
2535 * by `nghttp2_session_get_next_stream_id()`.
2537 * This function returns 0 if it succeeds, or one of the following
2538 * negative error codes:
2540 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2541 * The |next_stream_id| is strictly less than the value
2542 * `nghttp2_session_get_next_stream_id()` returns.
2544 int nghttp2_session_set_next_stream_id(nghttp2_session *session,
2545 int32_t next_stream_id);
2550 * Returns the next outgoing stream ID. Notice that return type is
2551 * uint32_t. If we run out of stream ID for this session, this
2552 * function returns 1 << 31.
2554 uint32_t nghttp2_session_get_next_stream_id(nghttp2_session *session);
2559 * Tells the |session| that |size| bytes for a stream denoted by
2560 * |stream_id| were consumed by application and are ready to
2561 * WINDOW_UPDATE. This function is intended to be used without
2562 * automatic window update (see
2563 * `nghttp2_option_set_no_auto_window_update()`).
2565 * This function returns 0 if it succeeds, or one of the following
2566 * negative error codes:
2568 * :enum:`NGHTTP2_ERR_NOMEM`
2570 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2571 * The |stream_id| is 0.
2572 * :enum:`NGHTTP2_ERR_INVALID_STATE`
2573 * Automatic WINDOW_UPDATE is not disabled.
2575 int nghttp2_session_consume(nghttp2_session *session, int32_t stream_id,
2581 * Performs post-process of HTTP Upgrade request. This function can
2582 * be called from both client and server, but the behavior is very
2583 * different in each other.
2585 * If called from client side, the |settings_payload| must be the
2586 * value sent in ``HTTP2-Settings`` header field and must be decoded
2587 * by base64url decoder. The |settings_payloadlen| is the length of
2588 * |settings_payload|. The |settings_payload| is unpacked and its
2589 * setting values will be submitted using `nghttp2_submit_settings()`.
2590 * This means that the client application code does not need to submit
2591 * SETTINGS by itself. The stream with stream ID=1 is opened and the
2592 * |stream_user_data| is used for its stream_user_data. The opened
2593 * stream becomes half-closed (local) state.
2595 * If called from server side, the |settings_payload| must be the
2596 * value received in ``HTTP2-Settings`` header field and must be
2597 * decoded by base64url decoder. The |settings_payloadlen| is the
2598 * length of |settings_payload|. It is treated as if the SETTINGS
2599 * frame with that payload is received. Thus, callback functions for
2600 * the reception of SETTINGS frame will be invoked. The stream with
2601 * stream ID=1 is opened. The |stream_user_data| is ignored. The
2602 * opened stream becomes half-closed (remote).
2604 * This function returns 0 if it succeeds, or one of the following
2605 * negative error codes:
2607 * :enum:`NGHTTP2_ERR_NOMEM`
2609 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2610 * The |settings_payload| is badly formed.
2611 * :enum:`NGHTTP2_ERR_PROTO`
2612 * The stream ID 1 is already used or closed; or is not available.
2614 int nghttp2_session_upgrade(nghttp2_session *session,
2615 const uint8_t *settings_payload,
2616 size_t settings_payloadlen, void *stream_user_data);
2621 * Serializes the SETTINGS values |iv| in the |buf|. The size of the
2622 * |buf| is specified by |buflen|. The number of entries in the |iv|
2623 * array is given by |niv|. The required space in |buf| for the |niv|
2624 * entries is ``8*niv`` bytes and if the given buffer is too small, an
2625 * error is returned. This function is used mainly for creating a
2626 * SETTINGS payload to be sent with the ``HTTP2-Settings`` header
2627 * field in an HTTP Upgrade request. The data written in |buf| is NOT
2628 * base64url encoded and the application is responsible for encoding.
2630 * This function returns the number of bytes written in |buf|, or one
2631 * of the following negative error codes:
2633 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2634 * The |iv| contains duplicate settings ID or invalid value.
2636 * :enum:`NGHTTP2_ERR_INSUFF_BUFSIZE`
2637 * The provided |buflen| size is too small to hold the output.
2639 ssize_t nghttp2_pack_settings_payload(uint8_t *buf, size_t buflen,
2640 const nghttp2_settings_entry *iv,
2646 * Returns string describing the |lib_error_code|. The
2647 * |lib_error_code| must be one of the :enum:`nghttp2_error`.
2649 const char *nghttp2_strerror(int lib_error_code);
2654 * Initializes |pri_spec| with the |stream_id| of the stream to depend
2655 * on with |weight| and its exclusive flag. If |exclusive| is
2656 * nonzero, exclusive flag is set.
2658 * The |weight| must be in [:enum:`NGHTTP2_MIN_WEIGHT`,
2659 * :enum:`NGHTTP2_MAX_WEIGHT`], inclusive.
2661 void nghttp2_priority_spec_init(nghttp2_priority_spec *pri_spec,
2662 int32_t stream_id, int32_t weight,
2668 * Initializes |pri_spec| with the default values. The default values
2669 * are: stream_id = 0, weight = :macro:`NGHTTP2_DEFAULT_WEIGHT` and
2672 void nghttp2_priority_spec_default_init(nghttp2_priority_spec *pri_spec);
2677 * Returns nonzero if the |pri_spec| is filled with default values.
2679 int nghttp2_priority_spec_check_default(const nghttp2_priority_spec *pri_spec);
2684 * Submits HEADERS frame and optionally one or more DATA frames.
2686 * The |pri_spec| is priority specification of this request. ``NULL``
2687 * means the default priority (see
2688 * `nghttp2_priority_spec_default_init()`). To specify the priority,
2689 * use `nghttp2_priority_spec_init()`. If |pri_spec| is not ``NULL``,
2690 * this function will copy its data members.
2692 * The `pri_spec->weight` must be in [:enum:`NGHTTP2_MIN_WEIGHT`,
2693 * :enum:`NGHTTP2_MAX_WEIGHT`], inclusive. If `pri_spec->weight` is
2694 * strictly less than :enum:`NGHTTP2_MIN_WEIGHT`, it becomes
2695 * :enum:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than
2696 * :enum:`NGHTTP2_MAX_WEIGHT`, it becomes :enum:`NGHTTP2_MAX_WEIGHT`.
2698 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with
2699 * |nvlen| elements. The application is responsible to include
2700 * required pseudo-header fields (header field whose name starts with
2701 * ":") in |nva| and must place pseudo-headers before regular header
2704 * This function creates copies of all name/value pairs in |nva|. It
2705 * also lower-cases all names in |nva|. The order of elements in
2706 * |nva| is preserved.
2708 * HTTP/2 specification has requirement about header fields in the
2709 * request HEADERS. See the specification for more details.
2711 * If |data_prd| is not ``NULL``, it provides data which will be sent
2712 * in subsequent DATA frames. In this case, a method that allows
2713 * request message bodies
2714 * (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9) must
2715 * be specified with ``:method`` key in |nva| (e.g. ``POST``). This
2716 * function does not take ownership of the |data_prd|. The function
2717 * copies the members of the |data_prd|. If |data_prd| is ``NULL``,
2718 * HEADERS have END_STREAM set. The |stream_user_data| is data
2719 * associated to the stream opened by this request and can be an
2720 * arbitrary pointer, which can be retrieved later by
2721 * `nghttp2_session_get_stream_user_data()`.
2723 * This function returns assigned stream ID if it succeeds, or one of
2724 * the following negative error codes:
2726 * :enum:`NGHTTP2_ERR_NOMEM`
2728 * :enum:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
2729 * No stream ID is available because maximum stream ID was
2734 * This function returns assigned stream ID if it succeeds. But
2735 * that stream is not opened yet. The application must not submit
2736 * frame to that stream ID before
2737 * :type:`nghttp2_before_frame_send_callback` is called for this
2741 int32_t nghttp2_submit_request(nghttp2_session *session,
2742 const nghttp2_priority_spec *pri_spec,
2743 const nghttp2_nv *nva, size_t nvlen,
2744 const nghttp2_data_provider *data_prd,
2745 void *stream_user_data);
2750 * Submits response HEADERS frame and optionally one or more DATA
2751 * frames against the stream |stream_id|.
2753 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with
2754 * |nvlen| elements. The application is responsible to include
2755 * required pseudo-header fields (header field whose name starts with
2756 * ":") in |nva| and must place pseudo-headers before regular header
2759 * This function creates copies of all name/value pairs in |nva|. It
2760 * also lower-cases all names in |nva|. The order of elements in
2761 * |nva| is preserved.
2763 * HTTP/2 specification has requirement about header fields in the
2764 * response HEADERS. See the specification for more details.
2766 * If |data_prd| is not ``NULL``, it provides data which will be sent
2767 * in subsequent DATA frames. This function does not take ownership
2768 * of the |data_prd|. The function copies the members of the
2769 * |data_prd|. If |data_prd| is ``NULL``, HEADERS will have
2770 * END_STREAM flag set.
2772 * This method can be used as normal HTTP response and push response.
2773 * When pushing a resource using this function, the |session| must be
2774 * configured using `nghttp2_session_server_new()` or its variants and
2775 * the target stream denoted by the |stream_id| must be reserved using
2776 * `nghttp2_submit_push_promise()`.
2778 * To send non-final response headers (e.g., HTTP status 101), don't
2779 * use this function because this function half-closes the outbound
2780 * stream. Instead, use `nghttp2_submit_headers()` for this purpose.
2782 * This function returns 0 if it succeeds, or one of the following
2783 * negative error codes:
2785 * :enum:`NGHTTP2_ERR_NOMEM`
2787 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2788 * The |stream_id| is 0.
2792 * Calling this function twice for the same stream ID may lead to
2793 * program crash. It is generally considered to a programming error
2794 * to commit response twice.
2796 int nghttp2_submit_response(nghttp2_session *session, int32_t stream_id,
2797 const nghttp2_nv *nva, size_t nvlen,
2798 const nghttp2_data_provider *data_prd);
2803 * Submits HEADERS frame. The |flags| is bitwise OR of the
2806 * * :enum:`NGHTTP2_FLAG_END_STREAM`
2808 * If |flags| includes :enum:`NGHTTP2_FLAG_END_STREAM`, this frame has
2809 * END_STREAM flag set.
2811 * The library handles the CONTINUATION frame internally and it
2812 * correctly sets END_HEADERS to the last sequence of the PUSH_PROMISE
2813 * or CONTINUATION frame.
2815 * If the |stream_id| is -1, this frame is assumed as request (i.e.,
2816 * request HEADERS frame which opens new stream). In this case, the
2817 * assigned stream ID will be returned. Otherwise, specify stream ID
2820 * The |pri_spec| is priority specification of this request. ``NULL``
2821 * means the default priority (see
2822 * `nghttp2_priority_spec_default_init()`). To specify the priority,
2823 * use `nghttp2_priority_spec_init()`. If |pri_spec| is not ``NULL``,
2824 * this function will copy its data members.
2826 * The `pri_spec->weight` must be in [:enum:`NGHTTP2_MIN_WEIGHT`,
2827 * :enum:`NGHTTP2_MAX_WEIGHT`], inclusive. If `pri_spec->weight` is
2828 * strictly less than :enum:`NGHTTP2_MIN_WEIGHT`, it becomes
2829 * :enum:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than
2830 * :enum:`NGHTTP2_MAX_WEIGHT`, it becomes :enum:`NGHTTP2_MAX_WEIGHT`.
2832 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with
2833 * |nvlen| elements. The application is responsible to include
2834 * required pseudo-header fields (header field whose name starts with
2835 * ":") in |nva| and must place pseudo-headers before regular header
2838 * This function creates copies of all name/value pairs in |nva|. It
2839 * also lower-cases all names in |nva|. The order of elements in
2840 * |nva| is preserved.
2842 * The |stream_user_data| is a pointer to an arbitrary data which is
2843 * associated to the stream this frame will open. Therefore it is
2844 * only used if this frame opens streams, in other words, it changes
2845 * stream state from idle or reserved to open.
2847 * This function is low-level in a sense that the application code can
2848 * specify flags directly. For usual HTTP request,
2849 * `nghttp2_submit_request()` is useful.
2851 * This function returns newly assigned stream ID if it succeeds and
2852 * |stream_id| is -1. Otherwise, this function returns 0 if it
2853 * succeeds, or one of the following negative error codes:
2855 * :enum:`NGHTTP2_ERR_NOMEM`
2857 * :enum:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
2858 * No stream ID is available because maximum stream ID was
2860 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2861 * The |stream_id| is 0.
2865 * This function returns assigned stream ID if it succeeds and
2866 * |stream_id| is -1. But that stream is not opened yet. The
2867 * application must not submit frame to that stream ID before
2868 * :type:`nghttp2_before_frame_send_callback` is called for this
2872 int32_t nghttp2_submit_headers(nghttp2_session *session, uint8_t flags,
2874 const nghttp2_priority_spec *pri_spec,
2875 const nghttp2_nv *nva, size_t nvlen,
2876 void *stream_user_data);
2881 * Submits one or more DATA frames to the stream |stream_id|. The
2882 * data to be sent are provided by |data_prd|. If |flags| contains
2883 * :enum:`NGHTTP2_FLAG_END_STREAM`, the last DATA frame has END_STREAM
2886 * This function does not take ownership of the |data_prd|. The
2887 * function copies the members of the |data_prd|.
2889 * This function returns 0 if it succeeds, or one of the following
2890 * negative error codes:
2892 * :enum:`NGHTTP2_ERR_NOMEM`
2894 * :enum:`NGHTTP2_ERR_DATA_EXIST`
2895 * DATA has been already submitted and not fully processed yet.
2896 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2897 * The |stream_id| is 0.
2898 * :enum:`NGHTTP2_ERR_STREAM_CLOSED`
2899 * The stream was alreay closed; or the |stream_id| is invalid.
2903 * Currently, only one data is allowed for a stream at a time.
2904 * Submitting data more than once before first data is finished
2905 * results in :enum:`NGHTTP2_ERR_DATA_EXIST` error code. The
2906 * earliest callback which tells that previous data is done is
2907 * :type:`nghttp2_on_frame_send_callback`. In side that callback,
2908 * new data can be submitted using `nghttp2_submit_data()`. Of
2909 * course, all data except for last one must not have
2910 * :enum:`NGHTTP2_FLAG_END_STREAM` flag set in |flags|.
2912 int nghttp2_submit_data(nghttp2_session *session, uint8_t flags,
2914 const nghttp2_data_provider *data_prd);
2919 * Submits PRIORITY frame to change the priority of stream |stream_id|
2920 * to the priority specification |pri_spec|.
2922 * The |flags| is currently ignored and should be
2923 * :enum:`NGHTTP2_FLAG_NONE`.
2925 * The |pri_spec| is priority specification of this request. ``NULL``
2926 * is not allowed for this function. To specify the priority, use
2927 * `nghttp2_priority_spec_init()`. This function will copy its data
2930 * The `pri_spec->weight` must be in [:enum:`NGHTTP2_MIN_WEIGHT`,
2931 * :enum:`NGHTTP2_MAX_WEIGHT`], inclusive. If `pri_spec->weight` is
2932 * strictly less than :enum:`NGHTTP2_MIN_WEIGHT`, it becomes
2933 * :enum:`NGHTTP2_MIN_WEIGHT`. If it is strictly greater than
2934 * :enum:`NGHTTP2_MAX_WEIGHT`, it becomes :enum:`NGHTTP2_MAX_WEIGHT`.
2936 * This function returns 0 if it succeeds, or one of the following
2937 * negative error codes:
2939 * :enum:`NGHTTP2_ERR_NOMEM`
2941 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2942 * The |stream_id| is 0; or the |pri_spec| is NULL; or trying to
2945 int nghttp2_submit_priority(nghttp2_session *session, uint8_t flags,
2947 const nghttp2_priority_spec *pri_spec);
2952 * Submits RST_STREAM frame to cancel/reject the stream |stream_id|
2953 * with the error code |error_code|.
2955 * The pre-defined error code is one of :enum:`nghttp2_error_code`.
2957 * The |flags| is currently ignored and should be
2958 * :enum:`NGHTTP2_FLAG_NONE`.
2960 * This function returns 0 if it succeeds, or one of the following
2961 * negative error codes:
2963 * :enum:`NGHTTP2_ERR_NOMEM`
2965 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2966 * The |stream_id| is 0.
2968 int nghttp2_submit_rst_stream(nghttp2_session *session, uint8_t flags,
2969 int32_t stream_id, uint32_t error_code);
2974 * Stores local settings and submits SETTINGS frame. The |iv| is the
2975 * pointer to the array of :type:`nghttp2_settings_entry`. The |niv|
2976 * indicates the number of :type:`nghttp2_settings_entry`.
2978 * The |flags| is currently ignored and should be
2979 * :enum:`NGHTTP2_FLAG_NONE`.
2981 * This function does not take ownership of the |iv|. This function
2982 * copies all the elements in the |iv|.
2984 * While updating individual stream's local window size, if the window
2985 * size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE,
2986 * RST_STREAM is issued against such a stream.
2988 * SETTINGS with :enum:`NGHTTP2_FLAG_ACK` is automatically submitted
2989 * by the library and application could not send it at its will.
2991 * This function returns 0 if it succeeds, or one of the following
2992 * negative error codes:
2994 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
2995 * The |iv| contains invalid value (e.g., initial window size
2996 * strictly greater than (1 << 31) - 1.
2997 * :enum:`NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGS`
2998 * There is already another in-flight SETTINGS. Note that the
2999 * current implementation only allows 1 in-flight SETTINGS frame
3000 * without ACK flag set.
3001 * :enum:`NGHTTP2_ERR_NOMEM`
3004 int nghttp2_submit_settings(nghttp2_session *session, uint8_t flags,
3005 const nghttp2_settings_entry *iv, size_t niv);
3010 * Submits PUSH_PROMISE frame.
3012 * The |flags| is currently ignored. The library handles the
3013 * CONTINUATION frame internally and it correctly sets END_HEADERS to
3014 * the last sequence of the PUSH_PROMISE or CONTINUATION frame.
3016 * The |stream_id| must be client initiated stream ID.
3018 * The |nva| is an array of name/value pair :type:`nghttp2_nv` with
3019 * |nvlen| elements. The application is responsible to include
3020 * required pseudo-header fields (header field whose name starts with
3021 * ":") in |nva| and must place pseudo-headers before regular header
3024 * This function creates copies of all name/value pairs in |nva|. It
3025 * also lower-cases all names in |nva|. The order of elements in
3026 * |nva| is preserved.
3028 * The |promised_stream_user_data| is a pointer to an arbitrary data
3029 * which is associated to the promised stream this frame will open and
3030 * make it in reserved state. It is available using
3031 * `nghttp2_session_get_stream_user_data()`. The application can
3032 * access it in :type:`nghttp2_before_frame_send_callback` and
3033 * :type:`nghttp2_on_frame_send_callback` of this frame.
3035 * The client side is not allowed to use this function.
3037 * This function returns assigned promised stream ID if it succeeds,
3038 * or one of the following negative error codes:
3040 * :enum:`NGHTTP2_ERR_NOMEM`
3042 * :enum:`NGHTTP2_ERR_PROTO`
3043 * This function was invoked when |session| is initialized as
3045 * :enum:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
3046 * No stream ID is available because maximum stream ID was
3048 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3049 * The |stream_id| is 0; The |stream_id| does not designate stream
3050 * that peer initiated.
3054 * This function returns assigned promised stream ID if it succeeds.
3055 * But that stream is not opened yet. The application must not
3056 * submit frame to that stream ID before
3057 * :type:`nghttp2_before_frame_send_callback` is called for this
3061 int32_t nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags,
3062 int32_t stream_id, const nghttp2_nv *nva,
3064 void *promised_stream_user_data);
3069 * Submits PING frame. You don't have to send PING back when you
3070 * received PING frame. The library automatically submits PING frame
3073 * The |flags| is currently ignored and should be
3074 * :enum:`NGHTTP2_FLAG_NONE`.
3076 * If the |opaque_data| is non ``NULL``, then it should point to the 8
3077 * bytes array of memory to specify opaque data to send with PING
3078 * frame. If the |opaque_data| is ``NULL``, zero-cleared 8 bytes will
3079 * be sent as opaque data.
3081 * This function returns 0 if it succeeds, or one of the following
3082 * negative error codes:
3084 * :enum:`NGHTTP2_ERR_NOMEM`
3087 int nghttp2_submit_ping(nghttp2_session *session, uint8_t flags,
3088 const uint8_t *opaque_data);
3093 * Submits GOAWAY frame with the last stream ID |last_stream_id| and
3094 * the error code |error_code|.
3096 * The pre-defined error code is one of :enum:`nghttp2_error_code`.
3098 * The |flags| is currently ignored and should be
3099 * :enum:`NGHTTP2_FLAG_NONE`.
3101 * The |last_stream_id| is peer's stream ID or 0. So if |session| is
3102 * initialized as client, |last_stream_id| must be even or 0. If
3103 * |session| is initialized as server, |last_stream_id| must be odd or
3106 * The HTTP/2 specification says last_stream_id must not be increased
3107 * from the value previously sent. So the actual value sent as
3108 * last_stream_id is the minimum value between the given
3109 * |last_stream_id| and the last_stream_id previously sent to the
3112 * If the |opaque_data| is not ``NULL`` and |opaque_data_len| is not
3113 * zero, those data will be sent as additional debug data. The
3114 * library makes a copy of the memory region pointed by |opaque_data|
3115 * with the length |opaque_data_len|, so the caller does not need to
3116 * keep this memory after the return of this function. If the
3117 * |opaque_data_len| is 0, the |opaque_data| could be ``NULL``.
3119 * After successful transmission of GOAWAY, following things happen.
3120 * All incoming streams having strictly more than |last_stream_id| are
3121 * closed. All incoming HEADERS which starts new stream are simply
3122 * ignored. After all active streams are handled, both
3123 * `nghttp2_session_want_read()` and `nghttp2_session_want_write()`
3124 * return 0 and the application can close session.
3126 * This function returns 0 if it succeeds, or one of the following
3127 * negative error codes:
3129 * :enum:`NGHTTP2_ERR_NOMEM`
3131 * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
3132 * The |opaque_data_len| is too large; the |last_stream_id| is
3135 int nghttp2_submit_goaway(nghttp2_session *session, uint8_t flags,
3136 int32_t last_stream_id, uint32_t error_code,
3137 const uint8_t *opaque_data, size_t opaque_data_len);
3142 * Returns the last stream ID of a stream for which
3143 * :type:`nghttp2_on_frame_recv_callback` was invoked most recently.
3144 * The returned value can be used as last_stream_id parameter for
3145 * `nghttp2_submit_goaway()` and
3146 * `nghttp2_session_terminate_session2()`.
3148 * This function always succeeds.
3150 int32_t nghttp2_session_get_last_proc_stream_id(nghttp2_session *session);
3155 * Submits WINDOW_UPDATE frame.
3157 * The |flags| is currently ignored and should be
3158 * :enum:`NGHTTP2_FLAG_NONE`.
3160 * If the |window_size_increment| is positive, the WINDOW_UPDATE with
3161 * that value as window_size_increment is queued. If the
3162 * |window_size_increment| is larger than the received bytes from the
3163 * remote endpoint, the local window size is increased by that
3166 * If the |window_size_increment| is negative, the local window size
3167 * is decreased by -|window_size_increment|. If automatic
3168 * WINDOW_UPDATE is enabled
3169 * (`nghttp2_option_set_no_auto_window_update()`), and the library
3170 * decided that the WINDOW_UPDATE should be submitted, then
3171 * WINDOW_UPDATE is queued with the current received bytes count.
3173 * If the |window_size_increment| is 0, the function does nothing and
3176 * This function returns 0 if it succeeds, or one of the following
3177 * negative error codes:
3179 * :enum:`NGHTTP2_ERR_FLOW_CONTROL`
3180 * The local window size overflow or gets negative.
3181 * :enum:`NGHTTP2_ERR_NOMEM`
3184 int nghttp2_submit_window_update(nghttp2_session *session, uint8_t flags,
3186 int32_t window_size_increment);
3191 * This function previously submits ALTSVC frame with given
3192 * parameters, but is deprecated and will be removed in a future
3193 * release. This function does nothing and just return 0.
3195 int nghttp2_submit_altsvc(nghttp2_session *session, uint8_t flags,
3196 int32_t stream_id, uint32_t max_age, uint16_t port,
3197 const uint8_t *protocol_id, size_t protocol_id_len,
3198 const uint8_t *host, size_t host_len,
3199 const uint8_t *origin, size_t origin_len);
3204 * Compares ``lhs->name`` of length ``lhs->namelen`` bytes and
3205 * ``rhs->name`` of length ``rhs->namelen`` bytes. Returns negative
3206 * integer if ``lhs->name`` is found to be less than ``rhs->name``; or
3207 * returns positive integer if ``lhs->name`` is found to be greater
3208 * than ``rhs->name``; or returns 0 otherwise.
3210 int nghttp2_nv_compare_name(const nghttp2_nv *lhs, const nghttp2_nv *rhs);
3215 * A helper function for dealing with NPN in client side or ALPN in
3216 * server side. The |in| contains peer's protocol list in preferable
3217 * order. The format of |in| is length-prefixed and not
3218 * null-terminated. For example, ``HTTP-draft-04/2.0`` and
3219 * ``http/1.1`` stored in |in| like this::
3222 * in[1..17] = "HTTP-draft-04/2.0"
3224 * in[19..26] = "http/1.1"
3227 * The selection algorithm is as follows:
3229 * 1. If peer's list contains HTTP/2 protocol the library supports,
3230 * it is selected and returns 1. The following step is not taken.
3232 * 2. If peer's list contains ``http/1.1``, this function selects
3233 * ``http/1.1`` and returns 0. The following step is not taken.
3235 * 3. This function selects nothing and returns -1 (So called
3236 * non-overlap case). In this case, |out| and |outlen| are left
3239 * Selecting ``HTTP-draft-04/2.0`` means that ``HTTP-draft-04/2.0`` is
3240 * written into |*out| and its length (which is 17) is assigned to
3243 * For ALPN, refer to
3244 * https://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-05
3246 * See http://technotes.googlecode.com/git/nextprotoneg.html for more
3247 * details about NPN.
3249 * For NPN, to use this method you should do something like::
3251 * static int select_next_proto_cb(SSL* ssl,
3252 * unsigned char **out,
3253 * unsigned char *outlen,
3254 * const unsigned char *in,
3255 * unsigned int inlen,
3259 * rv = nghttp2_select_next_protocol(out, outlen, in, inlen);
3261 * ((MyType*)arg)->http2_selected = 1;
3263 * return SSL_TLSEXT_ERR_OK;
3266 * SSL_CTX_set_next_proto_select_cb(ssl_ctx, select_next_proto_cb, my_obj);
3269 int nghttp2_select_next_protocol(unsigned char **out, unsigned char *outlen,
3270 const unsigned char *in, unsigned int inlen);
3275 * Returns a pointer to a nghttp2_info struct with version information
3276 * about the run-time library in use. The |least_version| argument
3277 * can be set to a 24 bit numerical value for the least accepted
3278 * version number and if the condition is not met, this function will
3279 * return a ``NULL``. Pass in 0 to skip the version checking.
3281 nghttp2_info *nghttp2_version(int least_version);
3286 * Returns nonzero if the :type:`nghttp2_error` library error code
3287 * |lib_error| is fatal.
3289 int nghttp2_is_fatal(int lib_error);
3294 * Returns nonzero if HTTP header field name |name| of length |len| is
3295 * valid according to http://tools.ietf.org/html/rfc7230#section-3.2
3297 * Because this is a header field name in HTTP2, the upper cased alphabet
3298 * is treated as error.
3300 int nghttp2_check_header_name(const uint8_t *name, size_t len);
3305 * Returns nonzero if HTTP header field value |value| of length |len|
3306 * is valid according to
3307 * http://tools.ietf.org/html/rfc7230#section-3.2
3309 int nghttp2_check_header_value(const uint8_t *value, size_t len);
3313 struct nghttp2_hd_deflater;
3318 * HPACK deflater object.
3320 typedef struct nghttp2_hd_deflater nghttp2_hd_deflater;
3325 * Initializes |*deflater_ptr| for deflating name/values pairs.
3327 * The |deflate_hd_table_bufsize_max| is the upper bound of header
3328 * table size the deflater will use.
3330 * If this function fails, |*deflater_ptr| is left untouched.
3332 * This function returns 0 if it succeeds, or one of the following
3333 * negative error codes:
3335 * :enum:`NGHTTP2_ERR_NOMEM`
3338 int nghttp2_hd_deflate_new(nghttp2_hd_deflater **deflater_ptr,
3339 size_t deflate_hd_table_bufsize_max);
3344 * Like `nghttp2_hd_deflate_new()`, but with additional custom memory
3345 * allocator specified in the |mem|.
3347 * The |mem| can be ``NULL`` and the call is equivalent to
3348 * `nghttp2_hd_deflate_new()`.
3350 * This function does not take ownership |mem|. The application is
3351 * responsible for freeing |mem|.
3353 * The library code does not refer to |mem| pointer after this
3354 * function returns, so the application can safely free it.
3356 int nghttp2_hd_deflate_new2(nghttp2_hd_deflater **deflater_ptr,
3357 size_t deflate_hd_table_bufsize_max,
3363 * Deallocates any resources allocated for |deflater|.
3365 void nghttp2_hd_deflate_del(nghttp2_hd_deflater *deflater);
3370 * Changes header table size of the |deflater| to
3371 * |settings_hd_table_bufsize_max| bytes. This may trigger eviction
3372 * in the dynamic table.
3374 * The |settings_hd_table_bufsize_max| should be the value received in
3375 * SETTINGS_HEADER_TABLE_SIZE.
3377 * The deflater never uses more memory than
3378 * ``deflate_hd_table_bufsize_max`` bytes specified in
3379 * `nghttp2_hd_deflate_new()`. Therefore, if
3380 * |settings_hd_table_bufsize_max| > ``deflate_hd_table_bufsize_max``,
3381 * resulting maximum table size becomes
3382 * ``deflate_hd_table_bufsize_max``.
3384 * This function returns 0 if it succeeds, or one of the following
3385 * negative error codes:
3387 * :enum:`NGHTTP2_ERR_NOMEM`
3390 int nghttp2_hd_deflate_change_table_size(nghttp2_hd_deflater *deflater,
3391 size_t settings_hd_table_bufsize_max);
3396 * Deflates the |nva|, which has the |nvlen| name/value pairs, into
3397 * the |buf| of length |buflen|.
3399 * If |buf| is not large enough to store the deflated header block,
3400 * this function fails with :enum:`NGHTTP2_ERR_INSUFF_BUFSIZE`. The
3401 * caller should use `nghttp2_hd_deflate_bound()` to know the upper
3402 * bound of buffer size required to deflate given header name/value
3405 * Once this function fails, subsequent call of this function always
3406 * returns :enum:`NGHTTP2_ERR_HEADER_COMP`.
3408 * After this function returns, it is safe to delete the |nva|.
3410 * This function returns 0 if it succeeds, or one of the following
3411 * negative error codes:
3413 * :enum:`NGHTTP2_ERR_NOMEM`
3415 * :enum:`NGHTTP2_ERR_HEADER_COMP`
3416 * Deflation process has failed.
3417 * :enum:`NGHTTP2_ERR_INSUFF_BUFSIZE`
3418 * The provided |buflen| size is too small to hold the output.
3420 ssize_t nghttp2_hd_deflate_hd(nghttp2_hd_deflater *deflater, uint8_t *buf,
3421 size_t buflen, const nghttp2_nv *nva,
3427 * Returns an upper bound on the compressed size after deflation of
3428 * |nva| of length |nvlen|.
3430 size_t nghttp2_hd_deflate_bound(nghttp2_hd_deflater *deflater,
3431 const nghttp2_nv *nva, size_t nvlen);
3433 struct nghttp2_hd_inflater;
3438 * HPACK inflater object.
3440 typedef struct nghttp2_hd_inflater nghttp2_hd_inflater;
3445 * Initializes |*inflater_ptr| for inflating name/values pairs.
3447 * If this function fails, |*inflater_ptr| is left untouched.
3449 * This function returns 0 if it succeeds, or one of the following
3450 * negative error codes:
3452 * :enum:`NGHTTP2_ERR_NOMEM`
3455 int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr);
3460 * Like `nghttp2_hd_inflate_new()`, but with additional custom memory
3461 * allocator specified in the |mem|.
3463 * The |mem| can be ``NULL`` and the call is equivalent to
3464 * `nghttp2_hd_inflate_new()`.
3466 * This function does not take ownership |mem|. The application is
3467 * responsible for freeing |mem|.
3469 * The library code does not refer to |mem| pointer after this
3470 * function returns, so the application can safely free it.
3472 int nghttp2_hd_inflate_new2(nghttp2_hd_inflater **inflater_ptr,
3478 * Deallocates any resources allocated for |inflater|.
3480 void nghttp2_hd_inflate_del(nghttp2_hd_inflater *inflater);
3485 * Changes header table size in the |inflater|. This may trigger
3486 * eviction in the dynamic table.
3488 * The |settings_hd_table_bufsize_max| should be the value transmitted
3489 * in SETTINGS_HEADER_TABLE_SIZE.
3491 * This function returns 0 if it succeeds, or one of the following
3492 * negative error codes:
3494 * :enum:`NGHTTP2_ERR_NOMEM`
3497 int nghttp2_hd_inflate_change_table_size(nghttp2_hd_inflater *inflater,
3498 size_t settings_hd_table_bufsize_max);
3503 * The flags for header inflation.
3509 NGHTTP2_HD_INFLATE_NONE = 0,
3511 * Indicates all headers were inflated.
3513 NGHTTP2_HD_INFLATE_FINAL = 0x01,
3515 * Indicates a header was emitted.
3517 NGHTTP2_HD_INFLATE_EMIT = 0x02
3518 } nghttp2_hd_inflate_flag;
3523 * Inflates name/value block stored in |in| with length |inlen|. This
3524 * function performs decompression. For each successful emission of
3525 * header name/value pair, :enum:`NGHTTP2_HD_INFLATE_EMIT` is set in
3526 * |*inflate_flags| and name/value pair is assigned to the |nv_out|
3527 * and the function returns. The caller must not free the members of
3530 * The |nv_out| may include pointers to the memory region in the |in|.
3531 * The caller must retain the |in| while the |nv_out| is used.
3533 * The application should call this function repeatedly until the
3534 * ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
3535 * return value is non-negative. This means the all input values are
3536 * processed successfully. Then the application must call
3537 * `nghttp2_hd_inflate_end_headers()` to prepare for the next header
3540 * The caller can feed complete compressed header block. It also can
3541 * feed it in several chunks. The caller must set |in_final| to
3542 * nonzero if the given input is the last block of the compressed
3545 * This function returns the number of bytes processed if it succeeds,
3546 * or one of the following negative error codes:
3548 * :enum:`NGHTTP2_ERR_NOMEM`
3550 * :enum:`NGHTTP2_ERR_HEADER_COMP`
3551 * Inflation process has failed.
3552 * :enum:`NGHTTP2_ERR_BUFFER_ERROR`
3553 * The heder field name or value is too large.
3557 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
3558 * uint8_t *in, size_t inlen, int final)
3564 * int inflate_flags = 0;
3566 * rv = nghttp2_hd_inflate_hd(hd_inflater, &nv, &inflate_flags,
3567 * in, inlen, final);
3570 * fprintf(stderr, "inflate failed with error code %zd", rv);
3577 * if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
3578 * fwrite(nv.name, nv.namelen, 1, stderr);
3579 * fprintf(stderr, ": ");
3580 * fwrite(nv.value, nv.valuelen, 1, stderr);
3581 * fprintf(stderr, "\n");
3583 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
3584 * nghttp2_hd_inflate_end_headers(hd_inflater);
3587 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
3597 ssize_t nghttp2_hd_inflate_hd(nghttp2_hd_inflater *inflater, nghttp2_nv *nv_out,
3598 int *inflate_flags, uint8_t *in, size_t inlen,
3604 * Signals the end of decompression for one header block.
3606 * This function returns 0 if it succeeds. Currently this function
3609 int nghttp2_hd_inflate_end_headers(nghttp2_hd_inflater *inflater);
3615 #endif /* NGHTTP2_H */