Types (structs, unions and typedefs) ==================================== .. type:: ptrdiff_t ngtcp2_ssize :type:`ngtcp2_ssize` is signed counterpart of size_t. .. type:: void *(*ngtcp2_malloc)(size_t size, void *user_data) :type:`ngtcp2_malloc` is a custom memory allocator to replace :manpage:`malloc(3)`. The *user_data* is :member:`ngtcp2_mem.user_data`. .. type:: void (*ngtcp2_free)(void *ptr, void *user_data) :type:`ngtcp2_free` is a custom memory allocator to replace :manpage:`free(3)`. The *user_data* is :member:`ngtcp2_mem.user_data`. .. type:: void *(*ngtcp2_calloc)(size_t nmemb, size_t size, void *user_data) :type:`ngtcp2_calloc` is a custom memory allocator to replace :manpage:`calloc(3)`. The *user_data* is the :member:`ngtcp2_mem.user_data`. .. type:: void *(*ngtcp2_realloc)(void *ptr, size_t size, void *user_data) :type:`ngtcp2_realloc` is a custom memory allocator to replace :manpage:`realloc(3)`. The *user_data* is the :member:`ngtcp2_mem.user_data`. .. type:: ngtcp2_mem :type:`ngtcp2_mem` is a custom memory allocator. The :member:`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 :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() { ngtcp2_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:: ngtcp2_malloc malloc :member:`malloc` is a custom allocator function to replace :manpage:`malloc(3)`. .. member:: ngtcp2_free free :member:`free` is a custom allocator function to replace :manpage:`free(3)`. .. member:: ngtcp2_calloc calloc :member:`calloc` is a custom allocator function to replace :manpage:`calloc(3)`. .. member:: ngtcp2_realloc realloc :member:`realloc` is a custom allocator function to replace :manpage:`realloc(3)`. .. type:: ngtcp2_pkt_info :type:`ngtcp2_pkt_info` is a packet metadata. .. member:: uint8_t ecn :member:`ecn` is ECN marking, and when it is passed to `ngtcp2_conn_read_pkt()`, it should be either :macro:`NGTCP2_ECN_NOT_ECT`, :macro:`NGTCP2_ECN_ECT_1`, :macro:`NGTCP2_ECN_ECT_0`, or :macro:`NGTCP2_ECN_CE`. .. type:: uint64_t ngtcp2_tstamp :type:`ngtcp2_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. .. type:: uint64_t ngtcp2_duration :type:`ngtcp2_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:: ngtcp2_cid :type:`ngtcp2_cid` holds a Connection ID. .. member:: size_t datalen :member:`datalen` is the length of Connection ID. .. member:: uint8_t data[NGTCP2_MAX_CIDLEN] :member:`data` is the buffer to store Connection ID. .. type:: ngtcp2_vec :type:`ngtcp2_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 base contains. .. type:: ngtcp2_pkt_hd :type:`ngtcp2_pkt_hd` represents QUIC packet header. .. member:: ngtcp2_cid dcid :member:`dcid` is Destination Connection ID. .. member:: ngtcp2_cid scid :member:`scid` is Source Connection ID. .. member:: int64_t pkt_num :member:`pkt_num` is a packet number. .. member:: const uint8_t *token :member:`token` contains token. Only Initial packet may contain token. NULL if no token is present. .. member:: size_t tokenlen :member:`tokenlen` is the length of :member:`token`. 0 if no token is present. .. member:: size_t pkt_numlen :member:`pkt_numlen` is the number of bytes spent to encode :member:`pkt_num`. .. member:: size_t len :member:`len` is the sum of :member:`pkt_numlen` and the length of QUIC packet payload. .. member:: uint32_t version :member:`version` is QUIC version. .. member:: uint8_t type :member:`type` is a type of QUIC packet. This field does not have a QUIC packet type defined for a specific QUIC version. Instead, it contains version independent packet type defined by this library. See :type:`ngtcp2_pkt_type`. .. member:: uint8_t flags :member:`flags` is zero or more of :macro:`NGTCP2_PKT_FLAG_* `. .. type:: ngtcp2_pkt_stateless_reset :type:`ngtcp2_pkt_stateless_reset` represents Stateless Reset. .. member:: uint8_t stateless_reset_token[NGTCP2_STATELESS_RESET_TOKENLEN] :member:`stateless_reset_token` contains stateless reset token. .. member:: const uint8_t *rand :member:`rand` points a buffer which contains random bytes section. .. member:: size_t randlen :member:`randlen` is the number of random bytes. .. type:: struct sockaddr ngtcp2_sockaddr :type:`ngtcp2_sockaddr` is typedefed to struct sockaddr. If :macro:`NGTCP2_USE_GENERIC_SOCKADDR` is defined, it is typedefed to the generic struct sockaddr defined in ngtcp2.h. .. type:: struct sockaddr_in ngtcp2_sockaddr_in :type:`ngtcp2_sockaddr_in` is typedefed to struct sockaddr_in. If :macro:`NGTCP2_USE_GENERIC_SOCKADDR` is defined, it is typedefed to the generic struct sockaddr_in defined in ngtcp2.h. .. type:: struct sockaddr_in6 ngtcp2_sockaddr_in6 :type:`ngtcp2_sockaddr_in6` is typedefed to struct sockaddr_in6. If :macro:`NGTCP2_USE_GENERIC_SOCKADDR` is defined, it is typedefed to the generic struct sockaddr_in6 defined in ngtcp2.h. .. type:: socklen_t ngtcp2_socklen :type:`ngtcp2_socklen` is typedefed to socklen_t. If :macro:`NGTCP2_USE_GENERIC_SOCKADDR` is defined, it is typedefed to uint32_t. .. type:: ngtcp2_sockaddr_union :type:`ngtcp2_sockaddr_union` conveniently includes all supported address types. .. type:: ngtcp2_preferred_addr :type:`ngtcp2_preferred_addr` represents preferred address structure. .. member:: ngtcp2_cid cid :member:`cid` is a Connection ID. .. member:: ngtcp2_sockaddr_in ipv4 :member:`ipv4` contains IPv4 address and port. .. member:: ngtcp2_sockaddr_in6 ipv6 :member:`ipv6` contains IPv6 address and port. .. member:: uint8_t ipv4_present :member:`ipv4_present` indicates that :member:`ipv4` contains IPv4 address and port. .. member:: uint8_t ipv6_present :member:`ipv6_present` indicates that :member:`ipv6` contains IPv6 address and port. .. member:: uint8_t stateless_reset_token[NGTCP2_STATELESS_RESET_TOKENLEN] :member:`stateless_reset_token` contains stateless reset token. .. type:: ngtcp2_version_info :type:`ngtcp2_version_info` represents version_information structure. See :rfc:`9368`. .. member:: uint32_t chosen_version :member:`chosen_version` is the version chosen by the sender. .. member:: const uint8_t *available_versions :member:`available_versions` points the wire image of available_versions field. The each version is therefore in network byte order. .. member:: size_t available_versionslen :member:`available_versionslen` is the number of bytes pointed by :member:`available_versions`, not the number of versions included. .. type:: ngtcp2_transport_params :type:`ngtcp2_transport_params` represents QUIC transport parameters. .. member:: ngtcp2_preferred_addr preferred_addr :member:`preferred_addr` contains preferred address if :member:`preferred_addr_present` is nonzero. .. member:: ngtcp2_cid original_dcid :member:`original_dcid` is the Destination Connection ID field from the first Initial packet from client. Server must specify this field and set :member:`original_dcid_present` to nonzero. It is expected that application knows the original Destination Connection ID even if it sends Retry packet, for example, by including it in retry token. Otherwise, application should not specify this field. .. member:: ngtcp2_cid initial_scid :member:`initial_scid` is the Source Connection ID field from the first Initial packet the local endpoint sends. Application should not specify this field. If :member:`initial_scid_present` is set to nonzero, it indicates this field is set. .. member:: ngtcp2_cid retry_scid :member:`retry_scid` is the Source Connection ID field from Retry packet. Only server uses this field. If server application received Initial packet with retry token from client, and server successfully verified its token, server application must set Destination Connection ID field from the Initial packet to this field, and set :member:`retry_scid_present` to nonzero. Server application must verify that the Destination Connection ID from Initial packet was sent in Retry packet by, for example, including the Connection ID in a token, or including it in AAD when encrypting a token. .. member:: uint64_t initial_max_stream_data_bidi_local :member:`initial_max_stream_data_bidi_local` is the size of flow control window of locally initiated stream. This is the number of bytes that the remote endpoint can send, and the local endpoint must ensure that it has enough buffer to receive them. .. member:: uint64_t initial_max_stream_data_bidi_remote :member:`initial_max_stream_data_bidi_remote` is the size of flow control window of remotely initiated stream. This is the number of bytes that the remote endpoint can send, and the local endpoint must ensure that it has enough buffer to receive them. .. member:: uint64_t initial_max_stream_data_uni :member:`initial_max_stream_data_uni` is the size of flow control window of remotely initiated unidirectional stream. This is the number of bytes that the remote endpoint can send, and the local endpoint must ensure that it has enough buffer to receive them. .. member:: uint64_t initial_max_data :member:`initial_max_data` is the connection level flow control window. .. member:: uint64_t initial_max_streams_bidi :member:`initial_max_streams_bidi` is the number of concurrent streams that the remote endpoint can create. .. member:: uint64_t initial_max_streams_uni :member:`initial_max_streams_uni` is the number of concurrent unidirectional streams that the remote endpoint can create. .. member:: ngtcp2_duration max_idle_timeout :member:`max_idle_timeout` is a duration during which sender allows quiescent. 0 means no idle timeout. It must not be UINT64_MAX. .. member:: uint64_t max_udp_payload_size :member:`max_udp_payload_size` is the maximum UDP payload size that the local endpoint can receive. .. member:: uint64_t active_connection_id_limit :member:`active_connection_id_limit` is the maximum number of Connection ID that sender can store. .. member:: uint64_t ack_delay_exponent :member:`ack_delay_exponent` is the exponent used in ACK Delay field in ACK frame. .. member:: ngtcp2_duration max_ack_delay :member:`max_ack_delay` is the maximum acknowledgement delay by which the local endpoint will delay sending acknowledgements. It must be strictly less than (1 << 14) milliseconds. Sub-millisecond part is dropped when sending it in a QUIC transport parameter. .. member:: uint64_t max_datagram_frame_size :member:`max_datagram_frame_size` is the maximum size of DATAGRAM frame that the local endpoint willingly receives. Specifying 0 disables DATAGRAM support. See :rfc:`9221`. .. member:: uint8_t stateless_reset_token_present :member:`stateless_reset_token_present` is nonzero if :member:`stateless_reset_token` field is set. .. member:: uint8_t disable_active_migration :member:`disable_active_migration` is nonzero if the local endpoint does not support active connection migration. .. member:: uint8_t original_dcid_present :member:`original_dcid_present` is nonzero if :member:`original_dcid` field is set. .. member:: uint8_t initial_scid_present :member:`initial_scid_present` is nonzero if :member:`initial_scid` field is set. .. member:: uint8_t retry_scid_present :member:`retry_scid_present` is nonzero if :member:`retry_scid` field is set. .. member:: uint8_t preferred_addr_present :member:`preferred_addr_present` is nonzero if :member:`preferred_address` is set. .. member:: uint8_t stateless_reset_token[NGTCP2_STATELESS_RESET_TOKENLEN] :member:`stateless_reset_token` contains stateless reset token. .. member:: uint8_t grease_quic_bit :member:`grease_quic_bit` is nonzero if sender supports "Greasing the QUIC Bit" extension. See :rfc:`9287`. .. member:: ngtcp2_version_info version_info :member:`version_info` contains version_information field if :member:`version_info_present` is nonzero. Application should not specify this field. .. member:: uint8_t version_info_present :member:`version_info_present` is nonzero if :member:`version_info` is set. Application should not specify this field. .. type:: ngtcp2_conn_info :type:`ngtcp2_conn_info` holds various connection statistics. .. member:: ngtcp2_duration latest_rtt :member:`latest_rtt` is the latest RTT sample which is not adjusted by acknowledgement delay. .. member:: ngtcp2_duration min_rtt :member:`min_rtt` is the minimum RTT seen so far. It is not adjusted by acknowledgement delay. .. member:: ngtcp2_duration smoothed_rtt :member:`smoothed_rtt` is the smoothed RTT. .. member:: ngtcp2_duration rttvar :member:`rttvar` is a mean deviation of observed RTT. .. member:: uint64_t cwnd :member:`cwnd` is the size of congestion window. .. member:: uint64_t ssthresh :member:`ssthresh` is slow start threshold. .. member:: uint64_t bytes_in_flight :member:`bytes_in_flight` is the number in bytes of all sent packets which have not been acknowledged. .. type:: void (*ngtcp2_printf)(void *user_data, const char *format, ...) :type:`ngtcp2_printf` is a callback function for logging. *user_data* is the same object passed to `ngtcp2_conn_client_new` or `ngtcp2_conn_server_new`. .. type:: ngtcp2_rand_ctx :type:`ngtcp2_rand_ctx` is a wrapper around native random number generator. It is opaque to the ngtcp2 library. This might be useful if application needs to specify random number generator per thread or per connection. .. member:: void *native_handle :member:`native_handle` is a pointer to an underlying random number generator. .. type:: void (*ngtcp2_qlog_write)(void *user_data, uint32_t flags, const void *data, size_t datalen) :type:`ngtcp2_qlog_write` is a callback function which is called to write qlog *data* of length *datalen* bytes. *flags* is bitwise OR of zero or more of :macro:`NGTCP2_QLOG_WRITE_FLAG_* `. If :macro:`NGTCP2_QLOG_WRITE_FLAG_FIN` is set, *datalen* may be 0. .. type:: ngtcp2_settings :type:`ngtcp2_settings` defines QUIC connection settings. .. member:: ngtcp2_qlog_write qlog_write :member:`qlog_write` is a callback function to write qlog. Setting ``NULL`` disables qlog. .. member:: ngtcp2_cc_algo cc_algo :member:`cc_algo` specifies congestion control algorithm. .. member:: ngtcp2_tstamp initial_ts :member:`initial_ts` is an initial timestamp given to the library. .. member:: ngtcp2_duration initial_rtt :member:`initial_rtt` is an initial RTT. .. member:: ngtcp2_printf log_printf :member:`log_printf` is a function that the library uses to write logs. ``NULL`` means no logging output. It is nothing to do with qlog. .. member:: size_t max_tx_udp_payload_size :member:`max_tx_udp_payload_size` is the maximum size of UDP datagram payload that the local endpoint transmits. .. member:: const uint8_t *token :member:`token` is a token from Retry packet or NEW_TOKEN frame. Server sets this field if it received the token in Client Initial packet and successfully validated. It should also set :member:`token_type` field. Client sets this field if it intends to send token in its Initial packet. `ngtcp2_conn_server_new` and `ngtcp2_conn_client_new` make a copy of token. Set NULL if there is no token. .. member:: size_t tokenlen :member:`tokenlen` is the length of :member:`token`. Set 0 if there is no token. .. member:: ngtcp2_token_type token_type :member:`token_type` is the type of token. Server application should set this field. .. member:: ngtcp2_rand_ctx rand_ctx :member:`rand_ctx` is an optional random number generator to be passed to :type:`ngtcp2_rand` callback. .. member:: uint64_t max_window :member:`max_window` is the maximum connection-level flow control window if connection-level window auto-tuning is enabled. The connection-level window auto tuning is enabled if nonzero value is specified in this field. The initial value of window size is :member:`ngtcp2_transport_params.initial_max_data`. The window size is scaled up to the value specified in this field. .. member:: uint64_t max_stream_window :member:`max_stream_window` is the maximum stream-level flow control window if stream-level window auto-tuning is enabled. The stream-level window auto-tuning is enabled if nonzero value is specified in this field. The initial value of window size is :member:`ngtcp2_transport_params.initial_max_stream_data_bidi_remote`, :member:`ngtcp2_transport_params.initial_max_stream_data_bidi_local`, or :member:`ngtcp2_transport_params.initial_max_stream_data_uni`, depending on the type of stream. The window size is scaled up to the value specified in this field. .. member:: size_t ack_thresh :member:`ack_thresh` is the minimum number of the received ACK eliciting packets that trigger the immediate acknowledgement from the local endpoint. .. member:: uint8_t no_tx_udp_payload_size_shaping :member:`no_tx_udp_payload_size_shaping`, if set to nonzero, instructs the library not to limit the UDP payload size to :macro:`NGTCP2_MAX_UDP_PAYLOAD_SIZE` (which can be extended by Path MTU Discovery), and instead use the minimum size among the given buffer size, :member:`max_tx_udp_payload_size`, and the received max_udp_payload_size QUIC transport parameter. .. member:: ngtcp2_duration handshake_timeout :member:`handshake_timeout` is the period of time before giving up QUIC connection establishment. If QUIC handshake is not complete within this period, `ngtcp2_conn_handle_expiry` returns :macro:`NGTCP2_ERR_HANDSHAKE_TIMEOUT` error. The deadline is :member:`initial_ts` + :member:`handshake_timeout`. If this field is set to ``UINT64_MAX``, no handshake timeout is set. .. member:: const uint32_t *preferred_versions :member:`preferred_versions` is the array of versions that are preferred by the local endpoint. All versions set in this array must be supported by the library, and compatible to QUIC v1. The reserved versions are not allowed. They are sorted in the order of preference. On compatible version negotiation, server will negotiate one of those versions contained in this array if there is some overlap between these versions and the versions offered by the client. If there is no overlap, but the client chosen version is supported by the library, the server chooses the client chosen version as the negotiated version. This version set corresponds to Offered Versions described in :rfc:`9368`, and it should be included in Version Negotiation packet. Client uses this field and :member:`original_version` to prevent version downgrade attack if it reacted upon Version Negotiation packet. If this field is specified, client must include *client_chosen_version* passed to `ngtcp2_conn_client_new` unless *client_chosen_version* is a reserved version. .. member:: size_t preferred_versionslen :member:`preferred_versionslen` is the number of versions that are contained in the array pointed by :member:`preferred_versions`. .. member:: const uint32_t *available_versions :member:`available_versions` is the array of versions that are going to be set in :member:`available_versions ` field of outgoing version_information QUIC transport parameter. For server, this corresponds to Fully-Deployed Versions described in :rfc:`9368`. If this field is not set, it is set to :member:`preferred_versions` internally if :member:`preferred_versionslen` is not zero. If this field is not set, and :member:`preferred_versionslen` is zero, this field is set to :macro:`NGTCP2_PROTO_VER_V1` internally. Client must include *client_chosen_version* passed to `ngtcp2_conn_client_new` in this array if this field is set and *client_chosen_version* is not a reserved version. If this field is not set, *client_chosen_version* passed to `ngtcp2_conn_client_new` will be set in this field internally unless *client_chosen_version* is a reserved version. .. member:: size_t available_versionslen :member:`available_versionslen` is the number of versions that are contained in the array pointed by :member:`available_versions`. .. member:: uint32_t original_version :member:`original_version` is the original version that client initially used to make a connection attempt. If it is set, and it differs from *client_chosen_version* passed to `ngtcp2_conn_client_new`, the library assumes that client reacted upon Version Negotiation packet. Server does not use this field. .. member:: uint8_t no_pmtud :member:`no_pmtud`, if set to nonzero, disables Path MTU Discovery. .. member:: uint32_t initial_pkt_num :member:`pkt_num` is the initial packet number for each packet number space. It must be in range [0, INT32_MAX], inclusive. .. member:: const uint16_t *pmtud_probes :member:`pmtud_probes` is the array of UDP datagram payload size to probe during Path MTU Discovery. The discovery is done in the order appeared in this array. The size must be strictly larger than 1200, otherwise the behavior is undefined. The maximum value in this array should be set to :member:`max_tx_udp_payload_size`. If this field is not set, the predefined PMTUD probes are made. This field has been available since v1.4.0. .. member:: size_t pmtud_probeslen :member:`pmtud_probeslen` is the number of elements that are contained in the array pointed by :member:`pmtud_probes`. This field has been available since v1.4.0. .. type:: ngtcp2_addr :type:`ngtcp2_addr` is the endpoint address. .. member:: ngtcp2_sockaddr *addr :member:`addr` points to the buffer which contains endpoint address. It must not be ``NULL``. .. member:: ngtcp2_socklen addrlen :member:`addrlen` is the length of :member:`addr`. It must not be longer than sizeof(:type:`ngtcp2_sockaddr_union`). .. type:: ngtcp2_path :type:`ngtcp2_path` is the network endpoints where a packet is sent and received. .. member:: ngtcp2_addr local :member:`local` is the address of local endpoint. .. member:: ngtcp2_addr remote :member:`remote` is the address of remote endpoint. .. member:: void *user_data :member:`user_data` is an arbitrary data and opaque to the library. Note that :type:`ngtcp2_path` is generally passed to :type:`ngtcp2_conn` by an application, and :type:`ngtcp2_conn` stores their copies. Unfortunately, there is no way for the application to know when :type:`ngtcp2_conn` finished using a specific :type:`ngtcp2_path` object in mid connection, which means that the application cannot free the data pointed by this field. Therefore, it is advised to use this field only when the data pointed by this field persists in an entire lifetime of the connection. .. type:: ngtcp2_path_storage :type:`ngtcp2_path_storage` is a convenient struct to have buffers to store the longest addresses. .. member:: ngtcp2_path path :member:`path` stores network path. .. member:: ngtcp2_sockaddr_union local_addrbuf :member:`local_addrbuf` is a buffer to store local address. .. member:: ngtcp2_sockaddr_union remote_addrbuf :member:`remote_addrbuf` is a buffer to store remote address. .. type:: ngtcp2_crypto_md :type:`ngtcp2_crypto_md` is a wrapper around native message digest object. .. member:: void *native_handle :member:`native_handle` is a pointer to an underlying message digest object. .. type:: ngtcp2_crypto_aead :type:`ngtcp2_crypto_aead` is a wrapper around native AEAD object. .. member:: void *native_handle :member:`native_handle` is a pointer to an underlying AEAD object. .. member:: size_t max_overhead :member:`max_overhead` is the number of additional bytes which AEAD encryption needs on encryption. .. type:: ngtcp2_crypto_cipher :type:`ngtcp2_crypto_cipher` is a wrapper around native cipher object. .. member:: void *native_handle :member:`native_handle` is a pointer to an underlying cipher object. .. type:: ngtcp2_crypto_aead_ctx :type:`ngtcp2_crypto_aead_ctx` is a wrapper around native AEAD cipher context object. It should be initialized with a specific key. ngtcp2 library reuses this context object to encrypt or decrypt multiple packets. .. member:: void *native_handle :member:`native_handle` is a pointer to an underlying AEAD context object. .. type:: ngtcp2_crypto_cipher_ctx :type:`ngtcp2_crypto_cipher_ctx` is a wrapper around native cipher context object. It should be initialized with a specific key. ngtcp2 library reuses this context object to encrypt or decrypt multiple packet headers. .. member:: void *native_handle :member:`native_handle` is a pointer to an underlying cipher context object. .. type:: ngtcp2_crypto_ctx :type:`ngtcp2_crypto_ctx` is a convenient structure to bind all crypto related objects in one place. Use `ngtcp2_crypto_ctx_initial` to initialize this struct for Initial packet encryption. For Handshake and 1-RTT packets, use `ngtcp2_crypto_ctx_tls`. For 0-RTT packets, use `ngtcp2_crypto_ctx_tls_early`. .. member:: ngtcp2_crypto_aead aead :member:`aead` is AEAD object. .. member:: ngtcp2_crypto_md md :member:`md` is message digest object. .. member:: ngtcp2_crypto_cipher hp :member:`hp` is header protection cipher. .. member:: uint64_t max_encryption :member:`max_encryption` is the number of encryption which this key can be used with. .. member:: uint64_t max_decryption_failure :member:`max_decryption_failure` is the number of decryption failure with this key. .. type:: ngtcp2_version_cid :type:`ngtcp2_version_cid` is a convenient struct to store the result of `ngtcp2_pkt_decode_version_cid`. .. member:: uint32_t version :member:`version` stores QUIC version. .. member:: const uint8_t *dcid :member:`dcid` points to the Destination Connection ID. .. member:: size_t dcidlen :member:`dcidlen` is the length of the Destination Connection ID pointed by :member:`dcid`. .. member:: const uint8_t *scid :member:`scid` points to the Source Connection ID. .. member:: size_t scidlen :member:`scidlen` is the length of the Source Connection ID pointed by :member:`scid`. .. type:: ngtcp2_conn :type:`ngtcp2_conn` represents a single QUIC connection. .. type:: int (*ngtcp2_client_initial)(ngtcp2_conn *conn, void *user_data) :type:`ngtcp2_client_initial` is invoked when client application asks TLS stack to produce first TLS cryptographic handshake data. This implementation of this callback must get the first handshake data from TLS stack, and pass it to ngtcp2 library using `ngtcp2_conn_submit_crypto_data` function. Make sure that before calling `ngtcp2_conn_submit_crypto_data` function, client application must create initial packet protection keys and IVs, and provide them to ngtcp2 library using `ngtcp2_conn_install_initial_key`. This callback function must return 0 if it succeeds, or :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library call return immediately. .. type:: int (*ngtcp2_recv_client_initial)(ngtcp2_conn *conn, const ngtcp2_cid *dcid, void *user_data) :type:`ngtcp2_recv_client_initial` is invoked when server receives Initial packet from client. An server application must implement this callback, and generate initial keys and IVs for both transmission and reception. Install them using `ngtcp2_conn_install_initial_key`. *dcid* is the Destination Connection ID in Initial packet received from client. It is used to derive initial packet protection keys. The callback function must return 0 if it succeeds. If an error occurs, return :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library call return immediately. .. type:: int (*ngtcp2_recv_crypto_data)(ngtcp2_conn *conn, ngtcp2_encryption_level encryption_level, uint64_t offset, const uint8_t *data, size_t datalen, void *user_data) :type`ngtcp2_recv_crypto_data` is invoked when crypto data is received. The received data is pointed by *data*, and its length is *datalen*. The *offset* specifies the offset where *data* is positioned. *user_data* is the arbitrary pointer passed to `ngtcp2_conn_client_new` or `ngtcp2_conn_server_new`. The ngtcp2 library ensures that the crypto data is passed to the application in the increasing order of *offset*. *datalen* is always strictly greater than 0. *encryption_level* indicates the encryption level where this data is received. Crypto data can never be received in :enum:`ngtcp2_encryption_level.NGTCP2_ENCRYPTION_LEVEL_0RTT`. The application should provide the given data to TLS stack. The callback function must return 0 if it succeeds, or one of the following negative error codes: - :macro:`NGTCP2_ERR_CRYPTO` - :macro:`NGTCP2_ERR_REQUIRED_TRANSPORT_PARAM` - :macro:`NGTCP2_ERR_MALFORMED_TRANSPORT_PARAM` - :macro:`NGTCP2_ERR_TRANSPORT_PARAM` - :macro:`NGTCP2_ERR_PROTO` - :macro:`NGTCP2_ERR_VERSION_NEGOTIATION_FAILURE` - :macro:`NGTCP2_ERR_NOMEM` - :macro:`NGTCP2_ERR_CALLBACK_FAILURE` If the other value is returned, it is treated as :macro:`NGTCP2_ERR_CALLBACK_FAILURE`. If application encounters fatal error, return :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library call return immediately. .. type:: int (*ngtcp2_handshake_completed)(ngtcp2_conn *conn, void *user_data) :type:`ngtcp2_handshake_completed` is invoked when QUIC cryptographic handshake has completed. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_handshake_confirmed)(ngtcp2_conn *conn, void *user_data) :type:`ngtcp2_handshake_confirmed` is invoked when QUIC cryptographic handshake is confirmed. The handshake confirmation means that both endpoints agree that handshake has finished. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_recv_version_negotiation)(ngtcp2_conn *conn, const ngtcp2_pkt_hd *hd, const uint32_t *sv, size_t nsv, void *user_data) :type:`ngtcp2_recv_version_negotiation` is invoked when Version Negotiation packet is received. *hd* is the pointer to the QUIC packet header object. The vector *sv* of *nsv* elements contains the QUIC version the server supports. Since Version Negotiation is only sent by server, this callback function is used by client only. The callback function must return 0 if it succeeds, or :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library call return immediately. .. type:: int (*ngtcp2_recv_retry)(ngtcp2_conn *conn, const ngtcp2_pkt_hd *hd, void *user_data) :type:`ngtcp2_recv_retry` is invoked when Retry packet is received. This callback is client use only. Application must regenerate packet protection key, IV, and header protection key for Initial packets using the Destination Connection ID obtained by :member:`hd->scid `, and install them by calling `ngtcp2_conn_install_initial_key`. 0-RTT data accepted by the ngtcp2 library will be automatically retransmitted as 0-RTT data by the library. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_encrypt)(uint8_t *dest, const ngtcp2_crypto_aead *aead, const ngtcp2_crypto_aead_ctx *aead_ctx, const uint8_t *plaintext, size_t plaintextlen, const uint8_t *nonce, size_t noncelen, const uint8_t *aad, size_t aadlen) :type:`ngtcp2_encrypt` is invoked when the ngtcp2 library asks the application to encrypt packet payload. The packet payload to encrypt is passed as *plaintext* of length *plaintextlen*. The AEAD cipher is *aead*. *aead_ctx* is the AEAD cipher context object which is initialized with the specific encryption key. The nonce is passed as *nonce* of length *noncelen*. The Additional Authenticated Data is passed as *aad* of length *aadlen*. The implementation of this callback must encrypt *plaintext* using the negotiated cipher suite, and write the ciphertext into the buffer pointed by *dest*. *dest* has enough capacity to store the ciphertext and any additional AEAD tag data. *dest* and *plaintext* may point to the same buffer. The callback function must return 0 if it succeeds, or :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library call return immediately. .. type:: int (*ngtcp2_decrypt)(uint8_t *dest, const ngtcp2_crypto_aead *aead, const ngtcp2_crypto_aead_ctx *aead_ctx, const uint8_t *ciphertext, size_t ciphertextlen, const uint8_t *nonce, size_t noncelen, const uint8_t *aad, size_t aadlen) :type:`ngtcp2_decrypt` is invoked when the ngtcp2 library asks the application to decrypt packet payload. The packet payload to decrypt is passed as *ciphertext* of length *ciphertextlen*. The AEAD cipher is *aead*. *aead_ctx* is the AEAD cipher context object which is initialized with the specific decryption key. The nonce is passed as *nonce* of length *noncelen*. The Additional Authenticated Data is passed as *aad* of length *aadlen*. The implementation of this callback must decrypt *ciphertext* using the negotiated cipher suite, and write the ciphertext into the buffer pointed by *dest*. *dest* has enough capacity to store the cleartext. *dest* and *ciphertext* may point to the same buffer. The callback function must return 0 if it succeeds. If TLS stack fails to decrypt data, return :macro:`NGTCP2_ERR_DECRYPT`. For any other errors, return :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library call return immediately. .. type:: int (*ngtcp2_hp_mask)(uint8_t *dest, const ngtcp2_crypto_cipher *hp, const ngtcp2_crypto_cipher_ctx *hp_ctx, const uint8_t *sample) :type:`ngtcp2_hp_mask` is invoked when the ngtcp2 library asks the application to produce a mask to encrypt or decrypt packet header. The encryption cipher is *hp*. *hp_ctx* is the cipher context object which is initialized with the specific header protection key. The sample is passed as *sample* which is :macro:`NGTCP2_HP_SAMPLELEN` bytes long. The implementation of this callback must produce a mask using the header protection cipher suite specified by QUIC specification, and write the result into the buffer pointed by *dest*. The length of the mask must be at least :macro:`NGTCP2_HP_MASKLEN`. The library only uses the first :macro:`NGTCP2_HP_MASKLEN` bytes of the produced mask. The buffer pointed by *dest* is guaranteed to have at least :macro:`NGTCP2_HP_SAMPLELEN` bytes available for convenience. The callback function must return 0 if it succeeds, or :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library call return immediately. .. type:: int (*ngtcp2_recv_stream_data)(ngtcp2_conn *conn, uint32_t flags, int64_t stream_id, uint64_t offset, const uint8_t *data, size_t datalen, void *user_data, void *stream_user_data) :type:`ngtcp2_recv_stream_data` is invoked when stream data is received. The stream is specified by *stream_id*. *flags* is the bitwise-OR of zero or more of :macro:`NGTCP2_STREAM_DATA_FLAG_* `. If *flags* & :macro:`NGTCP2_STREAM_DATA_FLAG_FIN` is nonzero, this portion of the data is the last data in this stream. *offset* is the offset where this data begins. The library ensures that data is passed to the application in the non-decreasing order of *offset* without any overlap. The data is passed as *data* of length *datalen*. *datalen* may be 0 if and only if *fin* is nonzero. If :macro:`NGTCP2_STREAM_DATA_FLAG_0RTT` is set in *flags*, it indicates that a part of or whole data was received in 0-RTT packet, and a handshake has not completed yet. The callback function must return 0 if it succeeds, or :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library return immediately. .. type:: int (*ngtcp2_stream_open)(ngtcp2_conn *conn, int64_t stream_id, void *user_data) :type:`ngtcp2_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 :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_stream_close)(ngtcp2_conn *conn, uint32_t flags, int64_t stream_id, uint64_t app_error_code, void *user_data, void *stream_user_data) :type:`ngtcp2_stream_close` is invoked when a stream is closed. This callback is not called when QUIC connection is closed before existing streams are closed. *flags* is the bitwise-OR of zero or more of :macro:`NGTCP2_STREAM_CLOSE_FLAG_* `. *app_error_code* indicates the error code of this closure if :macro:`NGTCP2_STREAM_CLOSE_FLAG_APP_ERROR_CODE_SET` is set in *flags*. If it is not set, the stream was closed without any error code, which generally means success. *app_error_code* is the first application error code sent by a local endpoint, or received from a remote endpoint. If a stream is closed cleanly, no application error code is exchanged. Since QUIC stack does not know the application error code which indicates "no errors", *app_error_code* is set to 0 and :macro:`NGTCP2_STREAM_CLOSE_FLAG_APP_ERROR_CODE_SET` is not set in *flags* in this case. The implementation of this callback should return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_stream_reset)(ngtcp2_conn *conn, int64_t stream_id, uint64_t final_size, uint64_t app_error_code, void *user_data, void *stream_user_data) :type:`ngtcp2_stream_reset` is invoked when a stream identified by *stream_id* is reset by a remote endpoint. The implementation of this callback should return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_acked_stream_data_offset)( ngtcp2_conn *conn, int64_t stream_id, uint64_t offset, uint64_t datalen, void *user_data, void *stream_user_data) :type:`ngtcp2_acked_stream_data_offset` is a callback function which is called when stream data in range [*offset*, *offset* + *datalen*) is acknowledged, and application can free the portion of data. For a given *stream_id*, this callback is called sequentially in increasing order of *offset* without any overlap. *datalen* is normally strictly greater than 0. One exception is that when a STREAM frame has fin flag set and 0 length data, this callback is invoked with *datalen* == 0. If a stream is closed prematurely, and stream data is still in-flight, this callback function is not called for those data. After :member:`ngtcp2_callbacks.stream_close` is called for a particular stream, *conn* does not touch data for the closed stream again, and application can free all unacknowledged stream data. The implementation of this callback should return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_recv_stateless_reset)(ngtcp2_conn *conn, const ngtcp2_pkt_stateless_reset *sr, void *user_data) :type:`ngtcp2_recv_stateless_reset` is a callback function which is called when Stateless Reset packet is received. The stateless reset details are given in *sr*. The implementation of this callback should return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_extend_max_streams)(ngtcp2_conn *conn, uint64_t max_streams, void *user_data) :type:`ngtcp2_extend_max_streams` is a callback function which is called every time max stream ID is strictly extended. *max_streams* is the cumulative number of streams which an endpoint can open. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_extend_max_stream_data)(ngtcp2_conn *conn, int64_t stream_id, uint64_t max_data, void *user_data, void *stream_user_data) :type:`ngtcp2_extend_max_stream_data` is a callback function which is invoked when max stream data is extended. *stream_id* identifies the stream. *max_data* is a cumulative number of bytes an endpoint can send on this stream. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: void (*ngtcp2_rand)(uint8_t *dest, size_t destlen, const ngtcp2_rand_ctx *rand_ctx) :type:`ngtcp2_rand` is a callback function to get random data of length *destlen*. Application must fill random *destlen* bytes to the buffer pointed by *dest*. The generated data is used only in non-cryptographic context. .. type:: int (*ngtcp2_get_new_connection_id)(ngtcp2_conn *conn, ngtcp2_cid *cid, uint8_t *token, size_t cidlen, void *user_data) :type:`ngtcp2_get_new_connection_id` is a callback function to ask an application for new connection ID. Application must generate new unused connection ID with the exact *cidlen* bytes, and store it in *cid*. It also has to generate a stateless reset token, and store it in *token*. The length of stateless reset token is :macro:`NGTCP2_STATELESS_RESET_TOKENLEN` and it is guaranteed that the buffer pointed by *token* has the sufficient space to store the token. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_remove_connection_id)(ngtcp2_conn *conn, const ngtcp2_cid *cid, void *user_data) :type:`ngtcp2_remove_connection_id` is a callback function which notifies the application that connection ID *cid* is no longer used by a remote endpoint. This Connection ID was previously offered by a local endpoint, and a remote endpoint could use it as Destination Connection ID when sending QUIC packet. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_update_key)( ngtcp2_conn *conn, uint8_t *rx_secret, uint8_t *tx_secret, ngtcp2_crypto_aead_ctx *rx_aead_ctx, uint8_t *rx_iv, ngtcp2_crypto_aead_ctx *tx_aead_ctx, uint8_t *tx_iv, const uint8_t *current_rx_secret, const uint8_t *current_tx_secret, size_t secretlen, void *user_data) :type:`ngtcp2_update_key` is a callback function which tells the application that it must generate new packet protection keying materials and AEAD cipher context objects with new keys. The current set of secrets are given as *current_rx_secret* and *current_tx_secret* of length *secretlen*. They are decryption and encryption secrets respectively. The application must generate new secrets and keys for both encryption and decryption. It must write decryption secret and IV to the buffer pointed by *rx_secret* and *rx_iv* respectively. It also must create new AEAD cipher context object with new decryption key and initialize *rx_aead_ctx* with it. Similarly, write encryption secret and IV to the buffer pointed by *tx_secret* and *tx_iv*. Create new AEAD cipher context object with new encryption key and initialize *tx_aead_ctx* with it. All given buffers have the enough capacity to store secret, key and IV. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_path_validation)(ngtcp2_conn *conn, uint32_t flags, const ngtcp2_path *path, const ngtcp2_path *old_path, ngtcp2_path_validation_result res, void *user_data) :type:`ngtcp2_path_validation` is a callback function which tells an application the outcome of path validation. *flags* is zero or more of :macro:`NGTCP2_PATH_VALIDATION_FLAG_* `. *path* is the path that was validated. *old_path* is the path that is previously used before a local endpoint has migrated to *path* if *old_path* is not NULL. If *res* is :enum:`ngtcp2_path_validation_result.NGTCP2_PATH_VALIDATION_RESULT_SUCCESS`, the path validation succeeded. If *res* is :enum:`ngtcp2_path_validation_result.NGTCP2_PATH_VALIDATION_RESULT_FAILURE`, the path validation failed. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_select_preferred_addr)(ngtcp2_conn *conn, ngtcp2_path *dest, const ngtcp2_preferred_addr *paddr, void *user_data) :type:`ngtcp2_select_preferred_addr` is a callback function which asks a client application to choose server address from preferred addresses *paddr* received from server. An application should write a network path for a selected preferred address in *dest*. More specifically, the selected preferred address must be set to :member:`dest->remote `, a client source address must be set to :member:`dest->local `. If a client source address does not change for the new server address, leave :member:`dest->local ` unmodified, or copy the value of :member:`local ` field of the current network path obtained from `ngtcp2_conn_get_path()`. Both :member:`dest->local.addr ` and :member:`dest->remote.addr ` point to buffers which are at least sizeof(:type:`ngtcp2_sockaddr_union`) bytes long, respectively. If an application denies the preferred addresses, just leave *dest* unmodified (or set :member:`dest->remote.addrlen ` to 0), and return 0. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_connection_id_status)( ngtcp2_conn *conn, ngtcp2_connection_id_status_type type, uint64_t seq, const ngtcp2_cid *cid, const uint8_t *token, void *user_data) :type:`ngtcp2_connection_id_status` is a callback function which is called when the status of Destination Connection ID changes. *token* is the associated stateless reset token, and it is ``NULL`` if no token is present. *type* is the one of the value defined in :type:`ngtcp2_connection_id_status_type`. The new value might be added in the future release. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_recv_new_token)(ngtcp2_conn *conn, const uint8_t *token, size_t tokenlen, void *user_data) :type:`ngtcp2_recv_new_token` is a callback function which is called when new token is received from server. This callback is client use only. *token* is the received token of length *tokenlen* bytes long. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: void (*ngtcp2_delete_crypto_aead_ctx)(ngtcp2_conn *conn, ngtcp2_crypto_aead_ctx *aead_ctx, void *user_data) :type:`ngtcp2_delete_crypto_aead_ctx` is a callback function which must delete the native object pointed by :member:`aead_ctx->native_handle `. .. type:: void (*ngtcp2_delete_crypto_cipher_ctx)( ngtcp2_conn *conn, ngtcp2_crypto_cipher_ctx *cipher_ctx, void *user_data) :type:`ngtcp2_delete_crypto_cipher_ctx` is a callback function which must delete the native object pointed by :member:`cipher_ctx->native_handle `. .. type:: int (*ngtcp2_recv_datagram)(ngtcp2_conn *conn, uint32_t flags, const uint8_t *data, size_t datalen, void *user_data) :type:`ngtcp2_recv_datagram` is invoked when DATAGRAM frame is received. *flags* is bitwise-OR of zero or more of :macro:`NGTCP2_DATAGRAM_FLAG_* `. If :macro:`NGTCP2_DATAGRAM_FLAG_0RTT` is set in *flags*, it indicates that DATAGRAM frame was received in 0-RTT packet, and a handshake has not completed yet. The callback function must return 0 if it succeeds, or :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library return immediately. .. type:: int (*ngtcp2_ack_datagram)(ngtcp2_conn *conn, uint64_t dgram_id, void *user_data) :type:`ngtcp2_ack_datagram` is invoked when a packet which contains DATAGRAM frame which is identified by *dgram_id* is acknowledged. *dgram_id* is the valued passed to `ngtcp2_conn_writev_datagram`. The callback function must return 0 if it succeeds, or :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library return immediately. .. type:: int (*ngtcp2_lost_datagram)(ngtcp2_conn *conn, uint64_t dgram_id, void *user_data) :type:`ngtcp2_lost_datagram` is invoked when a packet which contains DATAGRAM frame which is identified by *dgram_id* is declared lost. *dgram_id* is the valued passed to `ngtcp2_conn_writev_datagram`. Note that the loss might be spurious, and DATAGRAM frame might be acknowledged later. The callback function must return 0 if it succeeds, or :macro:`NGTCP2_ERR_CALLBACK_FAILURE` which makes the library return immediately. .. type:: int (*ngtcp2_get_path_challenge_data)(ngtcp2_conn *conn, uint8_t *data, void *user_data) :type:`ngtcp2_get_path_challenge_data` is a callback function to ask an application for new data that is sent in PATH_CHALLENGE frame. Application must generate new unpredictable, exactly :macro:`NGTCP2_PATH_CHALLENGE_DATALEN` bytes of random data, and store them into the buffer pointed by *data*. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_stream_stop_sending)(ngtcp2_conn *conn, int64_t stream_id, uint64_t app_error_code, void *user_data, void *stream_user_data) :type:`ngtcp2_stream_stop_sending` is invoked when a stream is no longer read by a local endpoint before it receives all stream data. This function is called at most once per stream. *app_error_code* is the error code passed to `ngtcp2_conn_shutdown_stream_read` or `ngtcp2_conn_shutdown_stream`. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_version_negotiation)(ngtcp2_conn *conn, uint32_t version, const ngtcp2_cid *client_dcid, void *user_data) :type:`ngtcp2_version_negotiation` is invoked when the compatible version negotiation takes place. For client, it is called when it sees a change in version field of a long header packet. This callback function might be called multiple times for client. For server, it is called once when the version is negotiated. The implementation of this callback must install new Initial keys for *version* and Destination Connection ID *client_dcid* from client. Use `ngtcp2_conn_install_vneg_initial_key` to install keys. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_recv_key)(ngtcp2_conn *conn, ngtcp2_encryption_level level, void *user_data) :type:`ngtcp2_recv_key` is invoked when new key is installed to *conn* during QUIC cryptographic handshake. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: int (*ngtcp2_tls_early_data_rejected)(ngtcp2_conn *conn, void *user_data) :type:`ngtcp2_tls_early_data_rejected` is invoked when early data was rejected by server during TLS handshake, or client decided not to attempt early data. The callback function must return 0 if it succeeds. Returning :macro:`NGTCP2_ERR_CALLBACK_FAILURE` makes the library call return immediately. .. type:: ngtcp2_callbacks :type:`ngtcp2_callbacks` holds a set of callback functions. .. member:: ngtcp2_client_initial client_initial :member:`client_initial` is a callback function which is invoked when client asks TLS stack to produce first TLS cryptographic handshake message. This callback function must be specified for a client application. .. member:: ngtcp2_recv_client_initial recv_client_initial :member:`recv_client_initial` is a callback function which is invoked when a server receives the first Initial packet from client. This callback function must be specified for a server application. .. member:: ngtcp2_recv_crypto_data recv_crypto_data :member:`recv_crypto_data` is a callback function which is invoked when cryptographic data (CRYPTO frame, in other words, TLS message) is received. This callback function must be specified. .. member:: ngtcp2_handshake_completed handshake_completed :member:`handshake_completed` is a callback function which is invoked when QUIC cryptographic handshake has completed. This callback function is optional. .. member:: ngtcp2_recv_version_negotiation recv_version_negotiation :member:`recv_version_negotiation` is a callback function which is invoked when Version Negotiation packet is received by a client. This callback function is optional. .. member:: ngtcp2_encrypt encrypt :member:`encrypt` is a callback function which is invoked to encrypt a QUIC packet. This callback function must be specified. .. member:: ngtcp2_decrypt decrypt :member:`decrypt` is a callback function which is invoked to decrypt a QUIC packet. This callback function must be specified. .. member:: ngtcp2_hp_mask hp_mask :member:`hp_mask` is a callback function which is invoked to get a mask to encrypt or decrypt QUIC packet header. This callback function must be specified. .. member:: ngtcp2_recv_stream_data recv_stream_data :member:`recv_stream_data` is a callback function which is invoked when stream data, which includes application data, is received. This callback function is optional. .. member:: ngtcp2_acked_stream_data_offset acked_stream_data_offset :member:`acked_stream_data_offset` is a callback function which is invoked when stream data, which includes application data, is acknowledged by a remote endpoint. It tells an application the largest offset of acknowledged stream data without a gap so that application can free memory for the data up to that offset. This callback function is optional. .. member:: ngtcp2_stream_open stream_open :member:`stream_open` is a callback function which is invoked when new remote stream is opened by a remote endpoint. This callback function is optional. .. member:: ngtcp2_stream_close stream_close :member:`stream_close` is a callback function which is invoked when a stream is closed. This callback function is optional. .. member:: ngtcp2_recv_stateless_reset recv_stateless_reset :member:`recv_stateless_reset` is a callback function which is invoked when Stateless Reset packet is received. This callback function is optional. .. member:: ngtcp2_recv_retry recv_retry :member:`recv_retry` is a callback function which is invoked when a client receives Retry packet. For client, this callback function must be specified. Server never receive Retry packet. .. member:: ngtcp2_extend_max_streams extend_max_local_streams_bidi :member:`extend_max_local_streams_bidi` is a callback function which is invoked when the number of bidirectional stream which a local endpoint can open is increased. This callback function is optional. .. member:: ngtcp2_extend_max_streams extend_max_local_streams_uni :member:`extend_max_local_streams_uni` is a callback function which is invoked when the number of unidirectional stream which a local endpoint can open is increased. This callback function is optional. .. member:: ngtcp2_rand rand :member:`rand` is a callback function which is invoked when the library needs random data. This callback function must be specified. .. member:: ngtcp2_get_new_connection_id get_new_connection_id :member:`get_new_connection_id` is a callback function which is invoked when the library needs new connection ID. This callback function must be specified. .. member:: ngtcp2_remove_connection_id remove_connection_id :member:`remove_connection_id` is a callback function which notifies an application that connection ID is no longer used by a remote endpoint. This callback function is optional. .. member:: ngtcp2_update_key update_key :member:`update_key` is a callback function which is invoked when the library tells an application that it must update keying materials, and install new keys. This callback function must be specified. .. member:: ngtcp2_path_validation path_validation :member:`path_validation` is a callback function which is invoked when path validation completed. This callback function is optional. .. member:: ngtcp2_select_preferred_addr select_preferred_addr :member:`select_preferred_addr` is a callback function which is invoked when the library asks a client to select preferred address presented by a server. If not set, client ignores preferred addresses. This callback function is optional. .. member:: ngtcp2_stream_reset stream_reset :member:`stream_reset` is a callback function which is invoked when a stream is reset by a remote endpoint. This callback function is optional. .. member:: ngtcp2_extend_max_streams extend_max_remote_streams_bidi :member:`extend_max_remote_streams_bidi` is a callback function which is invoked when the number of bidirectional streams which a remote endpoint can open is increased. This callback function is optional. .. member:: ngtcp2_extend_max_streams extend_max_remote_streams_uni :member:`extend_max_remote_streams_uni` is a callback function which is invoked when the number of unidirectional streams which a remote endpoint can open is increased. This callback function is optional. .. member:: ngtcp2_extend_max_stream_data extend_max_stream_data :member:`extend_max_stream_data` is callback function which is invoked when the maximum offset of stream data that a local endpoint can send is increased. This callback function is optional. .. member:: ngtcp2_connection_id_status dcid_status :member:`dcid_status` is a callback function which is invoked when the new Destination Connection ID is activated, or the activated Destination Connection ID is now deactivated. This callback function is optional. .. member:: ngtcp2_handshake_confirmed handshake_confirmed :member:`handshake_confirmed` is a callback function which is invoked when both endpoints agree that handshake has finished. This field is ignored by server because :member:`handshake_completed` also indicates the handshake confirmation for server. This callback function is optional. .. member:: ngtcp2_recv_new_token recv_new_token :member:`recv_new_token` is a callback function which is invoked when new token is received from server. This field is ignored by server. This callback function is optional. .. member:: ngtcp2_delete_crypto_aead_ctx delete_crypto_aead_ctx :member:`delete_crypto_aead_ctx` is a callback function which deletes a given AEAD cipher context object. This callback function must be specified. .. member:: ngtcp2_delete_crypto_cipher_ctx delete_crypto_cipher_ctx :member:`delete_crypto_cipher_ctx` is a callback function which deletes a given cipher context object. This callback function must be specified. .. member:: ngtcp2_recv_datagram recv_datagram :member:`recv_datagram` is a callback function which is invoked when DATAGRAM frame is received. This callback function is optional. .. member:: ngtcp2_ack_datagram ack_datagram :member:`ack_datagram` is a callback function which is invoked when a QUIC packet containing DATAGRAM frame is acknowledged by a remote endpoint. This callback function is optional. .. member:: ngtcp2_lost_datagram lost_datagram :member:`lost_datagram` is a callback function which is invoked when a QUIC packet containing DATAGRAM frame is declared lost. This callback function is optional. .. member:: ngtcp2_get_path_challenge_data get_path_challenge_data :member:`get_path_challenge_data` is a callback function which is invoked when the library needs new data sent along with PATH_CHALLENGE frame. This callback must be specified. .. member:: ngtcp2_stream_stop_sending stream_stop_sending :member:`stream_stop_sending` is a callback function which is invoked when a local endpoint no longer reads from a stream before it receives all stream data. This callback function is optional. .. member:: ngtcp2_version_negotiation version_negotiation :member:`version_negotiation` is a callback function which is invoked when the compatible version negotiation takes place. This callback function must be specified. .. member:: ngtcp2_recv_key recv_rx_key :member:`recv_rx_key` is a callback function which is invoked when a new key for decrypting packets is installed during QUIC cryptographic handshake. It is not called for :enum:`ngtcp2_encryption_level.NGTCP2_ENCRYPTION_LEVEL_INITIAL`. .. member:: ngtcp2_recv_key recv_tx_key :member:`recv_tx_key` is a callback function which is invoked when a new key for encrypting packets is installed during QUIC cryptographic handshake. It is not called for :enum:`ngtcp2_encryption_level.NGTCP2_ENCRYPTION_LEVEL_INITIAL`. .. member:: ngtcp2_tls_early_data_rejected tls_early_data_rejected :member:`tls_early_data_rejected` is a callback function which is invoked when server rejected early data during TLS handshake, or client decided not to attempt early data. This callback function is only used by client. .. type:: ngtcp2_cid_token :type:`ngtcp2_cid_token` is the convenient struct to store Connection ID, its associated path, and stateless reset token. .. member:: uint64_t seq :member:`seq` is the sequence number of this Connection ID. .. member:: ngtcp2_cid cid :member:`cid` is Connection ID. .. member:: ngtcp2_path_storage ps :member:`ps` is the path which this Connection ID is associated with. .. member:: uint8_t token[NGTCP2_STATELESS_RESET_TOKENLEN] :member:`token` is the stateless reset token for this Connection ID. .. member:: uint8_t token_present :member:`token_present` is nonzero if token contains stateless reset token. .. type:: ngtcp2_ccerr :type:`ngtcp2_ccerr` contains connection error code, its type, a frame type that caused this error, and the optional reason phrase. .. member:: ngtcp2_ccerr_type type :member:`type` is the type of this error. .. member:: uint64_t error_code :member:`error_code` is the error code for connection closure. Its interpretation depends on :member:`type`. .. member:: uint64_t frame_type :member:`frame_type` is the type of QUIC frame which triggers this connection error. This field is set to 0 if the frame type is unknown. .. member:: const uint8_t *reason :member:`reason` points to the buffer which contains a reason phrase. It may be NULL if there is no reason phrase. If it is received from a remote endpoint, it is truncated to at most 1024 bytes. .. member:: size_t reasonlen :member:`reasonlen` is the length of data pointed by :member:`reason`. .. type:: ngtcp2_info :type:`ngtcp2_info` is what `ngtcp2_version` returns. It holds information about the particular ngtcp2 version. .. member:: int age :member:`age` is the age of this struct. This instance of ngtcp2 sets it to :macro:`NGTCP2_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:`NGTCP2_VERSION_NUM` number (since :member:`age` ==1) .. member:: const char *version_str :member:`version_str` points to the :macro:`NGTCP2_VERSION` string (since :member:`age` ==1)