Types (structs, unions and typedefs)

typedef ptrdiff_t nghttp3_ssize: nghttp3_ssize is signed counterpart of size_t.

typedef uint64_t nghttp3_tstamp: nghttp3_tstamp is a timestamp with nanosecond resolution. UINT64_MAX is an invalid value, and it is often used to indicate that no value is set. This type is available since v1.12.0.

typedef uint64_t nghttp3_duration: nghttp3_duration is a period of time in nanosecond resolution. UINT64_MAX is an invalid value, and it is often used to indicate that no value is set. This type is available since v1.12.0.

typedef void *(*nghttp3_malloc)(size_t size, void *user_data): nghttp3_malloc is a custom memory allocator to replace malloc(3). The user_data is the nghttp3_mem.user_data.

typedef void (*nghttp3_free)(void *ptr, void *user_data): nghttp3_free is a custom memory allocator to replace free(3). The user_data is the nghttp3_mem.user_data.

typedef void *(*nghttp3_calloc)(size_t nmemb, size_t size, void *user_data): nghttp3_calloc is a custom memory allocator to replace calloc(3). The user_data is the nghttp3_mem.user_data.

typedef void *(*nghttp3_realloc)(void *ptr, size_t size, void *user_data): nghttp3_realloc is a custom memory allocator to replace realloc(3). The user_data is the nghttp3_mem.user_data.

type nghttp3_mem

nghttp3_mem is a custom memory allocator functions and user defined pointer. The user_data field 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(3), free(3), calloc(3) and realloc(3) respectively:

void *my_malloc_cb(size_t size, void *user_data) {
  (void)user_data;
  return my_malloc(size);
}

void my_free_cb(void *ptr, void *user_data) {
  (void)user_data;
  my_free(ptr);
}

void *my_calloc_cb(size_t nmemb, size_t size, void *user_data) {
  (void)user_data;
  return my_calloc(nmemb, size);
}

void *my_realloc_cb(void *ptr, size_t size, void *user_data) {
  (void)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};

  ...
}

void *user_data: user_data is an arbitrary user supplied data. This is passed to each allocator function.

nghttp3_malloc malloc: malloc is a custom allocator function to replace malloc(3).

nghttp3_free free: free is a custom allocator function to replace free(3).

nghttp3_calloc calloc: calloc is a custom allocator function to replace calloc(3).

nghttp3_realloc realloc: realloc is a custom allocator function to replace realloc(3).

type nghttp3_vec

nghttp3_vec is struct iovec compatible structure to reference arbitrary array of bytes.

uint8_t *base: base points to the data.

size_t len: len is the number of bytes which the buffer pointed by base contains.

type nghttp3_rcbuf: nghttp3_rcbuf is the object representing reference counted buffer. The details of this structure are intentionally hidden from the public API.

type nghttp3_buf

nghttp3_buf is the variable size buffer.

uint8_t *begin: begin points to the beginning of the buffer.

uint8_t *end: end points to the one beyond of the last byte of the buffer

uint8_t *pos: pos points to the start of data. Typically, this points to the address that next data should be read. Initially, it points to begin.

uint8_t *last: 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.

type nghttp3_nv

nghttp3_nv is the name/value pair, which mainly used to represent HTTP fields.

const uint8_t *name: name is the HTTP field name.

const uint8_t *value: value is the HTTP field value.

size_t namelen: namelen is the length of the name, excluding terminating NULL.

size_t valuelen: valuelen is the length of the value, excluding terminating NULL.

uint8_t flags: flags is bitwise OR of one or more of NGHTTP3_NV_FLAG_*.

type nghttp3_qpack_nv

nghttp3_qpack_nv represents HTTP field name/value pair just like nghttp3_nv. It is an extended version of nghttp3_nv, and has reference counted buffers and tokens.

nghttp3_rcbuf *name: name is the buffer containing HTTP field name. NULL-termination is guaranteed.

nghttp3_rcbuf *value: value is the buffer containing HTTP field value. NULL-termination is guaranteed.

int32_t token: token is nghttp3_qpack_token value of name. It could be -1 if we have no token for that HTTP field name.

uint8_t flags: flags is a bitwise OR of one or more of NGHTTP3_NV_FLAG_*.

type nghttp3_qpack_encoder: nghttp3_qpack_encoder is QPACK encoder. The details of this structure are intentionally hidden from the public API.

type nghttp3_qpack_stream_context: nghttp3_qpack_stream_context is a decoder context for an individual stream. Its state is per HTTP field section. In order to reuse this object for another HTTP field section, call nghttp3_qpack_stream_context_reset(). The details of this structure are intentionally hidden from the public API.

type nghttp3_qpack_decoder: nghttp3_qpack_decoder is QPACK decoder. The details of this structure are intentionally hidden from the public API.

typedef void (*nghttp3_debug_vprintf_callback)(const char *format, va_list args)

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.

type nghttp3_conn: nghttp3_conn represents a single HTTP/3 connection. The details of this structure are intentionally hidden from the public API.

type nghttp3_settings

nghttp3_settings defines HTTP/3 settings.

uint64_t max_field_section_size: max_field_section_size specifies the maximum header section (block) size.

size_t qpack_max_dtable_capacity: qpack_max_dtable_capacity is the maximum size of QPACK dynamic table.

size_t qpack_encoder_max_dtable_capacity

qpack_encoder_max_dtable_capacity is the upper bound of QPACK dynamic table capacity that the QPACK encoder is willing to use. The effective maximum dynamic table capacity is the minimum of this field and the value of the received SETTINGS_QPACK_MAX_TABLE_CAPACITY. If this field is set to 0, the encoder does not use the dynamic table.

When nghttp3_settings is passed to nghttp3_callbacks.recv_settings callback, this field should be ignored.

size_t qpack_blocked_streams: qpack_blocked_streams is the maximum number of streams which can be blocked while they are being decoded.

uint8_t enable_connect_protocol: enable_connect_protocol, if set to nonzero, enables Extended CONNECT Method (see RFC 9220). Client ignores this field.

uint8_t h3_datagram: h3_datagram, if set to nonzero, enables HTTP/3 Datagrams (see RFC 9297).

const nghttp3_vec *origin_list: origin_list, if set, must contain a serialized HTTP/3 ORIGIN frame (see RFC 9412) payload. The ORIGIN frame payload is a sequence of zero or more of a length prefixed byte string. The length is encoded in 2 bytes in network byte order. If origin_list->len is zero, an empty ORIGIN frame is sent. An application must keep the buffer pointed by origin_list->base alive until the nghttp3_conn to which this field was passed is freed by nghttp3_conn_del(). The object pointed to by this field is copied internally, and does not need to be kept alive. Only server uses this field. This field is available since v1.11.0.

uint64_t glitch_ratelim_burst: glitch_ratelim_burst is the maximum number of tokens available to “glitch” rate limiter. “glitch” is a suspicious activity from a remote endpoint. If detected, certain amount of tokens are consumed. If no tokens are available to consume, the connection is closed. The rate of token generation is specified by glitch_ratelim_rate. This feature is enabled only when nghttp3_conn_read_stream2() is used. This field has been available since v1.12.0.

uint64_t glitch_ratelim_rate: glitch_ratelim_rate is the number of tokens generated per second. See glitch_ratelim_burst for “glitch” rate limiter. This field has been available since v1.12.0.

typedef int (*nghttp3_acked_stream_data)(nghttp3_conn *conn, int64_t stream_id, uint64_t datalen, void *conn_user_data, void *stream_user_data)

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.