Types (structs, unions and typedefs)

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

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

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

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

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

type ngtcp2_mem

ngtcp2_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() {
  ngtcp2_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb,
                    my_realloc_cb};

  ...
}

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

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

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

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

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

type ngtcp2_pkt_info

ngtcp2_pkt_info is a packet metadata.

uint8_t ecn: ecn is ECN marking, and when it is passed to ngtcp2_conn_read_pkt(), it should be either NGTCP2_ECN_NOT_ECT, NGTCP2_ECN_ECT_1, NGTCP2_ECN_ECT_0, or NGTCP2_ECN_CE.

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

typedef uint64_t ngtcp2_duration: 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

ngtcp2_cid holds a Connection ID.

size_t datalen: datalen is the length of Connection ID.

uint8_t data[NGTCP2_MAX_CIDLEN]: data is the buffer to store Connection ID.

type ngtcp2_vec

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

uint8_t *base: base points to the data.

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

type ngtcp2_pkt_hd

ngtcp2_pkt_hd represents QUIC packet header.

ngtcp2_cid dcid: dcid is Destination Connection ID.

ngtcp2_cid scid: scid is Source Connection ID.

int64_t pkt_num: pkt_num is a packet number.

const uint8_t *token: token contains token. Only Initial packet may contain token. NULL if no token is present.

size_t tokenlen: tokenlen is the length of token. 0 if no token is present.

size_t pkt_numlen: pkt_numlen is the number of bytes spent to encode pkt_num.

size_t len: len is the sum of pkt_numlen and the length of QUIC packet payload.

uint32_t version: version is QUIC version.

uint8_t type: 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 ngtcp2_pkt_type.

uint8_t flags: flags is zero or more of NGTCP2_PKT_FLAG_*.

type ngtcp2_pkt_stateless_reset

ngtcp2_pkt_stateless_reset represents Stateless Reset.

uint8_t stateless_reset_token[NGTCP2_STATELESS_RESET_TOKENLEN]: stateless_reset_token contains stateless reset token.

const uint8_t *rand: rand points a buffer which contains random bytes section.

size_t randlen: randlen is the number of random bytes.

typedef struct sockaddr ngtcp2_sockaddr: ngtcp2_sockaddr is typedefed to struct sockaddr. If NGTCP2_USE_GENERIC_SOCKADDR is defined, it is typedefed to the generic struct sockaddr defined in ngtcp2.h.

typedef struct sockaddr_in ngtcp2_sockaddr_in: ngtcp2_sockaddr_in is typedefed to struct sockaddr_in. If NGTCP2_USE_GENERIC_SOCKADDR is defined, it is typedefed to the generic struct sockaddr_in defined in ngtcp2.h.

typedef struct sockaddr_in6 ngtcp2_sockaddr_in6: ngtcp2_sockaddr_in6 is typedefed to struct sockaddr_in6. If NGTCP2_USE_GENERIC_SOCKADDR is defined, it is typedefed to the generic struct sockaddr_in6 defined in ngtcp2.h.

typedef socklen_t ngtcp2_socklen: ngtcp2_socklen is typedefed to socklen_t. If NGTCP2_USE_GENERIC_SOCKADDR is defined, it is typedefed to uint32_t.

type ngtcp2_sockaddr_union: ngtcp2_sockaddr_union conveniently includes all supported address types.

type ngtcp2_preferred_addr

ngtcp2_preferred_addr represents preferred address structure.

ngtcp2_cid cid: cid is a Connection ID.

ngtcp2_sockaddr_in ipv4: ipv4 contains IPv4 address and port.

ngtcp2_sockaddr_in6 ipv6: ipv6 contains IPv6 address and port.

uint8_t ipv4_present: ipv4_present indicates that ipv4 contains IPv4 address and port.

uint8_t ipv6_present: ipv6_present indicates that ipv6 contains IPv6 address and port.

uint8_t stateless_reset_token[NGTCP2_STATELESS_RESET_TOKENLEN]: stateless_reset_token contains stateless reset token.

type ngtcp2_version_info

ngtcp2_version_info represents version_information structure. See RFC 9368.

uint32_t chosen_version: chosen_version is the version chosen by the sender.

const uint8_t *available_versions: available_versions points the wire image of available_versions field. The each version is therefore in network byte order.

size_t available_versionslen: available_versionslen is the number of bytes pointed by available_versions, not the number of versions included.

type ngtcp2_transport_params

ngtcp2_transport_params represents QUIC transport parameters.

ngtcp2_preferred_addr preferred_addr: preferred_addr contains preferred address if preferred_addr_present is nonzero.

ngtcp2_cid original_dcid: original_dcid is the Destination Connection ID field from the first Initial packet from client. Server must specify this field and set 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.

ngtcp2_cid initial_scid: initial_scid is the Source Connection ID field from the first Initial packet the local endpoint sends. Application should not specify this field. If initial_scid_present is set to nonzero, it indicates this field is set.

ngtcp2_cid retry_scid: 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 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.

uint64_t initial_max_stream_data_bidi_local: 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.

uint64_t initial_max_stream_data_bidi_remote: 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.

uint64_t initial_max_stream_data_uni: 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.

uint64_t initial_max_data: initial_max_data is the connection level flow control window.

uint64_t initial_max_streams_bidi: initial_max_streams_bidi is the number of concurrent streams that the remote endpoint can create.

uint64_t initial_max_streams_uni: initial_max_streams_uni is the number of concurrent unidirectional streams that the remote endpoint can create.

ngtcp2_duration max_idle_timeout: max_idle_timeout is a duration during which sender allows quiescent. 0 means no idle timeout. It must not be UINT64_MAX.

uint64_t max_udp_payload_size: max_udp_payload_size is the maximum UDP payload size that the local endpoint can receive.

uint64_t active_connection_id_limit: active_connection_id_limit is the maximum number of Connection ID that sender can store. If specified, it must be in the range of [NGTCP2_DEFAULT_ACTIVE_CONNECTION_ID_LIMIT, 8], inclusive.

uint64_t ack_delay_exponent: ack_delay_exponent is the exponent used in ACK Delay field in ACK frame.

ngtcp2_duration max_ack_delay: 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.

uint64_t max_datagram_frame_size: 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.

uint8_t stateless_reset_token_present: stateless_reset_token_present is nonzero if stateless_reset_token field is set.

uint8_t disable_active_migration: disable_active_migration is nonzero if the local endpoint does not support active connection migration.

uint8_t original_dcid_present: original_dcid_present is nonzero if original_dcid field is set.

uint8_t initial_scid_present: initial_scid_present is nonzero if initial_scid field is set.

uint8_t retry_scid_present: retry_scid_present is nonzero if retry_scid field is set.

uint8_t preferred_addr_present: preferred_addr_present is nonzero if preferred_address is set.

uint8_t stateless_reset_token[NGTCP2_STATELESS_RESET_TOKENLEN]: stateless_reset_token contains stateless reset token.

uint8_t grease_quic_bit: grease_quic_bit is nonzero if sender supports “Greasing the QUIC Bit” extension. See RFC 9287.

ngtcp2_version_info version_info: version_info contains version_information field if version_info_present is nonzero. Application should not specify this field.

uint8_t version_info_present: version_info_present is nonzero if version_info is set. Application should not specify this field.

type ngtcp2_conn_info

ngtcp2_conn_info holds various connection statistics.

ngtcp2_duration latest_rtt: latest_rtt is the latest RTT sample which is not adjusted by acknowledgement delay.

ngtcp2_duration min_rtt: min_rtt is the minimum RTT seen so far. It is not adjusted by acknowledgement delay.

ngtcp2_duration smoothed_rtt: smoothed_rtt is the smoothed RTT.

ngtcp2_duration rttvar: rttvar is a mean deviation of observed RTT.

uint64_t cwnd: cwnd is the size of congestion window.

uint64_t ssthresh: ssthresh is slow start threshold.

uint64_t bytes_in_flight: bytes_in_flight is the number in bytes of all sent packets which have not been acknowledged.

typedef void (*ngtcp2_printf)(void *user_data, const char *format, ...): 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

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.

void *native_handle: native_handle is a pointer to an underlying random number generator.

typedef void (*ngtcp2_qlog_write)(void *user_data, uint32_t flags, const void *data, size_t datalen): 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 NGTCP2_QLOG_WRITE_FLAG_*. If NGTCP2_QLOG_WRITE_FLAG_FIN is set, datalen may be 0.

type ngtcp2_settings

ngtcp2_settings defines QUIC connection settings.

ngtcp2_qlog_write qlog_write: qlog_write is a callback function to write qlog. Setting NULL disables qlog.

ngtcp2_cc_algo cc_algo: cc_algo specifies congestion control algorithm.

ngtcp2_tstamp initial_ts: initial_ts is an initial timestamp given to the library.

ngtcp2_duration initial_rtt: initial_rtt is an initial RTT.

ngtcp2_printf log_printf: log_printf is a function that the library uses to write logs. NULL means no logging output. It is nothing to do with qlog.

size_t max_tx_udp_payload_size: max_tx_udp_payload_size is the maximum size of UDP datagram payload that the local endpoint transmits.

const uint8_t *token

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

size_t tokenlen: tokenlen is the length of token. Set 0 if there is no token.

ngtcp2_token_type token_type: token_type is the type of token. Server application should set this field.

ngtcp2_rand_ctx rand_ctx: rand_ctx is an optional random number generator to be passed to ngtcp2_rand callback.

uint64_t max_window: 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 ngtcp2_transport_params.initial_max_data. The window size is scaled up to the value specified in this field.

uint64_t max_stream_window

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 ngtcp2_transport_params.initial_max_stream_data_bidi_remote, ngtcp2_transport_params.initial_max_stream_data_bidi_local, or 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.

Please note that the auto-tuning is done per stream. Even if the previous stream gets larger window as a result of auto-tuning, the new stream still starts with the initial value set in transport parameters. This might become a bottleneck if congestion window of a remote server is wide open. If this causes an issue, do not enable auto-tuning.

size_t ack_thresh: ack_thresh is the minimum number of the received ACK eliciting packets that trigger the immediate acknowledgement from the local endpoint.

uint8_t no_tx_udp_payload_size_shaping: no_tx_udp_payload_size_shaping, if set to nonzero, instructs the library not to limit the UDP payload size to NGTCP2_MAX_UDP_PAYLOAD_SIZE (which can be extended by Path MTU Discovery), and instead use the minimum size among the given buffer size, max_tx_udp_payload_size, and the received max_udp_payload_size QUIC transport parameter.

ngtcp2_duration handshake_timeout: 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 NGTCP2_ERR_HANDSHAKE_TIMEOUT error. The deadline is initial_ts + handshake_timeout. If this field is set to UINT64_MAX, no handshake timeout is set.

const uint32_t *preferred_versions

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

size_t preferred_versionslen: preferred_versionslen is the number of versions that are contained in the array pointed by preferred_versions.

const uint32_t *available_versions

available_versions is the array of versions that are going to be set in 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 preferred_versions internally if preferred_versionslen is not zero. If this field is not set, and preferred_versionslen is zero, this field is set to 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.

size_t available_versionslen: available_versionslen is the number of versions that are contained in the array pointed by available_versions.

uint32_t original_version: 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.

uint8_t no_pmtud: no_pmtud, if set to nonzero, disables Path MTU Discovery.

uint32_t initial_pkt_num: initial_pkt_num is the initial packet number for each packet number space. It must be in range [0, INT32_MAX], inclusive.

const uint16_t *pmtud_probes: 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 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.

size_t pmtud_probeslen: pmtud_probeslen is the number of elements that are contained in the array pointed by pmtud_probes. This field has been available since v1.4.0.

type ngtcp2_addr

ngtcp2_addr is the endpoint address.

ngtcp2_sockaddr *addr: addr points to the buffer which contains endpoint address. It must not be NULL.

ngtcp2_socklen addrlen: addrlen is the length of addr. It must not be longer than sizeof(ngtcp2_sockaddr_union).

type ngtcp2_path

ngtcp2_path is the network endpoints where a packet is sent and received.

ngtcp2_addr local: local is the address of local endpoint.

ngtcp2_addr remote: remote is the address of remote endpoint.

void *user_data

user_data is an arbitrary data and opaque to the library.

Note that ngtcp2_path is generally passed to ngtcp2_conn by an application, and ngtcp2_conn stores their copies. Unfortunately, there is no way for the application to know when ngtcp2_conn finished using a specific 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

ngtcp2_path_storage is a convenient struct to have buffers to store the longest addresses.

ngtcp2_path path: path stores network path.

ngtcp2_sockaddr_union local_addrbuf: local_addrbuf is a buffer to store local address.

ngtcp2_sockaddr_union remote_addrbuf: remote_addrbuf is a buffer to store remote address.

type ngtcp2_crypto_md

ngtcp2_crypto_md is a wrapper around native message digest object.

void *native_handle: native_handle is a pointer to an underlying message digest object.

type ngtcp2_crypto_aead

ngtcp2_crypto_aead is a wrapper around native AEAD object.

void *native_handle: native_handle is a pointer to an underlying AEAD object.

size_t max_overhead: max_overhead is the number of additional bytes which AEAD encryption needs on encryption.

type ngtcp2_crypto_cipher

ngtcp2_crypto_cipher is a wrapper around native cipher object.

void *native_handle: native_handle is a pointer to an underlying cipher object.

type ngtcp2_crypto_aead_ctx

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.

void *native_handle: native_handle is a pointer to an underlying AEAD context object.

type ngtcp2_crypto_cipher_ctx

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.

void *native_handle: native_handle is a pointer to an underlying cipher context object.

type ngtcp2_crypto_ctx

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().

ngtcp2_crypto_aead aead: aead is AEAD object.

ngtcp2_crypto_md md: md is message digest object.

ngtcp2_crypto_cipher hp: hp is header protection cipher.

uint64_t max_encryption: max_encryption is the number of encryption which this key can be used with.

uint64_t max_decryption_failure: max_decryption_failure is the number of decryption failure with this key.

type ngtcp2_version_cid

ngtcp2_version_cid is a convenient struct to store the result of ngtcp2_pkt_decode_version_cid().

uint32_t version: version stores QUIC version.

const uint8_t *dcid: dcid points to the Destination Connection ID.

size_t dcidlen: dcidlen is the length of the Destination Connection ID pointed by dcid.

const uint8_t *scid: scid points to the Source Connection ID.

size_t scidlen: scidlen is the length of the Source Connection ID pointed by scid.

type ngtcp2_conn: ngtcp2_conn represents a single QUIC connection.

typedef int (*ngtcp2_client_initial)(ngtcp2_conn *conn, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE which makes the library call return immediately.

typedef int (*ngtcp2_recv_client_initial)(ngtcp2_conn *conn, const ngtcp2_cid *dcid, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE which makes the library call return immediately.

typedef 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 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:

If the other value is returned, it is treated as NGTCP2_ERR_CALLBACK_FAILURE.

If application encounters fatal error, return NGTCP2_ERR_CALLBACK_FAILURE which makes the library call return immediately.

typedef int (*ngtcp2_handshake_completed)(ngtcp2_conn *conn, void *user_data)

ngtcp2_handshake_completed is invoked when QUIC cryptographic handshake has completed.

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

typedef int (*ngtcp2_handshake_confirmed)(ngtcp2_conn *conn, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_recv_version_negotiation)(ngtcp2_conn *conn, const ngtcp2_pkt_hd *hd, const uint32_t *sv, size_t nsv, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE which makes the library call return immediately.

typedef int (*ngtcp2_recv_retry)(ngtcp2_conn *conn, const ngtcp2_pkt_hd *hd, void *user_data)

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 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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef 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)

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 NGTCP2_ERR_CALLBACK_FAILURE which makes the library call return immediately.

typedef 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)

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 NGTCP2_ERR_DECRYPT. For any other errors, return NGTCP2_ERR_CALLBACK_FAILURE which makes the library call return immediately.

typedef int (*ngtcp2_hp_mask)(uint8_t *dest, const ngtcp2_crypto_cipher *hp, const ngtcp2_crypto_cipher_ctx *hp_ctx, const uint8_t *sample)

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 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 NGTCP2_HP_MASKLEN. The library only uses the first NGTCP2_HP_MASKLEN bytes of the produced mask. The buffer pointed by dest is guaranteed to have at least NGTCP2_HP_SAMPLELEN bytes available for convenience.

The callback function must return 0 if it succeeds, or NGTCP2_ERR_CALLBACK_FAILURE which makes the library call return immediately.

typedef 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)

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 NGTCP2_STREAM_DATA_FLAG_*. If flags & 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 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 NGTCP2_ERR_CALLBACK_FAILURE which makes the library return immediately.

typedef int (*ngtcp2_stream_open)(ngtcp2_conn *conn, int64_t stream_id, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef 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)

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 NGTCP2_STREAM_CLOSE_FLAG_*. app_error_code indicates the error code of this closure if 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 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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef 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)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef 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)

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 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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_recv_stateless_reset)(ngtcp2_conn *conn, const ngtcp2_pkt_stateless_reset *sr, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_extend_max_streams)(ngtcp2_conn *conn, uint64_t max_streams, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_extend_max_stream_data)(ngtcp2_conn *conn, int64_t stream_id, uint64_t max_data, void *user_data, void *stream_user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef void (*ngtcp2_rand)(uint8_t *dest, size_t destlen, const ngtcp2_rand_ctx *rand_ctx): 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.

typedef int (*ngtcp2_get_new_connection_id)(ngtcp2_conn *conn, ngtcp2_cid *cid, uint8_t *token, size_t cidlen, void *user_data)

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 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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_remove_connection_id)(ngtcp2_conn *conn, const ngtcp2_cid *cid, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef 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)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef 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)

ngtcp2_path_validation is a callback function which tells an application the outcome of path validation. flags is zero or more of 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 ngtcp2_path_validation_result.NGTCP2_PATH_VALIDATION_RESULT_SUCCESS, the path validation succeeded. If res is ngtcp2_path_validation_result.NGTCP2_PATH_VALIDATION_RESULT_FAILURE, the path validation failed.

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

typedef int (*ngtcp2_select_preferred_addr)(ngtcp2_conn *conn, ngtcp2_path *dest, const ngtcp2_preferred_addr *paddr, void *user_data)

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 dest->remote, a client source address must be set to dest->local. If a client source address does not change for the new server address, leave dest->local unmodified, or copy the value of local field of the current network path obtained from ngtcp2_conn_get_path(). Both dest->local.addr and dest->remote.addr point to buffers which are at least sizeof(ngtcp2_sockaddr_union) bytes long, respectively. If an application denies the preferred addresses, just leave dest unmodified (or set dest->remote.addrlen to 0), and return 0.

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

typedef 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)

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 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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_recv_new_token)(ngtcp2_conn *conn, const uint8_t *token, size_t tokenlen, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef void (*ngtcp2_delete_crypto_aead_ctx)(ngtcp2_conn *conn, ngtcp2_crypto_aead_ctx *aead_ctx, void *user_data): ngtcp2_delete_crypto_aead_ctx is a callback function which must delete the native object pointed by aead_ctx->native_handle.

typedef void (*ngtcp2_delete_crypto_cipher_ctx)(ngtcp2_conn *conn, ngtcp2_crypto_cipher_ctx *cipher_ctx, void *user_data): ngtcp2_delete_crypto_cipher_ctx is a callback function which must delete the native object pointed by cipher_ctx->native_handle.

typedef int (*ngtcp2_recv_datagram)(ngtcp2_conn *conn, uint32_t flags, const uint8_t *data, size_t datalen, void *user_data)

ngtcp2_recv_datagram is invoked when DATAGRAM frame is received. flags is bitwise-OR of zero or more of NGTCP2_DATAGRAM_FLAG_*.

If 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 NGTCP2_ERR_CALLBACK_FAILURE which makes the library return immediately.

typedef int (*ngtcp2_ack_datagram)(ngtcp2_conn *conn, uint64_t dgram_id, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE which makes the library return immediately.

typedef int (*ngtcp2_lost_datagram)(ngtcp2_conn *conn, uint64_t dgram_id, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE which makes the library return immediately.

typedef int (*ngtcp2_get_path_challenge_data)(ngtcp2_conn *conn, uint8_t *data, void *user_data)

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 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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_stream_stop_sending)(ngtcp2_conn *conn, int64_t stream_id, uint64_t app_error_code, void *user_data, void *stream_user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_version_negotiation)(ngtcp2_conn *conn, uint32_t version, const ngtcp2_cid *client_dcid, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_recv_key)(ngtcp2_conn *conn, ngtcp2_encryption_level level, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

typedef int (*ngtcp2_tls_early_data_rejected)(ngtcp2_conn *conn, void *user_data)

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 NGTCP2_ERR_CALLBACK_FAILURE makes the library call return immediately.

type ngtcp2_callbacks

ngtcp2_callbacks holds a set of callback functions.

ngtcp2_client_initial client_initial: 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.

ngtcp2_recv_client_initial recv_client_initial: 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.

ngtcp2_recv_crypto_data recv_crypto_data: 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.

ngtcp2_handshake_completed handshake_completed: handshake_completed is a callback function which is invoked when QUIC cryptographic handshake has completed. This callback function is optional.

ngtcp2_recv_version_negotiation recv_version_negotiation: recv_version_negotiation is a callback function which is invoked when Version Negotiation packet is received by a client. This callback function is optional.

ngtcp2_encrypt encrypt: encrypt is a callback function which is invoked to encrypt a QUIC packet. This callback function must be specified.

ngtcp2_decrypt decrypt: decrypt is a callback function which is invoked to decrypt a QUIC packet. This callback function must be specified.

ngtcp2_hp_mask hp_mask: 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.

ngtcp2_recv_stream_data recv_stream_data: recv_stream_data is a callback function which is invoked when stream data, which includes application data, is received. This callback function is optional.

ngtcp2_acked_stream_data_offset acked_stream_data_offset: 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.

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

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

ngtcp2_recv_stateless_reset recv_stateless_reset: recv_stateless_reset is a callback function which is invoked when Stateless Reset packet is received. This callback function is optional.

ngtcp2_recv_retry recv_retry: 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.

ngtcp2_extend_max_streams extend_max_local_streams_bidi: 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.

ngtcp2_extend_max_streams extend_max_local_streams_uni: 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.

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

ngtcp2_get_new_connection_id get_new_connection_id: get_new_connection_id is a callback function which is invoked when the library needs new connection ID. This callback function must be specified.

ngtcp2_remove_connection_id remove_connection_id: 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.

ngtcp2_update_key update_key: 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.

ngtcp2_path_validation path_validation: path_validation is a callback function which is invoked when path validation completed. This callback function is optional.

ngtcp2_select_preferred_addr select_preferred_addr: 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.

ngtcp2_stream_reset stream_reset: stream_reset is a callback function which is invoked when a stream is reset by a remote endpoint. This callback function is optional.

ngtcp2_extend_max_streams extend_max_remote_streams_bidi: 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.

ngtcp2_extend_max_streams extend_max_remote_streams_uni: 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.

ngtcp2_extend_max_stream_data extend_max_stream_data: 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.

ngtcp2_connection_id_status dcid_status: 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.

ngtcp2_handshake_confirmed handshake_confirmed: handshake_confirmed is a callback function which is invoked when both endpoints agree that handshake has finished. This field is ignored by server because handshake_completed also indicates the handshake confirmation for server. This callback function is optional.

ngtcp2_recv_new_token recv_new_token: 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.

ngtcp2_delete_crypto_aead_ctx delete_crypto_aead_ctx: delete_crypto_aead_ctx is a callback function which deletes a given AEAD cipher context object. This callback function must be specified.

ngtcp2_delete_crypto_cipher_ctx delete_crypto_cipher_ctx: delete_crypto_cipher_ctx is a callback function which deletes a given cipher context object. This callback function must be specified.

ngtcp2_recv_datagram recv_datagram: recv_datagram is a callback function which is invoked when DATAGRAM frame is received. This callback function is optional.

ngtcp2_ack_datagram ack_datagram: 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.

ngtcp2_lost_datagram lost_datagram: lost_datagram is a callback function which is invoked when a QUIC packet containing DATAGRAM frame is declared lost. This callback function is optional.

ngtcp2_get_path_challenge_data get_path_challenge_data: 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.

ngtcp2_stream_stop_sending stream_stop_sending: 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.

ngtcp2_version_negotiation version_negotiation: version_negotiation is a callback function which is invoked when the compatible version negotiation takes place. This callback function must be specified.

ngtcp2_recv_key recv_rx_key: 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 ngtcp2_encryption_level.NGTCP2_ENCRYPTION_LEVEL_INITIAL.

ngtcp2_recv_key recv_tx_key: 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 ngtcp2_encryption_level.NGTCP2_ENCRYPTION_LEVEL_INITIAL.

ngtcp2_tls_early_data_rejected tls_early_data_rejected: 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

ngtcp2_cid_token is the convenient struct to store Connection ID, its associated path, and stateless reset token.

uint64_t seq: seq is the sequence number of this Connection ID.

ngtcp2_cid cid: cid is Connection ID.

ngtcp2_path_storage ps: ps is the path which this Connection ID is associated with.

uint8_t token[NGTCP2_STATELESS_RESET_TOKENLEN]: token is the stateless reset token for this Connection ID.

uint8_t token_present: token_present is nonzero if token contains stateless reset token.

type ngtcp2_ccerr

ngtcp2_ccerr contains connection error code, its type, a frame type that caused this error, and the optional reason phrase.

ngtcp2_ccerr_type type: type is the type of this error.

uint64_t error_code: error_code is the error code for connection closure. Its interpretation depends on type.

uint64_t frame_type: 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.

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

size_t reasonlen: reasonlen is the length of data pointed by reason.

type ngtcp2_info

ngtcp2_info is what ngtcp2_version() returns. It holds information about the particular ngtcp2 version.

int age: age is the age of this struct. This instance of ngtcp2 sets it to NGTCP2_VERSION_AGE but a future version may bump it and add more struct fields at the bottom

int version_num: version_num is the NGTCP2_VERSION_NUM number (since age ==1)

const char *version_str: version_str points to the NGTCP2_VERSION string (since age ==1)