Types (structs, unions and typedefs)

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

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

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

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

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

type nghttp2_mem

nghttp2_mem is a custom memory allocator. The user_data field is passed to each allocator function. This can be used, for example, to achieve per-connection 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() {
  nghttp2_mem mem = {
    .malloc = my_malloc_cb,
    .free = my_free_cb,
    .calloc = my_calloc_cb,
    .realloc = my_realloc_cb,
  };

  ...
}

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

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

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

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

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

type nghttp2_vec

nghttp2_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.

typedef uint64_t nghttp2_tstamp: nghttp2_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.

typedef uint64_t nghttp2_duration: nghttp2_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.

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

type nghttp2_buf

nghttp2_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 nghttp2_nv

nghttp2_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 NGHTTP2_NV_FLAG_*.

type nghttp2_hpack_nv

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

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

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

int32_t token: token is nghttp2_hpack_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 NGHTTP2_NV_FLAG_*.

type nghttp2_conn: nghttp2_conn represents a single HTTP/2 connection.

typedef void (*nghttp2_log_write)(void *user_data, char *msg, size_t len): nghttp2_log_write is a callback function for logging. user_data is the same object passed to nghttp2_conn_client_new() or nghttp2_conn_server_new(). The caller guarantees that the memory region [msg, msg + len], inclusive, are writable, and msg*[*len] == ‘0’. If application needs to emit a single line with a line terminator, one can do msg[len] = ‘n’, and write len + 1 bytes from msg.

type nghttp2_settings_entry

nghttp2_settings_entry contains the SETTINGS ID and its value.

uint16_t id: id is the SETTINGS ID.

uint32_t value: value is the SETTINGS value.

type nghttp2_settings

nghttp2_settings defines HTTP/2 connection settings.

uint64_t conn_id: conn_id is the identifier of this connection. Currently, it is used in a log header so that people can distinguish the particular connection from the others.

nghttp2_tstamp initial_ts: initial_ts is an initial timestamp given to the library. This should be set to the current timestamp.

nghttp2_log_write log_write: log_write is the callback function when a single log message is emitted. If this field is NULL, logging is disabled.

nghttp2_duration settings_timeout: settings_timeout is the timeout before receiving SETTINGS frame with ACK flag set. Setting UINT64_MAX disables timeout.

size_t hpack_max_dtable_capacity: hpack_max_dtable_capacity is the maximum size of HPACK dynamic table.

size_t hpack_encoder_max_dtable_capacity: hpack_encoder_max_dtable_capacity is the upper bound of HPACK dynamic table capacity that the HPACK encoder is willing to use. The effective maximum dynamic table capacity is the minimum of this field and the value of the received SETTINGS_HEADER_TABLE_SIZE. If this field is set to 0, the encoder does not use the dynamic table.

size_t max_concurrent_streams_local: max_concurrent_streams_local is the number of concurrent streams that a local endpoint can open until the actual limit is known. When SETTINGS frame is received from the remote endpoint, and if SETTINGS_MAX_CONCURRENT_STREAMS is not included in the frame, the limit is unchanged because the unlimited concurrent stream is insane.

size_t max_concurrent_streams_remote: max_concurrent_streams_remote is the number of concurrent streams that a remote endpoint can open.

size_t initial_max_stream_data: initial_max_stream_data is the window size for stream-level flow control.

size_t initial_max_data: initial_max_data is the window size for connection-level flow control.

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

const nghttp2_settings_entry *extra_settings: extra_settings points to the array that contains the extra SETTINGS entries to be sent to the remote endpoint. The number of elements is specified by extra_settingslen. The maximum number of elements is NGHTTP2_MAX_EXTRA_SETTINGS. The excess elements are discarded. The library does not perform any validations and just sends them as is. Therefore, the application must be cautious not to specify SETTINGS that are handled by the library. It is best to use this field for the experimental and testing purposes only. When nghttp2_settings is passed to nghttp2_conn_server_new() or nghttp2_conn_client_new(), they make a copy of all elements pointed by this field.

size_t extra_settingslen: extra_settingslen specifies the number of elements contained in extra_settings.

uint64_t glitch_ratelim_burst: glitch_ratelim_burst is the maximum number of tokens available to “glitch” rate limiter. It is clamped to UINT64_MAX / NGHTTP2_SECONDS. “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.

uint64_t glitch_ratelim_rate: glitch_ratelim_rate is the number of tokens generated per second. See glitch_ratelim_burst for “glitch” rate limiter.

type nghttp2_proto_settings

nghttp2_proto_settings contains HTTP/2 settings that this library can recognize.

size_t hpack_max_dtable_capacity: hpack_max_dtable_capacity is the maximum size of HPACK dynamic table. It corresponds to SETTINGS_HEADER_TABLE_SIZE.

size_t max_concurrent_streams: max_concurrent_streams is the maximum number of the concurrent streams that the receiver can open. It corresponds to SETTINGS_MAX_CONCURRENT_STREAMS.

size_t initial_max_stream_data: initial_max_stream_data is the initial window size of stream-level flow control. It corresponds to SETTINGS_INITIAL_WINDOW_SIZE.

size_t max_field_section_size: max_field_section_size specifies the maximum header section (block) size. It corresponds to SETTINGS_MAX_HEADER_LIST_SIZE.

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

typedef int (*nghttp2_recv_settings_entry)(nghttp2_conn *conn, const nghttp2_settings_entry *ent, void *conn_user_data)

nghttp2_recv_settings_entry is a callback function which is invoked when each SETTINGS entry is received. ent contains the received SETTINGS entry.

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_recv_settings)(nghttp2_conn *conn, const nghttp2_proto_settings *settings, void *conn_user_data)

nghttp2_recv_settings is a callback function which is invoked when SETTINGS frame is received. settings is a received remote HTTP/2 settings.

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_recv_settings_ack)(nghttp2_conn *conn, void *conn_user_data)

nghttp2_recv_settings_ack is a callback function which is invoked when SETTINGS frame with ACK flag set is received.

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_stream_open)(nghttp2_conn *conn, int64_t stream_id, void *conn_user_data)

nghttp2_stream_open is a callback function which is called when remote stream is opened by a remote endpoint. This function is not called if stream is opened by implicitly (we might reconsider this behaviour later).

The implementation of this callback should return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*nghttp2_stream_close)(nghttp2_conn *conn, uint32_t flags, int64_t stream_id, uint32_t error_code, void *conn_user_data, void *stream_user_data)

nghttp2_stream_close is invoked when a stream is closed. This callback is not called when HTTP/2 connection is closed before existing streams are closed. flags is the bitwise-OR of zero or more of NGHTTP2_STREAM_CLOSE_FLAG_*. error_code indicates the error code that shut down this stream if NGHTTP2_STREAM_CLOSE_FLAG_ERROR_CODE_SET is set in flags. No error code means that a stream is closed cleanly.

The implementation of this callback should return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef void (*nghttp2_rand)(uint8_t *dest, size_t destlen): nghttp2_rand is a callback function which is invoked when unpredictable data of destlen bytes are needed. The implementation must write unpredictable data of destlen bytes into the buffer pointed by dest.

typedef int (*nghttp2_write_stream_data_offset)(nghttp2_conn *conn, int64_t stream_id, uint64_t offset, size_t len, void *conn_user_data, void *stream_user_data)

nghttp2_write_stream_data_offset is a callback function which is invoked when the stream data is written to DATA frame. stream_id identifies the stream. offset is the starting offset of the stream data. len is the length of the stream data.

The callback function must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*nghttp2_begin_fields)(nghttp2_conn *conn, int64_t stream_id, void *conn_user_data, void *stream_user_data)

nghttp2_begin_fields is a callback function which is invoked when an incoming HTTP field section is started on a stream denoted by stream_id. Each HTTP field is passed to application by nghttp2_recv_field callback. And then nghttp2_end_fields is called when a whole HTTP field section is processed.

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_recv_field)(nghttp2_conn *conn, int64_t stream_id, int32_t token, nghttp2_rcbuf *name, nghttp2_rcbuf *value, uint8_t flags, void *conn_user_data, void *stream_user_data)

nghttp2_recv_field is a callback function which is invoked when an HTTP field is received on a stream denoted by stream_id. name contains a field name, and value contains a field value. token is one of token defined in nghttp2_hpack_token or -1 if no token is defined for name. flags is bitwise OR of zero or more of NGHTTP2_NV_FLAG_*.

The buffers for name and value are reference counted. If application needs to keep them, increment the reference count with nghttp2_rcbuf_incref(). When they are no longer used, call nghttp2_rcbuf_decref().

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_end_fields)(nghttp2_conn *conn, int64_t stream_id, int fin, void *conn_user_data, void *stream_user_data)

nghttp2_end_fields is a callback function which is invoked when an incoming HTTP field section has ended.

If the stream ends with this HTTP field section, fin is set to nonzero.

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_recv_data)(nghttp2_conn *conn, int64_t stream_id, const uint8_t *data, size_t datalen, void *conn_user_data, void *stream_user_data)

nghttp2_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 (say, increasing by datalen bytes).

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_end_stream)(nghttp2_conn *conn, int64_t stream_id, void *conn_user_data, void *stream_user_data)

nghttp2_end_stream is a callback function which is invoked when the one side of stream is closed.

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_recv_ping_ack)(nghttp2_conn *conn, const nghttp2_ping_data *data, nghttp2_duration rtt, void *conn_user_data)

nghttp2_recv_ping_ack is a callback function which is invoked when PING with ACK flag set is received. data contains the data received with PING frame. This is the data that the local endpoint sent to the remote endpoint. The data is 8 bytes long. rtt is the round trip time between the transmission of PING frame and the reception of its acknowledgement.

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

typedef int (*nghttp2_shutdown)(nghttp2_conn *conn, int64_t last_stream_id, uint32_t error_code, void *conn_user_data)

nghttp2_shutdown is a callback function which is invoked when a shutdown is initiated by the remote endpoint. For client, last_stream_id contains a stream ID of a client initiated stream, for server, it contains a stream ID of server push. All client streams with stream ID larger than last_stream_id are guaranteed not to be processed by the remote endpoint. Because libnghttp2 does not implement Server Push, the server should ignore last_stream_id.

It is possible that this callback is invoked multiple times on a single connection, however the last_stream_id can only stay the same or decrease, never increase.

The implementation of this callback must return 0 if it succeeds. Returning NGHTTP2_ERR_CALLBACK_FAILURE will return to the caller immediately. Any values other than 0 is treated as NGHTTP2_ERR_CALLBACK_FAILURE.

type nghttp2_callbacks

nghttp2_callbacks holds a set of callback functions.

nghttp2_rand rand: rand is a callback function which is invoked when the library needs random data. This callback function must be specified.

nghttp2_recv_settings_entry recv_settings_entry: recv_settings_entry is a callback function which is invoked when SETTINGS entry is received from the remote endpoint. This callback function is optional.

nghttp2_recv_settings recv_settings: recv_settings is a callback function which is invoked when SETTINGS frame is received from the remote endpoint. This callback function is optional.

nghttp2_recv_settings_ack recv_settings_ack: recv_settings_ack is a callback function which is invoked when SETTINGS frame with ACK flag set is received from the remote endpoint. This callback function is optional.

nghttp2_stream_open stream_open: stream_open is a callback function which is invoked when new remote stream is opened by a remote endpoint. This callback function is optional.

nghttp2_stream_close stream_close: stream_close is a callback function which is invoked when a stream is closed. This callback function is optional.

nghttp2_write_stream_data_offset write_stream_data_offset: write_stream_data_offset is a callback function which is invoked when the stream data is written. This callback function is optional.

nghttp2_begin_fields begin_headers: begin_headers is a callback function which is invoked when an HTTP header field section has started on a particular stream. This callback function is optional.

nghttp2_recv_field recv_header: recv_header is a callback function which is invoked when a single HTTP header field is received on a particular stream. This callback function is optional.

nghttp2_end_fields end_headers: end_headers is a callback function which is invoked when an HTTP header field section has ended on a particular stream. This callback function is optional.

nghttp2_begin_fields begin_trailers: begin_trailers is a callback function which is invoked when an HTTP trailer field section has started on a particular stream. This callback function is optional.

nghttp2_recv_field recv_trailer: recv_trailer is a callback function which is invoked when a single HTTP trailer field is received on a particular stream. This callback function is optional.

nghttp2_end_fields end_trailers: end_trailers is a callback function which is invoked when an HTTP trailer field section has ended on a particular stream. This callback function is optional.

nghttp2_recv_data recv_data: recv_data is a callback function which is invoked when stream data is received. This callback function is optional.

nghttp2_end_stream local_end_stream: local_end_stream is a callback function which is invoked when a sending side of stream has been closed. For server, this callback function is invoked when HTTP response is sent completely. For client, this callback function is invoked when HTTP request is sent completely. This callback function is optional.

nghttp2_end_stream remote_end_stream: remote_end_stream is a callback function which is invoked when a receiving side of stream has been 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. This callback function is optional.

nghttp2_recv_ping_ack recv_ping_ack: recv_ping_ack is a callback function which is invoked when PING frame with ACK flag set is received. This callback function is optional.

nghttp2_shutdown shutdown: shutdown is a callback function which is invoked when GOAWAY frame is received. This callback function is optional.

typedef nghttp2_ssize (*nghttp2_read_data)(nghttp2_conn *conn, int64_t stream_id, nghttp2_vec *vec, size_t veccnt, uint32_t *pflags, void *conn_user_data, void *stream_user_data)

nghttp2_read_data 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 nghttp2_write_stream_data_offset callback.

If this is the last data to send (or there is no data to send because all data have been sent already), set NGHTTP2_READ_DATA_FLAG_EOF to *pflags.

If the application is unable to provide data temporarily, return NGHTTP2_ERR_WOULDBLOCK. When it is ready to provide data, call nghttp2_conn_resume_stream().

If the callback returns 0 or the sum of length in vec is 0, and NGHTTP2_READ_DATA_FLAG_EOF is not set in *pflags, it is treated as if NGHTTP2_ERR_CALLBACK_FAILURE is returned.

The callback should return the number of objects in vec that the application filled if it succeeds, or NGHTTP2_ERR_CALLBACK_FAILURE.

type nghttp2_data_reader

nghttp2_data_reader specifies the way how to generate request or response body.

nghttp2_read_data read_data: read_data is a callback function to generate body.

type nghttp2_pri

nghttp2_pri represents HTTP priority.

uint32_t urgency: urgency is the urgency of a stream, it must be in [NGHTTP2_URGENCY_HIGH, NGHTTP2_URGENCY_LOW], inclusive, and 0 is the highest urgency.

uint8_t inc: inc indicates that a content can be processed incrementally or not. If it is 0, it cannot be processed incrementally. If it is 1, it can be processed incrementally. Other value is not permitted.

type nghttp2_hpack_encoder: nghttp2_hpack_encoder represents HPACK encoder.

type nghttp2_hpack_decoder: nghttp2_hpack_decoder represents HPACK decoder.