
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 = {
            .malloc = my_malloc_cb,
            .free = my_free_cb,
            .calloc = my_calloc_cb,
            .realloc = 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_*
        <NGTCP2_PKT_FLAG_NONE>`.

.. 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.  If specified, it must be in
        the range of [:macro:`NGTCP2_DEFAULT_ACTIVE_CONNECTION_ID_LIMIT`,
        8], inclusive.
    .. 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.
    .. member::   uint64_t pkt_sent

        :member:`pkt_sent` is the number of QUIC packets sent.  This
        field has been available since v1.16.0.
    .. member::   uint64_t bytes_sent

        :member:`bytes_sent` is the number of bytes (the sum of QUIC
        packet length) sent.  This field has been available since
        v1.16.0.
    .. member::   uint64_t pkt_recv

        :member:`pkt_recv` is the number of QUIC packets received,
        excluding discarded ones.  This field has been available since
        v1.16.0.
    .. member::   uint64_t bytes_recv

        :member:`bytes_recv` is the number of bytes (the sum of QUIC
        packet length) received, excluding discarded ones.  This field
        has been available since v1.16.0.
    .. member::   uint64_t pkt_lost

        :member:`pkt_lost` is the number of QUIC packets that are
        considered lost, excluding PMTUD packets.  This field has been
        available since v1.16.0.
    .. member::   uint64_t bytes_lost

        :member:`bytes_lost` is the number of bytes (the sum of QUIC
        packet length) lost, excluding PMTUD packets.  This field has
        been available since v1.16.0.
    .. member::   uint64_t ping_recv

        :member:`ping_recv` is the number of PING frames received.  This
        field has been available since v1.16.0.
    .. member::   uint64_t pkt_discarded

        :member:`pkt_discarded` is the number of QUIC packets discarded.
        This field has been available since v1.16.0.

.. 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_*
    <NGTCP2_QLOG_WRITE_FLAG_NONE>`.  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.  This must be
        larger than or equal to :macro:`NGTCP2_MAX_UDP_PAYLOAD_SIZE`, and
        less then or equal to :macro:`NGTCP2_MAX_TX_UDP_PAYLOAD_SIZE`.
    .. 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.
        
        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.
    .. 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
        <ngtcp2_version_info.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:`initial_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 payload size must be strictly
        larger than :macro:`NGTCP2_MAX_UDP_PAYLOAD_SIZE`, and less than
        or equal to :macro:`NGTCP2_MAX_TX_UDP_PAYLOAD_SIZE`.  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.
    .. member::   uint64_t glitch_ratelim_burst

        :member:`glitch_ratelim_burst` is the maximum number of tokens
        available to "glitch" rate limiter.  "glitch" is a suspicious
        activity from a remote endpoint.  If detected, certain amount of
        tokens are consumed.  If no tokens are available to consume, the
        connection is closed.  The rate of token generation is specified
        by :member:`glitch_ratelim_rate`.  This field has been available
        since v1.15.0.
    .. member::   uint64_t glitch_ratelim_rate

        :member:`glitch_ratelim_rate` is the number of tokens generated
        per second.  See :member:`glitch_ratelim_burst` for "glitch" rate
        limiter.  This field has been available since v1.15.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 <ngtcp2_pkt_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_*
    <NGTCP2_STREAM_DATA_FLAG_NONE>`.  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_*
    <NGTCP2_STREAM_CLOSE_FLAG_NONE>`.  *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.  But it is strongly recommended to use a
    secure random number generator.
.. 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_begin_path_validation)(ngtcp2_conn *conn, uint32_t flags, const ngtcp2_path *path, const ngtcp2_path *fallback_path, void *user_data)

    
    :type:`ngtcp2_begin_path_validation` is a callback function which
    is called when the path validation has started.  *flags* is zero or
    more of :macro:`NGTCP2_PATH_VALIDATION_FLAG_*
    <NGTCP2_PATH_VALIDATION_FLAG_NONE>`.  *path* is the path that is
    being validated.  *fallback_path*, if not NULL, is the path that is
    used when this validation fails.
    
    Currently, the flags may only contain
    :macro:`NGTCP2_PATH_VALIDATION_FLAG_PREFERRED_ADDR`.
    
    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 *fallback_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_*
    <NGTCP2_PATH_VALIDATION_FLAG_NONE>`.  *path* is the path that was
    validated.  *fallback_path*, if not NULL, is the path that is used
    if the path validation failed.  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 <ngtcp2_path.remote>`, a client source
    address must be set to :member:`dest->local <ngtcp2_path.local>`.
    If a client source address does not change for the new server
    address, leave :member:`dest->local <ngtcp2_path.local>`
    unmodified, or copy the value of :member:`local
    <ngtcp2_path.local>` field of the current network path obtained
    from `ngtcp2_conn_get_path()`.  Both :member:`dest->local.addr
    <ngtcp2_addr.addr>` and :member:`dest->remote.addr
    <ngtcp2_addr.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
    <ngtcp2_addr.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
    <ngtcp2_crypto_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
    <ngtcp2_crypto_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_* <NGTCP2_DATAGRAM_FLAG_NONE>`.
    
    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.
    .. member::   ngtcp2_begin_path_validation begin_path_validation

        :member:`begin_path_validation` is a callback function which is
        invoked when a path validation has started.  This field is
        available since v1.14.0.

.. 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_ssize (*ngtcp2_write_pkt)(ngtcp2_conn *conn, ngtcp2_path *path, ngtcp2_pkt_info *pi, uint8_t *dest, size_t destlen, ngtcp2_tstamp ts, void *user_data)

    
    :type:`ngtcp2_write_pkt` is a callback function to write a single
    packet in the buffer pointed by *dest* of length *destlen*.  The
    implementation should use `ngtcp2_conn_write_pkt`,
    `ngtcp2_conn_writev_stream`, `ngtcp2_conn_writev_datagram`, or
    their variants to write the packet.  *path*, *pi*, *dest*,
    *destlen*, and *ts* should be directly passed to those functions.
    If the callback succeeds, it should return the number of bytes
    written to the buffer.  In general, this callback function should
    return the value that the above mentioned functions returned except
    for the following error codes:
    
    - :macro:`NGTCP2_ERR_STREAM_DATA_BLOCKED`
    - :macro:`NGTCP2_ERR_STREAM_SHUT_WR`
    - :macro:`NGTCP2_ERR_STREAM_NOT_FOUND`
    
    Those error codes should be handled by an application.  If any
    error occurred outside those functions, return
    :macro:`NGTCP2_ERR_CALLBACK_FAILURE`.  If no packet is produced,
    return 0.
    
    Because GSO requires that the aggregated packets have the same
    length, :macro:`NGTCP2_WRITE_STREAM_FLAG_PADDING` (or
    :macro:`NGTCP2_WRITE_DATAGRAM_FLAG_PADDING` if
    `ngtcp2_conn_writev_datagram` is used) is recommended.
    
    This callback function has been available since v1.15.0.
.. 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)

