connection.h File Reference

QUIC connection abstraction (headers) More...

#include <stdint.h>
#include <glib.h>
#include <picoquic_utils.h>
#include "stream.h"
#include "buffer.h"
#include "network.h"
#include "http3.h"
#include "error.h"
#include "qlog.h"
#include "utils.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
	QUIC Connection. More...
struct	imquic_connection_event
	QUIC event. More...

Functions
const char *	imquic_connection_id_str (picoquic_connection_id_t *cid, char *buffer, size_t blen)
	Helper method to stringify a connection ID.
imquic_connection *	imquic_connection_create (imquic_network_endpoint *socket, picoquic_cnx_t *piconn)
	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.
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 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 length)
	Helper to notify incoming STREAM data to the application.
void	imquic_connection_notify_gone (imquic_connection *conn)
	Helper to notify about the connection being gone.
void	imquic_connection_reset_stream (imquic_connection *conn, uint64_t stream_id, uint64_t error_code)
	Helper to reset a stream, sending a RESET_STREAM.
void	imquic_connection_close (imquic_connection *conn, uint64_t error_code, const char *reason)
	Helpers to close connections.

Connection events
enum	imquic_connection_event_type {   IMQUIC_CONNECTION_EVENT_UNKNOWN = 0 , IMQUIC_CONNECTION_EVENT_STREAM , IMQUIC_CONNECTION_EVENT_DATAGRAM , IMQUIC_CONNECTION_EVENT_RESET_STREAM ,   IMQUIC_CONNECTION_EVENT_CLOSE_CONN }
	QUIC event. More...
typedef enum imquic_connection_event_type	imquic_connection_event_type
	QUIC event.
typedef struct imquic_connection_event	imquic_connection_event
	QUIC event.
imquic_connection_event *	imquic_connection_event_create (imquic_connection_event_type type)
	Helper method to create a imquic_connection_event instance.
void	imquic_connection_event_destroy (imquic_connection_event *event)
	Helper method to destroy a imquic_connection_event instance.

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_event

typedef struct imquic_connection_event imquic_connection_event

QUIC event.

imquic_connection_event_type

typedef enum imquic_connection_event_type imquic_connection_event_type

QUIC event.

Enumeration Type Documentation

imquic_connection_event_type

enum imquic_connection_event_type

QUIC event.

Enumerator
IMQUIC_CONNECTION_EVENT_UNKNOWN
IMQUIC_CONNECTION_EVENT_STREAM
IMQUIC_CONNECTION_EVENT_DATAGRAM
IMQUIC_CONNECTION_EVENT_RESET_STREAM
IMQUIC_CONNECTION_EVENT_CLOSE_CONN

Function Documentation

imquic_connection_close()

void imquic_connection_close	(	imquic_connection *	conn,
		uint64_t	error_code,
		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
reason	A verbose description of the error, if any

imquic_connection_create()

imquic_connection * imquic_connection_create	(	imquic_network_endpoint *	socket,
		picoquic_cnx_t *	piconn )

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
piconn	The picoquic connection this connection will be associated to (only for servers)

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_event_create()

imquic_connection_event * imquic_connection_event_create

(

imquic_connection_event_type

type

)

Helper method to create a imquic_connection_event instance.

Parameters

type	The imquic_connection_event_type of the event

Returns

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

imquic_connection_event_destroy()

void imquic_connection_event_destroy

(

imquic_connection_event *

event

)

Helper method to destroy a imquic_connection_event instance.

Parameters

event

The imquic_connection_event instance to destroy

imquic_connection_id_str()

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

Helper method to stringify a connection ID.

Parameters

[in]	cid	The connection ID 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_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_gone()

void imquic_connection_notify_gone

(

imquic_connection *

conn

)

Helper to notify about the connection being gone.

Parameters

conn	The imquic_connection instance to notify the event for

imquic_connection_notify_stream_incoming()

void imquic_connection_notify_stream_incoming	(	imquic_connection *	conn,
		imquic_stream *	stream,
		uint8_t *	data,
		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
length	Size of the new data buffer

imquic_connection_reset_stream()

void imquic_connection_reset_stream	(	imquic_connection *	conn,
		uint64_t	stream_id,
		uint64_t	error_code )

Helper to reset a stream, sending a RESET_STREAM.

Parameters

conn	The imquic_connection instance that owns the stream to reset
stream_id	ID of the stream to reset
error_code	The error code to add to the frame

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	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]	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