xquic/xqc_http3.h

Classes

	Name
struct	xqc_http_header_s
struct	xqc_http_headers_s
struct	xqc_request_stats_s request statistics structure
struct	xqc_h3_ext_bytestream_stats_s bytestream statistics
struct	xqc_h3_conn_settings_s connection settings for http3
struct	xqc_h3_ext_dgram_callbacks_s
struct	xqc_h3_conn_callbacks_s http3 connection callbacks for application layer
struct	xqc_h3_request_callbacks_s http3 request callbacks for application layer
struct	xqc_h3_ext_bytestream_callbacks_s
struct	xqc_h3_callbacks_s

Types

	Name
enum	xqc_request_notify_flag_t { XQC_REQ_NOTIFY_READ_NULL = 0, XQC_REQ_NOTIFY_READ_HEADER = 1 << 0, XQC_REQ_NOTIFY_READ_BODY = 1 << 1, XQC_REQ_NOTIFY_READ_TRAILER = 1 << 2, XQC_REQ_NOTIFY_READ_EMPTY_FIN = 1 << 3} read flag of xqc_h3_request_read_notify_pt
enum	xqc_http3_nv_flag_s { XQC_HTTP_HEADER_FLAG_NONE = 0x00, XQC_HTTP_HEADER_FLAG_NEVER_INDEX = 0x01, XQC_HTTP_HEADER_FLAG_NEVER_INDEX_VALUE = 0x02} encode flags of http headers
typedef int(*)(xqc_h3_conn_t *h3_conn, const xqc_cid_t *cid, void *h3c_user_data)	xqc_h3_conn_notify_pt definition for http3 connection state callback function. including create and close
typedef void(*)(xqc_h3_conn_t *h3_conn, void *h3c_user_data)	xqc_h3_handshake_finished_pt
typedef void(*)(xqc_h3_conn_t *h3_conn, const xqc_cid_t *cid, void *ping_user_data, void *h3c_user_data)	xqc_h3_conn_ping_ack_notify_pt
typedef int(*)(xqc_h3_request_t *h3_request, void *h3s_user_data)	xqc_h3_request_notify_pt http3 request callbacks
typedef int(*)(xqc_h3_request_t *h3_request, xqc_request_notify_flag_t flag, void *h3s_user_data)	xqc_h3_request_read_notify_pt read data callback function
typedef void(*)(xqc_h3_request_t *h3_request, xqc_int_t err, void *h3s_user_data)	xqc_h3_request_closing_notify_pt
typedef enum xqc_http3_nv_flag_s	xqc_http3_nv_flag_t encode flags of http headers
typedef struct xqc_http_header_s	xqc_http_header_t
typedef struct xqc_http_headers_s	xqc_http_headers_t
typedef struct xqc_request_stats_s	xqc_request_stats_t request statistics structure
typedef struct xqc_h3_ext_bytestream_stats_s	xqc_h3_ext_bytestream_stats_t bytestream statistics
typedef struct xqc_h3_conn_settings_s	xqc_h3_conn_settings_t connection settings for http3
typedef int(*)(xqc_h3_ext_bytestream_t *h3_ext_bs, const void *data, size_t data_len, uint8_t fin, void *bs_user_data, uint64_t data_recv_time)	xqc_h3_ext_bytestream_read_notify_pt callback for h3 bytestream read
typedef int(*)(xqc_h3_ext_bytestream_t *h3_ext_bs, void *bs_user_data)	xqc_h3_ext_bytestream_notify_pt callbacks for extended h3 bytestream
typedef void(*)(xqc_h3_conn_t *conn, const void *data, size_t data_len, void *user_data, uint64_t data_recv_time)	xqc_h3_ext_datagram_read_notify_pt the callback API to notify the application that there is a datagram to be read
typedef void(*)(xqc_h3_conn_t *conn, void *user_data)	xqc_h3_ext_datagram_write_notify_pt the callback API to notify the application that datagrams can be sent
typedef int(*)(xqc_h3_conn_t *conn, uint64_t dgram_id, void *user_data)	xqc_h3_ext_datagram_lost_notify_pt the callback API to notify the application that a datagram is declared lost. However, the datagram could also be acknowledged later, as the underlying loss detection is not fully accurate. Applications should handle this type of spurious loss. The return value is used to ask the QUIC stack to retransmit the lost datagram packet.
typedef void(*)(xqc_h3_conn_t *conn, uint64_t dgram_id, void *user_data)	xqc_h3_ext_datagram_acked_notify_pt the callback API to notify the application that a datagram is acked
typedef void(*)(xqc_h3_conn_t *conn, size_t mss, void *user_data)	xqc_h3_ext_datagram_mss_updated_notify_pt the callback to notify application the MSS of QUIC datagrams. Note, the MSS of QUIC datagrams will never shrink. If the MSS is zero, it means this connection does not support sending QUIC datagrams.
typedef struct xqc_h3_ext_dgram_callbacks_s	xqc_h3_ext_dgram_callbacks_t
typedef struct xqc_h3_conn_callbacks_s	xqc_h3_conn_callbacks_t http3 connection callbacks for application layer
typedef struct xqc_h3_request_callbacks_s	xqc_h3_request_callbacks_t http3 request callbacks for application layer
typedef struct xqc_h3_ext_bytestream_callbacks_s	xqc_h3_ext_bytestream_callbacks_t
typedef struct xqc_h3_callbacks_s	xqc_h3_callbacks_t

Functions

	Name
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_ctx_init(xqc_engine_t * engine, xqc_h3_callbacks_t * h3_cbs) init h3 context into xqc_engine_t, this MUST BE called before create any http3 connection
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_ctx_destroy(xqc_engine_t * engine)
XQC_EXPORT_PUBLIC_API void	xqc_h3_engine_set_max_dtable_capacity(xqc_engine_t * engine, size_t capacity) set max h3 max dynamic table capacity. It MUST only be called after xqc_h3_ctx_init.
XQC_EXPORT_PUBLIC_API void	xqc_h3_engine_set_dec_max_dtable_capacity(xqc_engine_t * engine, size_t value)
XQC_EXPORT_PUBLIC_API void	xqc_h3_engine_set_enc_max_dtable_capacity(xqc_engine_t * engine, size_t value)
XQC_EXPORT_PUBLIC_API void	xqc_h3_engine_set_max_field_section_size(xqc_engine_t * engine, size_t size) set max h3 field section size. It MUST only be called after xqc_h3_ctx_init.
XQC_EXPORT_PUBLIC_API void	xqc_h3_engine_set_qpack_blocked_streams(xqc_engine_t * engine, size_t value) set the limit for qpack blocked streams. It MUST only be called after xqc_h3_ctx_init.
XQC_EXPORT_PUBLIC_API void	xqc_h3_engine_set_local_settings(xqc_engine_t * engine, const xqc_h3_conn_settings_t * h3_conn_settings)
XQC_EXPORT_PUBLIC_API const xqc_cid_t *	xqc_h3_connect(xqc_engine_t * engine, const xqc_conn_settings_t * conn_settings, const unsigned char * token, unsigned token_len, const char * server_host, int no_crypto_flag, const xqc_conn_ssl_config_t * conn_ssl_config, const struct sockaddr * peer_addr, socklen_t peer_addrlen, void * user_data) create and http3 connection
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_conn_close(xqc_engine_t * engine, const xqc_cid_t * cid) manually close a http3 connection
XQC_EXPORT_PUBLIC_API xqc_connection_t *	xqc_h3_conn_get_xqc_conn(xqc_h3_conn_t * h3c) get QUIC connection handler
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_conn_get_errno(xqc_h3_conn_t * h3c) get http3 protocol error number
XQC_EXPORT_PUBLIC_API void *	xqc_h3_conn_get_ssl(xqc_h3_conn_t * h3c) get ssl handler of http3 connection
XQC_EXPORT_PUBLIC_API void	xqc_h3_conn_set_user_data(xqc_h3_conn_t * h3c, void * user_data) set user_data for http3 connection, user_data could be the application layer context of http3 connection
XQC_EXPORT_PUBLIC_API void *	xqc_h3_conn_get_user_data(xqc_h3_conn_t * h3_conn) get user_data for http3 connection, user_data could be the application layer context of http3 connection
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_conn_get_peer_addr(xqc_h3_conn_t * h3c, struct sockaddr * addr, socklen_t addr_cap, socklen_t * peer_addr_len) get peer address information, server should call this when h3_conn_create_notify triggers
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_conn_get_local_addr(xqc_h3_conn_t * h3c, struct sockaddr * addr, socklen_t addr_cap, socklen_t * local_addr_len) get local address information, server should call this when h3_conn_create_notify triggers
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_conn_send_ping(xqc_engine_t * engine, const xqc_cid_t * cid, void * ping_user_data) Send PING to peer, if ack received, h3_conn_ping_acked will callback with user_data.
XQC_EXPORT_PUBLIC_API xqc_bool_t	xqc_h3_conn_is_ready_to_send_early_data(xqc_h3_conn_t * h3c) check if h3 connection is ready to send 0rtt data
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_conn_set_qpack_dtable_cap(xqc_h3_conn_t * h3c, size_t capacity) set the dynamic table capacity of an existing h3 connection
XQC_EXPORT_PUBLIC_API xqc_h3_request_t *	xqc_h3_request_create(xqc_engine_t * engine, const xqc_cid_t * cid, xqc_stream_settings_t * settings, void * user_data) create a http3 request
XQC_EXPORT_PUBLIC_API xqc_request_stats_t	xqc_h3_request_get_stats(xqc_h3_request_t * h3_request) get statistics of a http3 request user can get it before request destroyed
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_request_stats_print(xqc_h3_request_t * h3_request, char * str, size_t size) write important information into str
XQC_EXPORT_PUBLIC_API void	xqc_h3_request_set_user_data(xqc_h3_request_t * h3_request, void * user_data) set user_data of a http3 request, which will be used as parameter of request callback functions. server should set user_data when h3_request_create_notify triggers
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_request_close(xqc_h3_request_t * h3_request) close request, send QUIC RESET_STREAM frame to peer. h3_request_close_notify will triggered when request is finally destroyed
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_request_update_settings(xqc_h3_request_t * h3_request, xqc_stream_settings_t * settings)
XQC_EXPORT_PUBLIC_API ssize_t	xqc_h3_request_send_headers(xqc_h3_request_t * h3_request, xqc_http_headers_t * headers, uint8_t fin) send http headers to peer
XQC_EXPORT_PUBLIC_API ssize_t	xqc_h3_request_send_body(xqc_h3_request_t * h3_request, unsigned char * data, size_t data_size, uint8_t fin) send http body to peer
XQC_EXPORT_PUBLIC_API ssize_t	xqc_h3_request_finish(xqc_h3_request_t * h3_request) finish request. if fin is not sent yet, and application has nothing to send anymore, call this function to send a QUIC STREAM frame with only fin
XQC_EXPORT_PUBLIC_API xqc_http_headers_t *	xqc_h3_request_recv_headers(xqc_h3_request_t * h3_request, uint8_t * fin) receive headers of a request
XQC_EXPORT_PUBLIC_API ssize_t	xqc_h3_request_recv_body(xqc_h3_request_t * h3_request, unsigned char * recv_buf, size_t recv_buf_size, uint8_t * fin) receive body of a request
XQC_EXPORT_PUBLIC_API void *	xqc_h3_get_conn_user_data_by_request(xqc_h3_request_t * h3_request) get connection's user_data by request
XQC_EXPORT_PUBLIC_API xqc_stream_id_t	xqc_h3_stream_id(xqc_h3_request_t * h3_request) Get QUIC stream ID by request.
XQC_EXPORT_PUBLIC_API void	xqc_h3_priority_init(xqc_h3_priority_t * prio) RFC 9218 HTTP Priority.
XQC_EXPORT_PUBLIC_API size_t	xqc_write_http_priority(xqc_h3_priority_t * prio, uint8_t * dst, size_t dstcap)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_parse_http_priority(xqc_h3_priority_t * dst, const uint8_t * str, size_t str_len)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_request_set_priority(xqc_h3_request_t * h3r, xqc_h3_priority_t * prio)
XQC_EXPORT_PUBLIC_API xqc_h3_ext_bytestream_t *	xqc_h3_ext_bytestream_create(xqc_engine_t * engine, const xqc_cid_t * cid, void * user_data) create a bytestream based on extended H3
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_ext_bytestream_close(xqc_h3_ext_bytestream_t * h3_ext_bs) close bytestream, send QUIC RESET_STREAM frame to peer. h3_ext_bytestream_close_notify will triggered when bytestream is finally destroyed
XQC_EXPORT_PUBLIC_API ssize_t	xqc_h3_ext_bytestream_finish(xqc_h3_ext_bytestream_t * h3_ext_bs) finish bytestream. if fin is not sent yet, and application has nothing to send anymore, call this function to send a QUIC STREAM frame with only fin
XQC_EXPORT_PUBLIC_API void	xqc_h3_ext_bytestream_set_user_data(xqc_h3_ext_bytestream_t * h3_ext_bs, void * user_data) set user_data of a bytestream, which will be used as the parameter of the bytestream callback functions. server should set user_data when h3_ext_bytestream_create_notify triggers
XQC_EXPORT_PUBLIC_API void *	xqc_h3_ext_bytestream_get_user_data(xqc_h3_ext_bytestream_t * h3_ext_bs) get the user data associcated with the bytestream object
XQC_EXPORT_PUBLIC_API xqc_h3_ext_bytestream_stats_t	xqc_h3_ext_bytestream_get_stats(xqc_h3_ext_bytestream_t * h3_ext_bs) get statistics of a bytestream
XQC_EXPORT_PUBLIC_API ssize_t	xqc_h3_ext_bytestream_send(xqc_h3_ext_bytestream_t * h3_ext_bs, unsigned char * data, size_t data_size, uint8_t fin, xqc_data_qos_level_t qos_level) send data
XQC_EXPORT_PUBLIC_API xqc_stream_id_t	xqc_h3_ext_bytestream_id(xqc_h3_ext_bytestream_t * h3_ext_bs) Get QUIC stream ID by a bytestream.
XQC_EXPORT_PUBLIC_API xqc_h3_conn_t *	xqc_h3_ext_bytestream_get_h3_conn(xqc_h3_ext_bytestream_t * h3_ext_bs) get the h3 connection associated with a bytestream
XQC_EXPORT_PUBLIC_API size_t	xqc_h3_ext_datagram_get_mss(xqc_h3_conn_t * conn) the API to get the max length of the data that can be sent via a single call of xqc_datagram_send
XQC_EXPORT_PUBLIC_API void	xqc_h3_ext_datagram_set_user_data(xqc_h3_conn_t * conn, void * user_data)
XQC_EXPORT_PUBLIC_API void *	xqc_h3_ext_datagram_get_user_data(xqc_h3_conn_t * conn)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_ext_datagram_send(xqc_h3_conn_t * conn, void * data, size_t data_len, uint64_t * dgram_id, xqc_data_qos_level_t qos_level) the API to send a datagram over the h3 connection
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_h3_ext_datagram_send_multiple(xqc_h3_conn_t * conn, struct iovec * iov, uint64_t * dgram_id_list, size_t iov_size, size_t * sent_cnt, size_t * sent_bytes, xqc_data_qos_level_t qos_level) the API to send a datagram over the h3 connection

Defines

	Name
	XQC_STREAM_INFO_LEN

Types Documentation

enum xqc_request_notify_flag_t

Enumerator	Value	Description
XQC_REQ_NOTIFY_READ_NULL	0	nothing readable
XQC_REQ_NOTIFY_READ_HEADER	1 << 0	read header section flag, this will be set when the first HEADERS is processed
XQC_REQ_NOTIFY_READ_BODY	1 << 1	read body flag, this will be set when a DATA frame is processed
XQC_REQ_NOTIFY_READ_TRAILER	1 << 2	read trailer section flag, this will be set when trailer HEADERS frame is processed
XQC_REQ_NOTIFY_READ_EMPTY_FIN	1 << 3	read empty fin flag, notify callback will be triggered when a single fin frame is received while HEADERS and DATA were notified. This flag will NEVER be set with other flags

read flag of xqc_h3_request_read_notify_pt

Copyright: Copyright (c) 2022, Alibaba Group Holding Limited

enum xqc_http3_nv_flag_s

Enumerator	Value	Description
XQC_HTTP_HEADER_FLAG_NONE	0x00	no flag is set. encode header with default strategy.
XQC_HTTP_HEADER_FLAG_NEVER_INDEX	0x01	header's name and value shall be encoded as literal, and shall never be indexed.
XQC_HTTP_HEADER_FLAG_NEVER_INDEX_VALUE	0x02	header's value is variant and shall never be put into dynamic table and be indexed. this will reduce useless data in dynamic table and might increase the hit rate.

some headers might be frequent but with different values, it is a waste to put these value into dynamic table. application layer can use this flag to tell QPACK not to put value into dynamic table. |

encode flags of http headers

typedef xqc_h3_conn_notify_pt

typedef int(* xqc_h3_conn_notify_pt) (xqc_h3_conn_t *h3_conn, const xqc_cid_t *cid, void *h3c_user_data);

definition for http3 connection state callback function. including create and close

typedef xqc_h3_handshake_finished_pt

typedef void(* xqc_h3_handshake_finished_pt) (xqc_h3_conn_t *h3_conn, void *h3c_user_data);

typedef xqc_h3_conn_ping_ack_notify_pt

typedef void(* xqc_h3_conn_ping_ack_notify_pt) (xqc_h3_conn_t *h3_conn, const xqc_cid_t *cid, void *ping_user_data, void *h3c_user_data);

typedef xqc_h3_request_notify_pt

typedef int(* xqc_h3_request_notify_pt) (xqc_h3_request_t *h3_request, void *h3s_user_data);

http3 request callbacks

typedef xqc_h3_request_read_notify_pt

typedef int(* xqc_h3_request_read_notify_pt) (xqc_h3_request_t *h3_request, xqc_request_notify_flag_t flag, void *h3s_user_data);

read data callback function

typedef xqc_h3_request_closing_notify_pt

typedef void(* xqc_h3_request_closing_notify_pt) (xqc_h3_request_t *h3_request, xqc_int_t err, void *h3s_user_data);

typedef xqc_http3_nv_flag_t

typedef enum xqc_http3_nv_flag_s xqc_http3_nv_flag_t;

encode flags of http headers

typedef xqc_http_header_t

typedef struct xqc_http_header_s xqc_http_header_t;

typedef xqc_http_headers_t

typedef struct xqc_http_headers_s xqc_http_headers_t;

typedef xqc_request_stats_t

typedef struct xqc_request_stats_s xqc_request_stats_t;

request statistics structure

typedef xqc_h3_ext_bytestream_stats_t

typedef struct xqc_h3_ext_bytestream_stats_s xqc_h3_ext_bytestream_stats_t;

bytestream statistics

typedef xqc_h3_conn_settings_t

typedef struct xqc_h3_conn_settings_s xqc_h3_conn_settings_t;

connection settings for http3

typedef xqc_h3_ext_bytestream_read_notify_pt

typedef int(* xqc_h3_ext_bytestream_read_notify_pt) (xqc_h3_ext_bytestream_t *h3_ext_bs, const void *data, size_t data_len, uint8_t fin, void *bs_user_data, uint64_t data_recv_time);

callback for h3 bytestream read

Parameters:

• h3_ext_bs bytestream
• data data to be read. NOTE, this could be a NULL pointer, please ONLY read it if data_len > 0.
• data_len length of data to be read
• fin the bytestream is finished
• bs_user_data bytestream user data
• data_recv_time time spent for receiving data

typedef xqc_h3_ext_bytestream_notify_pt

typedef int(* xqc_h3_ext_bytestream_notify_pt) (xqc_h3_ext_bytestream_t *h3_ext_bs, void *bs_user_data);

callbacks for extended h3 bytestream

typedef xqc_h3_ext_datagram_read_notify_pt

typedef void(* xqc_h3_ext_datagram_read_notify_pt) (xqc_h3_conn_t *conn, const void *data, size_t data_len, void *user_data, uint64_t data_recv_time);

the callback API to notify the application that there is a datagram to be read

Parameters:

• conn the connection handle
• user_data the user_data set by xqc_h3_ext_datagram_set_user_data
• data the data delivered by this callback
• data_len the length of the delivered data
• data_recv_time time spent for receiving data

typedef xqc_h3_ext_datagram_write_notify_pt

typedef void(* xqc_h3_ext_datagram_write_notify_pt) (xqc_h3_conn_t *conn, void *user_data);

the callback API to notify the application that datagrams can be sent

Parameters:

• conn the connection handle
• user_data the user_data set by xqc_h3_ext_datagram_set_user_data

typedef xqc_h3_ext_datagram_lost_notify_pt

typedef int(* xqc_h3_ext_datagram_lost_notify_pt) (xqc_h3_conn_t *conn, uint64_t dgram_id, void *user_data);

the callback API to notify the application that a datagram is declared lost. However, the datagram could also be acknowledged later, as the underlying loss detection is not fully accurate. Applications should handle this type of spurious loss. The return value is used to ask the QUIC stack to retransmit the lost datagram packet.

Parameters:

• conn the connection handle
• user_data the user_data set by xqc_h3_ext_datagram_set_user_data
• dgram_id the id of the lost datagram

Return: 0, do not retransmit; XQC_DGRAM_RETX_ASKED_BY_APP, retransmit; others, ignored by the QUIC stack.

typedef xqc_h3_ext_datagram_acked_notify_pt

typedef void(* xqc_h3_ext_datagram_acked_notify_pt) (xqc_h3_conn_t *conn, uint64_t dgram_id, void *user_data);

the callback API to notify the application that a datagram is acked

Parameters:

• conn the connection handle
• user_data the user_data set by xqc_h3_ext_datagram_set_user_data
• dgram_id the id of the acked datagram

typedef xqc_h3_ext_datagram_mss_updated_notify_pt

typedef void(* xqc_h3_ext_datagram_mss_updated_notify_pt) (xqc_h3_conn_t *conn, size_t mss, void *user_data);

the callback to notify application the MSS of QUIC datagrams. Note, the MSS of QUIC datagrams will never shrink. If the MSS is zero, it means this connection does not support sending QUIC datagrams.

Parameters:

• conn the connection handle
• user_data the dgram_data set by xqc_h3_ext_datagram_set_user_data
• mss the MSS of QUIC datagrams

typedef xqc_h3_ext_dgram_callbacks_t

typedef struct xqc_h3_ext_dgram_callbacks_s xqc_h3_ext_dgram_callbacks_t;

typedef xqc_h3_conn_callbacks_t

typedef struct xqc_h3_conn_callbacks_s xqc_h3_conn_callbacks_t;

http3 connection callbacks for application layer

typedef xqc_h3_request_callbacks_t

typedef struct xqc_h3_request_callbacks_s xqc_h3_request_callbacks_t;

http3 request callbacks for application layer

typedef xqc_h3_ext_bytestream_callbacks_t

typedef struct xqc_h3_ext_bytestream_callbacks_s xqc_h3_ext_bytestream_callbacks_t;

typedef xqc_h3_callbacks_t

typedef struct xqc_h3_callbacks_s xqc_h3_callbacks_t;

Functions Documentation

function xqc_h3_ctx_init

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_ctx_init(
    xqc_engine_t * engine,
    xqc_h3_callbacks_t * h3_cbs
)

init h3 context into xqc_engine_t, this MUST BE called before create any http3 connection

Parameters:

• engine the engine handler created by xqc_engine_create

Return: xqc_int_t XQC_OK for success, others for failure

function xqc_h3_ctx_destroy

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_ctx_destroy(
    xqc_engine_t * engine
)

function xqc_h3_engine_set_max_dtable_capacity

XQC_EXPORT_PUBLIC_API void xqc_h3_engine_set_max_dtable_capacity(
    xqc_engine_t * engine,
    size_t capacity
)

set max h3 max dynamic table capacity. It MUST only be called after xqc_h3_ctx_init.

Parameters:

• engine the engine handler created by xqc_engine_create
• value capacity of dynamic table, 0 for disable dynamic table

function xqc_h3_engine_set_dec_max_dtable_capacity

XQC_EXPORT_PUBLIC_API void xqc_h3_engine_set_dec_max_dtable_capacity(
    xqc_engine_t * engine,
    size_t value
)

Parameters:

• engine the engine handler created by xqc_engine_create
• value 0:disable dynamic table

Deprecated:

use xqc_h3_engine_set_max_dtable_capacity instead. It MUST only be called after xqc_h3_ctx_init.

function xqc_h3_engine_set_enc_max_dtable_capacity

XQC_EXPORT_PUBLIC_API void xqc_h3_engine_set_enc_max_dtable_capacity(
    xqc_engine_t * engine,
    size_t value
)

Parameters:

• engine the engine handler created by xqc_engine_create
• value 0:disable dynamic table

Deprecated:

use xqc_h3_engine_set_max_dtable_capacity instead. It MUST only be called after xqc_h3_ctx_init.

function xqc_h3_engine_set_max_field_section_size

XQC_EXPORT_PUBLIC_API void xqc_h3_engine_set_max_field_section_size(
    xqc_engine_t * engine,
    size_t size
)

set max h3 field section size. It MUST only be called after xqc_h3_ctx_init.

Parameters:

• engine the engine handler created by xqc_engine_create
• size size of field section size

function xqc_h3_engine_set_qpack_blocked_streams

XQC_EXPORT_PUBLIC_API void xqc_h3_engine_set_qpack_blocked_streams(
    xqc_engine_t * engine,
    size_t value
)

set the limit for qpack blocked streams. It MUST only be called after xqc_h3_ctx_init.

Parameters:

• engine
• value

Return: XQC_EXPORT_PUBLIC_API

function xqc_h3_engine_set_local_settings

XQC_EXPORT_PUBLIC_API void xqc_h3_engine_set_local_settings(
    xqc_engine_t * engine,
    const xqc_h3_conn_settings_t * h3_conn_settings
)

User can set h3 settings when h3_conn_create_notify callbacks

function xqc_h3_connect

XQC_EXPORT_PUBLIC_API const xqc_cid_t * xqc_h3_connect(
    xqc_engine_t * engine,
    const xqc_conn_settings_t * conn_settings,
    const unsigned char * token,
    unsigned token_len,
    const char * server_host,
    int no_crypto_flag,
    const xqc_conn_ssl_config_t * conn_ssl_config,
    const struct sockaddr * peer_addr,
    socklen_t peer_addrlen,
    void * user_data
)

create and http3 connection

Parameters:

• engine return from xqc_engine_create
• conn_settings Include all the connection settings, which should be customized according to the actual needs, and will be defaultly set to internal_default_conn_settings if not specified.
• token token receive from server, xqc_save_token_pt callback
• token_len length of token
• server_host server domain
• no_crypto_flag 1:without crypto
• conn_ssl_config For handshake
• peer_addr address of peer
• peer_addrlen length of peer_addr
• user_data returned in connection callback functions

Return: cid of the connection; user should copy cid to your own memory, in case of cid destroyed in xquic library

function xqc_h3_conn_close

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_conn_close(
    xqc_engine_t * engine,
    const xqc_cid_t * cid
)

manually close a http3 connection

Parameters:

• engine engine handler created by xqc_engine_create
• cid connection id of http3 connection

Return: XQC_OK for success, others for failure

function xqc_h3_conn_get_xqc_conn

XQC_EXPORT_PUBLIC_API xqc_connection_t * xqc_h3_conn_get_xqc_conn(
    xqc_h3_conn_t * h3c
)

get QUIC connection handler

Parameters:

• h3c http3 connection handler

Return: quic_connection on which h3_conn rely

function xqc_h3_conn_get_errno

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_conn_get_errno(
    xqc_h3_conn_t * h3c
)

get http3 protocol error number

Parameters:

• h3c handler of http3 connection

Return: error number of http3 connection, HTTP_NO_ERROR(0x100) For no-error

function xqc_h3_conn_get_ssl

XQC_EXPORT_PUBLIC_API void * xqc_h3_conn_get_ssl(
    xqc_h3_conn_t * h3c
)

get ssl handler of http3 connection

Parameters:

• h3c handler of http3 connection

Return: ssl handler of http3 connection

function xqc_h3_conn_set_user_data

XQC_EXPORT_PUBLIC_API void xqc_h3_conn_set_user_data(
    xqc_h3_conn_t * h3c,
    void * user_data
)

set user_data for http3 connection, user_data could be the application layer context of http3 connection

Parameters:

• h3c handler of http3 connection
• user_data should set user_data when h3_conn_create_notify callbacks, which will be returned as parameter of http3 connection callback functions

function xqc_h3_conn_get_user_data

XQC_EXPORT_PUBLIC_API void * xqc_h3_conn_get_user_data(
    xqc_h3_conn_t * h3_conn
)

get user_data for http3 connection, user_data could be the application layer context of http3 connection

Parameters:

• h3c handler of http3 connection

Return: user_data

function xqc_h3_conn_get_peer_addr

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_conn_get_peer_addr(
    xqc_h3_conn_t * h3c,
    struct sockaddr * addr,
    socklen_t addr_cap,
    socklen_t * peer_addr_len
)

get peer address information, server should call this when h3_conn_create_notify triggers

Parameters:

• h3c handler of http3 connection
• addr [out] output address of peer
• addr_cap capacity of addr
• peer_addr_len [out] output length of addr

Return: XQC_OK for success, others for failure

function xqc_h3_conn_get_local_addr

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_conn_get_local_addr(
    xqc_h3_conn_t * h3c,
    struct sockaddr * addr,
    socklen_t addr_cap,
    socklen_t * local_addr_len
)

get local address information, server should call this when h3_conn_create_notify triggers

Parameters:

• h3c handler of http3 connection
• addr [out] output address of peer
• addr_cap capacity of addr
• peer_addr_len [out] output length of addr

Return: XQC_OK for success, others for failure

function xqc_h3_conn_send_ping

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_conn_send_ping(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    void * ping_user_data
)

Send PING to peer, if ack received, h3_conn_ping_acked will callback with user_data.

Parameters:

• engine handler of engine
• cid connection id of http3 connection, which is generated by xqc_h3_connect
• ping_user_data

Return: XQC_OK for success, < 0 for error

function xqc_h3_conn_is_ready_to_send_early_data

XQC_EXPORT_PUBLIC_API xqc_bool_t xqc_h3_conn_is_ready_to_send_early_data(
    xqc_h3_conn_t * h3c
)

check if h3 connection is ready to send 0rtt data

Parameters:

• h3c h3 connection handler

Return: XQC_TRUE for can send 0rtt, XQC_FALSE for can not

function xqc_h3_conn_set_qpack_dtable_cap

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_conn_set_qpack_dtable_cap(
    xqc_h3_conn_t * h3c,
    size_t capacity
)

set the dynamic table capacity of an existing h3 connection

Parameters:

• h3c h3 connection handler
• capacity capacity of dynamic table, 0 for disable dynamic table

Return: XQC_OK for success, others for failure

function xqc_h3_request_create

XQC_EXPORT_PUBLIC_API xqc_h3_request_t * xqc_h3_request_create(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    xqc_stream_settings_t * settings,
    void * user_data
)

create a http3 request

Parameters:

• engine handler created by xqc_engine_create
• cid connection id of http3 connection
• user_data For request
• settings stream settings

Return: handler of http3 request

function xqc_h3_request_get_stats

XQC_EXPORT_PUBLIC_API xqc_request_stats_t xqc_h3_request_get_stats(
    xqc_h3_request_t * h3_request
)

get statistics of a http3 request user can get it before request destroyed

Parameters:

• h3_request handler of http3 request

Return: statistics information of request

function xqc_h3_request_stats_print

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_request_stats_print(
    xqc_h3_request_t * h3_request,
    char * str,
    size_t size
)

write important information into str

Return: the number of characters printed

function xqc_h3_request_set_user_data

XQC_EXPORT_PUBLIC_API void xqc_h3_request_set_user_data(
    xqc_h3_request_t * h3_request,
    void * user_data
)

set user_data of a http3 request, which will be used as parameter of request callback functions. server should set user_data when h3_request_create_notify triggers

Parameters:

• h3_request handler of http3 request
• user_data user data of request callback functions

function xqc_h3_request_close

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_request_close(
    xqc_h3_request_t * h3_request
)

close request, send QUIC RESET_STREAM frame to peer. h3_request_close_notify will triggered when request is finally destroyed

Parameters:

• h3_request handler of http3 request

Return: XQC_OK for success, others for error

function xqc_h3_request_update_settings

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_request_update_settings(
    xqc_h3_request_t * h3_request,
    xqc_stream_settings_t * settings
)

function xqc_h3_request_send_headers

XQC_EXPORT_PUBLIC_API ssize_t xqc_h3_request_send_headers(
    xqc_h3_request_t * h3_request,
    xqc_http_headers_t * headers,
    uint8_t fin
)

send http headers to peer

Parameters:

• h3_request handler of http3 request
• headers http headers
• fin request finish flag, 1 for finish. if set here, it means request has no body

Return: > 0 for Bytes sent，-XQC_EAGAIN try next time, < 0 for error, 0 for request finished

function xqc_h3_request_send_body

XQC_EXPORT_PUBLIC_API ssize_t xqc_h3_request_send_body(
    xqc_h3_request_t * h3_request,
    unsigned char * data,
    size_t data_size,
    uint8_t fin
)

send http body to peer

Parameters:

• h3_request handler of http3 request
• data content of body
• data_size length of body
• fin request finish flag, 1 for finish.

Return: > 0 for Bytes sent，-XQC_EAGAIN try next time, < 0 for error, 0 for request finished

function xqc_h3_request_finish

XQC_EXPORT_PUBLIC_API ssize_t xqc_h3_request_finish(
    xqc_h3_request_t * h3_request
)

finish request. if fin is not sent yet, and application has nothing to send anymore, call this function to send a QUIC STREAM frame with only fin

Return: > 0 for Bytes sent，-XQC_EAGAIN try next time, < 0 for error, 0 for request finished

function xqc_h3_request_recv_headers

XQC_EXPORT_PUBLIC_API xqc_http_headers_t * xqc_h3_request_recv_headers(
    xqc_h3_request_t * h3_request,
    uint8_t * fin
)

receive headers of a request

Parameters:

• h3_request handler of http3 request
• fin request finish flag, 1 for finish. if not 0, it means request has no body

Return: request headers. user should copy headers to your own memory，NULL for error

function xqc_h3_request_recv_body

XQC_EXPORT_PUBLIC_API ssize_t xqc_h3_request_recv_body(
    xqc_h3_request_t * h3_request,
    unsigned char * recv_buf,
    size_t recv_buf_size,
    uint8_t * fin
)

receive body of a request

Parameters:

• h3_request handler of http3 request
• fin request finish flag, 1 for finish

Return: Bytes read，-XQC_EAGAIN try next time, <0 for error

function xqc_h3_get_conn_user_data_by_request

XQC_EXPORT_PUBLIC_API void * xqc_h3_get_conn_user_data_by_request(
    xqc_h3_request_t * h3_request
)

get connection's user_data by request

Parameters:

• h3_request handler of http3 request

Return: user_data set by user

function xqc_h3_stream_id

XQC_EXPORT_PUBLIC_API xqc_stream_id_t xqc_h3_stream_id(
    xqc_h3_request_t * h3_request
)

Get QUIC stream ID by request.

Parameters:

• h3_request handler of http3 request

Return: QUIC stream id

function xqc_h3_priority_init

XQC_EXPORT_PUBLIC_API void xqc_h3_priority_init(
    xqc_h3_priority_t * prio
)

RFC 9218 HTTP Priority.

function xqc_write_http_priority

XQC_EXPORT_PUBLIC_API size_t xqc_write_http_priority(
    xqc_h3_priority_t * prio,
    uint8_t * dst,
    size_t dstcap
)

function xqc_parse_http_priority

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_parse_http_priority(
    xqc_h3_priority_t * dst,
    const uint8_t * str,
    size_t str_len
)

function xqc_h3_request_set_priority

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_request_set_priority(
    xqc_h3_request_t * h3r,
    xqc_h3_priority_t * prio
)

function xqc_h3_ext_bytestream_create

XQC_EXPORT_PUBLIC_API xqc_h3_ext_bytestream_t * xqc_h3_ext_bytestream_create(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    void * user_data
)

create a bytestream based on extended H3

Parameters:

• engine handler created by xqc_engine_create
• cid connection id of http3 connection
• user_data For bytestream

Return: handler of bytestream

function xqc_h3_ext_bytestream_close

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_ext_bytestream_close(
    xqc_h3_ext_bytestream_t * h3_ext_bs
)

close bytestream, send QUIC RESET_STREAM frame to peer. h3_ext_bytestream_close_notify will triggered when bytestream is finally destroyed

Parameters:

• xqc_h3_ext_bytestream_t handler of bytestream

Return: XQC_OK for success, others for error

function xqc_h3_ext_bytestream_finish

XQC_EXPORT_PUBLIC_API ssize_t xqc_h3_ext_bytestream_finish(
    xqc_h3_ext_bytestream_t * h3_ext_bs
)

finish bytestream. if fin is not sent yet, and application has nothing to send anymore, call this function to send a QUIC STREAM frame with only fin

Return: > 0 for Bytes sent，-XQC_EAGAIN try next time, < 0 for error, 0 for bytestream finished

function xqc_h3_ext_bytestream_set_user_data

XQC_EXPORT_PUBLIC_API void xqc_h3_ext_bytestream_set_user_data(
    xqc_h3_ext_bytestream_t * h3_ext_bs,
    void * user_data
)

set user_data of a bytestream, which will be used as the parameter of the bytestream callback functions. server should set user_data when h3_ext_bytestream_create_notify triggers

Parameters:

• xqc_h3_ext_bytestream_t handler of the bytestream
• user_data user data of the bytestream callback functions

function xqc_h3_ext_bytestream_get_user_data

XQC_EXPORT_PUBLIC_API void * xqc_h3_ext_bytestream_get_user_data(
    xqc_h3_ext_bytestream_t * h3_ext_bs
)

get the user data associcated with the bytestream object

Parameters:

• xqc_h3_ext_bytestream_t handler of the bytestream
• user_data user data of the bytestream callback functions

Return: the pointer of user data

function xqc_h3_ext_bytestream_get_stats

XQC_EXPORT_PUBLIC_API xqc_h3_ext_bytestream_stats_t xqc_h3_ext_bytestream_get_stats(
    xqc_h3_ext_bytestream_t * h3_ext_bs
)

get statistics of a bytestream

Parameters:

• xqc_h3_ext_bytestream_t handler of the bytestream

Return: statistics information of the bytestream

function xqc_h3_ext_bytestream_send

XQC_EXPORT_PUBLIC_API ssize_t xqc_h3_ext_bytestream_send(
    xqc_h3_ext_bytestream_t * h3_ext_bs,
    unsigned char * data,
    size_t data_size,
    uint8_t fin,
    xqc_data_qos_level_t qos_level
)

send data

Parameters:

• xqc_h3_ext_bytestream_t handler of the bytestream
• data content
• data_size data length
• fin request finish flag, 1 for finish.
• qos level (must be the values defined in xqc_data_qos_level_t)

Return: > 0 for bytes sent，-XQC_EAGAIN try next time, < 0 for error, 0 for bytestream finished

function xqc_h3_ext_bytestream_id

XQC_EXPORT_PUBLIC_API xqc_stream_id_t xqc_h3_ext_bytestream_id(
    xqc_h3_ext_bytestream_t * h3_ext_bs
)

Get QUIC stream ID by a bytestream.

Parameters:

• xqc_h3_ext_bytestream_t handler of a bytestream

Return: QUIC stream id

function xqc_h3_ext_bytestream_get_h3_conn

XQC_EXPORT_PUBLIC_API xqc_h3_conn_t * xqc_h3_ext_bytestream_get_h3_conn(
    xqc_h3_ext_bytestream_t * h3_ext_bs
)

get the h3 connection associated with a bytestream

Parameters:

• xqc_h3_ext_bytestream_t handler of a bytestream

Return: an h3 connection

function xqc_h3_ext_datagram_get_mss

XQC_EXPORT_PUBLIC_API size_t xqc_h3_ext_datagram_get_mss(
    xqc_h3_conn_t * conn
)

the API to get the max length of the data that can be sent via a single call of xqc_datagram_send

Parameters:

• conn the connection handle

Return: 0 = the peer does not support datagram, >0 = the max length

function xqc_h3_ext_datagram_set_user_data

XQC_EXPORT_PUBLIC_API void xqc_h3_ext_datagram_set_user_data(
    xqc_h3_conn_t * conn,
    void * user_data
)

Server should set datagram user_data when datagram callbacks @dgram_data: the user_data of all datagram callbacks

function xqc_h3_ext_datagram_get_user_data

XQC_EXPORT_PUBLIC_API void * xqc_h3_ext_datagram_get_user_data(
    xqc_h3_conn_t * conn
)

Return: the user_data of all datagram callbacks

function xqc_h3_ext_datagram_send

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_ext_datagram_send(
    xqc_h3_conn_t * conn,
    void * data,
    size_t data_len,
    uint64_t * dgram_id,
    xqc_data_qos_level_t qos_level
)

the API to send a datagram over the h3 connection

Parameters:

• conn the connection handle
• data the data to be sent
• data_len the length of the data
• *dgram_id the pointer to return the id the datagram
• qos level (must be the values defined in xqc_data_qos_level_t)

Return: <0 = error (-XQC_EAGAIN, -XQC_CLOSING, -XQC_DGRAM_NOT_SUPPORTED, -XQC_DGRAM_TOO_LARGE, ...), 0 success

function xqc_h3_ext_datagram_send_multiple

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_h3_ext_datagram_send_multiple(
    xqc_h3_conn_t * conn,
    struct iovec * iov,
    uint64_t * dgram_id_list,
    size_t iov_size,
    size_t * sent_cnt,
    size_t * sent_bytes,
    xqc_data_qos_level_t qos_level
)

the API to send a datagram over the h3 connection

Parameters:

• conn the connection handle
• iov multiple data buffers need to be sent
• *dgram_id the pointer to return the list of dgram_id
• iov_size the size of iov list
• *sent_cnt the number of successfully sent datagrams
• *sent_bytes the total bytes of successfully sent datagrams
• qos level (must be the values defined in xqc_data_qos_level_t)

Return: <0 = error (-XQC_EAGAIN, -XQC_CLOSING, -XQC_DGRAM_NOT_SUPPORTED, -XQC_DGRAM_TOO_LARGE, ...), 0 success

Macros Documentation

define XQC_STREAM_INFO_LEN

#define XQC_STREAM_INFO_LEN 128

---

Updated on 2024-11-19 at 20:49:45 +0800