Macros ====== Library version macros ---------------------- .. macro:: NGTCP2_VERSION Version number of the ngtcp2 library release. .. macro:: NGTCP2_VERSION_NUM Numerical representation of the version number of the ngtcp2 library release. This is a 24 bit number with 8 bits for major number, 8 bits for minor and 8 bits for patch. Version 1.2.3 becomes 0x010203. Time related macros ------------------- .. macro:: NGTCP2_SECONDS :macro:`NGTCP2_SECONDS` is a count of tick which corresponds to 1 second. .. macro:: NGTCP2_MILLISECONDS :macro:`NGTCP2_MILLISECONDS` is a count of tick which corresponds to 1 millisecond. .. macro:: NGTCP2_MICROSECONDS :macro:`NGTCP2_MICROSECONDS` is a count of tick which corresponds to 1 microsecond. .. macro:: NGTCP2_NANOSECONDS :macro:`NGTCP2_NANOSECONDS` is a count of tick which corresponds to 1 nanosecond. QUIC protocol version macros ---------------------------- .. macro:: NGTCP2_PROTO_VER_V1 :macro:`NGTCP2_PROTO_VER_V1` is the QUIC version 1. .. macro:: NGTCP2_PROTO_VER_V2 :macro:`NGTCP2_PROTO_VER_V2` is the QUIC version 2. See :rfc:`9369`. .. macro:: NGTCP2_PROTO_VER_MAX :macro:`NGTCP2_PROTO_VER_MAX` is the highest QUIC version that this library supports. Deprecated since v1.1.0. .. macro:: NGTCP2_PROTO_VER_MIN :macro:`NGTCP2_PROTO_VER_MIN` is the lowest QUIC version that this library supports. Deprecated since v1.1.0. .. macro:: NGTCP2_RESERVED_VERSION_MASK :macro:`NGTCP2_RESERVED_VERSION_MASK` is the bit mask of reserved version. UDP datagram related macros --------------------------- .. macro:: NGTCP2_MAX_UDP_PAYLOAD_SIZE :macro:`NGTCP2_MAX_UDP_PAYLOAD_SIZE` is the default maximum UDP datagram payload size that the local endpoint transmits. .. macro:: NGTCP2_MAX_PMTUD_UDP_PAYLOAD_SIZE :macro:`NGTCP2_MAX_PMTUD_UDP_PAYLOAD_SIZE` is the maximum UDP datagram payload size that Path MTU Discovery can discover. QUIC specific macros -------------------- .. macro:: NGTCP2_MAX_VARINT :macro:`NGTCP2_MAX_VARINT` is the maximum value which can be encoded in variable-length integer encoding. .. macro:: NGTCP2_STATELESS_RESET_TOKENLEN :macro:`NGTCP2_STATELESS_RESET_TOKENLEN` is the length of Stateless Reset Token. .. macro:: NGTCP2_MIN_STATELESS_RESET_RANDLEN :macro:`NGTCP2_MIN_STATELESS_RESET_RANDLEN` is the minimum length of random bytes (Unpredictable Bits) in Stateless Reset packet. .. macro:: NGTCP2_PATH_CHALLENGE_DATALEN :macro:`NGTCP2_PATH_CHALLENGE_DATALEN` is the length of PATH_CHALLENGE data. .. macro:: NGTCP2_RETRY_KEY_V1 :macro:`NGTCP2_RETRY_KEY_V1` is an encryption key to create integrity tag of Retry packet. It is used for QUIC v1. .. macro:: NGTCP2_RETRY_NONCE_V1 :macro:`NGTCP2_RETRY_NONCE_V1` is nonce used when generating integrity tag of Retry packet. It is used for QUIC v1. .. macro:: NGTCP2_RETRY_KEY_V2 :macro:`NGTCP2_RETRY_KEY_V2` is an encryption key to create integrity tag of Retry packet. It is used for QUIC v2. See :rfc:`9369`. .. macro:: NGTCP2_RETRY_NONCE_V2 :macro:`NGTCP2_RETRY_NONCE_V2` is nonce used when generating integrity tag of Retry packet. It is used for QUIC v2. See :rfc:`9369`. .. macro:: NGTCP2_HP_MASKLEN :macro:`NGTCP2_HP_MASKLEN` is the length of header protection mask. .. macro:: NGTCP2_HP_SAMPLELEN :macro:`NGTCP2_HP_SAMPLELEN` is the number bytes sampled when encrypting a packet header. .. macro:: NGTCP2_DEFAULT_INITIAL_RTT :macro:`NGTCP2_DEFAULT_INITIAL_RTT` is a default initial RTT. .. macro:: NGTCP2_MAX_CIDLEN :macro:`NGTCP2_MAX_CIDLEN` is the maximum length of Connection ID. .. macro:: NGTCP2_MIN_CIDLEN :macro:`NGTCP2_MIN_CIDLEN` is the minimum length of Connection ID. .. macro:: NGTCP2_MIN_INITIAL_DCIDLEN :macro:`NGTCP2_MIN_INITIAL_DCIDLEN` is the minimum length of Destination Connection ID in Client Initial packet if it does not bear token from Retry packet. ECN related macros ------------------ .. macro:: NGTCP2_ECN_NOT_ECT :macro:`NGTCP2_ECN_NOT_ECT` indicates no ECN marking. .. macro:: NGTCP2_ECN_ECT_1 :macro:`NGTCP2_ECN_ECT_1` is ECT(1) codepoint. .. macro:: NGTCP2_ECN_ECT_0 :macro:`NGTCP2_ECN_ECT_0` is ECT(0) codepoint. .. macro:: NGTCP2_ECN_CE :macro:`NGTCP2_ECN_CE` is CE codepoint. .. macro:: NGTCP2_ECN_MASK :macro:`NGTCP2_ECN_MASK` is a bit mask to get ECN marking. ngtcp2 library error codes -------------------------- .. macro:: NGTCP2_ERR_INVALID_ARGUMENT :macro:`NGTCP2_ERR_INVALID_ARGUMENT` indicates that a passed argument is invalid. .. macro:: NGTCP2_ERR_NOBUF :macro:`NGTCP2_ERR_NOBUF` indicates that a provided buffer does not have enough space to store data. .. macro:: NGTCP2_ERR_PROTO :macro:`NGTCP2_ERR_PROTO` indicates a general protocol error. .. macro:: NGTCP2_ERR_INVALID_STATE :macro:`NGTCP2_ERR_INVALID_STATE` indicates that a requested operation is not allowed at the current connection state. .. macro:: NGTCP2_ERR_ACK_FRAME :macro:`NGTCP2_ERR_ACK_FRAME` indicates that an invalid ACK frame is received. .. macro:: NGTCP2_ERR_STREAM_ID_BLOCKED :macro:`NGTCP2_ERR_STREAM_ID_BLOCKED` indicates that there is no spare stream ID available. .. macro:: NGTCP2_ERR_STREAM_IN_USE :macro:`NGTCP2_ERR_STREAM_IN_USE` indicates that a stream ID is already in use. .. macro:: NGTCP2_ERR_STREAM_DATA_BLOCKED :macro:`NGTCP2_ERR_STREAM_DATA_BLOCKED` indicates that stream data cannot be sent because of flow control. .. macro:: NGTCP2_ERR_FLOW_CONTROL :macro:`NGTCP2_ERR_FLOW_CONTROL` indicates flow control error. .. macro:: NGTCP2_ERR_CONNECTION_ID_LIMIT :macro:`NGTCP2_ERR_CONNECTION_ID_LIMIT` indicates that the number of received Connection ID exceeds acceptable limit. .. macro:: NGTCP2_ERR_STREAM_LIMIT :macro:`NGTCP2_ERR_STREAM_LIMIT` indicates that a remote endpoint opens more streams that is permitted. .. macro:: NGTCP2_ERR_FINAL_SIZE :macro:`NGTCP2_ERR_FINAL_SIZE` indicates that inconsistent final size of a stream. .. macro:: NGTCP2_ERR_CRYPTO :macro:`NGTCP2_ERR_CRYPTO` indicates crypto (TLS) related error. .. macro:: NGTCP2_ERR_PKT_NUM_EXHAUSTED :macro:`NGTCP2_ERR_PKT_NUM_EXHAUSTED` indicates that packet number is exhausted. .. macro:: NGTCP2_ERR_REQUIRED_TRANSPORT_PARAM :macro:`NGTCP2_ERR_REQUIRED_TRANSPORT_PARAM` indicates that a required transport parameter is missing. .. macro:: NGTCP2_ERR_MALFORMED_TRANSPORT_PARAM :macro:`NGTCP2_ERR_MALFORMED_TRANSPORT_PARAM` indicates that a transport parameter is malformed. .. macro:: NGTCP2_ERR_FRAME_ENCODING :macro:`NGTCP2_ERR_FRAME_ENCODING` indicates there is an error in frame encoding. .. macro:: NGTCP2_ERR_DECRYPT :macro:`NGTCP2_ERR_DECRYPT` indicates a decryption failure. .. macro:: NGTCP2_ERR_STREAM_SHUT_WR :macro:`NGTCP2_ERR_STREAM_SHUT_WR` indicates no more data can be sent to a stream. .. macro:: NGTCP2_ERR_STREAM_NOT_FOUND :macro:`NGTCP2_ERR_STREAM_NOT_FOUND` indicates that a stream was not found. .. macro:: NGTCP2_ERR_STREAM_STATE :macro:`NGTCP2_ERR_STREAM_STATE` indicates that a requested operation is not allowed at the current stream state. .. macro:: NGTCP2_ERR_RECV_VERSION_NEGOTIATION :macro:`NGTCP2_ERR_RECV_VERSION_NEGOTIATION` indicates that Version Negotiation packet was received. .. macro:: NGTCP2_ERR_CLOSING :macro:`NGTCP2_ERR_CLOSING` indicates that connection is in closing state. .. macro:: NGTCP2_ERR_DRAINING :macro:`NGTCP2_ERR_DRAINING` indicates that connection is in draining state. .. macro:: NGTCP2_ERR_TRANSPORT_PARAM :macro:`NGTCP2_ERR_TRANSPORT_PARAM` indicates a general transport parameter error. .. macro:: NGTCP2_ERR_DISCARD_PKT :macro:`NGTCP2_ERR_DISCARD_PKT` indicates a packet was discarded. .. macro:: NGTCP2_ERR_CONN_ID_BLOCKED :macro:`NGTCP2_ERR_CONN_ID_BLOCKED` indicates that there is no spare Connection ID available. .. macro:: NGTCP2_ERR_INTERNAL :macro:`NGTCP2_ERR_INTERNAL` indicates an internal error. .. macro:: NGTCP2_ERR_CRYPTO_BUFFER_EXCEEDED :macro:`NGTCP2_ERR_CRYPTO_BUFFER_EXCEEDED` indicates that a crypto buffer exceeded. .. macro:: NGTCP2_ERR_WRITE_MORE :macro:`NGTCP2_ERR_WRITE_MORE` indicates :macro:`NGTCP2_WRITE_STREAM_FLAG_MORE` is used and a function call succeeded. .. macro:: NGTCP2_ERR_RETRY :macro:`NGTCP2_ERR_RETRY` indicates that server should send Retry packet. .. macro:: NGTCP2_ERR_DROP_CONN :macro:`NGTCP2_ERR_DROP_CONN` indicates that an endpoint should drop connection immediately. .. macro:: NGTCP2_ERR_AEAD_LIMIT_REACHED :macro:`NGTCP2_ERR_AEAD_LIMIT_REACHED` indicates AEAD encryption limit is reached and key update is not available. An endpoint should drop connection immediately. .. macro:: NGTCP2_ERR_NO_VIABLE_PATH :macro:`NGTCP2_ERR_NO_VIABLE_PATH` indicates that path validation could not probe that a path is capable of sending UDP datagram payload of size at least 1200 bytes. .. macro:: NGTCP2_ERR_VERSION_NEGOTIATION :macro:`NGTCP2_ERR_VERSION_NEGOTIATION` indicates that server should send Version Negotiation packet. .. macro:: NGTCP2_ERR_HANDSHAKE_TIMEOUT :macro:`NGTCP2_ERR_HANDSHAKE_TIMEOUT` indicates that QUIC connection is not established before the specified deadline. .. macro:: NGTCP2_ERR_VERSION_NEGOTIATION_FAILURE :macro:`NGTCP2_ERR_VERSION_NEGOTIATION_FAILURE` indicates the version negotiation failed. .. macro:: NGTCP2_ERR_IDLE_CLOSE :macro:`NGTCP2_ERR_IDLE_CLOSE` indicates the connection should be closed silently because of idle timeout. .. macro:: NGTCP2_ERR_FATAL :macro:`NGTCP2_ERR_FATAL` indicates that error codes less than this value is fatal error. When this error is returned, an endpoint should close connection immediately. .. macro:: NGTCP2_ERR_NOMEM :macro:`NGTCP2_ERR_NOMEM` indicates out of memory. .. macro:: NGTCP2_ERR_CALLBACK_FAILURE :macro:`NGTCP2_ERR_CALLBACK_FAILURE` indicates that user defined callback function failed. QUIC packet header flags ------------------------ .. macro:: NGTCP2_PKT_FLAG_NONE :macro:`NGTCP2_PKT_FLAG_NONE` indicates no flag set. .. macro:: NGTCP2_PKT_FLAG_LONG_FORM :macro:`NGTCP2_PKT_FLAG_LONG_FORM` indicates the Long header packet header. .. macro:: NGTCP2_PKT_FLAG_FIXED_BIT_CLEAR :macro:`NGTCP2_PKT_FLAG_FIXED_BIT_CLEAR` indicates that Fixed Bit (aka QUIC bit) is not set. .. macro:: NGTCP2_PKT_FLAG_KEY_PHASE :macro:`NGTCP2_PKT_FLAG_KEY_PHASE` indicates Key Phase bit set. QUIC transport error code ------------------------- .. macro:: NGTCP2_NO_ERROR :macro:`NGTCP2_NO_ERROR` is QUIC transport error code ``NO_ERROR``. .. macro:: NGTCP2_INTERNAL_ERROR :macro:`NGTCP2_INTERNAL_ERROR` is QUIC transport error code ``INTERNAL_ERROR``. .. macro:: NGTCP2_CONNECTION_REFUSED :macro:`NGTCP2_CONNECTION_REFUSED` is QUIC transport error code ``CONNECTION_REFUSED``. .. macro:: NGTCP2_FLOW_CONTROL_ERROR :macro:`NGTCP2_FLOW_CONTROL_ERROR` is QUIC transport error code ``FLOW_CONTROL_ERROR``. .. macro:: NGTCP2_STREAM_LIMIT_ERROR :macro:`NGTCP2_STREAM_LIMIT_ERROR` is QUIC transport error code ``STREAM_LIMIT_ERROR``. .. macro:: NGTCP2_STREAM_STATE_ERROR :macro:`NGTCP2_STREAM_STATE_ERROR` is QUIC transport error code ``STREAM_STATE_ERROR``. .. macro:: NGTCP2_FINAL_SIZE_ERROR :macro:`NGTCP2_FINAL_SIZE_ERROR` is QUIC transport error code ``FINAL_SIZE_ERROR``. .. macro:: NGTCP2_FRAME_ENCODING_ERROR :macro:`NGTCP2_FRAME_ENCODING_ERROR` is QUIC transport error code ``FRAME_ENCODING_ERROR``. .. macro:: NGTCP2_TRANSPORT_PARAMETER_ERROR :macro:`NGTCP2_TRANSPORT_PARAMETER_ERROR` is QUIC transport error code ``TRANSPORT_PARAMETER_ERROR``. .. macro:: NGTCP2_CONNECTION_ID_LIMIT_ERROR :macro:`NGTCP2_CONNECTION_ID_LIMIT_ERROR` is QUIC transport error code ``CONNECTION_ID_LIMIT_ERROR``. .. macro:: NGTCP2_PROTOCOL_VIOLATION :macro:`NGTCP2_PROTOCOL_VIOLATION` is QUIC transport error code ``PROTOCOL_VIOLATION``. .. macro:: NGTCP2_INVALID_TOKEN :macro:`NGTCP2_INVALID_TOKEN` is QUIC transport error code ``INVALID_TOKEN``. .. macro:: NGTCP2_APPLICATION_ERROR :macro:`NGTCP2_APPLICATION_ERROR` is QUIC transport error code ``APPLICATION_ERROR``. .. macro:: NGTCP2_CRYPTO_BUFFER_EXCEEDED :macro:`NGTCP2_CRYPTO_BUFFER_EXCEEDED` is QUIC transport error code ``CRYPTO_BUFFER_EXCEEDED``. .. macro:: NGTCP2_KEY_UPDATE_ERROR :macro:`NGTCP2_KEY_UPDATE_ERROR` is QUIC transport error code ``KEY_UPDATE_ERROR``. .. macro:: NGTCP2_AEAD_LIMIT_REACHED :macro:`NGTCP2_AEAD_LIMIT_REACHED` is QUIC transport error code ``AEAD_LIMIT_REACHED``. .. macro:: NGTCP2_NO_VIABLE_PATH :macro:`NGTCP2_NO_VIABLE_PATH` is QUIC transport error code ``NO_VIABLE_PATH``. .. macro:: NGTCP2_CRYPTO_ERROR :macro:`NGTCP2_CRYPTO_ERROR` is QUIC transport error code ``CRYPTO_ERROR``. .. macro:: NGTCP2_VERSION_NEGOTIATION_ERROR :macro:`NGTCP2_VERSION_NEGOTIATION_ERROR` is QUIC transport error code ``VERSION_NEGOTIATION_ERROR``. See :rfc:`9368`. QUIC transport parameters related macros ---------------------------------------- .. macro:: NGTCP2_DEFAULT_MAX_RECV_UDP_PAYLOAD_SIZE :macro:`NGTCP2_DEFAULT_MAX_RECV_UDP_PAYLOAD_SIZE` is the default value of max_udp_payload_size transport parameter. .. macro:: NGTCP2_DEFAULT_ACK_DELAY_EXPONENT :macro:`NGTCP2_DEFAULT_ACK_DELAY_EXPONENT` is a default value of scaling factor of ACK Delay field in ACK frame. .. macro:: NGTCP2_DEFAULT_MAX_ACK_DELAY :macro:`NGTCP2_DEFAULT_MAX_ACK_DELAY` is a default value of the maximum amount of time in nanoseconds by which endpoint delays sending acknowledgement. .. macro:: NGTCP2_DEFAULT_ACTIVE_CONNECTION_ID_LIMIT :macro:`NGTCP2_DEFAULT_ACTIVE_CONNECTION_ID_LIMIT` is the default value of active_connection_id_limit transport parameter value if omitted. .. macro:: NGTCP2_TLSEXT_QUIC_TRANSPORT_PARAMETERS_V1 :macro:`NGTCP2_TLSEXT_QUIC_TRANSPORT_PARAMETERS_V1` is TLS extension type of quic_transport_parameters. QLog related macros ------------------- .. macro:: NGTCP2_QLOG_WRITE_FLAG_NONE :macro:`NGTCP2_QLOG_WRITE_FLAG_NONE` indicates no flag set. .. macro:: NGTCP2_QLOG_WRITE_FLAG_FIN :macro:`NGTCP2_QLOG_WRITE_FLAG_FIN` indicates that this is the final call to :type:`ngtcp2_qlog_write` in the current connection. STREAM frame data flags ----------------------- .. macro:: NGTCP2_STREAM_DATA_FLAG_NONE :macro:`NGTCP2_STREAM_DATA_FLAG_NONE` indicates no flag set. .. macro:: NGTCP2_STREAM_DATA_FLAG_FIN :macro:`NGTCP2_STREAM_DATA_FLAG_FIN` indicates that this chunk of data is final piece of an incoming stream. .. macro:: NGTCP2_STREAM_DATA_FLAG_0RTT :macro:`NGTCP2_STREAM_DATA_FLAG_0RTT` indicates that this chunk of data contains data received in 0-RTT packet, and the handshake has not completed yet, which means that the data might be replayed. Stream close flags ------------------ .. macro:: NGTCP2_STREAM_CLOSE_FLAG_NONE :macro:`NGTCP2_STREAM_CLOSE_FLAG_NONE` indicates no flag set. .. macro:: NGTCP2_STREAM_CLOSE_FLAG_APP_ERROR_CODE_SET :macro:`NGTCP2_STREAM_CLOSE_FLAG_APP_ERROR_CODE_SET` indicates that app_error_code parameter is set. Path validation related macros ------------------------------ .. macro:: NGTCP2_PATH_VALIDATION_FLAG_NONE :macro:`NGTCP2_PATH_VALIDATION_FLAG_NONE` indicates no flag set. .. macro:: NGTCP2_PATH_VALIDATION_FLAG_PREFERRED_ADDR :macro:`NGTCP2_PATH_VALIDATION_FLAG_PREFERRED_ADDR` indicates the validation involving server preferred address. This flag is only set for client. .. macro:: NGTCP2_PATH_VALIDATION_FLAG_NEW_TOKEN :macro:`NGTCP2_PATH_VALIDATION_FLAG_NEW_TOKEN` indicates that server should send NEW_TOKEN frame for the new remote address. This flag is only set for server. DATAGRAM frame flags -------------------- .. macro:: NGTCP2_DATAGRAM_FLAG_NONE :macro:`NGTCP2_DATAGRAM_FLAG_NONE` indicates no flag set. .. macro:: NGTCP2_DATAGRAM_FLAG_0RTT :macro:`NGTCP2_DATAGRAM_FLAG_0RTT` indicates that DATAGRAM frame is received in 0-RTT packet, and the handshake has not completed yet, which means that the data might be replayed. Write stream data flags ----------------------- .. macro:: NGTCP2_WRITE_STREAM_FLAG_NONE :macro:`NGTCP2_WRITE_STREAM_FLAG_NONE` indicates no flag set. .. macro:: NGTCP2_WRITE_STREAM_FLAG_MORE :macro:`NGTCP2_WRITE_STREAM_FLAG_MORE` indicates that more data may come, and should be coalesced into the same packet if possible. .. macro:: NGTCP2_WRITE_STREAM_FLAG_FIN :macro:`NGTCP2_WRITE_STREAM_FLAG_FIN` indicates that a passed data is the final part of a stream. Write datagram flags -------------------- .. macro:: NGTCP2_WRITE_DATAGRAM_FLAG_NONE :macro:`NGTCP2_WRITE_DATAGRAM_FLAG_NONE` indicates no flag set. .. macro:: NGTCP2_WRITE_DATAGRAM_FLAG_MORE :macro:`NGTCP2_WRITE_DATAGRAM_FLAG_MORE` indicates that more data may come, and should be coalesced into the same packet if possible. ngtcp2_info macros ------------------ .. macro:: NGTCP2_VERSION_AGE :macro:`NGTCP2_VERSION_AGE` is the age of :type:`ngtcp2_info`