1 /*
2 * nghttp2 - HTTP/2 C Library
3 *
4 * Copyright (c) 2013, 2014 Tatsuhiro Tsujikawa
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining
7 * a copy of this software and associated documentation files (the
8 * "Software"), to deal in the Software without restriction, including
9 * without limitation the rights to use, copy, modify, merge, publish,
10 * distribute, sublicense, and/or sell copies of the Software, and to
11 * permit persons to whom the Software is furnished to do so, subject to
12 * the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be
15 * included in all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 */
25 #ifndef NGHTTP2_H
26 #define NGHTTP2_H
27
28 /* Define WIN32 when build target is Win32 API (borrowed from
29 libcurl) */
30 #if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32)
31 # define WIN32
32 #endif
33
34 /* Compatibility for non-Clang compilers */
35 #ifndef __has_declspec_attribute
36 # define __has_declspec_attribute(x) 0
37 #endif
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 #include <stdlib.h>
44 #if defined(_MSC_VER) && (_MSC_VER < 1800)
45 /* MSVC < 2013 does not have inttypes.h because it is not C99
46 compliant. See compiler macros and version number in
47 https://sourceforge.net/p/predef/wiki/Compilers/ */
48 # include <stdint.h>
49 #else /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */
50 # include <inttypes.h>
51 #endif /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */
52 #include <sys/types.h>
53 #include <stdarg.h>
54 #include <string.h>
55
nghttp2_cpymem(uint8_t * dest,const void * src,size_t len)56 static inline uint8_t *nghttp2_cpymem(uint8_t *dest, const void *src, size_t len) {
57 if (len == 0) {
58 return dest;
59 }
60
61 memcpy(dest, src, len);
62
63 return dest + len;
64 }
65
66 #define nghttp2_min(A, B) ((A) < (B) ? (A) : (B))
67 #define nghttp2_max(A, B) ((A) > (B) ? (A) : (B))
68
69 #define DEBUGF(s, ...)
70
71 const char *nghttp2_strerror(int error_code);
72
73 #ifdef NGHTTP2_STATICLIB
74 # define NGHTTP2_EXTERN
75 #elif defined(WIN32) || (__has_declspec_attribute(dllexport) && \
76 __has_declspec_attribute(dllimport))
77 # ifdef BUILDING_NGHTTP2
78 # define NGHTTP2_EXTERN __declspec(dllexport)
79 # else /* !BUILDING_NGHTTP2 */
80 # define NGHTTP2_EXTERN __declspec(dllimport)
81 # endif /* !BUILDING_NGHTTP2 */
82 #else /* !defined(WIN32) */
83 # ifdef BUILDING_NGHTTP2
84 # define NGHTTP2_EXTERN __attribute__((visibility("default")))
85 # else /* !BUILDING_NGHTTP2 */
86 # define NGHTTP2_EXTERN
87 # endif /* !BUILDING_NGHTTP2 */
88 #endif /* !defined(WIN32) */
89
90 /**
91 * @macro
92 *
93 * The protocol version identification string of this library
94 * supports. This identifier is used if HTTP/2 is used over TLS.
95 */
96 #define NGHTTP2_PROTO_VERSION_ID "h2"
97 /**
98 * @macro
99 *
100 * The length of :macro:`NGHTTP2_PROTO_VERSION_ID`.
101 */
102 #define NGHTTP2_PROTO_VERSION_ID_LEN 2
103
104 /**
105 * @macro
106 *
107 * The serialized form of ALPN protocol identifier this library
108 * supports. Notice that first byte is the length of following
109 * protocol identifier. This is the same wire format of `TLS ALPN
110 * extension <https://tools.ietf.org/html/rfc7301>`_. This is useful
111 * to process incoming ALPN tokens in wire format.
112 */
113 #define NGHTTP2_PROTO_ALPN "\x2h2"
114
115 /**
116 * @macro
117 *
118 * The length of :macro:`NGHTTP2_PROTO_ALPN`.
119 */
120 #define NGHTTP2_PROTO_ALPN_LEN (sizeof(NGHTTP2_PROTO_ALPN) - 1)
121
122 /**
123 * @macro
124 *
125 * The protocol version identification string of this library
126 * supports. This identifier is used if HTTP/2 is used over cleartext
127 * TCP.
128 */
129 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID "h2c"
130
131 /**
132 * @macro
133 *
134 * The length of :macro:`NGHTTP2_CLEARTEXT_PROTO_VERSION_ID`.
135 */
136 #define NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN 3
137
138
139 /**
140 * @macro
141 *
142 * The age of :type:`nghttp2_info`
143 */
144 #define NGHTTP2_VERSION_AGE 1
145
146 /**
147 * @struct
148 *
149 * This struct is what `nghttp2_version()` returns. It holds
150 * information about the particular nghttp2 version.
151 */
152 typedef struct {
153 /**
154 * Age of this struct. This instance of nghttp2 sets it to
155 * :macro:`NGHTTP2_VERSION_AGE` but a future version may bump it and
156 * add more struct fields at the bottom
157 */
158 int age;
159 /**
160 * the :macro:`NGHTTP2_VERSION_NUM` number (since age ==1)
161 */
162 int version_num;
163 /**
164 * points to the :macro:`NGHTTP2_VERSION` string (since age ==1)
165 */
166 const char *version_str;
167 /**
168 * points to the :macro:`NGHTTP2_PROTO_VERSION_ID` string this
169 * instance implements (since age ==1)
170 */
171 const char *proto_str;
172 /* -------- the above fields all exist when age == 1 */
173 } nghttp2_info;
174
175 /**
176 * @macro
177 *
178 * The default weight of stream dependency.
179 */
180 #define NGHTTP2_DEFAULT_WEIGHT 16
181
182 /**
183 * @macro
184 *
185 * The maximum weight of stream dependency.
186 */
187 #define NGHTTP2_MAX_WEIGHT 256
188
189 /**
190 * @macro
191 *
192 * The minimum weight of stream dependency.
193 */
194 #define NGHTTP2_MIN_WEIGHT 1
195
196 /**
197 * @macro
198 *
199 * The maximum window size
200 */
201 #define NGHTTP2_MAX_WINDOW_SIZE ((int32_t)((1U << 31) - 1))
202
203 /**
204 * @macro
205 *
206 * The initial window size for stream level flow control.
207 */
208 #define NGHTTP2_INITIAL_WINDOW_SIZE ((1 << 16) - 1)
209 /**
210 * @macro
211 *
212 * The initial window size for connection level flow control.
213 */
214 #define NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE ((1 << 16) - 1)
215
216 /**
217 * @macro
218 *
219 * The default header table size.
220 */
221 #define NGHTTP2_DEFAULT_HEADER_TABLE_SIZE (1 << 12)
222
223 /**
224 * @macro
225 *
226 * The client magic string, which is the first 24 bytes byte string of
227 * client connection preface.
228 */
229 #define NGHTTP2_CLIENT_MAGIC "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
230
231 /**
232 * @macro
233 *
234 * The length of :macro:`NGHTTP2_CLIENT_MAGIC`.
235 */
236 #define NGHTTP2_CLIENT_MAGIC_LEN 24
237
238 /**
239 * @macro
240 *
241 * The default max number of settings per SETTINGS frame
242 */
243 #define NGHTTP2_DEFAULT_MAX_SETTINGS 32
244
245 /**
246 * @enum
247 *
248 * Error codes used in this library. The code range is [-999, -500],
249 * inclusive. The following values are defined:
250 */
251 typedef enum {
252 /**
253 * Invalid argument passed.
254 */
255 NGHTTP2_ERR_INVALID_ARGUMENT = -501,
256 /**
257 * Out of buffer space.
258 */
259 NGHTTP2_ERR_BUFFER_ERROR = -502,
260 /**
261 * The specified protocol version is not supported.
262 */
263 NGHTTP2_ERR_UNSUPPORTED_VERSION = -503,
264 /**
265 * Used as a return value from :type:`nghttp2_send_callback`,
266 * :type:`nghttp2_recv_callback` and
267 * :type:`nghttp2_send_data_callback` to indicate that the operation
268 * would block.
269 */
270 NGHTTP2_ERR_WOULDBLOCK = -504,
271 /**
272 * General protocol error
273 */
274 NGHTTP2_ERR_PROTO = -505,
275 /**
276 * The frame is invalid.
277 */
278 NGHTTP2_ERR_INVALID_FRAME = -506,
279 /**
280 * The peer performed a shutdown on the connection.
281 */
282 NGHTTP2_ERR_EOF = -507,
283 /**
284 * Used as a return value from
285 * :func:`nghttp2_data_source_read_callback` to indicate that data
286 * transfer is postponed. See
287 * :func:`nghttp2_data_source_read_callback` for details.
288 */
289 NGHTTP2_ERR_DEFERRED = -508,
290 /**
291 * Stream ID has reached the maximum value. Therefore no stream ID
292 * is available.
293 */
294 NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE = -509,
295 /**
296 * The stream is already closed; or the stream ID is invalid.
297 */
298 NGHTTP2_ERR_STREAM_CLOSED = -510,
299 /**
300 * RST_STREAM has been added to the outbound queue. The stream is
301 * in closing state.
302 */
303 NGHTTP2_ERR_STREAM_CLOSING = -511,
304 /**
305 * The transmission is not allowed for this stream (e.g., a frame
306 * with END_STREAM flag set has already sent).
307 */
308 NGHTTP2_ERR_STREAM_SHUT_WR = -512,
309 /**
310 * The stream ID is invalid.
311 */
312 NGHTTP2_ERR_INVALID_STREAM_ID = -513,
313 /**
314 * The state of the stream is not valid (e.g., DATA cannot be sent
315 * to the stream if response HEADERS has not been sent).
316 */
317 NGHTTP2_ERR_INVALID_STREAM_STATE = -514,
318 /**
319 * Another DATA frame has already been deferred.
320 */
321 NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515,
322 /**
323 * Starting new stream is not allowed (e.g., GOAWAY has been sent
324 * and/or received).
325 */
326 NGHTTP2_ERR_START_STREAM_NOT_ALLOWED = -516,
327 /**
328 * GOAWAY has already been sent.
329 */
330 NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517,
331 /**
332 * The received frame contains the invalid header block (e.g., There
333 * are duplicate header names; or the header names are not encoded
334 * in US-ASCII character set and not lower cased; or the header name
335 * is zero-length string; or the header value contains multiple
336 * in-sequence NUL bytes).
337 */
338 NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518,
339 /**
340 * Indicates that the context is not suitable to perform the
341 * requested operation.
342 */
343 NGHTTP2_ERR_INVALID_STATE = -519,
344 /**
345 * The user callback function failed due to the temporal error.
346 */
347 NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE = -521,
348 /**
349 * The length of the frame is invalid, either too large or too small.
350 */
351 NGHTTP2_ERR_FRAME_SIZE_ERROR = -522,
352 /**
353 * Header block inflate/deflate error.
354 */
355 NGHTTP2_ERR_HEADER_COMP = -523,
356 /**
357 * Flow control error
358 */
359 NGHTTP2_ERR_FLOW_CONTROL = -524,
360 /**
361 * Insufficient buffer size given to function.
362 */
363 NGHTTP2_ERR_INSUFF_BUFSIZE = -525,
364 /**
365 * Callback was paused by the application
366 */
367 NGHTTP2_ERR_PAUSE = -526,
368 /**
369 * There are too many in-flight SETTING frame and no more
370 * transmission of SETTINGS is allowed.
371 */
372 NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGS = -527,
373 /**
374 * The server push is disabled.
375 */
376 NGHTTP2_ERR_PUSH_DISABLED = -528,
377 /**
378 * DATA or HEADERS frame for a given stream has been already
379 * submitted and has not been fully processed yet. Application
380 * should wait for the transmission of the previously submitted
381 * frame before submitting another.
382 */
383 NGHTTP2_ERR_DATA_EXIST = -529,
384 /**
385 * The current session is closing due to a connection error or
386 * `nghttp2_session_terminate_session()` is called.
387 */
388 NGHTTP2_ERR_SESSION_CLOSING = -530,
389 /**
390 * Invalid HTTP header field was received and stream is going to be
391 * closed.
392 */
393 NGHTTP2_ERR_HTTP_HEADER = -531,
394 /**
395 * Violation in HTTP messaging rule.
396 */
397 NGHTTP2_ERR_HTTP_MESSAGING = -532,
398 /**
399 * Stream was refused.
400 */
401 NGHTTP2_ERR_REFUSED_STREAM = -533,
402 /**
403 * Unexpected internal error, but recovered.
404 */
405 NGHTTP2_ERR_INTERNAL = -534,
406 /**
407 * Indicates that a processing was canceled.
408 */
409 NGHTTP2_ERR_CANCEL = -535,
410 /**
411 * When a local endpoint expects to receive SETTINGS frame, it
412 * receives an other type of frame.
413 */
414 NGHTTP2_ERR_SETTINGS_EXPECTED = -536,
415 /**
416 * When a local endpoint receives too many settings entries
417 * in a single SETTINGS frame.
418 */
419 NGHTTP2_ERR_TOO_MANY_SETTINGS = -537,
420 /**
421 * The errors < :enum:`nghttp2_error.NGHTTP2_ERR_FATAL` mean that
422 * the library is under unexpected condition and processing was
423 * terminated (e.g., out of memory). If application receives this
424 * error code, it must stop using that :type:`nghttp2_session`
425 * object and only allowed operation for that object is deallocate
426 * it using `nghttp2_session_del()`.
427 */
428 NGHTTP2_ERR_FATAL = -900,
429 /**
430 * Out of memory. This is a fatal error.
431 */
432 NGHTTP2_ERR_NOMEM = -901,
433 /**
434 * The user callback function failed. This is a fatal error.
435 */
436 NGHTTP2_ERR_CALLBACK_FAILURE = -902,
437 /**
438 * Invalid client magic (see :macro:`NGHTTP2_CLIENT_MAGIC`) was
439 * received and further processing is not possible.
440 */
441 NGHTTP2_ERR_BAD_CLIENT_MAGIC = -903,
442 /**
443 * Possible flooding by peer was detected in this HTTP/2 session.
444 * Flooding is measured by how many PING and SETTINGS frames with
445 * ACK flag set are queued for transmission. These frames are
446 * response for the peer initiated frames, and peer can cause memory
447 * exhaustion on server side to send these frames forever and does
448 * not read network.
449 */
450 NGHTTP2_ERR_FLOODED = -904
451 } nghttp2_error;
452
453 /**
454 * @struct
455 *
456 * The object representing single contiguous buffer.
457 */
458 typedef struct {
459 /**
460 * The pointer to the buffer.
461 */
462 uint8_t *base;
463 /**
464 * The length of the buffer.
465 */
466 size_t len;
467 } nghttp2_vec;
468
469 struct nghttp2_rcbuf;
470
471 /**
472 * @struct
473 *
474 * The object representing reference counted buffer. The details of
475 * this structure are intentionally hidden from the public API.
476 */
477 typedef struct nghttp2_rcbuf nghttp2_rcbuf;
478
479 /**
480 * @function
481 *
482 * Increments the reference count of |rcbuf| by 1.
483 */
484 NGHTTP2_EXTERN void nghttp2_rcbuf_incref(nghttp2_rcbuf *rcbuf);
485
486 /**
487 * @function
488 *
489 * Decrements the reference count of |rcbuf| by 1. If the reference
490 * count becomes zero, the object pointed by |rcbuf| will be freed.
491 * In this case, application must not use |rcbuf| again.
492 */
493 NGHTTP2_EXTERN void nghttp2_rcbuf_decref(nghttp2_rcbuf *rcbuf);
494
495 /**
496 * @function
497 *
498 * Returns the underlying buffer managed by |rcbuf|.
499 */
500 NGHTTP2_EXTERN nghttp2_vec nghttp2_rcbuf_get_buf(nghttp2_rcbuf *rcbuf);
501
502 /**
503 * @enum
504 *
505 * The flags for header field name/value pair.
506 */
507 typedef enum {
508 /**
509 * No flag set.
510 */
511 NGHTTP2_NV_FLAG_NONE = 0,
512 /**
513 * Indicates that this name/value pair must not be indexed ("Literal
514 * Header Field never Indexed" representation must be used in HPACK
515 * encoding). Other implementation calls this bit as "sensitive".
516 */
517 NGHTTP2_NV_FLAG_NO_INDEX = 0x01,
518 /**
519 * This flag is set solely by application. If this flag is set, the
520 * library does not make a copy of header field name. This could
521 * improve performance.
522 */
523 NGHTTP2_NV_FLAG_NO_COPY_NAME = 0x02,
524 /**
525 * This flag is set solely by application. If this flag is set, the
526 * library does not make a copy of header field value. This could
527 * improve performance.
528 */
529 NGHTTP2_NV_FLAG_NO_COPY_VALUE = 0x04
530 } nghttp2_nv_flag;
531
532 /**
533 * @struct
534 *
535 * The name/value pair, which mainly used to represent header fields.
536 */
537 typedef struct {
538 /**
539 * The |name| byte string. If this struct is presented from library
540 * (e.g., :type:`nghttp2_on_frame_recv_callback`), |name| is
541 * guaranteed to be NULL-terminated. For some callbacks
542 * (:type:`nghttp2_before_frame_send_callback`,
543 * :type:`nghttp2_on_frame_send_callback`, and
544 * :type:`nghttp2_on_frame_not_send_callback`), it may not be
545 * NULL-terminated if header field is passed from application with
546 * the flag :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`).
547 * When application is constructing this struct, |name| is not
548 * required to be NULL-terminated.
549 */
550 uint8_t *name;
551 /**
552 * The |value| byte string. If this struct is presented from
553 * library (e.g., :type:`nghttp2_on_frame_recv_callback`), |value|
554 * is guaranteed to be NULL-terminated. For some callbacks
555 * (:type:`nghttp2_before_frame_send_callback`,
556 * :type:`nghttp2_on_frame_send_callback`, and
557 * :type:`nghttp2_on_frame_not_send_callback`), it may not be
558 * NULL-terminated if header field is passed from application with
559 * the flag :enum:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE`).
560 * When application is constructing this struct, |value| is not
561 * required to be NULL-terminated.
562 */
563 uint8_t *value;
564 /**
565 * The length of the |name|, excluding terminating NULL.
566 */
567 size_t namelen;
568 /**
569 * The length of the |value|, excluding terminating NULL.
570 */
571 size_t valuelen;
572 /**
573 * Bitwise OR of one or more of :type:`nghttp2_nv_flag`.
574 */
575 uint8_t flags;
576 } nghttp2_nv;
577
578 /**
579 * @enum
580 *
581 * The frame types in HTTP/2 specification.
582 */
583 typedef enum {
584 /**
585 * The DATA frame.
586 */
587 NGHTTP2_DATA = 0,
588 /**
589 * The HEADERS frame.
590 */
591 NGHTTP2_HEADERS = 0x01,
592 /**
593 * The PRIORITY frame.
594 */
595 NGHTTP2_PRIORITY = 0x02,
596 /**
597 * The RST_STREAM frame.
598 */
599 NGHTTP2_RST_STREAM = 0x03,
600 /**
601 * The SETTINGS frame.
602 */
603 NGHTTP2_SETTINGS = 0x04,
604 /**
605 * The PUSH_PROMISE frame.
606 */
607 NGHTTP2_PUSH_PROMISE = 0x05,
608 /**
609 * The PING frame.
610 */
611 NGHTTP2_PING = 0x06,
612 /**
613 * The GOAWAY frame.
614 */
615 NGHTTP2_GOAWAY = 0x07,
616 /**
617 * The WINDOW_UPDATE frame.
618 */
619 NGHTTP2_WINDOW_UPDATE = 0x08,
620 /**
621 * The CONTINUATION frame. This frame type won't be passed to any
622 * callbacks because the library processes this frame type and its
623 * preceding HEADERS/PUSH_PROMISE as a single frame.
624 */
625 NGHTTP2_CONTINUATION = 0x09,
626 /**
627 * The ALTSVC frame, which is defined in `RFC 7383
628 * <https://tools.ietf.org/html/rfc7838#section-4>`_.
629 */
630 NGHTTP2_ALTSVC = 0x0a,
631 /**
632 * The ORIGIN frame, which is defined by `RFC 8336
633 * <https://tools.ietf.org/html/rfc8336>`_.
634 */
635 NGHTTP2_ORIGIN = 0x0c
636 } nghttp2_frame_type;
637
638 /**
639 * @enum
640 *
641 * The flags for HTTP/2 frames. This enum defines all flags for all
642 * frames.
643 */
644 typedef enum {
645 /**
646 * No flag set.
647 */
648 NGHTTP2_FLAG_NONE = 0,
649 /**
650 * The END_STREAM flag.
651 */
652 NGHTTP2_FLAG_END_STREAM = 0x01,
653 /**
654 * The END_HEADERS flag.
655 */
656 NGHTTP2_FLAG_END_HEADERS = 0x04,
657 /**
658 * The ACK flag.
659 */
660 NGHTTP2_FLAG_ACK = 0x01,
661 /**
662 * The PADDED flag.
663 */
664 NGHTTP2_FLAG_PADDED = 0x08,
665 /**
666 * The PRIORITY flag.
667 */
668 NGHTTP2_FLAG_PRIORITY = 0x20
669 } nghttp2_flag;
670
671 /**
672 * @enum
673 * The SETTINGS ID.
674 */
675 typedef enum {
676 /**
677 * SETTINGS_HEADER_TABLE_SIZE
678 */
679 NGHTTP2_SETTINGS_HEADER_TABLE_SIZE = 0x01,
680 /**
681 * SETTINGS_ENABLE_PUSH
682 */
683 NGHTTP2_SETTINGS_ENABLE_PUSH = 0x02,
684 /**
685 * SETTINGS_MAX_CONCURRENT_STREAMS
686 */
687 NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS = 0x03,
688 /**
689 * SETTINGS_INITIAL_WINDOW_SIZE
690 */
691 NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE = 0x04,
692 /**
693 * SETTINGS_MAX_FRAME_SIZE
694 */
695 NGHTTP2_SETTINGS_MAX_FRAME_SIZE = 0x05,
696 /**
697 * SETTINGS_MAX_HEADER_LIST_SIZE
698 */
699 NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE = 0x06,
700 /**
701 * SETTINGS_ENABLE_CONNECT_PROTOCOL
702 * (`RFC 8441 <https://tools.ietf.org/html/rfc8441>`_)
703 */
704 NGHTTP2_SETTINGS_ENABLE_CONNECT_PROTOCOL = 0x08
705 } nghttp2_settings_id;
706 /* Note: If we add SETTINGS, update the capacity of
707 NGHTTP2_INBOUND_NUM_IV as well */
708
709 /**
710 * @macro
711 *
712 * .. warning::
713 *
714 * Deprecated. The initial max concurrent streams is 0xffffffffu.
715 *
716 * Default maximum number of incoming concurrent streams. Use
717 * `nghttp2_submit_settings()` with
718 * :enum:`nghttp2_settings_id.NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS`
719 * to change the maximum number of incoming concurrent streams.
720 *
721 * .. note::
722 *
723 * The maximum number of outgoing concurrent streams is 100 by
724 * default.
725 */
726 #define NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS ((1U << 31) - 1)
727
728 /**
729 * @enum
730 * The status codes for the RST_STREAM and GOAWAY frames.
731 */
732 typedef enum {
733 /**
734 * No errors.
735 */
736 NGHTTP2_NO_ERROR = 0x00,
737 /**
738 * PROTOCOL_ERROR
739 */
740 NGHTTP2_PROTOCOL_ERROR = 0x01,
741 /**
742 * INTERNAL_ERROR
743 */
744 NGHTTP2_INTERNAL_ERROR = 0x02,
745 /**
746 * FLOW_CONTROL_ERROR
747 */
748 NGHTTP2_FLOW_CONTROL_ERROR = 0x03,
749 /**
750 * SETTINGS_TIMEOUT
751 */
752 NGHTTP2_SETTINGS_TIMEOUT = 0x04,
753 /**
754 * STREAM_CLOSED
755 */
756 NGHTTP2_STREAM_CLOSED = 0x05,
757 /**
758 * FRAME_SIZE_ERROR
759 */
760 NGHTTP2_FRAME_SIZE_ERROR = 0x06,
761 /**
762 * REFUSED_STREAM
763 */
764 NGHTTP2_REFUSED_STREAM = 0x07,
765 /**
766 * CANCEL
767 */
768 NGHTTP2_CANCEL = 0x08,
769 /**
770 * COMPRESSION_ERROR
771 */
772 NGHTTP2_COMPRESSION_ERROR = 0x09,
773 /**
774 * CONNECT_ERROR
775 */
776 NGHTTP2_CONNECT_ERROR = 0x0a,
777 /**
778 * ENHANCE_YOUR_CALM
779 */
780 NGHTTP2_ENHANCE_YOUR_CALM = 0x0b,
781 /**
782 * INADEQUATE_SECURITY
783 */
784 NGHTTP2_INADEQUATE_SECURITY = 0x0c,
785 /**
786 * HTTP_1_1_REQUIRED
787 */
788 NGHTTP2_HTTP_1_1_REQUIRED = 0x0d
789 } nghttp2_error_code;
790
791 /**
792 * @struct
793 * The frame header.
794 */
795 typedef struct {
796 /**
797 * The length field of this frame, excluding frame header.
798 */
799 size_t length;
800 /**
801 * The stream identifier (aka, stream ID)
802 */
803 int32_t stream_id;
804 /**
805 * The type of this frame. See `nghttp2_frame_type`.
806 */
807 uint8_t type;
808 /**
809 * The flags.
810 */
811 uint8_t flags;
812 /**
813 * Reserved bit in frame header. Currently, this is always set to 0
814 * and application should not expect something useful in here.
815 */
816 uint8_t reserved;
817 } nghttp2_frame_hd;
818
819 /**
820 * @union
821 *
822 * This union represents the some kind of data source passed to
823 * :type:`nghttp2_data_source_read_callback`.
824 */
825 typedef union {
826 /**
827 * The integer field, suitable for a file descriptor.
828 */
829 int fd;
830 /**
831 * The pointer to an arbitrary object.
832 */
833 void *ptr;
834 } nghttp2_data_source;
835
836 /**
837 * @enum
838 *
839 * The flags used to set in |data_flags| output parameter in
840 * :type:`nghttp2_data_source_read_callback`.
841 */
842 typedef enum {
843 /**
844 * No flag set.
845 */
846 NGHTTP2_DATA_FLAG_NONE = 0,
847 /**
848 * Indicates EOF was sensed.
849 */
850 NGHTTP2_DATA_FLAG_EOF = 0x01,
851 /**
852 * Indicates that END_STREAM flag must not be set even if
853 * NGHTTP2_DATA_FLAG_EOF is set. Usually this flag is used to send
854 * trailer fields with `nghttp2_submit_request()` or
855 * `nghttp2_submit_response()`.
856 */
857 NGHTTP2_DATA_FLAG_NO_END_STREAM = 0x02,
858 /**
859 * Indicates that application will send complete DATA frame in
860 * :type:`nghttp2_send_data_callback`.
861 */
862 NGHTTP2_DATA_FLAG_NO_COPY = 0x04
863 } nghttp2_data_flag;
864
865 /**
866 * @functypedef
867 *
868 * Custom memory allocator to replace malloc(). The |mem_user_data|
869 * is the mem_user_data member of :type:`nghttp2_mem` structure.
870 */
871 typedef void *(*nghttp2_malloc)(size_t size, void *mem_user_data);
872
873 /**
874 * @functypedef
875 *
876 * Custom memory allocator to replace free(). The |mem_user_data| is
877 * the mem_user_data member of :type:`nghttp2_mem` structure.
878 */
879 typedef void (*nghttp2_free)(void *ptr, void *mem_user_data);
880
881 /**
882 * @functypedef
883 *
884 * Custom memory allocator to replace calloc(). The |mem_user_data|
885 * is the mem_user_data member of :type:`nghttp2_mem` structure.
886 */
887 typedef void *(*nghttp2_calloc)(size_t nmemb, size_t size, void *mem_user_data);
888
889 /**
890 * @functypedef
891 *
892 * Custom memory allocator to replace realloc(). The |mem_user_data|
893 * is the mem_user_data member of :type:`nghttp2_mem` structure.
894 */
895 typedef void *(*nghttp2_realloc)(void *ptr, size_t size, void *mem_user_data);
896
897 typedef struct {
898 /**
899 * An arbitrary user supplied data. This is passed to each
900 * allocator function.
901 */
902 void *mem_user_data;
903 /**
904 * Custom allocator function to replace malloc().
905 */
906 nghttp2_malloc malloc;
907 /**
908 * Custom allocator function to replace free().
909 */
910 nghttp2_free free;
911 /**
912 * Custom allocator function to replace calloc().
913 */
914 nghttp2_calloc calloc;
915 /**
916 * Custom allocator function to replace realloc().
917 */
918 nghttp2_realloc realloc;
919 } nghttp2_mem;
920
921 /**
922 * @struct
923 *
924 * The DATA frame. The received data is delivered via
925 * :type:`nghttp2_on_data_chunk_recv_callback`.
926 */
927 typedef struct {
928 nghttp2_frame_hd hd;
929 /**
930 * The length of the padding in this frame. This includes PAD_HIGH
931 * and PAD_LOW.
932 */
933 size_t padlen;
934 } nghttp2_data;
935
936 /**
937 * @enum
938 *
939 * The category of HEADERS, which indicates the role of the frame. In
940 * HTTP/2 spec, request, response, push response and other arbitrary
941 * headers (e.g., trailer fields) are all called just HEADERS. To
942 * give the application the role of incoming HEADERS frame, we define
943 * several categories.
944 */
945 typedef enum {
946 /**
947 * The HEADERS frame is opening new stream, which is analogous to
948 * SYN_STREAM in SPDY.
949 */
950 NGHTTP2_HCAT_REQUEST = 0,
951 /**
952 * The HEADERS frame is the first response headers, which is
953 * analogous to SYN_REPLY in SPDY.
954 */
955 NGHTTP2_HCAT_RESPONSE = 1,
956 /**
957 * The HEADERS frame is the first headers sent against reserved
958 * stream.
959 */
960 NGHTTP2_HCAT_PUSH_RESPONSE = 2,
961 /**
962 * The HEADERS frame which does not apply for the above categories,
963 * which is analogous to HEADERS in SPDY. If non-final response
964 * (e.g., status 1xx) is used, final response HEADERS frame will be
965 * categorized here.
966 */
967 NGHTTP2_HCAT_HEADERS = 3
968 } nghttp2_headers_category;
969
970 /**
971 * @struct
972 *
973 * The structure to specify stream dependency.
974 */
975 typedef struct {
976 /**
977 * The stream ID of the stream to depend on. Specifying 0 makes
978 * stream not depend any other stream.
979 */
980 int32_t stream_id;
981 /**
982 * The weight of this dependency.
983 */
984 int32_t weight;
985 /**
986 * nonzero means exclusive dependency
987 */
988 uint8_t exclusive;
989 } nghttp2_priority_spec;
990
991 /**
992 * @struct
993 *
994 * The HEADERS frame. It has the following members:
995 */
996 typedef struct {
997 /**
998 * The frame header.
999 */
1000 nghttp2_frame_hd hd;
1001 /**
1002 * The length of the padding in this frame. This includes PAD_HIGH
1003 * and PAD_LOW.
1004 */
1005 size_t padlen;
1006 /**
1007 * The priority specification
1008 */
1009 nghttp2_priority_spec pri_spec;
1010 /**
1011 * The name/value pairs.
1012 */
1013 nghttp2_nv *nva;
1014 /**
1015 * The number of name/value pairs in |nva|.
1016 */
1017 size_t nvlen;
1018 /**
1019 * The category of this HEADERS frame.
1020 */
1021 nghttp2_headers_category cat;
1022 } nghttp2_headers;
1023
1024 /**
1025 * @struct
1026 *
1027 * The PRIORITY frame. It has the following members:
1028 */
1029 typedef struct {
1030 /**
1031 * The frame header.
1032 */
1033 nghttp2_frame_hd hd;
1034 /**
1035 * The priority specification.
1036 */
1037 nghttp2_priority_spec pri_spec;
1038 } nghttp2_priority;
1039
1040 /**
1041 * @struct
1042 *
1043 * The RST_STREAM frame. It has the following members:
1044 */
1045 typedef struct {
1046 /**
1047 * The frame header.
1048 */
1049 nghttp2_frame_hd hd;
1050 /**
1051 * The error code. See :type:`nghttp2_error_code`.
1052 */
1053 uint32_t error_code;
1054 } nghttp2_rst_stream;
1055
1056 /**
1057 * @struct
1058 *
1059 * The SETTINGS ID/Value pair. It has the following members:
1060 */
1061 typedef struct {
1062 /**
1063 * The SETTINGS ID. See :type:`nghttp2_settings_id`.
1064 */
1065 int32_t settings_id;
1066 /**
1067 * The value of this entry.
1068 */
1069 uint32_t value;
1070 } nghttp2_settings_entry;
1071
1072 /**
1073 * @struct
1074 *
1075 * The SETTINGS frame. It has the following members:
1076 */
1077 typedef struct {
1078 /**
1079 * The frame header.
1080 */
1081 nghttp2_frame_hd hd;
1082 /**
1083 * The number of SETTINGS ID/Value pairs in |iv|.
1084 */
1085 size_t niv;
1086 /**
1087 * The pointer to the array of SETTINGS ID/Value pair.
1088 */
1089 nghttp2_settings_entry *iv;
1090 } nghttp2_settings;
1091
1092 /**
1093 * @struct
1094 *
1095 * The PUSH_PROMISE frame. It has the following members:
1096 */
1097 typedef struct {
1098 /**
1099 * The frame header.
1100 */
1101 nghttp2_frame_hd hd;
1102 /**
1103 * The length of the padding in this frame. This includes PAD_HIGH
1104 * and PAD_LOW.
1105 */
1106 size_t padlen;
1107 /**
1108 * The name/value pairs.
1109 */
1110 nghttp2_nv *nva;
1111 /**
1112 * The number of name/value pairs in |nva|.
1113 */
1114 size_t nvlen;
1115 /**
1116 * The promised stream ID
1117 */
1118 int32_t promised_stream_id;
1119 /**
1120 * Reserved bit. Currently this is always set to 0 and application
1121 * should not expect something useful in here.
1122 */
1123 uint8_t reserved;
1124 } nghttp2_push_promise;
1125
1126 /**
1127 * @struct
1128 *
1129 * The PING frame. It has the following members:
1130 */
1131 typedef struct {
1132 /**
1133 * The frame header.
1134 */
1135 nghttp2_frame_hd hd;
1136 /**
1137 * The opaque data
1138 */
1139 uint8_t opaque_data[8];
1140 } nghttp2_ping;
1141
1142 /**
1143 * @struct
1144 *
1145 * The GOAWAY frame. It has the following members:
1146 */
1147 typedef struct {
1148 /**
1149 * The frame header.
1150 */
1151 nghttp2_frame_hd hd;
1152 /**
1153 * The last stream stream ID.
1154 */
1155 int32_t last_stream_id;
1156 /**
1157 * The error code. See :type:`nghttp2_error_code`.
1158 */
1159 uint32_t error_code;
1160 /**
1161 * The additional debug data
1162 */
1163 uint8_t *opaque_data;
1164 /**
1165 * The length of |opaque_data| member.
1166 */
1167 size_t opaque_data_len;
1168 /**
1169 * Reserved bit. Currently this is always set to 0 and application
1170 * should not expect something useful in here.
1171 */
1172 uint8_t reserved;
1173 } nghttp2_goaway;
1174
1175 /**
1176 * @struct
1177 *
1178 * The WINDOW_UPDATE frame. It has the following members:
1179 */
1180 typedef struct {
1181 /**
1182 * The frame header.
1183 */
1184 nghttp2_frame_hd hd;
1185 /**
1186 * The window size increment.
1187 */
1188 int32_t window_size_increment;
1189 /**
1190 * Reserved bit. Currently this is always set to 0 and application
1191 * should not expect something useful in here.
1192 */
1193 uint8_t reserved;
1194 } nghttp2_window_update;
1195
1196 /**
1197 * @struct
1198 *
1199 * The extension frame. It has following members:
1200 */
1201 typedef struct {
1202 /**
1203 * The frame header.
1204 */
1205 nghttp2_frame_hd hd;
1206 /**
1207 * The pointer to extension payload. The exact pointer type is
1208 * determined by hd.type.
1209 *
1210 * Currently, no extension is supported. This is a place holder for
1211 * the future extensions.
1212 */
1213 void *payload;
1214 } nghttp2_extension;
1215
1216 /**
1217 * @union
1218 *
1219 * This union includes all frames to pass them to various function
1220 * calls as nghttp2_frame type. The CONTINUATION frame is omitted
1221 * from here because the library deals with it internally.
1222 */
1223 typedef union {
1224 /**
1225 * The frame header, which is convenient to inspect frame header.
1226 */
1227 nghttp2_frame_hd hd;
1228 /**
1229 * The DATA frame.
1230 */
1231 nghttp2_data data;
1232 /**
1233 * The HEADERS frame.
1234 */
1235 nghttp2_headers headers;
1236 /**
1237 * The PRIORITY frame.
1238 */
1239 nghttp2_priority priority;
1240 /**
1241 * The RST_STREAM frame.
1242 */
1243 nghttp2_rst_stream rst_stream;
1244 /**
1245 * The SETTINGS frame.
1246 */
1247 nghttp2_settings settings;
1248 /**
1249 * The PUSH_PROMISE frame.
1250 */
1251 nghttp2_push_promise push_promise;
1252 /**
1253 * The PING frame.
1254 */
1255 nghttp2_ping ping;
1256 /**
1257 * The GOAWAY frame.
1258 */
1259 nghttp2_goaway goaway;
1260 /**
1261 * The WINDOW_UPDATE frame.
1262 */
1263 nghttp2_window_update window_update;
1264 /**
1265 * The extension frame.
1266 */
1267 nghttp2_extension ext;
1268 } nghttp2_frame;
1269
1270 /* HPACK API */
1271
1272 struct nghttp2_hd_deflater;
1273
1274 /**
1275 * @struct
1276 *
1277 * HPACK deflater object.
1278 */
1279 typedef struct nghttp2_hd_deflater nghttp2_hd_deflater;
1280
1281 /**
1282 * @function
1283 *
1284 * Initializes |*deflater_ptr| for deflating name/values pairs.
1285 *
1286 * The |max_deflate_dynamic_table_size| is the upper bound of header
1287 * table size the deflater will use.
1288 *
1289 * If this function fails, |*deflater_ptr| is left untouched.
1290 *
1291 * This function returns 0 if it succeeds, or one of the following
1292 * negative error codes:
1293 *
1294 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
1295 * Out of memory.
1296 */
1297 NGHTTP2_EXTERN int
1298 nghttp2_hd_deflate_new(nghttp2_hd_deflater **deflater_ptr,
1299 size_t max_deflate_dynamic_table_size);
1300
1301 /**
1302 * @function
1303 *
1304 * Like `nghttp2_hd_deflate_new()`, but with additional custom memory
1305 * allocator specified in the |mem|.
1306 *
1307 * The |mem| can be ``NULL`` and the call is equivalent to
1308 * `nghttp2_hd_deflate_new()`.
1309 *
1310 * This function does not take ownership |mem|. The application is
1311 * responsible for freeing |mem|.
1312 *
1313 * The library code does not refer to |mem| pointer after this
1314 * function returns, so the application can safely free it.
1315 */
1316 NGHTTP2_EXTERN int
1317 nghttp2_hd_deflate_new2(nghttp2_hd_deflater **deflater_ptr,
1318 size_t max_deflate_dynamic_table_size,
1319 nghttp2_mem *mem);
1320
1321 /**
1322 * @function
1323 *
1324 * Deallocates any resources allocated for |deflater|.
1325 */
1326 NGHTTP2_EXTERN void nghttp2_hd_deflate_del(nghttp2_hd_deflater *deflater);
1327
1328 /**
1329 * @function
1330 *
1331 * Changes header table size of the |deflater| to
1332 * |settings_max_dynamic_table_size| bytes. This may trigger eviction
1333 * in the dynamic table.
1334 *
1335 * The |settings_max_dynamic_table_size| should be the value received
1336 * in SETTINGS_HEADER_TABLE_SIZE.
1337 *
1338 * The deflater never uses more memory than
1339 * ``max_deflate_dynamic_table_size`` bytes specified in
1340 * `nghttp2_hd_deflate_new()`. Therefore, if
1341 * |settings_max_dynamic_table_size| >
1342 * ``max_deflate_dynamic_table_size``, resulting maximum table size
1343 * becomes ``max_deflate_dynamic_table_size``.
1344 *
1345 * This function returns 0 if it succeeds, or one of the following
1346 * negative error codes:
1347 *
1348 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
1349 * Out of memory.
1350 */
1351 NGHTTP2_EXTERN int
1352 nghttp2_hd_deflate_change_table_size(nghttp2_hd_deflater *deflater,
1353 size_t settings_max_dynamic_table_size);
1354
1355 /**
1356 * @function
1357 *
1358 * Deflates the |nva|, which has the |nvlen| name/value pairs, into
1359 * the |buf| of length |buflen|.
1360 *
1361 * If |buf| is not large enough to store the deflated header block,
1362 * this function fails with
1363 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`. The caller
1364 * should use `nghttp2_hd_deflate_bound()` to know the upper bound of
1365 * buffer size required to deflate given header name/value pairs.
1366 *
1367 * Once this function fails, subsequent call of this function always
1368 * returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`.
1369 *
1370 * After this function returns, it is safe to delete the |nva|.
1371 *
1372 * This function returns the number of bytes written to |buf| if it
1373 * succeeds, or one of the following negative error codes:
1374 *
1375 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
1376 * Out of memory.
1377 * :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
1378 * Deflation process has failed.
1379 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
1380 * The provided |buflen| size is too small to hold the output.
1381 */
1382 NGHTTP2_EXTERN ssize_t nghttp2_hd_deflate_hd(nghttp2_hd_deflater *deflater,
1383 uint8_t *buf, size_t buflen,
1384 const nghttp2_nv *nva,
1385 size_t nvlen);
1386
1387 /**
1388 * @function
1389 *
1390 * Deflates the |nva|, which has the |nvlen| name/value pairs, into
1391 * the |veclen| size of buf vector |vec|. The each size of buffer
1392 * must be set in len field of :type:`nghttp2_vec`. If and only if
1393 * one chunk is filled up completely, next chunk will be used. If
1394 * |vec| is not large enough to store the deflated header block, this
1395 * function fails with
1396 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`. The caller
1397 * should use `nghttp2_hd_deflate_bound()` to know the upper bound of
1398 * buffer size required to deflate given header name/value pairs.
1399 *
1400 * Once this function fails, subsequent call of this function always
1401 * returns :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`.
1402 *
1403 * After this function returns, it is safe to delete the |nva|.
1404 *
1405 * This function returns the number of bytes written to |vec| if it
1406 * succeeds, or one of the following negative error codes:
1407 *
1408 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
1409 * Out of memory.
1410 * :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
1411 * Deflation process has failed.
1412 * :enum:`nghttp2_error.NGHTTP2_ERR_INSUFF_BUFSIZE`
1413 * The provided |buflen| size is too small to hold the output.
1414 */
1415 NGHTTP2_EXTERN ssize_t nghttp2_hd_deflate_hd_vec(nghttp2_hd_deflater *deflater,
1416 const nghttp2_vec *vec,
1417 size_t veclen,
1418 const nghttp2_nv *nva,
1419 size_t nvlen);
1420
1421 /**
1422 * @function
1423 *
1424 * Returns an upper bound on the compressed size after deflation of
1425 * |nva| of length |nvlen|.
1426 */
1427 NGHTTP2_EXTERN size_t nghttp2_hd_deflate_bound(nghttp2_hd_deflater *deflater,
1428 const nghttp2_nv *nva,
1429 size_t nvlen);
1430
1431 /**
1432 * @function
1433 *
1434 * Returns the number of entries that header table of |deflater|
1435 * contains. This is the sum of the number of static table and
1436 * dynamic table, so the return value is at least 61.
1437 */
1438 NGHTTP2_EXTERN
1439 size_t nghttp2_hd_deflate_get_num_table_entries(nghttp2_hd_deflater *deflater);
1440
1441 /**
1442 * @function
1443 *
1444 * Returns the table entry denoted by |idx| from header table of
1445 * |deflater|. The |idx| is 1-based, and idx=1 returns first entry of
1446 * static table. idx=62 returns first entry of dynamic table if it
1447 * exists. Specifying idx=0 is error, and this function returns NULL.
1448 * If |idx| is strictly greater than the number of entries the tables
1449 * contain, this function returns NULL.
1450 */
1451 NGHTTP2_EXTERN
1452 const nghttp2_nv *
1453 nghttp2_hd_deflate_get_table_entry(nghttp2_hd_deflater *deflater, size_t idx);
1454
1455 /**
1456 * @function
1457 *
1458 * Returns the used dynamic table size, including the overhead 32
1459 * bytes per entry described in RFC 7541.
1460 */
1461 NGHTTP2_EXTERN
1462 size_t nghttp2_hd_deflate_get_dynamic_table_size(nghttp2_hd_deflater *deflater);
1463
1464 /**
1465 * @function
1466 *
1467 * Returns the maximum dynamic table size.
1468 */
1469 NGHTTP2_EXTERN
1470 size_t
1471 nghttp2_hd_deflate_get_max_dynamic_table_size(nghttp2_hd_deflater *deflater);
1472
1473 struct nghttp2_hd_inflater;
1474
1475 /**
1476 * @struct
1477 *
1478 * HPACK inflater object.
1479 */
1480 typedef struct nghttp2_hd_inflater nghttp2_hd_inflater;
1481
1482 /**
1483 * @function
1484 *
1485 * Initializes |*inflater_ptr| for inflating name/values pairs.
1486 *
1487 * If this function fails, |*inflater_ptr| is left untouched.
1488 *
1489 * This function returns 0 if it succeeds, or one of the following
1490 * negative error codes:
1491 *
1492 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
1493 * Out of memory.
1494 */
1495 NGHTTP2_EXTERN int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr);
1496
1497 /**
1498 * @function
1499 *
1500 * Like `nghttp2_hd_inflate_new()`, but with additional custom memory
1501 * allocator specified in the |mem|.
1502 *
1503 * The |mem| can be ``NULL`` and the call is equivalent to
1504 * `nghttp2_hd_inflate_new()`.
1505 *
1506 * This function does not take ownership |mem|. The application is
1507 * responsible for freeing |mem|.
1508 *
1509 * The library code does not refer to |mem| pointer after this
1510 * function returns, so the application can safely free it.
1511 */
1512 NGHTTP2_EXTERN int nghttp2_hd_inflate_new2(nghttp2_hd_inflater **inflater_ptr,
1513 nghttp2_mem *mem);
1514
1515 /**
1516 * @function
1517 *
1518 * Deallocates any resources allocated for |inflater|.
1519 */
1520 NGHTTP2_EXTERN void nghttp2_hd_inflate_del(nghttp2_hd_inflater *inflater);
1521
1522 /**
1523 * @function
1524 *
1525 * Changes header table size in the |inflater|. This may trigger
1526 * eviction in the dynamic table.
1527 *
1528 * The |settings_max_dynamic_table_size| should be the value
1529 * transmitted in SETTINGS_HEADER_TABLE_SIZE.
1530 *
1531 * This function must not be called while header block is being
1532 * inflated. In other words, this function must be called after
1533 * initialization of |inflater|, but before calling
1534 * `nghttp2_hd_inflate_hd2()`, or after
1535 * `nghttp2_hd_inflate_end_headers()`. Otherwise,
1536 * `NGHTTP2_ERR_INVALID_STATE` was returned.
1537 *
1538 * This function returns 0 if it succeeds, or one of the following
1539 * negative error codes:
1540 *
1541 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
1542 * Out of memory.
1543 * :enum:`nghttp2_error.NGHTTP2_ERR_INVALID_STATE`
1544 * The function is called while header block is being inflated.
1545 * Probably, application missed to call
1546 * `nghttp2_hd_inflate_end_headers()`.
1547 */
1548 NGHTTP2_EXTERN int
1549 nghttp2_hd_inflate_change_table_size(nghttp2_hd_inflater *inflater,
1550 size_t settings_max_dynamic_table_size);
1551
1552 /**
1553 * @enum
1554 *
1555 * The flags for header inflation.
1556 */
1557 typedef enum {
1558 /**
1559 * No flag set.
1560 */
1561 NGHTTP2_HD_INFLATE_NONE = 0,
1562 /**
1563 * Indicates all headers were inflated.
1564 */
1565 NGHTTP2_HD_INFLATE_FINAL = 0x01,
1566 /**
1567 * Indicates a header was emitted.
1568 */
1569 NGHTTP2_HD_INFLATE_EMIT = 0x02
1570 } nghttp2_hd_inflate_flag;
1571
1572 /**
1573 * @function
1574 *
1575 * .. warning::
1576 *
1577 * Deprecated. Use `nghttp2_hd_inflate_hd2()` instead.
1578 *
1579 * Inflates name/value block stored in |in| with length |inlen|. This
1580 * function performs decompression. For each successful emission of
1581 * header name/value pair,
1582 * :enum:`nghttp2_hd_inflate_flag.NGHTTP2_HD_INFLATE_EMIT` is set in
1583 * |*inflate_flags| and name/value pair is assigned to the |nv_out|
1584 * and the function returns. The caller must not free the members of
1585 * |nv_out|.
1586 *
1587 * The |nv_out| may include pointers to the memory region in the |in|.
1588 * The caller must retain the |in| while the |nv_out| is used.
1589 *
1590 * The application should call this function repeatedly until the
1591 * ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
1592 * return value is non-negative. This means the all input values are
1593 * processed successfully. Then the application must call
1594 * `nghttp2_hd_inflate_end_headers()` to prepare for the next header
1595 * block input.
1596 *
1597 * The caller can feed complete compressed header block. It also can
1598 * feed it in several chunks. The caller must set |in_final| to
1599 * nonzero if the given input is the last block of the compressed
1600 * header.
1601 *
1602 * This function returns the number of bytes processed if it succeeds,
1603 * or one of the following negative error codes:
1604 *
1605 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
1606 * Out of memory.
1607 * :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
1608 * Inflation process has failed.
1609 * :enum:`nghttp2_error.NGHTTP2_ERR_BUFFER_ERROR`
1610 * The header field name or value is too large.
1611 *
1612 * Example follows::
1613 *
1614 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
1615 * uint8_t *in, size_t inlen, int final)
1616 * {
1617 * ssize_t rv;
1618 *
1619 * for(;;) {
1620 * nghttp2_nv nv;
1621 * int inflate_flags = 0;
1622 *
1623 * rv = nghttp2_hd_inflate_hd(hd_inflater, &nv, &inflate_flags,
1624 * in, inlen, final);
1625 *
1626 * if(rv < 0) {
1627 * fprintf(stderr, "inflate failed with error code %zd", rv);
1628 * return -1;
1629 * }
1630 *
1631 * in += rv;
1632 * inlen -= rv;
1633 *
1634 * if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
1635 * fwrite(nv.name, nv.namelen, 1, stderr);
1636 * fprintf(stderr, ": ");
1637 * fwrite(nv.value, nv.valuelen, 1, stderr);
1638 * fprintf(stderr, "\n");
1639 * }
1640 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
1641 * nghttp2_hd_inflate_end_headers(hd_inflater);
1642 * break;
1643 * }
1644 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
1645 * inlen == 0) {
1646 * break;
1647 * }
1648 * }
1649 *
1650 * return 0;
1651 * }
1652 *
1653 */
1654 NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd(nghttp2_hd_inflater *inflater,
1655 nghttp2_nv *nv_out,
1656 int *inflate_flags, uint8_t *in,
1657 size_t inlen, int in_final);
1658
1659 /**
1660 * @function
1661 *
1662 * Inflates name/value block stored in |in| with length |inlen|. This
1663 * function performs decompression. For each successful emission of
1664 * header name/value pair,
1665 * :enum:`nghttp2_hd_inflate_flag.NGHTTP2_HD_INFLATE_EMIT` is set in
1666 * |*inflate_flags| and name/value pair is assigned to the |nv_out|
1667 * and the function returns. The caller must not free the members of
1668 * |nv_out|.
1669 *
1670 * The |nv_out| may include pointers to the memory region in the |in|.
1671 * The caller must retain the |in| while the |nv_out| is used.
1672 *
1673 * The application should call this function repeatedly until the
1674 * ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
1675 * return value is non-negative. If that happens, all given input
1676 * data (|inlen| bytes) are processed successfully. Then the
1677 * application must call `nghttp2_hd_inflate_end_headers()` to prepare
1678 * for the next header block input.
1679 *
1680 * In other words, if |in_final| is nonzero, and this function returns
1681 * |inlen|, you can assert that
1682 * :enum:`nghttp2_hd_inflate_final.NGHTTP2_HD_INFLATE_FINAL` is set in
1683 * |*inflate_flags|.
1684 *
1685 * The caller can feed complete compressed header block. It also can
1686 * feed it in several chunks. The caller must set |in_final| to
1687 * nonzero if the given input is the last block of the compressed
1688 * header.
1689 *
1690 * This function returns the number of bytes processed if it succeeds,
1691 * or one of the following negative error codes:
1692 *
1693 * :enum:`nghttp2_error.NGHTTP2_ERR_NOMEM`
1694 * Out of memory.
1695 * :enum:`nghttp2_error.NGHTTP2_ERR_HEADER_COMP`
1696 * Inflation process has failed.
1697 * :enum:`nghttp2_error.NGHTTP2_ERR_BUFFER_ERROR`
1698 * The header field name or value is too large.
1699 *
1700 * Example follows::
1701 *
1702 * int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
1703 * uint8_t *in, size_t inlen, int final)
1704 * {
1705 * ssize_t rv;
1706 *
1707 * for(;;) {
1708 * nghttp2_nv nv;
1709 * int inflate_flags = 0;
1710 *
1711 * rv = nghttp2_hd_inflate_hd2(hd_inflater, &nv, &inflate_flags,
1712 * in, inlen, final);
1713 *
1714 * if(rv < 0) {
1715 * fprintf(stderr, "inflate failed with error code %zd", rv);
1716 * return -1;
1717 * }
1718 *
1719 * in += rv;
1720 * inlen -= rv;
1721 *
1722 * if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
1723 * fwrite(nv.name, nv.namelen, 1, stderr);
1724 * fprintf(stderr, ": ");
1725 * fwrite(nv.value, nv.valuelen, 1, stderr);
1726 * fprintf(stderr, "\n");
1727 * }
1728 * if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
1729 * nghttp2_hd_inflate_end_headers(hd_inflater);
1730 * break;
1731 * }
1732 * if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
1733 * inlen == 0) {
1734 * break;
1735 * }
1736 * }
1737 *
1738 * return 0;
1739 * }
1740 *
1741 */
1742 NGHTTP2_EXTERN ssize_t nghttp2_hd_inflate_hd2(nghttp2_hd_inflater *inflater,
1743 nghttp2_nv *nv_out,
1744 int *inflate_flags,
1745 const uint8_t *in, size_t inlen,
1746 int in_final);
1747
1748 /**
1749 * @function
1750 *
1751 * Signals the end of decompression for one header block.
1752 *
1753 * This function returns 0 if it succeeds. Currently this function
1754 * always succeeds.
1755 */
1756 NGHTTP2_EXTERN int
1757 nghttp2_hd_inflate_end_headers(nghttp2_hd_inflater *inflater);
1758
1759 /**
1760 * @function
1761 *
1762 * Returns the number of entries that header table of |inflater|
1763 * contains. This is the sum of the number of static table and
1764 * dynamic table, so the return value is at least 61.
1765 */
1766 NGHTTP2_EXTERN
1767 size_t nghttp2_hd_inflate_get_num_table_entries(nghttp2_hd_inflater *inflater);
1768
1769 /**
1770 * @function
1771 *
1772 * Returns the table entry denoted by |idx| from header table of
1773 * |inflater|. The |idx| is 1-based, and idx=1 returns first entry of
1774 * static table. idx=62 returns first entry of dynamic table if it
1775 * exists. Specifying idx=0 is error, and this function returns NULL.
1776 * If |idx| is strictly greater than the number of entries the tables
1777 * contain, this function returns NULL.
1778 */
1779 NGHTTP2_EXTERN
1780 const nghttp2_nv *
1781 nghttp2_hd_inflate_get_table_entry(nghttp2_hd_inflater *inflater, size_t idx);
1782
1783 /**
1784 * @function
1785 *
1786 * Returns the used dynamic table size, including the overhead 32
1787 * bytes per entry described in RFC 7541.
1788 */
1789 NGHTTP2_EXTERN
1790 size_t nghttp2_hd_inflate_get_dynamic_table_size(nghttp2_hd_inflater *inflater);
1791
1792 /**
1793 * @function
1794 *
1795 * Returns the maximum dynamic table size.
1796 */
1797 NGHTTP2_EXTERN
1798 size_t
1799 nghttp2_hd_inflate_get_max_dynamic_table_size(nghttp2_hd_inflater *inflater);
1800
1801 /**
1802 * @enum
1803 *
1804 * State of stream as described in RFC 7540.
1805 */
1806 typedef enum {
1807 /**
1808 * idle state.
1809 */
1810 NGHTTP2_STREAM_STATE_IDLE = 1,
1811 /**
1812 * open state.
1813 */
1814 NGHTTP2_STREAM_STATE_OPEN,
1815 /**
1816 * reserved (local) state.
1817 */
1818 NGHTTP2_STREAM_STATE_RESERVED_LOCAL,
1819 /**
1820 * reserved (remote) state.
1821 */
1822 NGHTTP2_STREAM_STATE_RESERVED_REMOTE,
1823 /**
1824 * half closed (local) state.
1825 */
1826 NGHTTP2_STREAM_STATE_HALF_CLOSED_LOCAL,
1827 /**
1828 * half closed (remote) state.
1829 */
1830 NGHTTP2_STREAM_STATE_HALF_CLOSED_REMOTE,
1831 /**
1832 * closed state.
1833 */
1834 NGHTTP2_STREAM_STATE_CLOSED
1835 } nghttp2_stream_proto_state;
1836
1837 /**
1838 * @functypedef
1839 *
1840 * Callback function invoked when the library outputs debug logging.
1841 * The function is called with arguments suitable for ``vfprintf(3)``
1842 *
1843 * The debug output is only enabled if the library is built with
1844 * ``DEBUGBUILD`` macro defined.
1845 */
1846 typedef void (*nghttp2_debug_vprintf_callback)(const char *format,
1847 va_list args);
1848
1849 /**
1850 * @function
1851 *
1852 * Sets a debug output callback called by the library when built with
1853 * ``DEBUGBUILD`` macro defined. If this option is not used, debug
1854 * log is written into standard error output.
1855 *
1856 * For builds without ``DEBUGBUILD`` macro defined, this function is
1857 * noop.
1858 *
1859 * Note that building with ``DEBUGBUILD`` may cause significant
1860 * performance penalty to libnghttp2 because of extra processing. It
1861 * should be used for debugging purpose only.
1862 *
1863 * .. Warning::
1864 *
1865 * Building with ``DEBUGBUILD`` may cause significant performance
1866 * penalty to libnghttp2 because of extra processing. It should be
1867 * used for debugging purpose only. We write this two times because
1868 * this is important.
1869 */
1870 NGHTTP2_EXTERN void nghttp2_set_debug_vprintf_callback(
1871 nghttp2_debug_vprintf_callback debug_vprintf_callback);
1872
1873 #ifdef __cplusplus
1874 }
1875 #endif
1876
1877 #endif /* NGHTTP2_H */
1878