Types (structs, unions and typedefs) ==================================== .. type:: ptrdiff_t nghttp3_ssize :type:`nghttp3_ssize` is signed counterpart of size_t. .. type:: void *(*nghttp3_malloc)(size_t size, void *user_data) :type:`nghttp3_malloc` is a custom memory allocator to replace :manpage:`malloc(3)`. The *user_data* is the :member:`nghttp3_mem.user_data`. .. type:: void (*nghttp3_free)(void *ptr, void *user_data) :type:`nghttp3_free` is a custom memory allocator to replace :manpage:`free(3)`. The *user_data* is the :member:`nghttp3_mem.user_data`. .. type:: void *(*nghttp3_calloc)(size_t nmemb, size_t size, void *user_data) :type:`nghttp3_calloc` is a custom memory allocator to replace :manpage:`calloc(3)`. The *user_data* is the :member:`nghttp3_mem.user_data`. .. type:: void *(*nghttp3_realloc)(void *ptr, size_t size, void *user_data) :type:`nghttp3_realloc` is a custom memory allocator to replace :manpage:`realloc(3)`. The *user_data* is the :member:`nghttp3_mem.user_data`. .. type:: nghttp3_mem :type:`nghttp3_mem` is a custom memory allocator functions and user defined pointer. The :member:`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 :manpage:`malloc(3)`, :manpage:`free(3)`, :manpage:`calloc(3)` and :manpage:`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}; ... } .. member:: void *user_data :member:`user_data` is an arbitrary user supplied data. This is passed to each allocator function. .. member:: nghttp3_malloc malloc :member:`malloc` is a custom allocator function to replace :manpage:`malloc(3)`. .. member:: nghttp3_free free :member:`free` is a custom allocator function to replace :manpage:`free(3)`. .. member:: nghttp3_calloc calloc :member:`calloc` is a custom allocator function to replace :manpage:`calloc(3)`. .. member:: nghttp3_realloc realloc :member:`realloc` is a custom allocator function to replace :manpage:`realloc(3)`. .. type:: nghttp3_vec :type:`nghttp3_vec` is ``struct iovec`` compatible structure to reference arbitrary array of bytes. .. member:: uint8_t *base :member:`base` points to the data. .. member:: size_t len :member:`len` is the number of bytes which the buffer pointed by :member:`base` contains. .. type:: nghttp3_rcbuf :type:`nghttp3_rcbuf` is the object representing reference counted buffer. The details of this structure are intentionally hidden from the public API. .. type:: nghttp3_buf :type:`nghttp3_buf` is the variable size buffer. .. member:: uint8_t *begin :member:`begin` points to the beginning of the buffer. .. member:: uint8_t *end :member:`end` points to the one beyond of the last byte of the buffer .. member:: uint8_t *pos :member:`pos` points to the start of data. Typically, this points to the address that next data should be read. Initially, it points to :member:`begin`. .. member:: uint8_t *last :member:`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 :member:`begin`. .. type:: nghttp3_nv :type:`nghttp3_nv` is the name/value pair, which mainly used to represent HTTP fields. .. member:: const uint8_t *name :member:`name` is the HTTP field name. .. member:: const uint8_t *value :member:`value` is the HTTP field value. .. member:: size_t namelen :member:`namelen` is the length of the *name*, excluding terminating NULL. .. member:: size_t valuelen :member:`valuelen` is the length of the *value*, excluding terminating NULL. .. member:: uint8_t flags :member:`flags` is bitwise OR of one or more of :macro:`NGHTTP3_NV_FLAG_* `. .. type:: nghttp3_qpack_nv :type:`nghttp3_qpack_nv` represents HTTP 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. .. member:: nghttp3_rcbuf *name :member:`name` is the buffer containing HTTP field name. NULL-termination is guaranteed. .. member:: nghttp3_rcbuf *value :member:`value` is the buffer containing HTTP field value. NULL-termination is guaranteed. .. member:: int32_t token :member:`token` is :type:`nghttp3_qpack_token` value of :member:`name`. It could be -1 if we have no token for that HTTP field name. .. member:: uint8_t flags :member:`flags` is a bitwise OR of one or more of :macro:`NGHTTP3_NV_FLAG_* `. .. type:: nghttp3_qpack_encoder :type:`nghttp3_qpack_encoder` is QPACK encoder. The details of this structure are intentionally hidden from the public API. .. type:: nghttp3_qpack_stream_context :type:`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 :type:`nghttp3_qpack_decoder` is QPACK decoder. The details of this structure are intentionally hidden from the public API. .. type:: void (*nghttp3_debug_vprintf_callback)(const char *format, va_list args) :type:`nghttp3_debug_vprintf_callback` is a callback function invoked when the library outputs debug logging. The function is called with arguments suitable for :manpage:`vfprintf(3)`. The debug output is only enabled if the library is built with :macro:`DEBUGBUILD` macro defined. .. type:: nghttp3_conn :type:`nghttp3_conn` represents a single HTTP/3 connection. The details of this structure are intentionally hidden from the public API. .. type:: nghttp3_settings :type:`nghttp3_settings` defines HTTP/3 settings. .. member:: uint64_t max_field_section_size :member:`max_field_section_size` specifies the maximum header section (block) size. .. member:: size_t qpack_max_dtable_capacity :member:`qpack_max_dtable_capacity` is the maximum size of QPACK dynamic table. .. member:: size_t qpack_encoder_max_dtable_capacity :member:`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 :type:`nghttp3_settings` is passed to :member:`nghttp3_callbacks.recv_settings` callback, this field should be ignored. .. member:: size_t qpack_blocked_streams :member:`qpack_blocked_streams` is the maximum number of streams which can be blocked while they are being decoded. .. member:: uint8_t enable_connect_protocol :member:`enable_connect_protocol`, if set to nonzero, enables Extended CONNECT Method (see :rfc:`9220`). Client ignores this field. .. member:: uint8_t h3_datagram :member:`h3_datagram`, if set to nonzero, enables HTTP/3 Datagrams (see :rfc:`9297`). .. type:: int (*nghttp3_acked_stream_data)(nghttp3_conn *conn, int64_t stream_id, uint64_t datalen, void *conn_user_data, void *stream_user_data) :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 :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_stream_close)(nghttp3_conn *conn, int64_t stream_id, uint64_t app_error_code, void *conn_user_data, void *stream_user_data) :type:`nghttp3_conn_stream_close` is a callback function which is invoked when a stream identified by *stream_id* is closed. QUIC application error code *app_error_code* indicates the reason of this closure. The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: 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) :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 (say, increasing by *datalen* bytes). The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_deferred_consume)(nghttp3_conn *conn, int64_t stream_id, size_t consumed, void *conn_user_data, void *stream_user_data) :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 due to synchronization between streams. The application is responsible for increasing flow control credit by *consumed* bytes. The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_begin_headers)(nghttp3_conn *conn, int64_t stream_id, void *conn_user_data, void *stream_user_data) :type:`nghttp3_begin_headers` 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 :type:`nghttp3_recv_header` callback. And then :type:`nghttp3_end_headers` is called when a whole HTTP field section is processed. The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: 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) :type:`nghttp3_recv_header` 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 :type:`nghttp3_qpack_token` or -1 if no token is defined for *name*. *flags* is bitwise OR of zero or more of :macro:`NGHTTP3_NV_FLAG_* `. The buffers for *name* and *value* are reference counted. If application needs to keep them, increment the reference count with `nghttp3_rcbuf_incref`. When they are no longer used, call `nghttp3_rcbuf_decref`. The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_end_headers)(nghttp3_conn *conn, int64_t stream_id, int fin, void *conn_user_data, void *stream_user_data) :type:`nghttp3_end_headers` 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 :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_end_stream)(nghttp3_conn *conn, int64_t stream_id, void *conn_user_data, void *stream_user_data) :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 :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_stop_sending)(nghttp3_conn *conn, int64_t stream_id, uint64_t app_error_code, void *conn_user_data, void *stream_user_data) :type:`nghttp3_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*. QUIC application error code *app_error_code* indicates the reason for this action. The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_reset_stream)(nghttp3_conn *conn, int64_t stream_id, uint64_t app_error_code, void *conn_user_data, void *stream_user_data) :type:`nghttp3_reset_stream` is a callback function which is invoked when the library asks application to reset stream identified by *stream_id*. QUIC application error code *app_error_code* indicates the reason for this action. The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_shutdown)(nghttp3_conn *conn, int64_t id, void *conn_user_data) :type:`nghttp3_shutdown` is a callback function which is invoked when a shutdown is initiated by the remote endpoint. For client, *id* contains a stream ID of a client initiated stream, for server, it contains a push ID. All client streams with stream ID, or pushes with push ID equal to, or larger than *ID* are guaranteed to not be processed by the remote endpoint. Note that libnghttp3 does not implement Server Push. Parameter *id* for client can contain a special value :macro:`NGHTTP3_SHUTDOWN_NOTICE_STREAM_ID`, and for server it can contain special value :macro:`NGHTTP3_SHUTDOWN_NOTICE_PUSH_ID`. These values signal request for graceful shutdown of the connection, triggered by remote endpoint's invocation of `nghttp3_conn_submit_shutdown_notice`. It is possible that this callback is invoked multiple times on a single connection, however the *id* can only stay the same or decrease, never increase. The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: int (*nghttp3_recv_settings)(nghttp3_conn *conn, const nghttp3_settings *settings, void *conn_user_data) :type:`nghttp3_recv_settings` is a callback function which is invoked when SETTINGS frame is received. *settings* is a received remote HTTP/3 settings. The implementation of this callback must return 0 if it succeeds. Returning :macro:`NGHTTP3_ERR_CALLBACK_FAILURE` will return to the caller immediately. Any values other than 0 is treated as :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. .. type:: nghttp3_callbacks :type:`nghttp3_callbacks` holds a set of callback functions. .. member:: nghttp3_acked_stream_data acked_stream_data :member:`acked_stream_data` is a callback function which is invoked when data sent on a particular stream have been acknowledged by a remote endpoint. .. member:: nghttp3_stream_close stream_close :member:`stream_close` is a callback function which is invoked when a particular stream has closed. .. member:: nghttp3_recv_data recv_data :member:`recv_data` is a callback function which is invoked when stream data is received. .. member:: nghttp3_deferred_consume deferred_consume :member:`deferred_consume` is a callback function which is invoked when the library consumed data for a particular stream which had been blocked for synchronization between streams. .. member:: nghttp3_begin_headers begin_headers :member:`begin_headers` is a callback function which is invoked when an HTTP header field section has started on a particular stream. .. member:: nghttp3_recv_header recv_header :member:`recv_header` is a callback function which is invoked when a single HTTP header field is received on a particular stream. .. member:: nghttp3_end_headers end_headers :member:`end_headers` is a callback function which is invoked when an HTTP header field section has ended on a particular stream. .. member:: nghttp3_begin_headers begin_trailers :member:`begin_trailers` is a callback function which is invoked when an HTTP trailer field section has started on a particular stream. .. member:: nghttp3_recv_header recv_trailer :member:`recv_trailer` is a callback function which is invoked when a single HTTP trailer field is received on a particular stream. .. member:: nghttp3_end_headers end_trailers :member:`end_trailers` is a callback function which is invoked when an HTTP trailer field section has ended on a particular stream. .. member:: nghttp3_stop_sending stop_sending :member:`stop_sending` is a callback function which is invoked when the library asks application to send STOP_SENDING to a particular stream. .. member:: nghttp3_end_stream end_stream :member:`end_stream` is a callback function which is invoked when a receiving side of stream has been closed. .. member:: nghttp3_reset_stream reset_stream :member:`reset_stream` is a callback function which is invoked when the library asks application to reset stream (by sending RESET_STREAM). .. member:: nghttp3_shutdown shutdown :member:`shutdown` is a callback function which is invoked when the remote endpoint has signalled initiation of connection shutdown. .. member:: nghttp3_recv_settings recv_settings :member:`recv_settings` is a callback function which is invoked when SETTINGS frame is received. .. type:: 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) :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 :macro:`NGHTTP3_DATA_FLAG_EOF` to *\*pflags*. If the application is unable to provide data temporarily, return :macro:`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 :macro:`NGHTTP3_ERR_CALLBACK_FAILURE`. TODO Add NGHTTP3_ERR_TEMPORAL_CALLBACK_FAILURE to reset just this stream. .. type:: nghttp3_data_reader :type:`nghttp3_data_reader` specifies the way how to generate request or response body. .. member:: nghttp3_read_data_callback read_data :member:`read_data` is a callback function to generate body. .. type:: nghttp3_pri :type:`nghttp3_pri` represents HTTP priority. .. member:: uint32_t urgency :member:`urgency` is the urgency of a stream, it must be in [:macro:`NGHTTP3_URGENCY_HIGH`, :macro:`NGHTTP3_URGENCY_LOW`], inclusive, and 0 is the highest urgency. .. member:: uint8_t inc :member:`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:: nghttp3_info :type:`nghttp3_info` is what `nghttp3_version` returns. It holds information about the particular nghttp3 version. .. member:: int age :member:`age` is the 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 .. member:: int version_num :member:`version_num` is the :macro:`NGHTTP3_VERSION_NUM` number (since age == 1) .. member:: const char *version_str :member:`version_str` points to the :macro:`NGHTTP3_VERSION` string (since age ==1)