connection.h File Reference

QUIC connection abstraction (headers) More...

#include <stdint.h>
#include <glib.h>
#include "stream.h"
#include "buffer.h"
#include "crypto.h"
#include "network.h"
#include "http3.h"
#include "error.h"
#include "utils.h"
#include "listmap.h"
#include "refcount.h"

Include dependency graph for connection.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	imquic_connection_id
	QUIC Connection ID. More...
struct	imquic_connection_parameters
	QUIC Transport parameters. More...
struct	imquic_connection_rtt
	Round Trip Time (RTT) tracking. More...
struct	imquic_connection
	QUIC Connection. More...

Typedefs
typedef struct imquic_connection_id	imquic_connection_id
	QUIC Connection ID.
typedef struct imquic_connection_parameters	imquic_connection_parameters
	QUIC Transport parameters.
typedef struct imquic_connection_rtt	imquic_connection_rtt
	Round Trip Time (RTT) tracking.

Functions
const char *	imquic_connection_id_str (imquic_connection_id *cid, char *buffer, size_t blen)
	Helper method to stringify a imquic_connection_id instance.
imquic_connection_id *	imquic_connection_id_dup (imquic_connection_id *cid)
	Helper method to duplicate (copy) a imquic_connection_id instance.
gboolean	imquic_connection_id_equal (const void *a, const void *b)
	Helper method to check if two imquic_connection_id instances are actually the same Connection ID.
guint	imquic_connection_id_hash (gconstpointer v)
	Helper method to return a hash associated to a imquic_connection_id instance.
void	imquic_connection_parameters_init (imquic_connection_parameters *params)
	Helper method to reset/initialize a imquic_connection_parameters instance.
imquic_connection *	imquic_connection_create (imquic_network_endpoint *socket)
	Helper method to create a new imquic_connection instance owned by a specific imquic_network_endpoint in the QUIC stack.
void	imquic_connection_destroy (imquic_connection *conn)
	Helper method to destroy an existing imquic_connection instance.
Loss detection and retransmissions
void	imquic_connection_change_level (imquic_connection *conn, enum ssl_encryption_level_t level)
	Helper to change the current encryption level of a connection.
void	imquic_connection_update_rtt (imquic_connection *conn, int64_t sent_time, uint16_t ack_delay)
	Helper method to update the RTT of a connection, when parsing ACKs.
GList *	imquic_connection_detect_lost (imquic_connection *conn)
	Helper method to detect lost packets.
void	imquic_connection_update_loss_timer (imquic_connection *conn)
	Helper method to update the loss detection timer.
gboolean	imquic_connection_loss_detection_timeout (gpointer user_data)
	Callback invoked when the loss detection timer fires.
Interacting with connections
int	imquic_connection_new_stream_id (imquic_connection *conn, gboolean bidirectional, uint64_t *stream_id)
	Helper to generate a new stream ID for this connection.
int	imquic_connection_send_on_datagram (imquic_connection *conn, uint8_t *bytes, uint64_t length)
	Helper method to send data on a QUIC DATAGRAM.
int	imquic_connection_send_on_stream (imquic_connection *conn, uint64_t stream_id, uint8_t *bytes, uint64_t offset, uint64_t length, gboolean complete)
	Helper method to send data on a QUIC STREAM.
void	imquic_connection_notify_datagram_incoming (imquic_connection *conn, uint8_t *data, uint64_t length)
	Helper to notify incoming DATAGRAM data to the application.
void	imquic_connection_notify_stream_incoming (imquic_connection *conn, imquic_stream *stream, uint8_t *data, uint64_t offset, uint64_t length)
	Helper to notify incoming STREAM data to the application.
void	imquic_connection_flush_stream (imquic_connection *conn, uint64_t stream_id)
	Helper to flush a stream, in order to send data right away.
void	imquic_connection_close (imquic_connection *conn, uint64_t error_code, uint64_t frame_type, const char *reason)
	Helpers to close connections.

Detailed Description

QUIC connection abstraction (headers)

Author

Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

Copyright

MIT License

Abstraction of QUIC connections, during or after establishment. This is where helper functions are exposed to the QUIC stack internals for the purpose of creating STREAM ids, send data, and notify upper layers about incoming data or shutdowns.

Typedef Documentation

imquic_connection_id

typedef struct imquic_connection_id imquic_connection_id

QUIC Connection ID.

imquic_connection_parameters

typedef struct imquic_connection_parameters imquic_connection_parameters

QUIC Transport parameters.

imquic_connection_rtt

typedef struct imquic_connection_rtt imquic_connection_rtt

Round Trip Time (RTT) tracking.

Function Documentation

imquic_connection_change_level()

void imquic_connection_change_level	(	imquic_connection *	conn,
		enum ssl_encryption_level_t	level )

Helper to change the current encryption level of a connection.

Note

This may result in resetting the loss detection state for the previous level

Parameters

conn	The imquic_connection instance to update
level	The new SSL encryption level

imquic_connection_close()

void imquic_connection_close	(	imquic_connection *	conn,
		uint64_t	error_code,
		uint64_t	frame_type,
		const char *	reason )

Helpers to close connections.

Parameters

conn	The imquic_connection instance to close
error_code	The error code to send back in the CONNECTION_CLOSE frame
frame_type	The frame type that caused this connection to be closed
reason	A verbose description of the error, if any

imquic_connection_create()

imquic_connection * imquic_connection_create

(

imquic_network_endpoint *

socket

)

Helper method to create a new imquic_connection instance owned by a specific imquic_network_endpoint in the QUIC stack.

Parameters

socket

The network endpoint this connection will be associated to

Returns

A pointer to a new imquic_connection instance, if successful, or NULL otherwise

imquic_connection_destroy()

void imquic_connection_destroy

(

imquic_connection *

conn

)

Helper method to destroy an existing imquic_connection instance.

Parameters

conn	The imquic_connection instance to destroy

imquic_connection_detect_lost()

GList * imquic_connection_detect_lost

(

imquic_connection *

conn

)

Helper method to detect lost packets.

Parameters

conn	The imquic_connection instance to refer to

Returns

A linked list of imquic_sent_packet packets, or NULL if there are none

imquic_connection_flush_stream()

void imquic_connection_flush_stream	(	imquic_connection *	conn,
		uint64_t	stream_id )

Helper to flush a stream, in order to send data right away.

Parameters

conn	The imquic_connection instance that owns the stream to flush
stream_id	ID of the stream to flush

imquic_connection_id_dup()

imquic_connection_id * imquic_connection_id_dup

(

imquic_connection_id *

cid

)

Helper method to duplicate (copy) a imquic_connection_id instance.

Parameters

cid	The imquic_connection_id instance to duplicate

Returns

A pointer to a new imquic_connection_id instance with the same data as the original, if successful, or NULL otherwise

imquic_connection_id_equal()

gboolean imquic_connection_id_equal	(	const void *	a,
		const void *	b )

Helper method to check if two imquic_connection_id instances are actually the same Connection ID.

Note

Helpful for using a imquic_connection_id instance as a key in hashtables.

Parameters

a	The Opaque pointer to the first imquic_connection_id instance to compare
b	The Opaque pointer to the first imquic_connection_id instance to compare

Returns

TRUE if the two IDs contain the same data, FALSE otherwise

imquic_connection_id_hash()

guint imquic_connection_id_hash

(

gconstpointer

v

)

Helper method to return a hash associated to a imquic_connection_id instance.

Note

Helpful for using a imquic_connection_id instance as a key in hashtables.

Parameters

v	The Opaque pointer to the imquic_connection_id instance to hash

Returns

The hash computed from the ID

imquic_connection_id_str()

const char * imquic_connection_id_str	(	imquic_connection_id *	cid,
		char *	buffer,
		size_t	blen )

Helper method to stringify a imquic_connection_id instance.

Parameters

[in]	cid	The imquic_connection_id instance to stringify
[out]	buffer	The buffer where the string will be written
[in]	blen	Size of the string output buffer

Returns

A pointer to buffer, if successful, or NULL otherwise

imquic_connection_loss_detection_timeout()

gboolean imquic_connection_loss_detection_timeout

(

gpointer

user_data

)

Callback invoked when the loss detection timer fires.

Note

This is never invoked manually: only by the ld_timer timer

Parameters

user_data

Opaque pointer to the connection the timer refers to

Returns

Always FALSE, since the next timer is always recreated from scratch

imquic_connection_new_stream_id()

int imquic_connection_new_stream_id	(	imquic_connection *	conn,
		gboolean	bidirectional,
		uint64_t *	stream_id )

Helper to generate a new stream ID for this connection.

Parameters

[in]	conn	The imquic_connection instance to get a new stream ID from
[in]	bidirectional	Whether the new stream will be bidirectional
[out]	stream_id	Pointer to where the new stream ID will be placed

Returns

0 in case of success, a negative integer otherwise

imquic_connection_notify_datagram_incoming()

void imquic_connection_notify_datagram_incoming	(	imquic_connection *	conn,
		uint8_t *	data,
		uint64_t	length )

Helper to notify incoming DATAGRAM data to the application.

Parameters

conn	The imquic_connection instance to notify the event for
data	Buffer containing the new data
length	Size of the new data buffer

imquic_connection_notify_stream_incoming()

void imquic_connection_notify_stream_incoming	(	imquic_connection *	conn,
		imquic_stream *	stream,
		uint8_t *	data,
		uint64_t	offset,
		uint64_t	length )

Helper to notify incoming STREAM data to the application.

Parameters

conn	The imquic_connection instance to notify the event for
stream	The imquic_stream that originated the new data to notify about
data	Buffer containing the new data
offset	Offset in the overall STREAM this data is positioned at
length	Size of the new data buffer

imquic_connection_parameters_init()

void imquic_connection_parameters_init

(

imquic_connection_parameters *

params

)

Helper method to reset/initialize a imquic_connection_parameters instance.

Note

This will set all properties to a default value, as per RFC 9000.

Parameters

params

The imquic_connection_parameters instance to initialize

imquic_connection_send_on_datagram()

int imquic_connection_send_on_datagram	(	imquic_connection *	conn,
		uint8_t *	bytes,
		uint64_t	length )

Helper method to send data on a QUIC DATAGRAM.

Note

Datagrams support must have been negotiated on the connection. Notice that this method will queue the data for delivery, but not send it right away. The event loop will take care of that internally.

Parameters

[in]	conn	The imquic_connection to send data on
[in]	bytes	Buffer containing the data to send
[in]	length	Size of the buffer of data

Returns

0 if successful, a negative integer otherwise

imquic_connection_send_on_stream()

int imquic_connection_send_on_stream	(	imquic_connection *	conn,
		uint64_t	stream_id,
		uint8_t *	bytes,
		uint64_t	offset,
		uint64_t	length,
		gboolean	complete )

Helper method to send data on a QUIC STREAM.

Note

The stream ID must already be known by the stack, either because created by the peer, or previously created via imquic_connection_new_stream_id. Notice that this method will queue the data for delivery, but not send it right away. The event loop will take care of that internally.

Parameters

[in]	conn	The imquic_connection to send data on
[in]	stream_id	The QUIC stream to use for sending data
[in]	bytes	Buffer containing the data to send
[in]	offset	Offset value to put in the outgoing STREAM fragment
[in]	length	Size of the buffer of data
[in]	complete	Whether this (offset+length) is the end of the STREAM data

Returns

0 if successful, a negative integer otherwise

imquic_connection_update_loss_timer()

void imquic_connection_update_loss_timer

(

imquic_connection *

conn

)

Helper method to update the loss detection timer.

Parameters

conn	The imquic_connection instance to update

imquic_connection_update_rtt()

void imquic_connection_update_rtt	(	imquic_connection *	conn,
		int64_t	sent_time,
		uint16_t	ack_delay )

Helper method to update the RTT of a connection, when parsing ACKs.

Parameters

conn	The imquic_connection instance to update
sent_time	Monotonic time of when the largest acked packet was sent
ack_delay	ACK delay value in the ACK frame