diff options
Diffstat (limited to 'deps/nghttp3/lib/includes/nghttp3/nghttp3.h')
| -rw-r--r-- | deps/nghttp3/lib/includes/nghttp3/nghttp3.h | 1759 |
1 files changed, 1759 insertions, 0 deletions
diff --git a/deps/nghttp3/lib/includes/nghttp3/nghttp3.h b/deps/nghttp3/lib/includes/nghttp3/nghttp3.h new file mode 100644 index 0000000000..5c3a95c4c6 --- /dev/null +++ b/deps/nghttp3/lib/includes/nghttp3/nghttp3.h @@ -0,0 +1,1759 @@ +/* + * nghttp3 + * + * Copyright (c) 2018 nghttp3 contributors + * Copyright (c) 2017 ngtcp2 contributors + * Copyright (c) 2017 nghttp2 contributors + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files (the + * "Software"), to deal in the Software without restriction, including + * without limitation the rights to use, copy, modify, merge, publish, + * distribute, sublicense, and/or sell copies of the Software, and to + * permit persons to whom the Software is furnished to do so, subject to + * the following conditions: + * + * The above copyright notice and this permission notice shall be + * included in all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + */ +#ifndef NGHTTP3_H +#define NGHTTP3_H + +/* Define WIN32 when build target is Win32 API (borrowed from + libcurl) */ +#if (defined(_WIN32) || defined(__WIN32__)) && !defined(WIN32) +# define WIN32 +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +#include <stdlib.h> +#if defined(_MSC_VER) && (_MSC_VER < 1800) +/* MSVC < 2013 does not have inttypes.h because it is not C99 + compliant. See compiler macros and version number in + https://sourceforge.net/p/predef/wiki/Compilers/ */ +# include <stdint.h> +#else /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */ +# include <inttypes.h> +#endif /* !defined(_MSC_VER) || (_MSC_VER >= 1800) */ +#include <sys/types.h> +#include <stdarg.h> +#include <stddef.h> + +#include <nghttp3/version.h> + +#ifdef NGHTTP3_STATICLIB +# define NGHTTP3_EXTERN +#elif defined(WIN32) +# ifdef BUILDING_NGHTTP3 +# define NGHTTP3_EXTERN __declspec(dllexport) +# else /* !BUILDING_NGHTTP3 */ +# define NGHTTP3_EXTERN __declspec(dllimport) +# endif /* !BUILDING_NGHTTP3 */ +#else /* !defined(WIN32) */ +# ifdef BUILDING_NGHTTP3 +# define NGHTTP3_EXTERN __attribute__((visibility("default"))) +# else /* !BUILDING_NGHTTP3 */ +# define NGHTTP3_EXTERN +# endif /* !BUILDING_NGHTTP3 */ +#endif /* !defined(WIN32) */ + +typedef ptrdiff_t nghttp3_ssize; + +typedef enum { + NGHTTP3_ERR_INVALID_ARGUMENT = -101, + NGHTTP3_ERR_NOBUF = -102, + NGHTTP3_ERR_INVALID_STATE = -103, + NGHTTP3_ERR_WOULDBLOCK = -104, + NGHTTP3_ERR_STREAM_IN_USE = -105, + NGHTTP3_ERR_PUSH_ID_BLOCKED = -106, + NGHTTP3_ERR_MALFORMED_HTTP_HEADER = -107, + NGHTTP3_ERR_REMOVE_HTTP_HEADER = -108, + NGHTTP3_ERR_MALFORMED_HTTP_MESSAGING = -109, + NGHTTP3_ERR_TOO_LATE = -110, + NGHTTP3_ERR_QPACK_FATAL = -111, + NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE = -112, + NGHTTP3_ERR_IGNORE_STREAM = -113, + NGHTTP3_ERR_STREAM_NOT_FOUND = -114, + NGHTTP3_ERR_IGNORE_PUSH_PROMISE = -115, + NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED = -402, + NGHTTP3_ERR_QPACK_ENCODER_STREAM_ERROR = -403, + NGHTTP3_ERR_QPACK_DECODER_STREAM_ERROR = -404, + NGHTTP3_ERR_H3_FRAME_UNEXPECTED = -408, + NGHTTP3_ERR_H3_FRAME_ERROR = -409, + NGHTTP3_ERR_H3_MISSING_SETTINGS = -665, + NGHTTP3_ERR_H3_INTERNAL_ERROR = -667, + NGHTTP3_ERR_H3_CLOSED_CRITICAL_STREAM = -668, + NGHTTP3_ERR_H3_GENERAL_PROTOCOL_ERROR = -669, + NGHTTP3_ERR_H3_ID_ERROR = -670, + NGHTTP3_ERR_H3_SETTINGS_ERROR = -671, + NGHTTP3_ERR_H3_STREAM_CREATION_ERROR = -672, + NGHTTP3_ERR_FATAL = -900, + NGHTTP3_ERR_NOMEM = -901, + NGHTTP3_ERR_CALLBACK_FAILURE = -902 +} nghttp3_lib_error; + +#define NGHTTP3_H3_NO_ERROR 0x0100 +#define NGHTTP3_H3_GENERAL_PROTOCOL_ERROR 0x0101 +#define NGHTTP3_H3_INTERNAL_ERROR 0x0102 +#define NGHTTP3_H3_STREAM_CREATION_ERROR 0x0103 +#define NGHTTP3_H3_CLOSED_CRITICAL_STREAM 0x0104 +#define NGHTTP3_H3_FRAME_UNEXPECTED 0x0105 +#define NGHTTP3_H3_FRAME_ERROR 0x0106 +#define NGHTTP3_H3_EXCESSIVE_LOAD 0x0107 +#define NGHTTP3_H3_ID_ERROR 0x0108 +#define NGHTTP3_H3_SETTINGS_ERROR 0x0109 +#define NGHTTP3_H3_MISSING_SETTINGS 0x010a +#define NGHTTP3_H3_REQUEST_REJECTED 0x010b +#define NGHTTP3_H3_REQUEST_CANCELLED 0x010c +#define NGHTTP3_H3_REQUEST_INCOMPLETE 0x010d +#define NGHTTP3_H3_CONNECT_ERROR 0x010f +#define NGHTTP3_H3_VERSION_FALLBACK 0x0110 +#define NGHTTP3_QPACK_DECOMPRESSION_FAILED 0x0200 +#define NGHTTP3_QPACK_ENCODER_STREAM_ERROR 0x0201 +#define NGHTTP3_QPACK_DECODER_STREAM_ERROR 0x0202 + +/** + * @functypedef + * + * Custom memory allocator to replace malloc(). The |mem_user_data| + * is the mem_user_data member of :type:`nghttp3_mem` structure. + */ +typedef void *(*nghttp3_malloc)(size_t size, void *mem_user_data); + +/** + * @functypedef + * + * Custom memory allocator to replace free(). The |mem_user_data| is + * the mem_user_data member of :type:`nghttp3_mem` structure. + */ +typedef void (*nghttp3_free)(void *ptr, void *mem_user_data); + +/** + * @functypedef + * + * Custom memory allocator to replace calloc(). The |mem_user_data| + * is the mem_user_data member of :type:`nghttp3_mem` structure. + */ +typedef void *(*nghttp3_calloc)(size_t nmemb, size_t size, void *mem_user_data); + +/** + * @functypedef + * + * Custom memory allocator to replace realloc(). The |mem_user_data| + * is the mem_user_data member of :type:`nghttp3_mem` structure. + */ +typedef void *(*nghttp3_realloc)(void *ptr, size_t size, void *mem_user_data); + +/** + * @struct + * + * Custom memory allocator functions and user defined pointer. The + * |mem_user_data| member is passed to each allocator function. This + * can be used, for example, to achieve per-session memory pool. + * + * In the following example code, ``my_malloc``, ``my_free``, + * ``my_calloc`` and ``my_realloc`` are the replacement of the + * standard allocators ``malloc``, ``free``, ``calloc`` and + * ``realloc`` respectively:: + * + * void *my_malloc_cb(size_t size, void *mem_user_data) { + * return my_malloc(size); + * } + * + * void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); } + * + * void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) { + * return my_calloc(nmemb, size); + * } + * + * void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) { + * return my_realloc(ptr, size); + * } + * + * void conn_new() { + * nghttp3_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb, + * my_realloc_cb}; + * + * ... + * } + */ +typedef struct { + /** + * An arbitrary user supplied data. This is passed to each + * allocator function. + */ + void *mem_user_data; + /** + * Custom allocator function to replace malloc(). + */ + nghttp3_malloc malloc; + /** + * Custom allocator function to replace free(). + */ + nghttp3_free free; + /** + * Custom allocator function to replace calloc(). + */ + nghttp3_calloc calloc; + /** + * Custom allocator function to replace realloc(). + */ + nghttp3_realloc realloc; +} nghttp3_mem; + +/** + * @function + * + * `nghttp3_mem_default` returns the default memory allocator which + * uses malloc/calloc/realloc/free. + */ +NGHTTP3_EXTERN const nghttp3_mem *nghttp3_mem_default(void); + +/** + * @struct + * + * nghttp3_vec is struct iovec compatible structure to reference + * arbitrary array of bytes. + */ +typedef struct { + /** + * base points to the data. + */ + uint8_t *base; + /** + * len is the number of bytes which the buffer pointed by base + * contains. + */ + size_t len; +} nghttp3_vec; + +struct nghttp3_rcbuf; + +/** + * @struct + * + * :type:`nghttp3_rcbuf` is the object representing reference counted + * buffer. The details of this structure are intentionally hidden + * from the public API. + */ +typedef struct nghttp3_rcbuf nghttp3_rcbuf; + +/** + * @function + * + * `nghttp3_rcbuf_incref` increments the reference count of |rcbuf| by + * 1. + */ +NGHTTP3_EXTERN void nghttp3_rcbuf_incref(nghttp3_rcbuf *rcbuf); + +/** + * @function + * + * `nghttp3_rcbuf_decref` decrements the reference count of |rcbuf| by + * 1. If the reference count becomes zero, the object pointed by + * |rcbuf| will be freed. In this case, application must not use + * |rcbuf| again. + */ +NGHTTP3_EXTERN void nghttp3_rcbuf_decref(nghttp3_rcbuf *rcbuf); + +/** + * @function + * + * `nghttp3_rcbuf_get_buf` returns the underlying buffer managed by + * |rcbuf|. + */ +NGHTTP3_EXTERN nghttp3_vec nghttp3_rcbuf_get_buf(const nghttp3_rcbuf *rcbuf); + +/** + * @function + * + * `nghttp3_rcbuf_is_static` returns nonzero if the underlying buffer + * is statically allocated, and 0 otherwise. This can be useful for + * language bindings that wish to avoid creating duplicate strings for + * these buffers. + */ +NGHTTP3_EXTERN int nghttp3_rcbuf_is_static(const nghttp3_rcbuf *rcbuf); + +/** + * @struct + * + * :type:`nghttp3_buf` is the variable size buffer. + */ +typedef struct { + /** + * begin points to the beginning of the buffer. + */ + uint8_t *begin; + /** + * end points to the one beyond of the last byte of the buffer + */ + uint8_t *end; + /** + * pos pointers to the start of data. Typically, this points to the + * point that next data should be read. Initially, it points to + * |begin|. + */ + uint8_t *pos; + /** + * last points to the one beyond of the last data of the buffer. + * Typically, new data is written at this point. Initially, it + * points to |begin|. + */ + uint8_t *last; +} nghttp3_buf; + +/** + * @function + * + * `nghttp3_buf_init` initializes empty |buf|. + */ +NGHTTP3_EXTERN void nghttp3_buf_init(nghttp3_buf *buf); + +/** + * @function + * + * `nghttp3_buf_free` frees resources allocated for |buf| using |mem| + * as memory allocator. buf->begin must be a heap buffer allocated by + * |mem|. + */ +NGHTTP3_EXTERN void nghttp3_buf_free(nghttp3_buf *buf, const nghttp3_mem *mem); + +/** + * @function + * + * `nghttp3_buf_left` returns the number of additional bytes which can + * be written to the underlying buffer. In other words, it returns + * buf->end - buf->last. + */ +NGHTTP3_EXTERN size_t nghttp3_buf_left(const nghttp3_buf *buf); + +/** + * @function + * + * `nghttp3_buf_len` returns the number of bytes left to read. In + * other words, it returns buf->last - buf->pos. + */ +NGHTTP3_EXTERN size_t nghttp3_buf_len(const nghttp3_buf *buf); + +/** + * @function + * + * `nghttp3_buf_reset` sets buf->pos and buf->last to buf->begin. + */ +NGHTTP3_EXTERN void nghttp3_buf_reset(nghttp3_buf *buf); + +/** + * @enum + * + * :type:`nghttp3_nv_flag` is the flags for header field name/value + * pair. + */ +typedef enum { + /** + * :enum:`NGHTTP3_NV_FLAG_NONE` indicates no flag set. + */ + NGHTTP3_NV_FLAG_NONE = 0, + /** + * :enum:`NGHTTP3_NV_FLAG_NEVER_INDEX` indicates that this + * name/value pair must not be indexed. Other implementation calls + * this bit as "sensitive". + */ + NGHTTP3_NV_FLAG_NEVER_INDEX = 0x01, + /** + * :enum:`NGHTTP3_NV_FLAG_NO_COPY_NAME` is set solely by + * application. If this flag is set, the library does not make a + * copy of header field name. This could improve performance. + */ + NGHTTP3_NV_FLAG_NO_COPY_NAME = 0x02, + /** + * :enum:`NGHTTP3_NV_FLAG_NO_COPY_VALUE` is set solely by + * application. If this flag is set, the library does not make a + * copy of header field value. This could improve performance. + */ + NGHTTP3_NV_FLAG_NO_COPY_VALUE = 0x04 +} nghttp3_nv_flag; + +/** + * @struct + * + * :type:`nghttp3_nv` is the name/value pair, which mainly used to + * represent header fields. + */ +typedef struct { + /** + * name is the header field name. + */ + uint8_t *name; + /** + * value is the header field value. + */ + uint8_t *value; + /** + * namelen is the length of the |name|, excluding terminating NULL. + */ + size_t namelen; + /** + * valuelen is the length of the |value|, excluding terminating + * NULL. + */ + size_t valuelen; + /** + * flags is bitwise OR of one or more of :type:`nghttp3_nv_flag`. + */ + uint8_t flags; +} nghttp3_nv; + +/* Generated by mkstatichdtbl.py */ +typedef enum { + NGHTTP3_QPACK_TOKEN__AUTHORITY = 0, + NGHTTP3_QPACK_TOKEN__PATH = 8, + NGHTTP3_QPACK_TOKEN_AGE = 43, + NGHTTP3_QPACK_TOKEN_CONTENT_DISPOSITION = 52, + NGHTTP3_QPACK_TOKEN_CONTENT_LENGTH = 55, + NGHTTP3_QPACK_TOKEN_COOKIE = 68, + NGHTTP3_QPACK_TOKEN_DATE = 69, + NGHTTP3_QPACK_TOKEN_ETAG = 71, + NGHTTP3_QPACK_TOKEN_IF_MODIFIED_SINCE = 74, + NGHTTP3_QPACK_TOKEN_IF_NONE_MATCH = 75, + NGHTTP3_QPACK_TOKEN_LAST_MODIFIED = 77, + NGHTTP3_QPACK_TOKEN_LINK = 78, + NGHTTP3_QPACK_TOKEN_LOCATION = 79, + NGHTTP3_QPACK_TOKEN_REFERER = 83, + NGHTTP3_QPACK_TOKEN_SET_COOKIE = 85, + NGHTTP3_QPACK_TOKEN__METHOD = 1, + NGHTTP3_QPACK_TOKEN__SCHEME = 9, + NGHTTP3_QPACK_TOKEN__STATUS = 11, + NGHTTP3_QPACK_TOKEN_ACCEPT = 25, + NGHTTP3_QPACK_TOKEN_ACCEPT_ENCODING = 27, + NGHTTP3_QPACK_TOKEN_ACCEPT_RANGES = 29, + NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_HEADERS = 32, + NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_ORIGIN = 38, + NGHTTP3_QPACK_TOKEN_CACHE_CONTROL = 46, + NGHTTP3_QPACK_TOKEN_CONTENT_ENCODING = 53, + NGHTTP3_QPACK_TOKEN_CONTENT_TYPE = 57, + NGHTTP3_QPACK_TOKEN_RANGE = 82, + NGHTTP3_QPACK_TOKEN_STRICT_TRANSPORT_SECURITY = 86, + NGHTTP3_QPACK_TOKEN_VARY = 92, + NGHTTP3_QPACK_TOKEN_X_CONTENT_TYPE_OPTIONS = 94, + NGHTTP3_QPACK_TOKEN_X_XSS_PROTECTION = 98, + NGHTTP3_QPACK_TOKEN_ACCEPT_LANGUAGE = 28, + NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_CREDENTIALS = 30, + NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_ALLOW_METHODS = 35, + NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_EXPOSE_HEADERS = 39, + NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_HEADERS = 40, + NGHTTP3_QPACK_TOKEN_ACCESS_CONTROL_REQUEST_METHOD = 41, + NGHTTP3_QPACK_TOKEN_ALT_SVC = 44, + NGHTTP3_QPACK_TOKEN_AUTHORIZATION = 45, + NGHTTP3_QPACK_TOKEN_CONTENT_SECURITY_POLICY = 56, + NGHTTP3_QPACK_TOKEN_EARLY_DATA = 70, + NGHTTP3_QPACK_TOKEN_EXPECT_CT = 72, + NGHTTP3_QPACK_TOKEN_FORWARDED = 73, + NGHTTP3_QPACK_TOKEN_IF_RANGE = 76, + NGHTTP3_QPACK_TOKEN_ORIGIN = 80, + NGHTTP3_QPACK_TOKEN_PURPOSE = 81, + NGHTTP3_QPACK_TOKEN_SERVER = 84, + NGHTTP3_QPACK_TOKEN_TIMING_ALLOW_ORIGIN = 89, + NGHTTP3_QPACK_TOKEN_UPGRADE_INSECURE_REQUESTS = 90, + NGHTTP3_QPACK_TOKEN_USER_AGENT = 91, + NGHTTP3_QPACK_TOKEN_X_FORWARDED_FOR = 95, + NGHTTP3_QPACK_TOKEN_X_FRAME_OPTIONS = 96, + /* Additional header fields for HTTP messaging validation */ + NGHTTP3_QPACK_TOKEN_HOST = 1000, + NGHTTP3_QPACK_TOKEN_CONNECTION, + NGHTTP3_QPACK_TOKEN_KEEP_ALIVE, + NGHTTP3_QPACK_TOKEN_PROXY_CONNECTION, + NGHTTP3_QPACK_TOKEN_TRANSFER_ENCODING, + NGHTTP3_QPACK_TOKEN_UPGRADE, + NGHTTP3_QPACK_TOKEN_TE, + NGHTTP3_QPACK_TOKEN__PROTOCOL +} nghttp3_qpack_token; + +/** + * @struct + * + * nghttp3_qpack_nv represents header field name/value pair just like + * :type:`nghttp3_nv`. It is an extended version of + * :type:`nghttp3_nv` and has reference counted buffers and tokens + * which might be useful for applications. + */ +typedef struct { + /* The buffer containing header field name. NULL-termination is + guaranteed. */ + nghttp3_rcbuf *name; + /* The buffer containing header field value. NULL-termination is + guaranteed. */ + nghttp3_rcbuf *value; + /* nghttp3_qpack_token value for name. It could be -1 if we have no + token for that header field name. */ + int32_t token; + /* Bitwise OR of one or more of nghttp3_nv_flag. */ + uint8_t flags; +} nghttp3_qpack_nv; + +struct nghttp3_qpack_encoder; + +/** + * @struct + * + * :type:`nghttp3_qpack_encoder` is QPACK encoder. + */ +typedef struct nghttp3_qpack_encoder nghttp3_qpack_encoder; + +/** + * @function + * + * `nghttp3_qpack_encoder_new` initializes QPACK encoder. |pencoder| + * must be non-NULL pointer. |max_dtable_size| is the maximum dynamic + * table size. |max_blocked| is the maximum number of streams which + * can be blocked. |mem| is a memory allocator. This function + * allocates memory for :type:`nghttp3_qpack_encoder` itself and + * assigns its pointer to |*pencoder| if it succeeds. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory. + */ +NGHTTP3_EXTERN int nghttp3_qpack_encoder_new(nghttp3_qpack_encoder **pencoder, + size_t max_dtable_size, + size_t max_blocked, + const nghttp3_mem *mem); + +/** + * @function + * + * `nghttp3_qpack_encoder_del` frees memory allocated for |encoder|. + * This function frees memory pointed by |encoder| itself. + */ +NGHTTP3_EXTERN void nghttp3_qpack_encoder_del(nghttp3_qpack_encoder *encoder); + +/** + * @function + * + * `nghttp3_qpack_encoder_encode` encodes the list of header fields + * |nva|. |nvlen| is the length of |nva|. |stream_id| is the + * identifier of the stream which this header fields belong to. This + * function writes header block prefix, encoded header fields, and + * encoder stream to |pbuf|, |rbuf|, and |ebuf| respectively. The + * last field of nghttp3_buf will be adjusted when data is written. + * An application should write |pbuf| and |rbuf| to the request stream + * in this order. + * + * The buffer pointed by |pbuf|, |rbuf|, and |ebuf| can be empty + * buffer. It is fine to pass a buffer initialized by + * nghttp3_buf_init(buf). This function allocates memory for these + * buffers as necessary. In particular, it frees and expands buffer + * if the current capacity of buffer is not enough. If begin field of + * any buffer is not NULL, it must be allocated by the same memory + * allocator passed to `nghttp3_qpack_encoder_new()`. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory + * :enum:`NGHTTP3_ERR_QPACK_FATAL` + * |encoder| is in unrecoverable error state and cannot be used + * anymore. + */ +NGHTTP3_EXTERN int nghttp3_qpack_encoder_encode( + nghttp3_qpack_encoder *encoder, nghttp3_buf *pbuf, nghttp3_buf *rbuf, + nghttp3_buf *ebuf, int64_t stream_id, const nghttp3_nv *nva, size_t nvlen); + +/** + * @function + * + * `nghttp3_qpack_encoder_read_decoder` reads decoder stream. The + * buffer pointed by |src| of length |srclen| contains decoder stream. + * + * This function returns the number of bytes read, or one of the + * following negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory + * :enum:`NGHTTP3_ERR_QPACK_FATAL` + * |encoder| is in unrecoverable error state and cannot be used + * anymore. + * :enum:`NGHTTP3_ERR_QPACK_DECODER_STREAM` + * |encoder| is unable to process input because it is malformed. + */ +NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_encoder_read_decoder( + nghttp3_qpack_encoder *encoder, const uint8_t *src, size_t srclen); + +/** + * @function + * + * `nghttp3_qpack_encoder_set_max_dtable_size` sets max dynamic table + * size to |max_dtable_size|. + * + * This function returns the number of bytes read, or one of the + * following negative error codes: + * + * :enum:`NGHTTP3_ERR_INVALID_ARGUMENT` + * |max_dtable_size| exceeds the hard limit that decoder specifies. + */ +NGHTTP3_EXTERN int +nghttp3_qpack_encoder_set_max_dtable_size(nghttp3_qpack_encoder *encoder, + size_t max_dtable_size); + +/** + * @function + * + * `nghttp3_qpack_encoder_set_hard_max_dtable_size` sets hard maximum + * dynamic table size to |hard_max_dtable_size|. + * + * This function returns the number of bytes read, or one of the + * following negative error codes: + * + * TBD + */ +NGHTTP3_EXTERN int +nghttp3_qpack_encoder_set_hard_max_dtable_size(nghttp3_qpack_encoder *encoder, + size_t hard_max_dtable_size); + +/** + * @function + * + * `nghttp3_qpack_encoder_set_max_blocked` sets the number of streams + * which can be blocked to |max_blocked|. + * + * This function returns the number of bytes read, or one of the + * following negative error codes: + * + * TBD + */ +NGHTTP3_EXTERN int +nghttp3_qpack_encoder_set_max_blocked(nghttp3_qpack_encoder *encoder, + size_t max_blocked); + +/** + * @function + * + * `nghttp3_qpack_encoder_ack_header` tells |encoder| that header + * block for a stream denoted by |stream_id| was acknowledged by + * decoder. This function is provided for debugging purpose only. In + * HTTP/3, |encoder| knows acknowledgement of header block by reading + * decoder stream with `nghttp3_qpack_encoder_read_decoder()`. + */ +NGHTTP3_EXTERN void +nghttp3_qpack_encoder_ack_header(nghttp3_qpack_encoder *encoder, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_qpack_encoder_add_insert_count` increments known received + * count of |encoder| by |n|. This function is provided for debugging + * purpose only. In HTTP/3, |encoder| increments known received count + * by reading decoder stream with + * `nghttp3_qpack_encoder_read_decoder()`. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory. + * :enum:`NGHTTP3_QPACK_DECODER_STREAM` + * |n| is too large. + */ +NGHTTP3_EXTERN int +nghttp3_qpack_encoder_add_insert_count(nghttp3_qpack_encoder *encoder, + size_t n); + +/** + * @function + * + * `nghttp3_qpack_encoder_ack_everything` tells |encoder| that all + * encoded header blocks are acknowledged. This function is provided + * for debugging purpose only. In HTTP/3, |encoder| knows this by + * reading decoder stream with `nghttp3_qpack_encoder_read_decoder()`. + */ +NGHTTP3_EXTERN void +nghttp3_qpack_encoder_ack_everything(nghttp3_qpack_encoder *encoder); + +/** + * @function + * + * `nghttp3_qpack_encoder_cancel_stream` tells |encoder| that stream + * denoted by |stream_id| is cancelled. This function is provided for + * debugging purpose only. In HTTP/3, |encoder| knows this by reading + * decoder stream with `nghttp3_qpack_encoder_read_decoder()`. + */ +NGHTTP3_EXTERN void +nghttp3_qpack_encoder_cancel_stream(nghttp3_qpack_encoder *encoder, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_qpack_encoder_get_num_blocked` returns the number of + * streams which is potentially blocked at decoder side. + */ +NGHTTP3_EXTERN size_t +nghttp3_qpack_encoder_get_num_blocked(nghttp3_qpack_encoder *encoder); + +struct nghttp3_qpack_stream_context; + +/** + * @struct + * + * :type:`nghttp3_qpack_stream_context` is a decoder context for an + * individual stream. + */ +typedef struct nghttp3_qpack_stream_context nghttp3_qpack_stream_context; + +/** + * @function + * + * `nghttp3_qpack_stream_context_new` initializes stream context. + * |psctx| must be non-NULL pointer. |stream_id| is stream ID. |mem| + * is a memory allocator. This function allocates memory for + * :type:`nghttp3_qpack_stream_context` itself and assigns its pointer + * to |*psctx| if it succeeds. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory. + */ +NGHTTP3_EXTERN int +nghttp3_qpack_stream_context_new(nghttp3_qpack_stream_context **psctx, + int64_t stream_id, const nghttp3_mem *mem); + +/** + * @function + * + * `nghttp3_qpack_stream_context_del` frees memory allocated for + * |sctx|. This function frees memory pointed by |sctx| itself. + */ +NGHTTP3_EXTERN void +nghttp3_qpack_stream_context_del(nghttp3_qpack_stream_context *sctx); + +/** + * @function + * + * `nghttp3_qpack_stream_context_get_ricnt` returns required insert + * count. + */ +NGHTTP3_EXTERN size_t +nghttp3_qpack_stream_context_get_ricnt(nghttp3_qpack_stream_context *sctx); + +struct nghttp3_qpack_decoder; + +/** + * @struct + * + * `nghttp3_qpack_decoder` is QPACK decoder. + */ +typedef struct nghttp3_qpack_decoder nghttp3_qpack_decoder; + +/** + * @function + * + * `nghttp3_qpack_decoder_new` initializes QPACK decoder. |pdecoder| + * must be non-NULL pointer. |max_dtable_size| is the maximum dynamic + * table size. |max_blocked| is the maximum number of streams which + * can be blocked. |mem| is a memory allocator. This function + * allocates memory for :type:`nghttp3_qpack_decoder` itself and + * assigns its pointer to |*pdecoder| if it succeeds. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory. + */ +NGHTTP3_EXTERN int nghttp3_qpack_decoder_new(nghttp3_qpack_decoder **pdecoder, + size_t max_dtable_size, + size_t max_blocked, + const nghttp3_mem *mem); + +/** + * @function + * + * `nghttp3_qpack_decoder_del` frees memory allocated for |decoder|. + * This function frees memory pointed by |decoder| itself. + */ +NGHTTP3_EXTERN void nghttp3_qpack_decoder_del(nghttp3_qpack_decoder *decoder); + +/** + * @function + * + * `nghttp3_qpack_decoder_read_encoder` reads encoder stream. The + * buffer pointed by |src| of length |srclen| contains encoder stream. + * + * This function returns the number of bytes read, or one of the + * following negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory. + * :enum:`NGHTTP3_ERR_QPACK_FATAL` + * |decoder| is in unrecoverable error state and cannot be used + * anymore. + * :enum:`NGHTTP3_ERR_QPACK_ENCODER_STREAM` + * Could not interpret encoder stream instruction. + */ +NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_decoder_read_encoder( + nghttp3_qpack_decoder *decoder, const uint8_t *src, size_t srclen); + +/** + * @function + * + * `nghttp3_qpack_decoder_get_icnt` returns insert count. + */ +NGHTTP3_EXTERN size_t +nghttp3_qpack_decoder_get_icnt(const nghttp3_qpack_decoder *decoder); + +/** + * @enum + * + * :type:`nghttp3_qpack_decode_flag` is a set of flags for decoder. + */ +typedef enum { + /** + * :enum:`NGHTTP3_QPACK_DECODE_FLAG_NONE` indicates that no flag + * set. + */ + NGHTTP3_QPACK_DECODE_FLAG_NONE, + /** + * :enum:`NGHTTP3_QPACK_DECODE_FLAG_EMIT` indicates that a header + * field is successfully decoded. + */ + NGHTTP3_QPACK_DECODE_FLAG_EMIT = 0x01, + /** + * :enum:`NGHTTP3_QPACK_DECODE_FLAG_FINAL` indicates that all header + * fields have been decoded. + */ + NGHTTP3_QPACK_DECODE_FLAG_FINAL = 0x02, + /** + * :enum:`NGHTTP3_QPACK_DECODE_FLAG_BLOCKED` indicates that decoding + * has been blocked. + */ + NGHTTP3_QPACK_DECODE_FLAG_BLOCKED = 0x04 +} nghttp3_qpack_decode_flag; + +/** + * @function + * + * `nghttp3_qpack_decoder_read_request` reads request stream. The + * request stream is given as the buffer pointed by |src| of length + * |srclen|. |sctx| is the stream context and it must be initialized + * by `nghttp3_qpack_stream_context_init()`. |*pflags| must be + * non-NULL pointer. |nv| must be non-NULL pointer. + * + * If this function succeeds, it assigns flags to |*pflags|. If + * |*pflags| has :enum:`NGHTTP3_QPACK_DECODE_FLAG_EMIT` set, a decoded + * header field is assigned to |nv|. If |*pflags| has + * :enum:`NGHTTP3_QPACK_DECODE_FLAG_FINAL` set, all header fields have + * been successfully decoded. If |*pflags| has + * :enum:`NGHTTP3_QPACK_DECODE_FLAG_BLOCKED` set, decoding is blocked + * due to required insert count. + * + * When a header field is decoded, an application receives it in |nv|. + * nv->name and nv->value are reference counted buffer, and the their + * reference counts are already incremented for application use. + * Therefore, when application finishes processing the header field, + * it must call nghttp3_rcbuf_decref(nv->name) and + * nghttp3_rcbuf_decref(nv->value) or memory leak might occur. + * + * This function returns the number of bytes read, or one of the + * following negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory. + * :enum:`NGHTTP3_ERR_QPACK_FATAL` + * |decoder| is in unrecoverable error state and cannot be used + * anymore. + * :enum:`NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED` + * Could not interpret header block instruction. + * :enum:`NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE` + * Header field is too large. + */ +NGHTTP3_EXTERN nghttp3_ssize nghttp3_qpack_decoder_read_request( + nghttp3_qpack_decoder *decoder, nghttp3_qpack_stream_context *sctx, + nghttp3_qpack_nv *nv, uint8_t *pflags, const uint8_t *src, size_t srclen, + int fin); + +/** + * @function + * + * `nghttp3_qpack_decoder_write_decoder` writes decoder stream into + * |dbuf|. + * + * The caller must ensure that nghttp3_buf_left(dbuf) >= + * nghttp3_qpack_decoder_get_decoder_streamlen(decoder). + */ +NGHTTP3_EXTERN void +nghttp3_qpack_decoder_write_decoder(nghttp3_qpack_decoder *decoder, + nghttp3_buf *dbuf); + +/** + * @function + * + * `nghttp3_qpack_decoder_get_decoder_streamlen` returns the length of + * decoder stream. + */ +NGHTTP3_EXTERN size_t +nghttp3_qpack_decoder_get_decoder_streamlen(nghttp3_qpack_decoder *decoder); + +/** + * @function + * + * `nghttp3_qpack_decoder_cancel_stream` cancels header decoding for + * stream denoted by |stream_id|. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * :enum:`NGHTTP3_ERR_NOMEM` + * Out of memory. + * :enum:`NGHTTP3_ERR_QPACK_FATAL` + * Decoder stream overflow. + */ +NGHTTP3_EXTERN int +nghttp3_qpack_decoder_cancel_stream(nghttp3_qpack_decoder *decoder, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_qpack_decoder_set_dtable_cap` sets |cap| as maximum + * dynamic table size. Normally, the maximum capacity is communicated + * in encoder stream. This function is provided for debugging and + * testing purpose. + */ +NGHTTP3_EXTERN void +nghttp3_qpack_decoder_set_dtable_cap(nghttp3_qpack_decoder *decoder, + size_t cap); + +/** + * @function + * + * `nghttp3_qpack_decoder_set_max_concurrent_streams` tells |decoder| + * the maximum number of concurrent streams that a remote endpoint can + * open, including both bidirectional and unidirectional streams which + * potentially receive QPACK encoded HEADERS frame. This value is + * used as a hint to limit the length of decoder stream. + */ +NGHTTP3_EXTERN void +nghttp3_qpack_decoder_set_max_concurrent_streams(nghttp3_qpack_decoder *decoder, + size_t max_concurrent_streams); + +/** + * @function + * + * `nghttp3_strerror` returns textual representation of |liberr| which + * should be one of error codes defined in :type:`nghttp3_lib_error`. + */ +NGHTTP3_EXTERN const char *nghttp3_strerror(int liberr); + +/** + * @function + * + * `nghttp3_err_infer_quic_app_error_code` returns a QUIC application + * error code which corresponds to |liberr|. + */ +NGHTTP3_EXTERN uint64_t nghttp3_err_infer_quic_app_error_code(int liberr); + +/** + * @functypedef + * + * :type:`nghttp3_debug_vprintf_callback` is a callback function + * invoked when the library outputs debug logging. The function is + * called with arguments suitable for ``vfprintf(3)`` + * + * The debug output is only enabled if the library is built with + * ``DEBUGBUILD`` macro defined. + */ +typedef void (*nghttp3_debug_vprintf_callback)(const char *format, + va_list args); + +/** + * @function + * + * `nghttp3_set_debug_vprintf_callback` sets a debug output callback + * called by the library when built with ``DEBUGBUILD`` macro defined. + * If this option is not used, debug log is written into standard + * error output. + * + * For builds without ``DEBUGBUILD`` macro defined, this function is + * noop. + * + * Note that building with ``DEBUGBUILD`` may cause significant + * performance penalty to libnghttp3 because of extra processing. It + * should be used for debugging purpose only. + * + * .. Warning:: + * + * Building with ``DEBUGBUILD`` may cause significant performance + * penalty to libnghttp3 because of extra processing. It should be + * used for debugging purpose only. We write this two times because + * this is important. + */ +NGHTTP3_EXTERN void nghttp3_set_debug_vprintf_callback( + nghttp3_debug_vprintf_callback debug_vprintf_callback); + +struct nghttp3_conn; +typedef struct nghttp3_conn nghttp3_conn; + +/** + * @functypedef + * + * :type:`nghttp3_acked_stream_data` is a callback function which is + * invoked when data sent on stream denoted by |stream_id| supplied + * from application is acknowledged by remote endpoint. The number of + * bytes acknowledged is given in |datalen|. + * + * The implementation of this callback must return 0 if it succeeds. + * Returning :enum:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the + * caller immediately. Any values other than 0 is treated as + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp3_acked_stream_data)(nghttp3_conn *conn, int64_t stream_id, + size_t datalen, void *conn_user_data, + void *stream_user_data); + +/** + * @functypedef + * + * :type:`nghttp3_conn_stream_close` is a callback function which is + * invoked when a stream identified by |stream_id| is closed. + * |app_error_code| indicates the reason of this closure. + * + * The implementation of this callback must return 0 if it succeeds. + * Returning :enum:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the + * caller immediately. Any values other than 0 is treated as + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp3_stream_close)(nghttp3_conn *conn, int64_t stream_id, + uint64_t app_error_code, + void *conn_user_data, + void *stream_user_data); + +/** + * @functypedef + * + * :type:`nghttp3_recv_data` is a callback function which is invoked + * when a part of request or response body on stream identified by + * |stream_id| is received. |data| points to the received data and + * its length is |datalen|. + * + * The application is responsible for increasing flow control credit + * by |datalen| bytes. + * + * The implementation of this callback must return 0 if it succeeds. + * Returning :enum:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the + * caller immediately. Any values other than 0 is treated as + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp3_recv_data)(nghttp3_conn *conn, int64_t stream_id, + const uint8_t *data, size_t datalen, + void *conn_user_data, void *stream_user_data); + +/** + * @functypedef + * + * :type:`nghttp3_deferred_consume` is a callback function which is + * invoked when the library consumed |consumed| bytes for a stream + * identified by |stream_id|. This callback is used to notify the + * consumed bytes for stream blocked by QPACK decoder. The + * application is responsible for increasing flow control credit by + * |consumed| bytes. + * + * The implementation of this callback must return 0 if it succeeds. + * Returning :enum:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the + * caller immediately. Any values other than 0 is treated as + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp3_deferred_consume)(nghttp3_conn *conn, int64_t stream_id, + size_t consumed, void *conn_user_data, + void *stream_user_data); + +typedef int (*nghttp3_begin_headers)(nghttp3_conn *conn, int64_t stream_id, + void *conn_user_data, + void *stream_user_data); + +typedef int (*nghttp3_recv_header)(nghttp3_conn *conn, int64_t stream_id, + int32_t token, nghttp3_rcbuf *name, + nghttp3_rcbuf *value, uint8_t flags, + void *conn_user_data, + void *stream_user_data); + +typedef int (*nghttp3_end_headers)(nghttp3_conn *conn, int64_t stream_id, + void *conn_user_data, + void *stream_user_data); + +typedef int (*nghttp3_begin_push_promise)(nghttp3_conn *conn, int64_t stream_id, + int64_t push_id, void *conn_user_data, + void *stream_user_data); + +typedef int (*nghttp3_recv_push_promise)(nghttp3_conn *conn, int64_t stream_id, + int64_t push_id, int32_t token, + nghttp3_rcbuf *name, + nghttp3_rcbuf *value, uint8_t flags, + void *conn_user_data, + void *stream_user_data); + +typedef int (*nghttp3_end_push_promise)(nghttp3_conn *conn, int64_t stream_id, + int64_t push_id, void *conn_user_data, + void *stream_user_data); + +/** + * @functypedef + * + * :type:`nghttp3_end_stream` is a callback function which is invoked + * when the receiving side of stream is closed. For server, this + * callback function is invoked when HTTP request is received + * completely. For client, this callback function is invoked when + * HTTP response is received completely. + * + * The implementation of this callback must return 0 if it succeeds. + * Returning :enum:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the + * caller immediately. Any values other than 0 is treated as + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp3_end_stream)(nghttp3_conn *conn, int64_t stream_id, + void *conn_user_data, void *stream_user_data); + +/** + * @functypedef + * + * :type:`nghttp3_cancel_push` is a callback function which is invoked + * when the push identified by |push_id| is cancelled by remote + * endpoint. If a stream has been bound to the push ID, |stream_id| + * contains the stream ID and |stream_user_data| points to the stream + * user data. Otherwise, |stream_id| is -1 and |stream_user_data| is + * NULL. + * + * The implementation of this callback must return 0 if it succeeds. + * Returning :enum:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the + * caller immediately. Any values other than 0 is treated as + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp3_cancel_push)(nghttp3_conn *conn, int64_t push_id, + int64_t stream_id, void *conn_user_data, + void *stream_user_data); + +/** + * @functypedef + * + * :type:`nghttp3_send_stop_sending` is a callback function which is + * invoked when the library asks application to send STOP_SENDING to + * the stream identified by |stream_id|. |app_error_code| indicates + * the reason for this action. + * + * The implementation of this callback must return 0 if it succeeds. + * Returning :enum:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the + * caller immediately. Any values other than 0 is treated as + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp3_send_stop_sending)(nghttp3_conn *conn, int64_t stream_id, + uint64_t app_error_code, + void *conn_user_data, + void *stream_user_data); + +/** + * @functypedef + * + * :type:`nghttp3_push_stream` is a callback function which is invoked + * when a push stream identified by |stream_id| is opened with + * |push_id|. + * + * The implementation of this callback must return 0 if it succeeds. + * Returning :enum:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the + * caller immediately. Any values other than 0 is treated as + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + */ +typedef int (*nghttp3_push_stream)(nghttp3_conn *conn, int64_t push_id, + int64_t stream_id, void *conn_user_data); + +typedef struct { + nghttp3_acked_stream_data acked_stream_data; + nghttp3_stream_close stream_close; + nghttp3_recv_data recv_data; + nghttp3_deferred_consume deferred_consume; + nghttp3_begin_headers begin_headers; + nghttp3_recv_header recv_header; + nghttp3_end_headers end_headers; + nghttp3_begin_headers begin_trailers; + nghttp3_recv_header recv_trailer; + nghttp3_end_headers end_trailers; + nghttp3_begin_push_promise begin_push_promise; + nghttp3_recv_push_promise recv_push_promise; + nghttp3_end_push_promise end_push_promise; + nghttp3_cancel_push cancel_push; + nghttp3_send_stop_sending send_stop_sending; + nghttp3_push_stream push_stream; + nghttp3_end_stream end_stream; +} nghttp3_conn_callbacks; + +typedef struct { + uint64_t max_header_list_size; + uint64_t max_pushes; + size_t qpack_max_table_capacity; + size_t qpack_blocked_streams; +} nghttp3_conn_settings; + +NGHTTP3_EXTERN void +nghttp3_conn_settings_default(nghttp3_conn_settings *settings); + +NGHTTP3_EXTERN int +nghttp3_conn_client_new(nghttp3_conn **pconn, + const nghttp3_conn_callbacks *callbacks, + const nghttp3_conn_settings *settings, + const nghttp3_mem *mem, void *conn_user_data); + +NGHTTP3_EXTERN int +nghttp3_conn_server_new(nghttp3_conn **pconn, + const nghttp3_conn_callbacks *callbacks, + const nghttp3_conn_settings *settings, + const nghttp3_mem *mem, void *conn_user_data); + +NGHTTP3_EXTERN void nghttp3_conn_del(nghttp3_conn *conn); + +/** + * @function + * + * `nghttp3_conn_bind_control_stream` binds stream denoted by + * |stream_id| to outgoing unidirectional control stream. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * :enum:`NGHTTP3_ERR_INVALID_STATE` + * Control stream has already corresponding stream ID. + * TBD + */ +NGHTTP3_EXTERN int nghttp3_conn_bind_control_stream(nghttp3_conn *conn, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_conn_bind_qpack_streams` binds stream denoted by + * |qenc_stream_id| to outgoing QPACK encoder stream and stream + * denoted by |qdec_stream_id| to outgoing QPACK encoder stream. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * :enum:`NGHTTP3_ERR_INVALID_STATE` + * QPACK encoder/decoder stream have already corresponding stream + * IDs. + * TBD + */ +NGHTTP3_EXTERN int nghttp3_conn_bind_qpack_streams(nghttp3_conn *conn, + int64_t qenc_stream_id, + int64_t qdec_stream_id); + +typedef enum { + NGHTTP3_FRAME_DATA = 0x00, + NGHTTP3_FRAME_HEADERS = 0x01, + NGHTTP3_FRAME_CANCEL_PUSH = 0x03, + NGHTTP3_FRAME_SETTINGS = 0x04, + NGHTTP3_FRAME_PUSH_PROMISE = 0x05, + NGHTTP3_FRAME_GOAWAY = 0x07, + NGHTTP3_FRAME_MAX_PUSH_ID = 0x0d, +} nghttp3_frame_type; + +typedef struct { + int64_t type; + int64_t length; +} nghttp3_frame_hd; + +typedef struct { + nghttp3_frame_hd hd; +} nghttp3_frame_data; + +typedef struct { + nghttp3_frame_hd hd; + nghttp3_nv *nva; + size_t nvlen; +} nghttp3_frame_headers; + +typedef struct { + nghttp3_frame_hd hd; + int64_t push_id; +} nghttp3_frame_cancel_push; + +#define NGHTTP3_SETTINGS_ID_MAX_HEADER_LIST_SIZE 0x06 +#define NGHTTP3_SETTINGS_ID_QPACK_MAX_TABLE_CAPACITY 0x01 +#define NGHTTP3_SETTINGS_ID_QPACK_BLOCKED_STREAMS 0x07 + +typedef struct { + uint64_t id; + uint64_t value; +} nghttp3_settings_entry; + +typedef struct { + nghttp3_frame_hd hd; + size_t niv; + nghttp3_settings_entry iv[1]; +} nghttp3_frame_settings; + +typedef struct { + nghttp3_frame_hd hd; + nghttp3_nv *nva; + size_t nvlen; + int64_t push_id; +} nghttp3_frame_push_promise; + +typedef struct { + nghttp3_frame_hd hd; + int64_t stream_id; +} nghttp3_frame_goaway; + +typedef struct { + nghttp3_frame_hd hd; + int64_t push_id; +} nghttp3_frame_max_push_id; + +typedef union { + nghttp3_frame_hd hd; + nghttp3_frame_data data; + nghttp3_frame_headers headers; + nghttp3_frame_cancel_push cancel_push; + nghttp3_frame_settings settings; + nghttp3_frame_push_promise push_promise; + nghttp3_frame_goaway goaway; + nghttp3_frame_max_push_id max_push_id; +} nghttp3_frame; + +/** + * @function + * + * nghttp3_conn_read_stream reads data |src| of length |srclen| on + * stream identified by |stream_id|. It returns the number of bytes + * consumed. The "consumed" means that application can increase flow + * control credit (both stream and connection) of underlying QUIC + * connection by that amount. It does not include the amount of data + * carried by DATA frame which contains application data (excluding + * any control or QPACK unidirectional streams) . See + * type:`nghttp3_recv_data` to handle those bytes. If |fin| is + * nonzero, this is the last data from remote endpoint in this stream. + */ +NGHTTP3_EXTERN nghttp3_ssize nghttp3_conn_read_stream(nghttp3_conn *conn, + int64_t stream_id, + const uint8_t *src, + size_t srclen, int fin); + +/** + * @function + * + * `nghttp3_conn_writev_stream` stores stream data to send to |vec| of + * length |veccnt| and returns the number of nghttp3_vec object in + * which it stored data. It stores stream ID to |*pstream_id|. An + * application has to call `nghttp3_conn_add_write_offset` to inform + * |conn| of the actual number of bytes that underlying QUIC stack + * accepted. |*pfin| will be nonzero if this is the last data to + * send. If there is no stream to write data or send fin, this + * function returns 0, and -1 is assigned to |*pstream_id|. + */ +NGHTTP3_EXTERN nghttp3_ssize nghttp3_conn_writev_stream(nghttp3_conn *conn, + int64_t *pstream_id, + int *pfin, + nghttp3_vec *vec, + size_t veccnt); + +/** + * @function + * + * `nghttp3_conn_add_write_offset` tells |conn| the number of bytes + * |n| for stream denoted by |stream_id| QUIC stack accepted. + * + * If stream has no data to send but just sends fin (closing the write + * side of a stream), the number of bytes sent is 0. It is important + * to call this function even if |n| is 0 in this case. It is safe to + * call this function if |n| is 0. + * + * `nghttp3_conn_writev_stream` must be called before calling this + * function to get data to send, and those data must be fed into QUIC + * stack. + */ +NGHTTP3_EXTERN int nghttp3_conn_add_write_offset(nghttp3_conn *conn, + int64_t stream_id, size_t n); + +/** + * @function + * + * `nghttp3_conn_add_ack_offset` tells |conn| the number of bytes |n| + * for stream denoted by |stream_id| QUIC stack has acknowledged. + */ +NGHTTP3_EXTERN int nghttp3_conn_add_ack_offset(nghttp3_conn *conn, + int64_t stream_id, size_t n); + +/** + * @function + * + * `nghttp3_conn_block_stream` tells the library that stream + * identified by |stream_id| is blocked due to QUIC flow control. + */ +NGHTTP3_EXTERN int nghttp3_conn_block_stream(nghttp3_conn *conn, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_conn_unblock_stream` tells the library that stream + * identified by |stream_id| which was blocked by QUIC flow control is + * unblocked. + */ +NGHTTP3_EXTERN int nghttp3_conn_unblock_stream(nghttp3_conn *conn, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_conn_resume_stream` resumes stream identified by + * |stream_id| which was previously unable to provide data. + */ +NGHTTP3_EXTERN int nghttp3_conn_resume_stream(nghttp3_conn *conn, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_conn_close_stream` closes stream identified by + * |stream_id|. |app_error_code| is the reason of the closure. + */ +NGHTTP3_EXTERN int nghttp3_conn_close_stream(nghttp3_conn *conn, + int64_t stream_id, + uint64_t app_error_code); + +/** + * @function + * + * `nghttp3_conn_reset_stream` must be called if stream identified by + * |stream_id| is reset by a remote endpoint. This is required in + * order to cancel QPACK stream. + */ +NGHTTP3_EXTERN int nghttp3_conn_reset_stream(nghttp3_conn *conn, + int64_t stream_id); + +typedef enum { + NGHTTP3_DATA_FLAG_NONE = 0x00, + /** + * ``NGHTTP3_DATA_FLAG_EOF`` indicates that all request or response + * body has been provided to the library. It also indicates that + * sending side of stream is closed unless + * :enum:`NGHTTP3_DATA_FLAG_NO_END_STREAM` is given at the same + * time. + */ + NGHTTP3_DATA_FLAG_EOF = 0x01, + /** + * ``NGHTTP3_DATA_FLAG_NO_END_STREAM`` indicates that sending side + * of stream is not closed even if NGHTTP3_DATA_FLAG_EOF is set. + * Usually this flag is used to send trailer fields with + * `nghttp3_conn_submit_trailers()`. If + * `nghttp3_conn_submit_trailers()` has been called, regardless of + * this flag, the submitted trailer fields are sent. + */ + NGHTTP3_DATA_FLAG_NO_END_STREAM = 0x02 +} nghttp3_data_flag; + +/** + * @function + * + * `nghttp3_conn_set_max_client_streams_bidi` tells |conn| the + * cumulative number of bidirectional streams that client can open. + */ +NGHTTP3_EXTERN void +nghttp3_conn_set_max_client_streams_bidi(nghttp3_conn *conn, + uint64_t max_streams); + +/** + * @function + * + * `nghttp3_conn_set_max_concurrent_streams` tells |conn| the maximum + * number of concurrent streams that a remote endpoint can open, + * including both bidirectional and unidirectional streams which + * potentially receive QPACK encoded HEADERS frame. This value is + * used as a hint to limit the internal resource consumption. + */ +NGHTTP3_EXTERN void +nghttp3_conn_set_max_concurrent_streams(nghttp3_conn *conn, + size_t max_concurrent_streams); + +/** + * @functypedef + * + * :type:`nghttp3_read_data_callback` is a callback function invoked + * when the library asks an application to provide stream data for a + * stream denoted by |stream_id|. + * + * The library provides |vec| of length |veccnt| to the application. + * The application should fill data and its length to |vec|. It has + * to return the number of the filled objects. The application must + * retain data until they are safe to free. It is notified by + * :type:`nghttp3_acked_stream_data` callback. + * + * If this is the last data to send (or there is no data to send + * because all data have been sent already), set + * :enum:`NGHTTP3_DATA_FLAG_EOF` to |*pflags|. + * + * If the application is unable to provide data temporarily, return + * :enum:`NGHTTP3_ERR_WOULDBLOCK`. When it is ready to provide + * data, call `nghttp3_conn_resume_stream()`. + * + * The callback should return the number of objects in |vec| that the + * application filled if it succeeds, or + * :enum:`NGHTTP3_ERR_CALLBACK_FAILURE`. + * + * TODO Add NGHTTP3_ERR_TEMPORAL_CALLBACK_FAILURE to reset just this + * stream. + */ +typedef nghttp3_ssize (*nghttp3_read_data_callback)( + nghttp3_conn *conn, int64_t stream_id, nghttp3_vec *vec, size_t veccnt, + uint32_t *pflags, void *conn_user_data, void *stream_user_data); + +/** + * @struct + * + * :type:`nghttp3_data_reader` specifies the way how to generate + * request or response body. + */ +typedef struct { + /** + * read_data is a callback function to generate body. + */ + nghttp3_read_data_callback read_data; +} nghttp3_data_reader; + +/** + * @function + * + * `nghttp3_conn_submit_request` submits HTTP request header fields + * and body on the stream identified by |stream_id|. |stream_id| must + * be a client initiated bidirectional stream. Only client can submit + * HTTP request. |nva| of length |nvlen| specifies HTTP request + * header fields. |dr| specifies a request body. If there is no + * request body, specify NULL. If |dr| is NULL, it implies the end of + * stream. |stream_user_data| is an opaque pointer attached to the + * stream. + */ +NGHTTP3_EXTERN int nghttp3_conn_submit_request( + nghttp3_conn *conn, int64_t stream_id, const nghttp3_nv *nva, size_t nvlen, + const nghttp3_data_reader *dr, void *stream_user_data); + +/** + * @function + * + * `nghttp3_conn_submit_push_promise` submits push promise on the + * stream identified by |stream_id|. |stream_id| must be a client + * initiated bidirectional stream. Only server can submit push + * promise. On success, a push ID is assigned to |*ppush_id|. |nva| + * of length |nvlen| specifies HTTP request header fields. In order + * to submit HTTP response, first call + * `nghttp3_conn_bind_push_stream()` and then + * `nghttp3_conn_submit_response()`. + */ +NGHTTP3_EXTERN int nghttp3_conn_submit_push_promise(nghttp3_conn *conn, + int64_t *ppush_id, + int64_t stream_id, + const nghttp3_nv *nva, + size_t nvlen); + +/** + * @function + * + * `nghttp3_conn_submit_info` submits HTTP non-final response header + * fields on the stream identified by |stream_id|. |nva| of length + * |nvlen| specifies HTTP response header fields. + */ +NGHTTP3_EXTERN int nghttp3_conn_submit_info(nghttp3_conn *conn, + int64_t stream_id, + const nghttp3_nv *nva, + size_t nvlen); + +/** + * @function + * + * `nghttp3_conn_submit_response` submits HTTP response header fields + * and body on the stream identified by |stream_id|. |nva| of length + * |nvlen| specifies HTTP response header fields. |dr| specifies a + * response body. If there is no response body, specify NULL. If + * |dr| is NULL, it implies the end of stream. + */ +NGHTTP3_EXTERN int nghttp3_conn_submit_response(nghttp3_conn *conn, + int64_t stream_id, + const nghttp3_nv *nva, + size_t nvlen, + const nghttp3_data_reader *dr); + +/** + * @function + * + * `nghttp3_conn_submit_trailers` submits HTTP trailer fields on the + * stream identified by |stream_id|. |nva| of length |nvlen| + * specifies HTTP trailer fields. Calling this function implies the + * end of stream. + */ +NGHTTP3_EXTERN int nghttp3_conn_submit_trailers(nghttp3_conn *conn, + int64_t stream_id, + const nghttp3_nv *nva, + size_t nvlen); + +/** + * @function + * + * `nghttp3_conn_bind_push_stream` binds the stream identified by + * |stream_id| to the push identified by |push_id|. |stream_id| must + * be a server initiated unidirectional stream. |push_id| must be + * obtained from `nghttp3_conn_submit_push_promise()`. To send + * response to this push, call `nghttp3_conn_submit_response()`. + */ +NGHTTP3_EXTERN int nghttp3_conn_bind_push_stream(nghttp3_conn *conn, + int64_t push_id, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_conn_cancel_push` cancels the push identified by + * |push_id|. It is not possible to cancel the push after the + * response stream opens. In that case, send RESET_STREAM (if |conn| + * is server) or STOP_SENDING (if |conn| is client) on the underlying + * QUIC stream. + */ +NGHTTP3_EXTERN int nghttp3_conn_cancel_push(nghttp3_conn *conn, + int64_t push_id); + +/** + * @function + * + * `nghttp3_conn_set_stream_user_data` sets |stream_user_data| to the + * stream identified by |stream_id|. + */ +NGHTTP3_EXTERN int nghttp3_conn_set_stream_user_data(nghttp3_conn *conn, + int64_t stream_id, + void *stream_user_data); + +/** + * @function + * + * `nghttp3_conn_get_frame_payload_left` returns the number of bytes + * left to read current frame payload for a stream denoted by + * |stream_id|. If no such stream is found, it returns + * :enum:`NGHTTP3_ERR_STREAM_NOT_FOUND`. + */ +NGHTTP3_EXTERN int64_t nghttp3_conn_get_frame_payload_left(nghttp3_conn *conn, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_conn_is_remote_qpack_encoder_stream` returns nonzero if a + * stream denoted by |stream_id| is QPACK encoder stream of a remote + * endpoint. + */ +NGHTTP3_EXTERN int +nghttp3_conn_is_remote_qpack_encoder_stream(nghttp3_conn *conn, + int64_t stream_id); + +/** + * @function + * + * `nghttp3_vec_len` returns the sum of length in |vec| of |cnt| + * elements. + */ +NGHTTP3_EXTERN size_t nghttp3_vec_len(const nghttp3_vec *vec, size_t cnt); + +/** + * @function + * + * `nghttp3_vec_empty` returns nonzero if |vec| of |cnt| elements has + * 0 length data. + */ +NGHTTP3_EXTERN int nghttp3_vec_empty(const nghttp3_vec *vec, size_t cnt); + +/** + * @function + * + * `nghttp3_vec_consume` removes first |len| bytes from |*pvec| of + * |*pcnt| elements. The adjusted vector and number of elements are + * stored in |*pvec| and |*pcnt| respectively. + */ +NGHTTP3_EXTERN void nghttp3_vec_consume(nghttp3_vec **pvec, size_t *pcnt, + size_t len); + +/** + * @function + * + * `nghttp3_check_header_name` returns nonzero if HTTP header field + * name |name| of length |len| is valid according to + * http://tools.ietf.org/html/rfc7230#section-3.2 + * + * Because this is a header field name in HTTP/3, the upper cased + * alphabet is treated as error. + */ +NGHTTP3_EXTERN int nghttp3_check_header_name(const uint8_t *name, size_t len); + +/** + * @function + * + * `nghttp3_check_header_value` returns nonzero if HTTP header field + * value |value| of length |len| is valid according to + * http://tools.ietf.org/html/rfc7230#section-3.2 + */ +NGHTTP3_EXTERN int nghttp3_check_header_value(const uint8_t *value, size_t len); + +/** + * @macro + * + * The age of :type:`nghttp3_info` + */ +#define NGHTTP3_VERSION_AGE 1 + +/** + * @struct + * + * This struct is what `nghttp3_version()` returns. It holds + * information about the particular nghttp3 version. + */ +typedef struct { + /** + * Age of this struct. This instance of nghttp3 sets it to + * :macro:`NGHTTP3_VERSION_AGE` but a future version may bump it and + * add more struct fields at the bottom + */ + int age; + /** + * the :macro:`NGHTTP3_VERSION_NUM` number (since age ==1) + */ + int version_num; + /** + * points to the :macro:`NGHTTP3_VERSION` string (since age ==1) + */ + const char *version_str; + /* -------- the above fields all exist when age == 1 */ +} nghttp3_info; + +/** + * @function + * + * Returns a pointer to a nghttp3_info struct with version information + * about the run-time library in use. The |least_version| argument + * can be set to a 24 bit numerical value for the least accepted + * version number and if the condition is not met, this function will + * return a ``NULL``. Pass in 0 to skip the version checking. + */ +NGHTTP3_EXTERN nghttp3_info *nghttp3_version(int least_version); + +#ifdef __cplusplus +} +#endif + +#endif /* NGHTTP3_H */ |