lsquic.h File Reference

#include <stdarg.h>
#include <lsquic_types.h>
#include <sys/uio.h>
#include <sys/types.h>
#include <time.h>

Include dependency graph for lsquic.h:

Go to the source code of this file.

Data Structures
struct	lsquic_stream_if
	The definition of callback functions call by lsquic_stream to process events. More...
struct	lsquic_engine_settings
struct	lsquic_out_spec
struct	lsquic_packout_mem_if
struct	lsquic_engine_api
struct	lsquic_reader
struct	lsquic_http_header
struct	lsquic_http_headers
struct	lsquic_logger_if

Macros
#define	LSENG_SERVER   (1 << 0)
#define	LSENG_HTTP   (1 << 1)
#define	LSENG_HTTP_SERVER   (LSENG_SERVER|LSENG_HTTP)
#define	LSQUIC_SUPPORTED_VERSIONS
#define	LSQUIC_EXPERIMENTAL_VERSIONS   ((1 << LSQVER_041))
#define	LSQUIC_MIN_FCW   (16 * 1024)
#define	LSQUIC_DF_VERSIONS
#define	LSQUIC_DF_CFCW_SERVER   (3 * 1024 * 1024 / 2)
#define	LSQUIC_DF_CFCW_CLIENT   (15 * 1024 * 1024)
#define	LSQUIC_DF_SFCW_SERVER   (1 * 1024 * 1024)
#define	LSQUIC_DF_SFCW_CLIENT   (6 * 1024 * 1024)
#define	LSQUIC_DF_MAX_STREAMS_IN   100
#define	LSQUIC_DF_HANDSHAKE_TO   (10 * 1000 * 1000)
#define	LSQUIC_DF_IDLE_CONN_TO   (30 * 1000 * 1000)
#define	LSQUIC_DF_SILENT_CLOSE   1
#define	LSQUIC_DF_MAX_HEADER_LIST_SIZE   0
#define	LSQUIC_DF_UA   "LSQUIC"
#define	LSQUIC_DF_STTL   86400
#define	LSQUIC_DF_MAX_INCHOATE   (1 * 1000 * 1000)
#define	LSQUIC_DF_SUPPORT_SREJ_SERVER   1
#define	LSQUIC_DF_SUPPORT_SREJ_CLIENT   0 /* TODO: client support */
#define	LSQUIC_DF_SUPPORT_NSTP   0
#define	LSQUIC_DF_SUPPORT_PUSH   1
#define	LSQUIC_DF_SUPPORT_TCID0   1
#define	LSQUIC_DF_HONOR_PRST   0
#define	LSQUIC_DF_PROGRESS_CHECK   1000
#define	LSQUIC_DF_PENDRW_CHECK   10
#define	LSQUIC_DF_RW_ONCE   0
#define	LSQUIC_DF_PROC_TIME_THRESH   0
#define	LSQUIC_DF_PACE_PACKETS   1
#define	LSQUIC_GLOBAL_CLIENT   (1 << 0)
#define	LSQUIC_GLOBAL_SERVER   (1 << 1)

Typedefs
typedef int(*	lsquic_packets_out_f) (void *packets_out_ctx, const struct lsquic_out_spec *out_spec, unsigned n_packets_out)
typedef struct lsquic_engine_api	lsquic_engine_api_t
typedef struct lsquic_http_header	lsquic_http_header_t
	HTTP header structure. Contains header name and value.

Enumerations
enum	lsquic_version {   LSQVER_035, LSQVER_037, LSQVER_038, LSQVER_039,   LSQVER_041, N_LSQVER }
enum	lsquic_logger_timestamp_style {   LLTS_NONE, LLTS_HHMMSSMS, LLTS_YYYYMMDD_HHMMSSMS, LLTS_CHROMELIKE,   LLTS_HHMMSSUS, N_LLTS }

Functions
void	lsquic_engine_init_settings (struct lsquic_engine_settings *, unsigned lsquic_engine_flags)
int	lsquic_engine_check_settings (const struct lsquic_engine_settings *settings, unsigned lsquic_engine_flags, char *err_buf, size_t err_buf_sz)
lsquic_engine_t *	lsquic_engine_new (unsigned lsquic_engine_flags, const struct lsquic_engine_api *)
int	lsquic_engine_connect (lsquic_engine_t *, const struct sockaddr *peer_sa, void *peer_ctx, const char *hostname, unsigned short max_packet_size)
int	lsquic_engine_packet_in (lsquic_engine_t *, const unsigned char *packet_in_data, size_t packet_in_size, const struct sockaddr *sa_local, const struct sockaddr *sa_peer, void *peer_ctx)
void	lsquic_engine_proc_all (lsquic_engine_t *engine)
void	lsquic_engine_process_conns_with_incoming (lsquic_engine_t *)
void	lsquic_engine_process_conns_to_tick (lsquic_engine_t *)
int	lsquic_engine_has_pend_rw (lsquic_engine_t *)
void	lsquic_engine_process_conns_with_pend_rw (lsquic_engine_t *)
int	lsquic_engine_has_unsent_packets (lsquic_engine_t *engine)
void	lsquic_engine_send_unsent_packets (lsquic_engine_t *engine)
void	lsquic_engine_destroy (lsquic_engine_t *)
void	lsquic_conn_make_stream (lsquic_conn_t *)
unsigned	lsquic_conn_n_pending_streams (const lsquic_conn_t *)
unsigned	lsquic_conn_cancel_pending_streams (lsquic_conn_t *, unsigned n)
void	lsquic_conn_going_away (lsquic_conn_t *conn)
void	lsquic_conn_close (lsquic_conn_t *conn)
int	lsquic_stream_wantread (lsquic_stream_t *s, int is_want)
ssize_t	lsquic_stream_read (lsquic_stream_t *s, void *buf, size_t len)
ssize_t	lsquic_stream_readv (lsquic_stream_t *s, const struct iovec *, int iovcnt)
int	lsquic_stream_wantwrite (lsquic_stream_t *s, int is_want)
ssize_t	lsquic_stream_write (lsquic_stream_t *s, const void *buf, size_t len)
ssize_t	lsquic_stream_writev (lsquic_stream_t *s, const struct iovec *vec, int count)
ssize_t	lsquic_stream_writef (lsquic_stream_t *, struct lsquic_reader *)
int	lsquic_stream_flush (lsquic_stream_t *s)
int	lsquic_stream_send_headers (lsquic_stream_t *s, const lsquic_http_headers_t *h, int eos)
int	lsquic_conn_is_push_enabled (lsquic_conn_t *c)
int	lsquic_stream_shutdown (lsquic_stream_t *s, int how)
int	lsquic_stream_close (lsquic_stream_t *s)
uint32_t	lsquic_stream_id (const lsquic_stream_t *s)
lsquic_stream_ctx_t *	lsquic_stream_get_ctx (const lsquic_stream_t *s)
int	lsquic_stream_is_pushed (const lsquic_stream_t *s)
int	lsquic_stream_refuse_push (lsquic_stream_t *s)
int	lsquic_stream_push_info (const lsquic_stream_t *, uint32_t *ref_stream_id, const char **headers, size_t *headers_sz)
unsigned	lsquic_stream_priority (const lsquic_stream_t *s)
int	lsquic_stream_set_priority (lsquic_stream_t *s, unsigned priority)
lsquic_conn_t *	lsquic_stream_conn (const lsquic_stream_t *s)
lsquic_stream_t *	lsquic_conn_get_stream_by_id (lsquic_conn_t *c, uint32_t stream_id)
lsquic_cid_t	lsquic_conn_id (const lsquic_conn_t *c)
int	lsquic_conn_get_sockaddr (const lsquic_conn_t *c, const struct sockaddr **local, const struct sockaddr **peer)
void	lsquic_logger_init (const struct lsquic_logger_if *, void *logger_ctx, enum lsquic_logger_timestamp_style)
int	lsquic_set_log_level (const char *log_level)
int	lsquic_logger_lopt (const char *optarg)
unsigned	lsquic_engine_quic_versions (const lsquic_engine_t *)
int	lsquic_global_init (int flags)
void	lsquic_global_cleanup (void)
enum lsquic_version	lsquic_conn_quic_version (const lsquic_conn_t *c)
enum lsquic_version	lsquic_str2ver (const char *str, size_t len)
lsquic_conn_ctx_t *	lsquic_conn_get_ctx (const lsquic_conn_t *c)
void *	lsquic_conn_get_peer_ctx (const lsquic_conn_t *lconn)
void	lsquic_conn_abort (lsquic_conn_t *c)
int	lsquic_engine_earliest_adv_tick (lsquic_engine_t *engine, int *diff)
unsigned	lsquic_engine_count_attq (lsquic_engine_t *engine, int from_now)

Detailed Description

public API for using liblsquic is defined in this file.

Macro Definition Documentation

#define LSENG_HTTP   (1 << 1)

Treat stream 3 as headers stream and, in general, behave like the regular QUIC.

#define LSENG_SERVER   (1 << 0)

Engine flags:Server mode

#define LSQUIC_DF_HANDSHAKE_TO   (10 * 1000 * 1000)

Default handshake timeout in microseconds.

#define LSQUIC_DF_HONOR_PRST   0

By default, LSQUIC ignores Public Reset packets.

#define LSQUIC_DF_MAX_HEADER_LIST_SIZE   0

Default value of maximum header list size. If set to non-zero value, SETTINGS_MAX_HEADER_LIST_SIZE will be sent to peer after handshake is completed (assuming the peer supports this setting frame type).

#define LSQUIC_DF_PACE_PACKETS   1

By default, packets are paced

#define LSQUIC_DF_PENDRW_CHECK   10

By default, Pending RW Queue infinite loop checks are turned on:

#define LSQUIC_DF_PROC_TIME_THRESH   0

By default, the threshold is not enabled

#define LSQUIC_DF_PROGRESS_CHECK   1000

By default, infinite loop checks are turned on

#define LSQUIC_DF_RW_ONCE   0

By default, read/write events are dispatched in a loop

#define LSQUIC_DF_SUPPORT_NSTP   0

Do not use NSTP by default

#define LSQUIC_DF_UA   "LSQUIC"

Default value of UAID (user-agent ID).

#define LSQUIC_DF_VERSIONS

Value:

(LSQUIC_SUPPORTED_VERSIONS & \
                                            ~LSQUIC_EXPERIMENTAL_VERSIONS)

By default, experimental versions are not included.

#define LSQUIC_GLOBAL_CLIENT   (1 << 0)

This is one of the flags that can be passed to lsquic_global_init. Use it to initialize LSQUIC for use in client mode.

#define LSQUIC_GLOBAL_SERVER   (1 << 1)

This is one of the flags that can be passed to lsquic_global_init. Use it to initialize LSQUIC for use in server mode.

#define LSQUIC_MIN_FCW   (16 * 1024)

Minimum flow control window is set to 16 KB for both client and server. This means we can send up to this amount of data before handshake gets completed.

#define LSQUIC_SUPPORTED_VERSIONS

Value:

((1 << LSQVER_035) | (1 << LSQVER_037) | \
                    (1 << LSQVER_038) | (1 << LSQVER_039) | (1 << LSQVER_041))

We currently support versions 35, 37, 38, 39, and 40.

See also

lsquic_version

Typedef Documentation

typedef int(* lsquic_packets_out_f) (void *packets_out_ctx, const struct lsquic_out_spec *out_spec, unsigned n_packets_out)

Returns number of packets successfully sent out or -1 on error. -1 should only be returned if no packets were sent out.

Enumeration Type Documentation

enum lsquic_logger_timestamp_style

Enumerate timestamp styles supported by LSQUIC logger mechanism.

Enumerator
LLTS_NONE	No timestamp is generated.
LLTS_HHMMSSMS	The timestamp consists of 24 hours, minutes, seconds, and milliseconds. Example: 13:43:46.671
LLTS_YYYYMMDD_HHMMSSMS	Like above, plus date, e.g: 2017-03-21 13:43:46.671
LLTS_CHROMELIKE	This is Chrome-like timestamp used by proto-quic. The timestamp includes month, date, hours, minutes, seconds, and microseconds. Example: 1223/104613.946956 (instead of 12/23 10:46:13.946956). This is to facilitate reading two logs side-by-side.
LLTS_HHMMSSUS	The timestamp consists of 24 hours, minutes, seconds, and microseconds. Example: 13:43:46.671123

enum lsquic_version

This is a list of QUIC versions that we know of. List of supported versions is in LSQUIC_SUPPORTED_VERSIONS.

Enumerator
LSQVER_035	Q035. This is the first version to be supported by LSQUIC.
LSQVER_037	Q037. This version is like Q035, except the way packet hashes are generated is different for clients and servers. In addition, new option NSTP (no STOP_WAITING frames) is rumored to be supported at some point in the future.
LSQVER_038	Q038. Based on Q037, supports PADDING frames in the middle of packet and NSTP (no STOP_WAITING frames) option.
LSQVER_039	Q039. Switch to big endian. Do not ack acks. Send connection level WINDOW_UPDATE frame every 20 sent packets which do not contain retransmittable frames.
LSQVER_041	Q041. RST_STREAM, ACK and STREAM frames match IETF format.

Function Documentation

void lsquic_conn_abort

(

lsquic_conn_t *

c

)

Abort connection.

unsigned lsquic_conn_cancel_pending_streams	(	lsquic_conn_t *	,
		unsigned	n
	)

Cancel `n' pending streams. Returns new number of pending streams.

void lsquic_conn_close

(

lsquic_conn_t *

conn

)

This forces connection close. on_conn_closed and on_close callbacks will be called.

lsquic_conn_ctx_t* lsquic_conn_get_ctx

(

const lsquic_conn_t *

c

)

Get user-supplied context associated with the connection.

void* lsquic_conn_get_peer_ctx

(

const lsquic_conn_t *

lconn

)

Get peer context associated with the connection. should be UdpListener *.

void lsquic_conn_going_away

(

lsquic_conn_t *

conn

)

Mark connection as going away: send GOAWAY frame and do not accept any more incoming streams, nor generate streams of our own.

lsquic_cid_t lsquic_conn_id

(

const lsquic_conn_t *

c

)

Get connection ID

unsigned lsquic_conn_n_pending_streams

(

const lsquic_conn_t *

)

Return number of delayed streams currently pending

enum lsquic_version lsquic_conn_quic_version

(

const lsquic_conn_t *

c

)

Get QUIC version used by the connection.

See also

lsquic_version

int lsquic_engine_check_settings	(	const struct lsquic_engine_settings *	settings,
		unsigned	lsquic_engine_flags,
		char *	err_buf,
		size_t	err_buf_sz
	)

Check settings for errors.

Parameters

settings	Settings struct.
flags	Engine flags.
err_buf	Optional pointer to buffer into which error string is written.
err_buf_sz	Size of err_buf. No more than this number of bytes will be written to err_buf, including the NUL byte.

Return values

0	Settings have no errors.
-1	There are errors in settings.

int lsquic_engine_connect	(	lsquic_engine_t *	,
		const struct sockaddr *	peer_sa,
		void *	peer_ctx,
		const char *	hostname,
		unsigned short	max_packet_size
	)

Create a client connection to peer identified by `peer_ctx'. If `max_packet_size' is set to zero, it is inferred based on `peer_sa': 1350 for IPv6 and 1370 for IPv4.

unsigned lsquic_engine_count_attq	(	lsquic_engine_t *	engine,
		int	from_now
	)

Return number of connections whose advisory tick time is before $now plus `from_now' delta. `from_now' can be negative.

int lsquic_engine_earliest_adv_tick	(	lsquic_engine_t *	engine,
		int *	diff
	)

Returns true if there is a connection on the Advisory Tick Time queue, false otherwise. If true, `diff' is set to the difference between the earliest advisory tick time and now. If the former is in the past, the value of `diff' is negative.

int lsquic_engine_has_pend_rw

(

lsquic_engine_t *

)

Returns true if engine has connections that have pending read or write events.

Connections with pending read or write events are those that have at least one stream whose state changed outside of the regular callback mechanism. The simplest example is writing directly to the stream object when data comes in.

A call to lsquic_engine_proc_all, lsquic_engine_process_conns_with_incoming, lsquic_engine_process_conns_to_tick, or lsquic_engine_process_conns_with_pend_rw removes processed connection from Pending RW queue.

int lsquic_engine_has_unsent_packets

(

lsquic_engine_t *

engine

)

Returns true if engine has some unsent packets. This happens if ea_packets_out() could not send everything out.

lsquic_engine_t* lsquic_engine_new	(	unsigned	lsquic_engine_flags,
		const struct lsquic_engine_api *
	)

Create new engine.

Parameters

lsquic_engine_flags

A bitmask of LSENG_SERVER and LSENG_HTTP

int lsquic_engine_packet_in	(	lsquic_engine_t *	,
		const unsigned char *	packet_in_data,
		size_t	packet_in_size,
		const struct sockaddr *	sa_local,
		const struct sockaddr *	sa_peer,
		void *	peer_ctx
	)

Pass incoming packet to the QUIC engine. This function can be called more than once in a row. After you add one or more packets, call lsquic_engine_process_conns_with_incoming() to schedule output, if any.

Return values

0	Packet was processed by a real connection.
-1	Some error occurred. Possible reasons are invalid packet size or failure to allocate memory.

void lsquic_engine_proc_all

(

lsquic_engine_t *

engine

)

Process all connections. This function must be called often enough so that packets and connections do not expire.

void lsquic_engine_process_conns_to_tick

(

lsquic_engine_t *

)

Process connections in Advisory Tick Time queue whose tick times are in the past.

void lsquic_engine_process_conns_with_incoming

(

lsquic_engine_t *

)

Process connections that have incoming packets. Call this after adding one or more incoming packets using lsquic_engine_packet_in().

void lsquic_engine_process_conns_with_pend_rw

(

lsquic_engine_t *

)

Process connections that have pending read or write events (

See also

lsquic_engine_has_pend_rw for description).

unsigned lsquic_engine_quic_versions

(

const lsquic_engine_t *

)

Return the list of QUIC versions (as bitmask) this engine instance supports.

void lsquic_engine_send_unsent_packets

(

lsquic_engine_t *

engine

)

Send out as many unsent packets as possibe: until we are out of unsent packets or until ea_packets_out() fails.

void lsquic_global_cleanup

(

void

)

Clean up global state created by lsquic_global_init. Should be called after all LSQUIC engine instances are gone.

int lsquic_global_init

(

int

flags

)

Initialize LSQUIC. This must be called before any other LSQUIC function is called. Returns 0 on success and -1 on failure.

Parameters

flags

This a bitmask of LSQUIC_GLOBAL_CLIENT and LSQUIC_GLOBAL_SERVER. At least one of these flags should be specified.

Return values

0	Success.
-1	Initialization failed.

See also

LSQUIC_GLOBAL_CLIENT

LSQUIC_GLOBAL_SERVER

void lsquic_logger_init	(	const struct lsquic_logger_if *	,
		void *	logger_ctx,
		enum	lsquic_logger_timestamp_style
	)

Call this if you want to do something with LSQUIC log messages, as they are thrown out by default.

int lsquic_logger_lopt

(

const char *

optarg

)

E.g. "event=debug"

int lsquic_set_log_level

(

const char *

log_level

)

Set log level for all LSQUIC modules. Acceptable values are debug, info, notice, warning, error, alert, emerg, crit (case-insensitive).

Return values

0	Success.
-1	Failure: log_level is not valid.

enum lsquic_version lsquic_str2ver	(	const char *	str,
		size_t	len
	)

Translate string QUIC version to LSQUIC QUIC version representation

lsquic_conn_t* lsquic_stream_conn

(

const lsquic_stream_t *

s

)

Get a pointer to the connection object. Use it with lsquic_conn_* functions.

int lsquic_stream_flush

(

lsquic_stream_t *

s

)

Flush any buffered data. This triggers packetizing even a single byte into a separate frame. Flushing a closed stream is an error.

Return values

0	Success
-1	Failure

lsquic_stream_ctx_t* lsquic_stream_get_ctx

(

const lsquic_stream_t *

s

)

Returns stream ctx associated with the stream. (The context is what is returned by on_new_stream callback).

uint32_t lsquic_stream_id

(

const lsquic_stream_t *

s

)

Returns ID of the stream

int lsquic_stream_is_pushed

(

const lsquic_stream_t *

s

)

Returns true if this is a pushed stream

unsigned lsquic_stream_priority

(

const lsquic_stream_t *

s

)

Return current priority of the stream

int lsquic_stream_push_info	(	const lsquic_stream_t *	,
		uint32_t *	ref_stream_id,
		const char **	headers,
		size_t *	headers_sz
	)

Get information associated with pushed stream:

Parameters

ref_stream_id	Stream ID in response to which push promise was sent.
headers	Uncompressed request headers.
headers_sz	Size of uncompressed request headers, not counting the NUL byte.

Return values

0	Success.
-1	This is not a pushed stream.

int lsquic_stream_refuse_push

(

lsquic_stream_t *

s

)

Refuse pushed stream. Call it from on_new_stream.

No need to call lsquic_stream_close() after this. on_close will be called.

See also

lsquic_stream_is_pushed

int lsquic_stream_set_priority	(	lsquic_stream_t *	s,
		unsigned	priority
	)

Set stream priority. Valid priority values are 1 through 256, inclusive.

Return values

0	Success.
-1	Priority value is invalid.

int lsquic_stream_shutdown	(	lsquic_stream_t *	s,
		int	how
	)

Possible values for how are 0, 1, and 2. See shutdown(2).

ssize_t lsquic_stream_write	(	lsquic_stream_t *	s,
		const void *	buf,
		size_t	len
	)

Write `len' bytes to the stream. Returns number of bytes written, which may be smaller that `len'.

ssize_t lsquic_stream_writef	(	lsquic_stream_t *	,
		struct lsquic_reader *
	)

Write to stream using lsquic_reader. This is the most generic of the write functions – lsquic_stream_write() and lsquic_stream_writev() utilize the same mechanism.

Return values

Number

of bytes written or -1 on error.