xquic/xquic.h

Classes

	Name
struct	xqc_log_callbacks_s log callback functions
struct	xqc_transport_callbacks_s tranport callback functions are more related to attributes of QUIC [Transport] but not ALPN.
struct	xqc_conn_callbacks_s QUIC connection callback functions for Application-layer-Protocol.
struct	xqc_stream_callbacks_s QUIC layer stream callback functions.
struct	xqc_datagram_callbacks_s QUIC layer datagram callback functions.
struct	xqc_app_proto_callbacks_s connection and stream callbacks for QUIC level, Application-Layer-Protocol shall implement these callback functions and register ALP with xqc_engine_register_alpn
struct	xqc_cc_params_s congestion control algorithm parameters
struct	xqc_scheduler_params_u multipath scheduler algorithm parameters
struct	xqc_fec_params_s FEC parameters on connection settings.
struct	xqc_congestion_control_callback_s congestion control callbacks
struct	xqc_scheduler_callback_s multipath scheduler callbacks
struct	xqc_reinj_ctl_callback_s
struct	xqc_fec_code_callback_s
struct	xqc_config_s
struct	xqc_engine_callback_s engine callback functions.
struct	xqc_engine_ssl_config_s engine's ssl config
struct	xqc_conn_ssl_config_s connection tls config for client
struct	xqc_linger_s
struct	xqc_conn_settings_s structures of connection settings
struct	xqc_path_metrics_s
struct	xqc_conn_stats_s connection stats
struct	xqc_conn_qos_stats_s

Types

	Name
enum	xqc_engine_type_t { XQC_ENGINE_SERVER = 0, XQC_ENGINE_CLIENT = 1} engine type definition
enum	xqc_proto_version_s { XQC_IDRAFT_INIT_VER = 0, XQC_VERSION_V1 = 1, XQC_IDRAFT_VER_29 = 2, XQC_IDRAFT_VER_NEGOTIATION = 3, XQC_VERSION_MAX = 4} supported versions for IETF drafts
enum	xqc_path_status_change_type_t
enum	xqc_data_qos_level_t
enum	xqc_fec_schemes_e { XQC_REED_SOLOMON_CODE = 8, XQC_XOR_CODE = 11, XQC_PACKET_MASK_CODE = 12} FEC schemes type enum.
enum	xqc_fec_mp_mode_e
enum	xqc_scheduler_path_event_e
enum	xqc_scheduler_conn_event_e
enum	xqc_reinjection_mode_t
enum	xqc_cert_verify_flag_e
enum	xqc_dgram_red_setting_e
enum	xqc_multipath_version_t
enum	xqc_fec_version_t
enum	xqc_0rtt_flag_t
typedef enum xqc_proto_version_s	xqc_proto_version_t supported versions for IETF drafts
typedef xqc_usec_t(*)(void)	xqc_timestamp_pt get timestamp callback function. this might be useful on different platforms
typedef void(*)(xqc_usec_t wake_after, void *engine_user_data)	xqc_set_event_timer_pt event timer callback function. MUST be set for both client and server xquic don't have implementation of timer, but will tell the interval of timer by this function. applications shall implement the timer, and invoke xqc_engine_main_logic after timer expires.
typedef ssize_t(*)(const xqc_cid_t *ori_cid, uint8_t *cid_buf, size_t cid_buflen, void *engine_user_data)	xqc_cid_generate_pt cid generate callback.
typedef void(*)(const xqc_cid_t *scid, const char *line, void *engine_user_data)	xqc_eng_keylog_pt engine secret log callback. will only be effective when build with XQC_PRINT_SECRET
typedef void(*)(const char *line, void *engine_user_data)	xqc_keylog_pt tls secret log callback. will only be effective when build with XQC_PRINT_SECRET
typedef struct xqc_log_callbacks_s	xqc_log_callbacks_t log callback functions
typedef int(*)(xqc_engine_t *engine, xqc_connection_t *conn, const xqc_cid_t *cid, void *user_data)	xqc_server_accept_pt connection accept callback.
typedef void(*)(xqc_engine_t *engine, xqc_connection_t *conn, const xqc_cid_t *cid, void *user_data)	xqc_server_refuse_pt connection refused callback. corresponding to xqc_server_accept_pt callback function. this function will be invoked when a QUIC connection is refused by xquic due to security considerations, applications SHALL link the connection's lifetime between itself and xquic, and free the context if it was created during xqc_server_accept_pt.
typedef ssize_t(*)(const unsigned char *buf, size_t size, const struct sockaddr *peer_addr, socklen_t peer_addrlen, const struct sockaddr *local_addr, socklen_t local_addrlen, void *user_data)	xqc_stateless_reset_pt engine can't find connection related to input udp packet, and return a STATELESS_RESET packet, implementations shall send this buffer back to peer. this callback function is almost the same with xqc_socket_write_pt, but with different user_data definition.
typedef xqc_int_t(*)(xqc_connection_t *conn, const xqc_cid_t *cid, xqc_int_t err_code, void *conn_user_data)	xqc_conn_closing_notify_pt connection closing notify callback function.
typedef int(*)(xqc_connection_t *conn, const xqc_cid_t *cid, void *conn_user_data, void *conn_proto_data)	xqc_conn_notify_pt general callback function definition for connection create and close
typedef void(*)(const unsigned char *token, uint32_t token_len, void *conn_user_data)	xqc_save_token_pt QUIC connection token callback. REQUIRED for client. token is used by the server to validate client's address during the handshake period of next connection to the same server. client applications shall save token to local storage, if need to connect the same server, read the token and take it as the parameter of xqc_connect.
typedef void(*)(const char *data, size_t data_len, void *conn_user_data)	xqc_save_string_pt general type of session ticket and transport parameter callback function
typedef xqc_save_string_pt	xqc_save_session_pt session ticket callback function
typedef xqc_save_string_pt	xqc_save_trans_param_pt transport parameters callback
typedef void(*)(xqc_connection_t *conn, void *conn_user_data, void *conn_proto_data)	xqc_handshake_finished_pt handshake finished callback function
typedef void(*)(xqc_connection_t *conn, const xqc_cid_t *cid, void *ping_user_data, void *conn_user_data, void *conn_proto_data)	xqc_conn_ping_ack_notify_pt PING acked callback function.
typedef void(*)(xqc_connection_t *conn, const xqc_cid_t *retire_cid, const xqc_cid_t *new_cid, void *conn_user_data)	xqc_conn_update_cid_notify_pt cid update callback function.
typedef int(*)(const unsigned char *certs[], const size_t cert_len[], size_t certs_len, void *conn_user_data)	xqc_cert_verify_pt client certificate verify callback
typedef void(*)(xqc_connection_t *conn, void *conn_user_data)	xqc_conn_peer_addr_changed_nofity_pt server peer addr changed notify
typedef void(*)(xqc_connection_t *conn, uint64_t path_id, void *conn_user_data)	xqc_path_peer_addr_changed_nofity_pt server peer addr changed notify
typedef ssize_t(*)(const unsigned char *buf, size_t size, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *conn_user_data)	xqc_socket_write_pt writing data callback function
typedef ssize_t(*)(const struct iovec *msg_iov, unsigned int vlen, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *conn_user_data)	xqc_send_mmsg_pt sendmmsg callback function. the implementation of this shall send data with sendmmsg
typedef ssize_t(*)(const unsigned char *buf, size_t size, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *cb_user_data)	xqc_conn_pkt_filter_callback_pt set data callback mode for a transport connection. this mode differs from write_socket, which has a different user_data, once this callback function is set, write_socket will be not functional until it is unset.
typedef void(*)(const xqc_cid_t *scid, void *conn_user_data)	xqc_conn_ready_to_create_path_notify_pt multi-path ready callback function
typedef xqc_int_t(*)(const char *sni, void **chain, void **crt, void **key, void *user_data)	xqc_conn_cert_cb_pt get chain certs and key by sin
typedef int(*)(xqc_connection_t *conn, const xqc_cid_t *scid, uint64_t path_id, void *conn_user_data)	xqc_path_created_notify_pt multi-path create callback function
typedef void(*)(const xqc_cid_t *scid, uint64_t path_id, void *conn_user_data)	xqc_path_removed_notify_pt multi-path remove path callback function.
typedef ssize_t(*)(uint64_t path_id, const unsigned char *buf, size_t size, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *conn_user_data)	xqc_socket_write_ex_pt multi-path write socket callback function
typedef ssize_t(*)(uint64_t path_id, const struct iovec *msg_iov, unsigned int vlen, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *conn_user_data)	xqc_send_mmsg_ex_pt multi-path write socket callback function with sendmmsg
typedef xqc_int_t(*)(xqc_stream_t *stream, void *strm_user_data)	xqc_stream_notify_pt general callback function definition for stream create, close, read and write.
typedef void(*)(xqc_stream_t *stream, xqc_int_t err_code, void *strm_user_data)	xqc_stream_closing_notify_pt stream closing callback function, this will be triggered when some error on a stream happens.
typedef void(*)(xqc_connection_t *conn, void *user_data, const void *data, size_t data_len, uint64_t unix_ts)	xqc_datagram_read_notify_pt the callback API to notify application that there is a datagram to be read
typedef void(*)(xqc_connection_t *conn, void *user_data)	xqc_datagram_write_notify_pt the callback API to notify application that datagrams can be sent
typedef xqc_int_t(*)(xqc_connection_t *conn, uint64_t dgram_id, void *user_data)	xqc_datagram_lost_notify_pt the callback API to notify application that a datagram is declared lost.
typedef void(*)(xqc_connection_t *conn, uint64_t dgram_id, void *user_data)	xqc_datagram_acked_notify_pt the callback API to notify application that a datagram is acked. Note, for every unique dgram_id, this callback will be only called once.
typedef void(*)(xqc_connection_t *conn, size_t mss, void *user_data)	xqc_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_transport_callbacks_s	xqc_transport_callbacks_t tranport callback functions are more related to attributes of QUIC [Transport] but not ALPN.
typedef struct xqc_conn_callbacks_s	xqc_conn_callbacks_t QUIC connection callback functions for Application-layer-Protocol.
typedef struct xqc_stream_callbacks_s	xqc_stream_callbacks_t QUIC layer stream callback functions.
typedef struct xqc_datagram_callbacks_s	xqc_datagram_callbacks_t QUIC layer datagram callback functions.
typedef struct xqc_app_proto_callbacks_s	xqc_app_proto_callbacks_t connection and stream callbacks for QUIC level, Application-Layer-Protocol shall implement these callback functions and register ALP with xqc_engine_register_alpn
typedef struct xqc_cc_params_s	xqc_cc_params_t congestion control algorithm parameters
typedef struct xqc_scheduler_params_u	xqc_scheduler_params_t multipath scheduler algorithm parameters
typedef struct xqc_fec_params_s	xqc_fec_params_t FEC parameters on connection settings.
typedef struct xqc_congestion_control_callback_s	xqc_cong_ctrl_callback_t congestion control callbacks
typedef enum xqc_scheduler_path_event_e	xqc_scheduler_path_event_t
typedef enum xqc_scheduler_conn_event_e	xqc_scheduler_conn_event_t
typedef struct xqc_scheduler_callback_s	xqc_scheduler_callback_t multipath scheduler callbacks
typedef struct xqc_reinj_ctl_callback_s	xqc_reinj_ctl_callback_t
typedef struct xqc_fec_code_callback_s	xqc_fec_code_callback_t
typedef struct xqc_config_s	xqc_config_t
typedef struct xqc_engine_callback_s	xqc_engine_callback_t engine callback functions.
typedef struct xqc_engine_ssl_config_s	xqc_engine_ssl_config_t engine's ssl config
typedef struct xqc_conn_ssl_config_s	xqc_conn_ssl_config_t connection tls config for client
typedef struct xqc_linger_s	xqc_linger_t
typedef struct xqc_conn_settings_s	xqc_conn_settings_t structures of connection settings
typedef struct xqc_path_metrics_s	xqc_path_metrics_t
typedef struct xqc_conn_stats_s	xqc_conn_stats_t connection stats
typedef struct xqc_conn_qos_stats_s	xqc_conn_qos_stats_t

Functions

	Name
XQC_EXPORT_PUBLIC_API xqc_engine_t *	xqc_engine_create(xqc_engine_type_t engine_type, const xqc_config_t * engine_config, const xqc_engine_ssl_config_t * ssl_config, const xqc_engine_callback_t * engine_callback, const xqc_transport_callbacks_t * transport_cbs, void * user_data) Create new xquic engine.
XQC_EXPORT_PUBLIC_API void	xqc_engine_destroy(xqc_engine_t * engine) destroy engine. this is called after all connections are destroyed NOTICE: MUST NOT be called in any xquic callback functions, for this function will destroy engine immediately, result in segmentation fault.
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_engine_register_alpn(xqc_engine_t * engine, const char * alpn, size_t alpn_len, xqc_app_proto_callbacks_t * ap_cbs, void * alp_ctx) register alpn and connection and stream callbacks. user can implement his own application protocol by registering alpn, and taking quic connection and streams as application connection and request
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_engine_unregister_alpn(xqc_engine_t * engine, const char * alpn, size_t alpn_len) unregister an alpn and its quic connection callbacks
XQC_EXPORT_PUBLIC_API void *	xqc_engine_get_alpn_ctx(xqc_engine_t * engine, const char * alpn, size_t alpn_len) get the context an application layer protocol
XQC_EXPORT_PUBLIC_API void *	xqc_engine_get_priv_ctx(xqc_engine_t * engine) get the private context
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_engine_set_priv_ctx(xqc_engine_t * engine, void * priv_ctx) save the private context
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_engine_packet_process(xqc_engine_t * engine, const unsigned char * packet_in_buf, size_t packet_in_size, const struct sockaddr * local_addr, socklen_t local_addrlen, const struct sockaddr * peer_addr, socklen_t peer_addrlen, xqc_usec_t recv_time, void * user_data)
XQC_EXPORT_PUBLIC_API void	xqc_engine_main_logic(xqc_engine_t * engine) Process all connections, application implements MUST call this function in timer callback.
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_engine_get_default_config(xqc_config_t * config, xqc_engine_type_t engine_type) get default config of xquic
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_engine_set_config(xqc_engine_t * engine, const xqc_config_t * engine_config)
XQC_EXPORT_PUBLIC_API void	xqc_server_set_conn_settings(xqc_engine_t * engine, const xqc_conn_settings_t * settings) Set server's connection settings. it can be called anytime. settings will take effect on new created connections.
XQC_EXPORT_PUBLIC_API void	xqc_engine_set_log_level(xqc_engine_t * engine, xqc_log_level_t log_level) Set the log level of xquic.
XQC_EXPORT_PUBLIC_API void	xqc_log_disable(xqc_bool_t disable) enable/disable the log module of xquic
XQC_EXPORT_PUBLIC_API void	xqc_engine_finish_recv(xqc_engine_t * engine)
XQC_EXPORT_PUBLIC_API void	xqc_engine_finish_send(xqc_engine_t * engine) only useful for manually triggered send mode
XQC_EXPORT_PUBLIC_API xqc_connection_t *	xqc_engine_get_conn_by_scid(xqc_engine_t * engine, const xqc_cid_t * cid)
XQC_EXPORT_PUBLIC_API const xqc_cid_t *	xqc_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, const char * alpn, void * user_data)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_close(xqc_engine_t * engine, const xqc_cid_t * cid)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_close_with_error(xqc_connection_t * conn, uint64_t err_code) close connection with error code
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_get_errno(xqc_connection_t * conn)
XQC_EXPORT_PUBLIC_API void *	xqc_conn_get_ssl(xqc_connection_t * conn)
XQC_EXPORT_PUBLIC_API xqc_usec_t	xqc_conn_get_lastest_rtt(xqc_engine_t * engine, const xqc_cid_t * cid) get latest rtt sample of the initial path
XQC_EXPORT_PUBLIC_API void	xqc_conn_set_transport_user_data(xqc_connection_t * conn, void * user_data)
XQC_EXPORT_PUBLIC_API void	xqc_conn_set_alp_user_data(xqc_connection_t * conn, void * proto_data) set application-layer-protocol user_data to xqc_connection_t. which will be used in xqc_conn_callbacks_t
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_get_peer_addr(xqc_connection_t * conn, struct sockaddr * addr, socklen_t addr_cap, socklen_t * peer_addr_len)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_get_local_addr(xqc_connection_t * conn, struct sockaddr * addr, socklen_t addr_cap, socklen_t * local_addr_len)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_send_ping(xqc_engine_t * engine, const xqc_cid_t * cid, void * ping_user_data)
XQC_EXPORT_PUBLIC_API xqc_bool_t	xqc_conn_is_ready_to_send_early_data(xqc_connection_t * conn)
XQC_EXPORT_PUBLIC_API void	xqc_conn_set_pkt_filter_callback(xqc_connection_t * conn, xqc_conn_pkt_filter_callback_pt pf_cb, void * pf_cb_user_data) set the packet filter callback function, and replace write_socket. NOTICE: this function is not conflict with send_mmsg.
XQC_EXPORT_PUBLIC_API void	xqc_conn_unset_pkt_filter_callback(xqc_connection_t * conn) unset the packet filter callback function, and restore write_socket
XQC_EXPORT_PUBLIC_API xqc_conn_public_local_trans_settings_t	xqc_conn_get_public_local_trans_settings(xqc_connection_t * conn) get public local transport settings.
XQC_EXPORT_PUBLIC_API void	xqc_conn_set_public_local_trans_settings(xqc_connection_t * conn, xqc_conn_public_local_trans_settings_t * settings) set public local transport settings
XQC_EXPORT_PUBLIC_API xqc_conn_public_remote_trans_settings_t	xqc_conn_get_public_remote_trans_settings(xqc_connection_t * conn) get public remote transport settings.
XQC_EXPORT_PUBLIC_API void	xqc_conn_set_public_remote_trans_settings(xqc_connection_t * conn, xqc_conn_public_remote_trans_settings_t * settings) set public remote transport settings
XQC_EXPORT_PUBLIC_API xqc_stream_t *	xqc_stream_create(xqc_engine_t * engine, const xqc_cid_t * cid, xqc_stream_settings_t * settings, void * user_data)
XQC_EXPORT_PUBLIC_API xqc_stream_t *	xqc_stream_create_with_direction(xqc_connection_t * conn, xqc_stream_direction_t dir, void * user_data)
XQC_EXPORT_PUBLIC_API xqc_stream_direction_t	xqc_stream_get_direction(xqc_stream_t * strm)
XQC_EXPORT_PUBLIC_API void	xqc_stream_set_user_data(xqc_stream_t * stream, void * user_data)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_stream_update_settings(xqc_stream_t * stream, xqc_stream_settings_t * settings)
XQC_EXPORT_PUBLIC_API void *	xqc_get_conn_user_data_by_stream(xqc_stream_t * stream)
XQC_EXPORT_PUBLIC_API void *	xqc_get_conn_alp_user_data_by_stream(xqc_stream_t * stream)
XQC_EXPORT_PUBLIC_API xqc_stream_id_t	xqc_stream_id(xqc_stream_t * stream)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_stream_close(xqc_stream_t * stream)
XQC_EXPORT_PUBLIC_API ssize_t	xqc_stream_recv(xqc_stream_t * stream, unsigned char * recv_buf, size_t recv_buf_size, uint8_t * fin)
XQC_EXPORT_PUBLIC_API ssize_t	xqc_stream_send(xqc_stream_t * stream, unsigned char * send_data, size_t send_data_size, uint8_t fin)
XQC_EXPORT_PUBLIC_API size_t	xqc_datagram_get_mss(xqc_connection_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_datagram_set_user_data(xqc_connection_t * conn, void * dgram_data)
XQC_EXPORT_PUBLIC_API void *	xqc_datagram_get_user_data(xqc_connection_t * conn)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_datagram_send(xqc_connection_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 QUIC connection
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_datagram_send_multiple(xqc_connection_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 QUIC connection
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_packet_parse_cid(xqc_cid_t * dcid, xqc_cid_t * scid, uint8_t cid_len, const unsigned char * buf, size_t size)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_cid_is_equal(const xqc_cid_t * dst, const xqc_cid_t * src) compare two cids
XQC_EXPORT_PUBLIC_API unsigned char *	xqc_scid_str(xqc_engine_t * engine, const xqc_cid_t * scid)
XQC_EXPORT_PUBLIC_API unsigned char *	xqc_dcid_str(xqc_engine_t * engine, const xqc_cid_t * dcid)
XQC_EXPORT_PUBLIC_API unsigned char *	xqc_dcid_str_by_scid(xqc_engine_t * engine, const xqc_cid_t * scid)
XQC_EXPORT_PUBLIC_API uint8_t	xqc_engine_config_get_cid_len(xqc_engine_t * engine)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_continue_send(xqc_engine_t * engine, const xqc_cid_t * cid)
XQC_EXPORT_PUBLIC_API void	xqc_conn_continue_send_by_conn(xqc_connection_t * conn)
XQC_EXPORT_PUBLIC_API xqc_conn_stats_t	xqc_conn_get_stats(xqc_engine_t * engine, const xqc_cid_t * cid)
XQC_EXPORT_PUBLIC_API xqc_conn_qos_stats_t	xqc_conn_get_qos_stats(xqc_engine_t * engine, const xqc_cid_t * cid)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_create_path(xqc_engine_t * engine, const xqc_cid_t * cid, uint64_t * new_path_id, int path_status)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_close_path(xqc_engine_t * engine, const xqc_cid_t * cid, uint64_t closed_path_id)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_mark_path_standby(xqc_engine_t * engine, const xqc_cid_t * cid, uint64_t path_id)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_mark_path_available(xqc_engine_t * engine, const xqc_cid_t * cid, uint64_t path_id)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_mark_path_frozen(xqc_engine_t * engine, const xqc_cid_t * cid, uint64_t path_id)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_conn_available_paths(xqc_engine_t * engine, const xqc_cid_t * cid)
XQC_EXPORT_PUBLIC_API xqc_conn_type_t	xqc_conn_get_type(xqc_connection_t * conn)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_path_get_peer_addr(xqc_connection_t * conn, uint64_t path_id, struct sockaddr * addr, socklen_t addr_cap, socklen_t * peer_addr_len)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_path_get_local_addr(xqc_connection_t * conn, uint64_t path_id, struct sockaddr * addr, socklen_t addr_cap, socklen_t * local_addr_len)
XQC_EXPORT_PUBLIC_API xqc_int_t	xqc_lb_cid_encryption(uint8_t * cid_buf, size_t enc_len, uint8_t * out_buf, size_t out_buf_len, uint8_t * lb_cid_key, size_t lb_cid_key_len, xqc_engine_t * engine) load balance cid encryption. According to Draft : https://datatracker.ietf.org/doc/html/draft-ietf-quic-load-balancers-13#section-4.3.2
XQC_EXPORT_PUBLIC_API xqc_bool_t	xqc_conn_should_clear_0rtt_ticket(xqc_int_t conn_err) client calls this API to check if it should delete 0rtt ticket according to the errorcode of xqc_conn in conn_close_notify
XQC_EXPORT_PUBLIC_API xqc_conn_settings_t	xqc_conn_get_conn_settings_template(xqc_conn_settings_type_t settings_type) Users call this function to get a template of conn settings, which serves as the starting point for users who want to refine conn settings according to their needs.

Attributes

	Name
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_cong_ctrl_callback_t	xqc_bbr_cb
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_cong_ctrl_callback_t	xqc_cubic_cb
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_scheduler_callback_t	xqc_minrtt_scheduler_cb
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_scheduler_callback_t	xqc_backup_scheduler_cb
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_scheduler_callback_t	xqc_backup_fec_scheduler_cb
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_scheduler_callback_t	xqc_rap_scheduler_cb
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_reinj_ctl_callback_t	xqc_default_reinj_ctl_cb
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_reinj_ctl_callback_t	xqc_deadline_reinj_ctl_cb
XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_reinj_ctl_callback_t	xqc_dgram_reinj_ctl_cb
XQC_EXPORT_PUBLIC_API const xqc_fec_code_callback_t	xqc_xor_code_cb
XQC_EXPORT_PUBLIC_API const xqc_fec_code_callback_t	xqc_reed_solomon_code_cb
XQC_EXPORT_PUBLIC_API const xqc_fec_code_callback_t	xqc_packet_mask_code_cb

Defines

	Name
	XQC_SUPPORT_VERSION_MAX
	XQC_TLS_CIPHERS
	XQC_TLS_GROUPS
	XQC_RESET_TOKEN_MAX_KEY_LEN
	XQC_MAX_SEND_MSG_ONCE
	XQC_INITIAL_PATH_ID
	XQC_DGRAM_RETX_ASKED_BY_APP
	XQC_CO_MAX_NUM
	XQC_CO_STR_MAX_LEN
	XQC_FEC_MAX_SCHEME_NUM
	XQC_SOCKET_ERROR return value of xqc_socket_write_pt and xqc_send_mmsg_pt callback function
	XQC_SOCKET_EAGAIN
	XQC_MAX_PATHS_COUNT
	XQC_CONN_INFO_LEN

Types Documentation

enum xqc_engine_type_t

Enumerator	Value	Description
XQC_ENGINE_SERVER	0
XQC_ENGINE_CLIENT	1

engine type definition

Copyright: Copyright (c) 2022, Alibaba Group Holding Limited Public API for using libxquic

enum xqc_proto_version_s

Enumerator	Value	Description
XQC_IDRAFT_INIT_VER	0	placeholder
XQC_VERSION_V1	1	former version of QUIC RFC 9000
XQC_IDRAFT_VER_29	2	IETF Draft-29
XQC_IDRAFT_VER_NEGOTIATION	3	Special version for version negotiation.
XQC_VERSION_MAX	4	max value of proto value.

supported versions for IETF drafts

enum xqc_path_status_change_type_t

Enumerator	Value	Description
XQC_PATH_DEGRADE	0
XQC_PATH_RECOVERY	1

enum xqc_data_qos_level_t

Enumerator	Value	Description
XQC_DATA_QOS_HIGHEST	1
XQC_DATA_QOS_HIGH	2
XQC_DATA_QOS_MEDIUM	3
XQC_DATA_QOS_NORMAL	4
XQC_DATA_QOS_LOW	5
XQC_DATA_QOS_LOWEST	6
XQC_DATA_QOS_PROBING	7

enum xqc_fec_schemes_e

Enumerator	Value	Description
XQC_REED_SOLOMON_CODE	8
XQC_XOR_CODE	11
XQC_PACKET_MASK_CODE	12

FEC schemes type enum.

enum xqc_fec_mp_mode_e

Enumerator	Value	Description
XQC_FEC_MP_DEFAULT	0
XQC_FEC_MP_USE_STB	1

enum xqc_scheduler_path_event_e

Enumerator	Value	Description
XQC_SCHED_EVENT_PATH_NOT_FULL	0

enum xqc_scheduler_conn_event_e

Enumerator	Value	Description
XQC_SCHED_EVENT_CONN_ROUND_START	0
XQC_SCHED_EVENT_CONN_ROUND_FIN	1

enum xqc_reinjection_mode_t

Enumerator	Value	Description
XQC_REINJ_UNACK_AFTER_SCHED	1 << 0
XQC_REINJ_UNACK_BEFORE_SCHED	1 << 1
XQC_REINJ_UNACK_AFTER_SEND	1 << 2

enum xqc_cert_verify_flag_e

Enumerator	Value	Description
XQC_TLS_CERT_FLAG_NEED_VERIFY	1 << 0
XQC_TLS_CERT_FLAG_ALLOW_SELF_SIGNED	1 << 1

enum xqc_dgram_red_setting_e

Enumerator	Value	Description
XQC_RED_NOT_USE	0
XQC_RED_SET_CLOSE	1

enum xqc_multipath_version_t

Enumerator	Value	Description
XQC_ERR_MULTIPATH_VERSION	0x00
XQC_MULTIPATH_10	0x0a

enum xqc_fec_version_t

Enumerator	Value	Description
XQC_ERR_FEC_VERSION	0x00
XQC_FEC_02	0x02

enum xqc_0rtt_flag_t

Enumerator	Value	Description
XQC_0RTT_NONE	0	without 0-RTT
XQC_0RTT_ACCEPT	1	0-RTT was accepted
XQC_0RTT_REJECT	2	0-RTT was rejected

typedef xqc_proto_version_t

typedef enum xqc_proto_version_s xqc_proto_version_t;

supported versions for IETF drafts

typedef xqc_timestamp_pt

typedef xqc_usec_t(* xqc_timestamp_pt) (void);

get timestamp callback function. this might be useful on different platforms

Return: timestamp in microsecond

typedef xqc_set_event_timer_pt

typedef void(* xqc_set_event_timer_pt) (xqc_usec_t wake_after, void *engine_user_data);

event timer callback function. MUST be set for both client and server xquic don't have implementation of timer, but will tell the interval of timer by this function. applications shall implement the timer, and invoke xqc_engine_main_logic after timer expires.

Parameters:

• wake_after interval of timer, with micro-second.
• engine_user_data user_data of engine

typedef xqc_cid_generate_pt

typedef ssize_t(* xqc_cid_generate_pt) (const xqc_cid_t *ori_cid, uint8_t *cid_buf, size_t cid_buflen, void *engine_user_data);

cid generate callback.

Parameters:

• ori_cid the original dcid sent by client.
• cid_buf buffer for cid generated
• cid_buflen len for cid_buf
• engine_user_data user data of engine from xqc_engine_create

Return: negative for failed, non-negative (including 0) for the length of bytes written. if the count of written bytes is less than cid_buflen, xquic will fill rest of cid_buf with random bytes

typedef xqc_eng_keylog_pt

typedef void(* xqc_eng_keylog_pt) (const xqc_cid_t *scid, const char *line, void *engine_user_data);

engine secret log callback. will only be effective when build with XQC_PRINT_SECRET

this callback will be invoked everytime when TLS layer generates a secret, and will be triggered multiple times during handshake. keylog could be used in wireshark to parse QUIC packets

typedef xqc_keylog_pt

typedef void(* xqc_keylog_pt) (const char *line, void *engine_user_data);

tls secret log callback. will only be effective when build with XQC_PRINT_SECRET

this callback will be invoked everytime when TLS layer generates a secret, and will be triggered multiple times during handshake. keylog could be used in wireshark to parse QUIC packets

typedef xqc_log_callbacks_t

typedef struct xqc_log_callbacks_s xqc_log_callbacks_t;

log callback functions

typedef xqc_server_accept_pt

typedef int(* xqc_server_accept_pt) (xqc_engine_t *engine, xqc_connection_t *conn, const xqc_cid_t *cid, void *user_data);

connection accept callback.

Parameters:

• user_data the user_data parameter of xqc_engine_packet_process

Return: negative for refuse connection. 0 for accept

this function is invoked when incoming a new QUIC connection. return 0 means accept this new connection. return negative values if application layer will not accept the new connection due to busy or some reason else

typedef xqc_server_refuse_pt

typedef void(* xqc_server_refuse_pt) (xqc_engine_t *engine, xqc_connection_t *conn, const xqc_cid_t *cid, void *user_data);

connection refused callback. corresponding to xqc_server_accept_pt callback function. this function will be invoked when a QUIC connection is refused by xquic due to security considerations, applications SHALL link the connection's lifetime between itself and xquic, and free the context if it was created during xqc_server_accept_pt.

Parameters:

• user_data the user_data parameter of connection

typedef xqc_stateless_reset_pt

typedef ssize_t(* xqc_stateless_reset_pt) (const unsigned char *buf, size_t size, const struct sockaddr *peer_addr, socklen_t peer_addrlen, const struct sockaddr *local_addr, socklen_t local_addrlen, void *user_data);

engine can't find connection related to input udp packet, and return a STATELESS_RESET packet, implementations shall send this buffer back to peer. this callback function is almost the same with xqc_socket_write_pt, but with different user_data definition.

Parameters:

• user_data user_data related to connection, originated from the user_data parameter of xqc_engine_packet_process

typedef xqc_conn_closing_notify_pt

typedef xqc_int_t(* xqc_conn_closing_notify_pt) (xqc_connection_t *conn, const xqc_cid_t *cid, xqc_int_t err_code, void *conn_user_data);

connection closing notify callback function.

Parameters:

• conn pointer of connection
• cid connection id
• err_code the reason of connection close
• conn_user_data the user_data which will be used in callback functions between xquic transport connection and application

This function will be triggered when a connection is not available and will not send/receive data any more. this callback is helpful to avoid attempts to send data on a closing connection.

NOTICE: this callback function will be triggered at the beginning of connection close, while the conn_close_notify will be triggered at the end of connection close.

typedef xqc_conn_notify_pt

typedef int(* xqc_conn_notify_pt) (xqc_connection_t *conn, const xqc_cid_t *cid, void *conn_user_data, void *conn_proto_data);

general callback function definition for connection create and close

Parameters:

• conn_user_data the user_data which will be used in callback functions between xquic transport connection and application
• conn_proto_data the user_data which will be used in callback functions between xquic transport connection and application-layer-protocol

typedef xqc_save_token_pt

typedef void(* xqc_save_token_pt) (const unsigned char *token, uint32_t token_len, void *conn_user_data);

QUIC connection token callback. REQUIRED for client. token is used by the server to validate client's address during the handshake period of next connection to the same server. client applications shall save token to local storage, if need to connect the same server, read the token and take it as the parameter of xqc_connect.

NOTICE: as client initiate multiple connections to multiple QUIC servers or server clusters, it shall save the tokens separately, e.g. save the token with the domain as the key

typedef xqc_save_string_pt

typedef void(* xqc_save_string_pt) (const char *data, size_t data_len, void *conn_user_data);

general type of session ticket and transport parameter callback function

typedef xqc_save_session_pt

typedef xqc_save_string_pt xqc_save_session_pt;

session ticket callback function

session ticket is essential for 0-RTT connections. with the same storage requirements and strategy as token. when initiating a new connection, session ticket is part of xqc_conn_ssl_config_t parameter

typedef xqc_save_trans_param_pt

typedef xqc_save_string_pt xqc_save_trans_param_pt;

transport parameters callback

transport parameters are use when initiating 0-RTT connections to avoid violating the server's restriction, it shall be remembered with the same storage requirements and strategy as token. When initiating a new connection, transport parameters is part of xqc_conn_ssl_config_t parameter

typedef xqc_handshake_finished_pt

typedef void(* xqc_handshake_finished_pt) (xqc_connection_t *conn, void *conn_user_data, void *conn_proto_data);

handshake finished callback function

this will be trigger when the QUIC connection handshake is completed, that is, when the TLS stack has both sent a Finished message and verified the peer's Finished message

typedef xqc_conn_ping_ack_notify_pt

typedef void(* xqc_conn_ping_ack_notify_pt) (xqc_connection_t *conn, const xqc_cid_t *cid, void *ping_user_data, void *conn_user_data, void *conn_proto_data);

PING acked callback function.

if application send a PING frame with xqc_conn_send_ping function, this callback function will be triggered when this PING frame is acked by peer. noticing that PING frame do not need repair, it might not be triggered if PING frame is lost or ACK frame is lost. xquic might send PING frames will not trigger this callback

typedef xqc_conn_update_cid_notify_pt

typedef void(* xqc_conn_update_cid_notify_pt) (xqc_connection_t *conn, const xqc_cid_t *retire_cid, const xqc_cid_t *new_cid, void *conn_user_data);

cid update callback function.

Parameters:

• conn connection handler
• retire_cid cid that was retired by peer
• new_cid cid that would be used
• conn_user_data connection level user_data

this function will be trigger after receive peer's RETIRE_CONNECTION_ID frame and the SCID of endpoint is changed. cid change might be essential if load balance or some other mechanism related with cid is introduced, applications shall update the CID after the callback is triggered

typedef xqc_cert_verify_pt

typedef int(* xqc_cert_verify_pt) (const unsigned char *certs[], const size_t cert_len[], size_t certs_len, void *conn_user_data);

client certificate verify callback

Parameters:

• certs[] X509 certificates in DER format
• cert_len[] lengths of X509 certificates in DER format

Return: 0 for success, -1 for verify failed and xquic will close the connection

typedef xqc_conn_peer_addr_changed_nofity_pt

typedef void(* xqc_conn_peer_addr_changed_nofity_pt) (xqc_connection_t *conn, void *conn_user_data);

server peer addr changed notify

Parameters:

• conn connection handler
• conn_user_data connection level user_data

this function will be trigger after receive peer's changed addr.

typedef xqc_path_peer_addr_changed_nofity_pt

typedef void(* xqc_path_peer_addr_changed_nofity_pt) (xqc_connection_t *conn, uint64_t path_id, void *conn_user_data);

server peer addr changed notify

Parameters:

• conn connection handler
• path_id id of path
• conn_user_data connection level user_data

this function will be trigger after receive peer's changed addr.

typedef xqc_socket_write_pt

typedef ssize_t(* xqc_socket_write_pt) (const unsigned char *buf, size_t size, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *conn_user_data);

writing data callback function

Parameters:

• buf packet buffer
• size packet size
• peer_addr peer address
• peer_addrlen peer address length
• conn_user_data user_data of connection

Return: bytes of data which is successfully sent: XQC_SOCKET_ERROR for error, xquic will destroy the connection XQC_SOCKET_EAGAIN for EAGAIN, application could continue sending data with xqc_conn_continue_send function when socket write event is ready

typedef xqc_send_mmsg_pt

typedef ssize_t(* xqc_send_mmsg_pt) (const struct iovec *msg_iov, unsigned int vlen, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *conn_user_data);

sendmmsg callback function. the implementation of this shall send data with sendmmsg

Parameters:

• msg_iov message vector
• vlen vector of messages
• peer_addr address of peer
• peer_addrlen length of peer_addr param
• conn_user_data user_data of connection

Return: count of messages that are successfully sent: XQC_SOCKET_ERROR for error, xquic will destroy the connection XQC_SOCKET_EAGAIN for EAGAIN, application could continue sending data with xqc_conn_continue_send function when socket write event is ready Warning: server's user_data is what passed in xqc_engine_packet_process when send a stateless reset packet, as xquic can't find a connection

typedef xqc_conn_pkt_filter_callback_pt

typedef ssize_t(* xqc_conn_pkt_filter_callback_pt) (const unsigned char *buf, size_t size, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *cb_user_data);

set data callback mode for a transport connection. this mode differs from write_socket, which has a different user_data, once this callback function is set, write_socket will be not functional until it is unset.

Parameters:

• buf packet buffer
• size packet size
• peer_addr peer address
• peer_addrlen peer address length
• cb_user_data user_data of xqc_conn_pkt_filter_callback_pt

typedef xqc_conn_ready_to_create_path_notify_pt

typedef void(* xqc_conn_ready_to_create_path_notify_pt) (const xqc_cid_t *scid, void *conn_user_data);

multi-path ready callback function

Parameters:

• scid source connection id of endpoint
• conn_user_data user_data of connection

this callback function will be triggered when a new connection id is received and endpoint get unused cids. it's a precondition of multi-path

typedef xqc_conn_cert_cb_pt

typedef xqc_int_t(* xqc_conn_cert_cb_pt) (const char *sni, void **chain, void **crt, void **key, void *user_data);

get chain certs and key by sin

typedef xqc_path_created_notify_pt

typedef int(* xqc_path_created_notify_pt) (xqc_connection_t *conn, const xqc_cid_t *scid, uint64_t path_id, void *conn_user_data);

multi-path create callback function

Parameters:

• conn connection handler
• scid source connection id of endpoint
• path_id id of path
• conn_user_data user_data of connection

typedef xqc_path_removed_notify_pt

typedef void(* xqc_path_removed_notify_pt) (const xqc_cid_t *scid, uint64_t path_id, void *conn_user_data);

multi-path remove path callback function.

Parameters:

• scid source connection id of endpoint
• path_id id of path
• conn_user_data user_data of connection

this callback function will be triggered when path is closing and then the application-layer can release related resource.

typedef xqc_socket_write_ex_pt

typedef ssize_t(* xqc_socket_write_ex_pt) (uint64_t path_id, const unsigned char *buf, size_t size, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *conn_user_data);

multi-path write socket callback function

Parameters:

• path_id path identifier
• conn_user_data user_data of connection
• buf packet buffer
• size packet size
• peer_addr peer address
• peer_addrlen peer address length
• conn_user_data user_data of connection

Return: bytes of data which is successfully sent to socket: XQC_SOCKET_ERROR for error, xquic will destroy the connection XQC_SOCKET_EAGAIN for EAGAIN, we should call xqc_conn_continue_send when socket is ready to write Warning: server's user_data is what passed in xqc_engine_packet_process when send a reset packet

typedef xqc_send_mmsg_ex_pt

typedef ssize_t(* xqc_send_mmsg_ex_pt) (uint64_t path_id, const struct iovec *msg_iov, unsigned int vlen, const struct sockaddr *peer_addr, socklen_t peer_addrlen, void *conn_user_data);

multi-path write socket callback function with sendmmsg

Parameters:

• path_id path identifier
• msg_iov vector of messages
• vlen count of messages
• peer_addr peer address
• peer_addrlen peer address length
• conn_user_data user_data of connection, which was the parameter of xqc_connect set by client, or the parameter of xqc_conn_set_transport_user_data set by server

Return: bytes of data which is successfully sent to socket: XQC_SOCKET_ERROR for error, xquic will destroy the connection XQC_SOCKET_EAGAIN for EAGAIN, we should call xqc_conn_continue_send when socket is ready to write Warning: server's user_data is what passed in xqc_engine_packet_process when send a reset packet

typedef xqc_stream_notify_pt

typedef xqc_int_t(* xqc_stream_notify_pt) (xqc_stream_t *stream, void *strm_user_data);

general callback function definition for stream create, close, read and write.

Parameters:

• stream QUIC stream handler
• strm_user_data stream level user_data, which was the parameter of xqc_stream_create set by client, or the parameter of xqc_stream_set_user_data set by server

Return: 0 for success, -1 for failure

typedef xqc_stream_closing_notify_pt

typedef void(* xqc_stream_closing_notify_pt) (xqc_stream_t *stream, xqc_int_t err_code, void *strm_user_data);

stream closing callback function, this will be triggered when some error on a stream happens.

Parameters:

• stream QUIC stream handler
• err_code error code
• strm_user_data stream level user_data, which was the parameter of xqc_stream_create set by client, or the parameter of xqc_stream_set_user_data set by server

Return: 0 for success, -1 for failure

typedef xqc_datagram_read_notify_pt

typedef void(* xqc_datagram_read_notify_pt) (xqc_connection_t *conn, void *user_data, const void *data, size_t data_len, uint64_t unix_ts);

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

Parameters:

• conn the connection handle
• user_data the dgram_data set by xqc_datagram_set_user_data
• data the data delivered by this callback
• data_len the length of the delivered data
• dgram_recv_ts the unix timestamp when the datagram is received from socket

typedef xqc_datagram_write_notify_pt

typedef void(* xqc_datagram_write_notify_pt) (xqc_connection_t *conn, void *user_data);

the callback API to notify application that datagrams can be sent

Parameters:

• conn the connection handle
• user_data the dgram_data set by xqc_datagram_set_user_data

typedef xqc_datagram_lost_notify_pt

typedef xqc_int_t(* xqc_datagram_lost_notify_pt) (xqc_connection_t *conn, uint64_t dgram_id, void *user_data);

the callback API to notify application that a datagram is declared lost.

Parameters:

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

Return: 0: the stack will not retransmit the packet; XQC_DGRAM_RETX_ASKED_BY_APP (1): the stack will retransmit the packet; others are ignored by the QUIC stack.

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 indicates how this lost datagram is handled by the QUIC stack. NOTE, if the QUIC stack replicates the datagram (e.g. reinjection or retransmission), this callback can be triggered multiple times for a dgram_id.

typedef xqc_datagram_acked_notify_pt

typedef void(* xqc_datagram_acked_notify_pt) (xqc_connection_t *conn, uint64_t dgram_id, void *user_data);

the callback API to notify application that a datagram is acked. Note, for every unique dgram_id, this callback will be only called once.

Parameters:

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

typedef xqc_datagram_mss_updated_notify_pt

typedef void(* xqc_datagram_mss_updated_notify_pt) (xqc_connection_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_datagram_set_user_data
• mss the MSS of QUIC datagrams

typedef xqc_transport_callbacks_t

typedef struct xqc_transport_callbacks_s xqc_transport_callbacks_t;

tranport callback functions are more related to attributes of QUIC [Transport] but not ALPN.

These callback functions are events of QUIC Transport layer, and need to interact with application-layer, which have less thing to do with ALPN layer.

These callback functions shall directly call back to application layer, with user_data from struct xqc_connection_t. unless Application-Layer-Protocol take over them.

Generally, xquic defines callbacks as below:

1. Callbacks between Transport and Application: QUIC events that are common between different Application Protocols, and is much more convenient to interact with Application and Application Protocol.
2. Callbacks between Application Protocol and Application: Application-Protocol events will interact with Application Layer. these callback functions are defined by Application Protocol Layers.
3. Callbacks between Transport and Application Protocol: QUIC events that might be more essential to Application-Layer-Protocols, especially stream data

typedef xqc_conn_callbacks_t

typedef struct xqc_conn_callbacks_s xqc_conn_callbacks_t;

QUIC connection callback functions for Application-layer-Protocol.

typedef xqc_stream_callbacks_t

typedef struct xqc_stream_callbacks_s xqc_stream_callbacks_t;

QUIC layer stream callback functions.

typedef xqc_datagram_callbacks_t

typedef struct xqc_datagram_callbacks_s xqc_datagram_callbacks_t;

QUIC layer datagram callback functions.

typedef xqc_app_proto_callbacks_t

typedef struct xqc_app_proto_callbacks_s xqc_app_proto_callbacks_t;

connection and stream callbacks for QUIC level, Application-Layer-Protocol shall implement these callback functions and register ALP with xqc_engine_register_alpn

typedef xqc_cc_params_t

typedef struct xqc_cc_params_s xqc_cc_params_t;

congestion control algorithm parameters

typedef xqc_scheduler_params_t

typedef struct xqc_scheduler_params_u xqc_scheduler_params_t;

multipath scheduler algorithm parameters

typedef xqc_fec_params_t

typedef struct xqc_fec_params_s xqc_fec_params_t;

FEC parameters on connection settings.

typedef xqc_cong_ctrl_callback_t

typedef struct xqc_congestion_control_callback_s xqc_cong_ctrl_callback_t;

congestion control callbacks

typedef xqc_scheduler_path_event_t

typedef enum xqc_scheduler_path_event_e xqc_scheduler_path_event_t;

typedef xqc_scheduler_conn_event_t

typedef enum xqc_scheduler_conn_event_e xqc_scheduler_conn_event_t;

typedef xqc_scheduler_callback_t

typedef struct xqc_scheduler_callback_s xqc_scheduler_callback_t;

multipath scheduler callbacks

typedef xqc_reinj_ctl_callback_t

typedef struct xqc_reinj_ctl_callback_s xqc_reinj_ctl_callback_t;

typedef xqc_fec_code_callback_t

typedef struct xqc_fec_code_callback_s xqc_fec_code_callback_t;

typedef xqc_config_t

typedef struct xqc_config_s xqc_config_t;

typedef xqc_engine_callback_t

typedef struct xqc_engine_callback_s xqc_engine_callback_t;

engine callback functions.

typedef xqc_engine_ssl_config_t

typedef struct xqc_engine_ssl_config_s xqc_engine_ssl_config_t;

engine's ssl config

typedef xqc_conn_ssl_config_t

typedef struct xqc_conn_ssl_config_s xqc_conn_ssl_config_t;

connection tls config for client

typedef xqc_linger_t

typedef struct xqc_linger_s xqc_linger_t;

typedef xqc_conn_settings_t

typedef struct xqc_conn_settings_s xqc_conn_settings_t;

structures of connection settings

typedef xqc_path_metrics_t

typedef struct xqc_path_metrics_s xqc_path_metrics_t;

typedef xqc_conn_stats_t

typedef struct xqc_conn_stats_s xqc_conn_stats_t;

connection stats

typedef xqc_conn_qos_stats_t

typedef struct xqc_conn_qos_stats_s xqc_conn_qos_stats_t;

Functions Documentation

function xqc_engine_create

XQC_EXPORT_PUBLIC_API xqc_engine_t * xqc_engine_create(
    xqc_engine_type_t engine_type,
    const xqc_config_t * engine_config,
    const xqc_engine_ssl_config_t * ssl_config,
    const xqc_engine_callback_t * engine_callback,
    const xqc_transport_callbacks_t * transport_cbs,
    void * user_data
)

Create new xquic engine.

Parameters:

• engine_type XQC_ENGINE_SERVER or XQC_ENGINE_CLIENT
• engine_config config for basic framework, quic, network, etc.
• ssl_config basic ssl config
• engine_callback environment callback functions, including timer, socket, log, etc.
• transport_cbs transport callback functions
• conn_callback default connection callback functions

function xqc_engine_destroy

XQC_EXPORT_PUBLIC_API void xqc_engine_destroy(
    xqc_engine_t * engine
)

destroy engine. this is called after all connections are destroyed NOTICE: MUST NOT be called in any xquic callback functions, for this function will destroy engine immediately, result in segmentation fault.

function xqc_engine_register_alpn

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_engine_register_alpn(
    xqc_engine_t * engine,
    const char * alpn,
    size_t alpn_len,
    xqc_app_proto_callbacks_t * ap_cbs,
    void * alp_ctx
)

register alpn and connection and stream callbacks. user can implement his own application protocol by registering alpn, and taking quic connection and streams as application connection and request

Parameters:

• engine engine handler
• alpn Application-Layer-Protocol, for example, h3, hq-interop, or self-defined
• alpn_len length of Application-Layer-Protocol string
• ap_cbs connection and stream event callback functions for application-layer-protocol
• alp_ctx the context of the upper layer protocol (e.g. the callback functions and default settings of the upper layer protocol)

Return: XQC_EXPORT_PUBLIC_API

function xqc_engine_unregister_alpn

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_engine_unregister_alpn(
    xqc_engine_t * engine,
    const char * alpn,
    size_t alpn_len
)

unregister an alpn and its quic connection callbacks

Parameters:

• engine engine handler
• alpn Application-Layer-Protocol, for example, h3, hq-interop, or self-defined
• alpn_len length of alpn

Return: XQC_EXPORT_PUBLIC_API

function xqc_engine_get_alpn_ctx

XQC_EXPORT_PUBLIC_API void * xqc_engine_get_alpn_ctx(
    xqc_engine_t * engine,
    const char * alpn,
    size_t alpn_len
)

get the context an application layer protocol

Parameters:

• engine engine handler
• alpn Application-Layer-Protocol, for example, h3, hq-interop, or self-defined
• alpn_len length of alpn

Return: the context

function xqc_engine_get_priv_ctx

XQC_EXPORT_PUBLIC_API void * xqc_engine_get_priv_ctx(
    xqc_engine_t * engine
)

get the private context

Parameters:

• engine

Return: XQC_EXPORT_PUBLIC_API*

function xqc_engine_set_priv_ctx

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_engine_set_priv_ctx(
    xqc_engine_t * engine,
    void * priv_ctx
)

save the private context

Parameters:

• engine
• priv_ctx

Return: XQC_EXPORT_PUBLIC_API

function xqc_engine_packet_process

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_engine_packet_process(
    xqc_engine_t * engine,
    const unsigned char * packet_in_buf,
    size_t packet_in_size,
    const struct sockaddr * local_addr,
    socklen_t local_addrlen,
    const struct sockaddr * peer_addr,
    socklen_t peer_addrlen,
    xqc_usec_t recv_time,
    void * user_data
)

Parameters:

• recv_time UDP packet received time in microsecond
• user_data connection user_data, server is NULL

Pass received UDP packet payload into xquic engine.

function xqc_engine_main_logic

XQC_EXPORT_PUBLIC_API void xqc_engine_main_logic(
    xqc_engine_t * engine
)

Process all connections, application implements MUST call this function in timer callback.

function xqc_engine_get_default_config

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_engine_get_default_config(
    xqc_config_t * config,
    xqc_engine_type_t engine_type
)

get default config of xquic

function xqc_engine_set_config

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_engine_set_config(
    xqc_engine_t * engine,
    const xqc_config_t * engine_config
)

Return: 0 for success, <0 for error. default value is used if config item is illegal

Modify engine config before engine created. Default config will be used otherwise. Item value 0 means use default value.

function xqc_server_set_conn_settings

XQC_EXPORT_PUBLIC_API void xqc_server_set_conn_settings(
    xqc_engine_t * engine,
    const xqc_conn_settings_t * settings
)

Set server's connection settings. it can be called anytime. settings will take effect on new created connections.

function xqc_engine_set_log_level

XQC_EXPORT_PUBLIC_API void xqc_engine_set_log_level(
    xqc_engine_t * engine,
    xqc_log_level_t log_level
)

Set the log level of xquic.

Parameters:

• log_level engine will print logs which level >= log_level

function xqc_log_disable

XQC_EXPORT_PUBLIC_API void xqc_log_disable(
    xqc_bool_t disable
)

enable/disable the log module of xquic

Parameters:

• enable XQC_TRUE for disable, XQC_FALSE for enable

Note: This function is not thread-safe.

function xqc_engine_finish_recv

XQC_EXPORT_PUBLIC_API void xqc_engine_finish_recv(
    xqc_engine_t * engine
)

user should call after a number of packet processed in xqc_engine_packet_process call after recv a batch packets, may destroy connection when error

function xqc_engine_finish_send

XQC_EXPORT_PUBLIC_API void xqc_engine_finish_send(
    xqc_engine_t * engine
)

only useful for manually triggered send mode

Parameters:

• engine

Return: XQC_EXPORT_PUBLIC_API

function xqc_engine_get_conn_by_scid

XQC_EXPORT_PUBLIC_API xqc_connection_t * xqc_engine_get_conn_by_scid(
    xqc_engine_t * engine,
    const xqc_cid_t * cid
)

function xqc_connect

XQC_EXPORT_PUBLIC_API const xqc_cid_t * xqc_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,
    const char * alpn,
    void * user_data
)

Parameters:

• engine return from xqc_engine_create
• conn_settings settings of connection
• token token receive from server, xqc_save_token_pt callback
• token_len
• server_host server domain
• no_crypto_flag 1: stop encrypt 0-RTT and 1-RTT packets.

This flag will add no_crypto transport parameter when initiating a connection, which is not an official parameter and might be modified or removed

• conn_ssl_config For handshake
• user_data application data, for connection usage
• peer_addr address of peer
• peer_addrlen length of peer_addr
• alpn Application-Layer-Protocol, MUST NOT be NULL

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

Client connect without http3

function xqc_conn_close

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

Return: 0 for success, <0 for error

Send CONNECTION_CLOSE to peer, conn_close_notify will callback when connection destroyed

function xqc_conn_close_with_error

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_close_with_error(
    xqc_connection_t * conn,
    uint64_t err_code
)

close connection with error code

function xqc_conn_get_errno

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_get_errno(
    xqc_connection_t * conn
)

Get errno when conn_close_notify, 0 For no-error

function xqc_conn_get_ssl

XQC_EXPORT_PUBLIC_API void * xqc_conn_get_ssl(
    xqc_connection_t * conn
)

Get ssl handler of specified connection

function xqc_conn_get_lastest_rtt

XQC_EXPORT_PUBLIC_API xqc_usec_t xqc_conn_get_lastest_rtt(
    xqc_engine_t * engine,
    const xqc_cid_t * cid
)

get latest rtt sample of the initial path

function xqc_conn_set_transport_user_data

XQC_EXPORT_PUBLIC_API void xqc_conn_set_transport_user_data(
    xqc_connection_t * conn,
    void * user_data
)

Server should set user_data when conn_create_notify callbacks

function xqc_conn_set_alp_user_data

XQC_EXPORT_PUBLIC_API void xqc_conn_set_alp_user_data(
    xqc_connection_t * conn,
    void * proto_data
)

set application-layer-protocol user_data to xqc_connection_t. which will be used in xqc_conn_callbacks_t

function xqc_conn_get_peer_addr

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_get_peer_addr(
    xqc_connection_t * conn,
    struct sockaddr * addr,
    socklen_t addr_cap,
    socklen_t * peer_addr_len
)

Parameters:

• peer_addr_len is a return value

Return: XQC_OK for success, others for failure

Server should get peer addr when conn_create_notify callbacks

function xqc_conn_get_local_addr

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_get_local_addr(
    xqc_connection_t * conn,
    struct sockaddr * addr,
    socklen_t addr_cap,
    socklen_t * local_addr_len
)

Parameters:

• local_addr_len is a return value

Return: XQC_OK for success, others for failure

Server should get local addr when conn_create_notify callbacks

function xqc_conn_send_ping

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

Return: 0 for success, <0 for error

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

function xqc_conn_is_ready_to_send_early_data

XQC_EXPORT_PUBLIC_API xqc_bool_t xqc_conn_is_ready_to_send_early_data(
    xqc_connection_t * conn
)

Return: 1 for can send 0rtt, 0 for cannot send 0rtt

function xqc_conn_set_pkt_filter_callback

XQC_EXPORT_PUBLIC_API void xqc_conn_set_pkt_filter_callback(
    xqc_connection_t * conn,
    xqc_conn_pkt_filter_callback_pt pf_cb,
    void * pf_cb_user_data
)

set the packet filter callback function, and replace write_socket. NOTICE: this function is not conflict with send_mmsg.

function xqc_conn_unset_pkt_filter_callback

XQC_EXPORT_PUBLIC_API void xqc_conn_unset_pkt_filter_callback(
    xqc_connection_t * conn
)

unset the packet filter callback function, and restore write_socket

function xqc_conn_get_public_local_trans_settings

XQC_EXPORT_PUBLIC_API xqc_conn_public_local_trans_settings_t xqc_conn_get_public_local_trans_settings(
    xqc_connection_t * conn
)

get public local transport settings.

function xqc_conn_set_public_local_trans_settings

XQC_EXPORT_PUBLIC_API void xqc_conn_set_public_local_trans_settings(
    xqc_connection_t * conn,
    xqc_conn_public_local_trans_settings_t * settings
)

set public local transport settings

function xqc_conn_get_public_remote_trans_settings

XQC_EXPORT_PUBLIC_API xqc_conn_public_remote_trans_settings_t xqc_conn_get_public_remote_trans_settings(
    xqc_connection_t * conn
)

get public remote transport settings.

function xqc_conn_set_public_remote_trans_settings

XQC_EXPORT_PUBLIC_API void xqc_conn_set_public_remote_trans_settings(
    xqc_connection_t * conn,
    xqc_conn_public_remote_trans_settings_t * settings
)

set public remote transport settings

function xqc_stream_create

XQC_EXPORT_PUBLIC_API xqc_stream_t * xqc_stream_create(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    xqc_stream_settings_t * settings,
    void * user_data
)

Parameters:

• user_data user_data for this stream

Create new stream in quic connection.

function xqc_stream_create_with_direction

XQC_EXPORT_PUBLIC_API xqc_stream_t * xqc_stream_create_with_direction(
    xqc_connection_t * conn,
    xqc_stream_direction_t dir,
    void * user_data
)

function xqc_stream_get_direction

XQC_EXPORT_PUBLIC_API xqc_stream_direction_t xqc_stream_get_direction(
    xqc_stream_t * strm
)

function xqc_stream_set_user_data

XQC_EXPORT_PUBLIC_API void xqc_stream_set_user_data(
    xqc_stream_t * stream,
    void * user_data
)

Server should set user_data when stream_create_notify callbacks

function xqc_stream_update_settings

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_stream_update_settings(
    xqc_stream_t * stream,
    xqc_stream_settings_t * settings
)

function xqc_get_conn_user_data_by_stream

XQC_EXPORT_PUBLIC_API void * xqc_get_conn_user_data_by_stream(
    xqc_stream_t * stream
)

Get connection's user_data by stream

function xqc_get_conn_alp_user_data_by_stream

XQC_EXPORT_PUBLIC_API void * xqc_get_conn_alp_user_data_by_stream(
    xqc_stream_t * stream
)

Get connection's app_proto_user_data by stream

function xqc_stream_id

XQC_EXPORT_PUBLIC_API xqc_stream_id_t xqc_stream_id(
    xqc_stream_t * stream
)

Get stream ID

function xqc_stream_close

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_stream_close(
    xqc_stream_t * stream
)

Returns:

• XQC_OK for success, others for failure

Send RESET_STREAM to peer, stream_close_notify will callback when stream destroyed

function xqc_stream_recv

XQC_EXPORT_PUBLIC_API ssize_t xqc_stream_recv(
    xqc_stream_t * stream,
    unsigned char * recv_buf,
    size_t recv_buf_size,
    uint8_t * fin
)

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

Recv data in stream.

function xqc_stream_send

XQC_EXPORT_PUBLIC_API ssize_t xqc_stream_send(
    xqc_stream_t * stream,
    unsigned char * send_data,
    size_t send_data_size,
    uint8_t fin
)

Parameters:

• fin 0 or 1, 1 - final data block send in this stream.

Return: bytes sent, -XQC_EAGAIN try next time, <0 for error

Send data in stream.

function xqc_datagram_get_mss

XQC_EXPORT_PUBLIC_API size_t xqc_datagram_get_mss(
    xqc_connection_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

NOTE: if the DCID length could be changed during the lifetime of the connection, applications is suggested to call xqc_datagram_get_mss every time before send datagram data or when getting -XQC_EDGRAM_TOO_LARGE error from sending datagram data. In MPQUIC cases, the DCID of all paths MUST be the same. Otherwise, there might be unexpected errors.

function xqc_datagram_set_user_data

XQC_EXPORT_PUBLIC_API void xqc_datagram_set_user_data(
    xqc_connection_t * conn,
    void * dgram_data
)

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

function xqc_datagram_get_user_data

XQC_EXPORT_PUBLIC_API void * xqc_datagram_get_user_data(
    xqc_connection_t * conn
)

@dgram_data: the user_data of all datagram callbacks

function xqc_datagram_send

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_datagram_send(
    xqc_connection_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 QUIC 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_EDGRAM_NOT_SUPPORTED, -XQC_EDGRAM_TOO_LARGE, ...), 0 success

function xqc_datagram_send_multiple

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_datagram_send_multiple(
    xqc_connection_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 QUIC 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_EDGRAM_NOT_SUPPORTED, -XQC_EDGRAM_TOO_LARGE, ...), 0 success

function xqc_packet_parse_cid

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_packet_parse_cid(
    xqc_cid_t * dcid,
    xqc_cid_t * scid,
    uint8_t cid_len,
    const unsigned char * buf,
    size_t size
)

Get dcid and scid before process packet

function xqc_cid_is_equal

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_cid_is_equal(
    const xqc_cid_t * dst,
    const xqc_cid_t * src
)

compare two cids

Return: XQC_OK if equal, others if not equal

function xqc_scid_str

XQC_EXPORT_PUBLIC_API unsigned char * xqc_scid_str(
    xqc_engine_t * engine,
    const xqc_cid_t * scid
)

Parameters:

• scid is returned from xqc_connect or xqc_h3_connect

Return: user should copy return buffer to your own memory if you will access in the future

Get scid in hex, end with '\0'

function xqc_dcid_str

XQC_EXPORT_PUBLIC_API unsigned char * xqc_dcid_str(
    xqc_engine_t * engine,
    const xqc_cid_t * dcid
)

function xqc_dcid_str_by_scid

XQC_EXPORT_PUBLIC_API unsigned char * xqc_dcid_str_by_scid(
    xqc_engine_t * engine,
    const xqc_cid_t * scid
)

function xqc_engine_config_get_cid_len

XQC_EXPORT_PUBLIC_API uint8_t xqc_engine_config_get_cid_len(
    xqc_engine_t * engine
)

function xqc_conn_continue_send

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

User should call xqc_conn_continue_send when write event ready

function xqc_conn_continue_send_by_conn

XQC_EXPORT_PUBLIC_API void xqc_conn_continue_send_by_conn(
    xqc_connection_t * conn
)

User should call xqc_conn_continue_send when write event ready

function xqc_conn_get_stats

XQC_EXPORT_PUBLIC_API xqc_conn_stats_t xqc_conn_get_stats(
    xqc_engine_t * engine,
    const xqc_cid_t * cid
)

User can get xqc_conn_stats_t by cid

function xqc_conn_get_qos_stats

XQC_EXPORT_PUBLIC_API xqc_conn_qos_stats_t xqc_conn_get_qos_stats(
    xqc_engine_t * engine,
    const xqc_cid_t * cid
)

User can get xqc_conn_qos_stats_t by cid

function xqc_conn_create_path

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_create_path(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    uint64_t * new_path_id,
    int path_status
)

Parameters:

• cid scid for connection
• new_path_id if new path is created successfully, return new_path_id in this param
• path_status the initial status of the new path (1 = STANDBY, other values = AVAILABLE)

Return: XQC_OK (0) when success, <0 for error

create new path for client

function xqc_conn_close_path

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_close_path(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    uint64_t closed_path_id
)

Parameters:

• cid scid for connection
• close_path_id path identifier for the closing path

Return: XQC_OK (0) when success, <0 for error

Close a path

function xqc_conn_mark_path_standby

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_mark_path_standby(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    uint64_t path_id
)

Parameters:

• cid scid for connection
• path_id path identifier for the path

Return: XQC_OK (0) when success, <0 for error

Mark a path as "standby", i.e., suggest that no traffic should be sent on that path if another path is available.

function xqc_conn_mark_path_available

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_mark_path_available(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    uint64_t path_id
)

Parameters:

• cid scid for connection
• path_id path identifier for the path

Return: XQC_OK (0) when success, <0 for error

Mark a path as "available", i.e., allow the peer to use its own logic to split traffic among available paths.

function xqc_conn_mark_path_frozen

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_conn_mark_path_frozen(
    xqc_engine_t * engine,
    const xqc_cid_t * cid,
    uint64_t path_id
)

Parameters:

• cid scid for connection
• path_id path identifier for the path

Return: XQC_OK (0) when success, <0 for error

Mark a path as "frozen", i.e., both peers should not send any traffic on this path.

function xqc_conn_available_paths

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

Parameters:

• engine xquic engine ctx
• cid scid for connection

Return: number of available paths when success, <0 for error

Calculate how many available paths on the current connection, i.e., paths which finished validation and is marked "available" status.

function xqc_conn_get_type

XQC_EXPORT_PUBLIC_API xqc_conn_type_t xqc_conn_get_type(
    xqc_connection_t * conn
)

function xqc_path_get_peer_addr

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_path_get_peer_addr(
    xqc_connection_t * conn,
    uint64_t path_id,
    struct sockaddr * addr,
    socklen_t addr_cap,
    socklen_t * peer_addr_len
)

Parameters:

• peer_addr_len is a return value

Return: XQC_OK for success, others for failure

Server should get peer addr when path_create_notify callbacks

function xqc_path_get_local_addr

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_path_get_local_addr(
    xqc_connection_t * conn,
    uint64_t path_id,
    struct sockaddr * addr,
    socklen_t addr_cap,
    socklen_t * local_addr_len
)

Parameters:

• local_addr_len is a return value

Return: XQC_OK for success, others for failure

Server should get local addr when path_create_notify callbacks

function xqc_lb_cid_encryption

XQC_EXPORT_PUBLIC_API xqc_int_t xqc_lb_cid_encryption(
    uint8_t * cid_buf,
    size_t enc_len,
    uint8_t * out_buf,
    size_t out_buf_len,
    uint8_t * lb_cid_key,
    size_t lb_cid_key_len,
    xqc_engine_t * engine
)

load balance cid encryption. According to Draft : https://datatracker.ietf.org/doc/html/draft-ietf-quic-load-balancers-13#section-4.3.2

Parameters:

• enc_len plaintext length.
• cid_buf the plaintext to be encrypted.
• out_buf the ciphertext of the plaintext encrypted.
• out_buf_len the length of the ciphertext to be encrypted.
• lb_cid_key encryption secret.
• lb_cid_key_len secret length.
• engine engine from xqc_engine_create

Return: negative for failed, 0 for the success.

The length of cid_buf must not exceed the maximum length of the cid (20 byte), the length of out_buf should be no less than cid_buf_length. The length of lb_cid_key should be exactly 16 bytes.

function xqc_conn_should_clear_0rtt_ticket

XQC_EXPORT_PUBLIC_API xqc_bool_t xqc_conn_should_clear_0rtt_ticket(
    xqc_int_t conn_err
)

client calls this API to check if it should delete 0rtt ticket according to the errorcode of xqc_conn in conn_close_notify

Return: XQC_TRUE = yes;

function xqc_conn_get_conn_settings_template

XQC_EXPORT_PUBLIC_API xqc_conn_settings_t xqc_conn_get_conn_settings_template(
    xqc_conn_settings_type_t settings_type
)

Users call this function to get a template of conn settings, which serves as the starting point for users who want to refine conn settings according to their needs.

Parameters:

• settings_type there are different types of templates in XQUIC

Return: conn settings

Attributes Documentation

variable xqc_bbr_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_cong_ctrl_callback_t xqc_bbr_cb;

variable xqc_cubic_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_cong_ctrl_callback_t xqc_cubic_cb;

variable xqc_minrtt_scheduler_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_scheduler_callback_t xqc_minrtt_scheduler_cb;

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

variable xqc_backup_scheduler_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_scheduler_callback_t xqc_backup_scheduler_cb;

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

variable xqc_backup_fec_scheduler_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_scheduler_callback_t xqc_backup_fec_scheduler_cb;

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

variable xqc_rap_scheduler_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_scheduler_callback_t xqc_rap_scheduler_cb;

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

variable xqc_default_reinj_ctl_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_reinj_ctl_callback_t xqc_default_reinj_ctl_cb;

variable xqc_deadline_reinj_ctl_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_reinj_ctl_callback_t xqc_deadline_reinj_ctl_cb;

variable xqc_dgram_reinj_ctl_cb

XQC_EXPORT_PUBLIC_API XQC_EXTERN const xqc_reinj_ctl_callback_t xqc_dgram_reinj_ctl_cb;

variable xqc_xor_code_cb

XQC_EXPORT_PUBLIC_API const xqc_fec_code_callback_t xqc_xor_code_cb;

variable xqc_reed_solomon_code_cb

XQC_EXPORT_PUBLIC_API const xqc_fec_code_callback_t xqc_reed_solomon_code_cb;

variable xqc_packet_mask_code_cb

XQC_EXPORT_PUBLIC_API const xqc_fec_code_callback_t xqc_packet_mask_code_cb;

Macros Documentation

define XQC_SUPPORT_VERSION_MAX

#define XQC_SUPPORT_VERSION_MAX 64

define XQC_TLS_CIPHERS

#define XQC_TLS_CIPHERS "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

define XQC_TLS_GROUPS

#define XQC_TLS_GROUPS "P-256:X25519:P-384:P-521"

define XQC_RESET_TOKEN_MAX_KEY_LEN

#define XQC_RESET_TOKEN_MAX_KEY_LEN 256

define XQC_MAX_SEND_MSG_ONCE

#define XQC_MAX_SEND_MSG_ONCE 32

the max message count of iovec in sendmmsg

define XQC_INITIAL_PATH_ID

#define XQC_INITIAL_PATH_ID 0

define XQC_DGRAM_RETX_ASKED_BY_APP

#define XQC_DGRAM_RETX_ASKED_BY_APP 1

define XQC_CO_MAX_NUM

#define XQC_CO_MAX_NUM 16

define XQC_CO_STR_MAX_LEN

#define XQC_CO_STR_MAX_LEN (5 * XQC_CO_MAX_NUM)

define XQC_FEC_MAX_SCHEME_NUM

#define XQC_FEC_MAX_SCHEME_NUM 5

define XQC_SOCKET_ERROR

#define XQC_SOCKET_ERROR -1

return value of xqc_socket_write_pt and xqc_send_mmsg_pt callback function

define XQC_SOCKET_EAGAIN

#define XQC_SOCKET_EAGAIN -2

define XQC_MAX_PATHS_COUNT

#define XQC_MAX_PATHS_COUNT 8

define XQC_CONN_INFO_LEN

#define XQC_CONN_INFO_LEN 400

---

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