roq.h File Reference

imquic RoQ public interface (headers) More...

#include "imquic.h"

Include dependency graph for roq.h:

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

Go to the source code of this file.

Typedefs
typedef enum imquic_roq_multiplexing	imquic_roq_multiplexing
	RTP Over QUIC multiplexing modes.

Enumerations
enum	imquic_roq_multiplexing { IMQUIC_ROQ_DATAGRAM , IMQUIC_ROQ_STREAM }
	RTP Over QUIC multiplexing modes. More...

Functions
const char *	imquic_roq_multiplexing_str (imquic_roq_multiplexing type)
	Helper function to serialize to string the name of a imquic_roq_multiplexing property.
RoQ endpoints management
imquic_server *	imquic_create_roq_server (const char *name,...)
	Method to create a new RoQ server, using variable arguments to dictate what the server should do (e.g., port to bind to, ALPN, etc.). Variable arguments are in the form of a sequence of name-value started with a IMQUIC_CONFIG_INIT and ended by a IMQUIC_CONFIG_DONE , e.g.:
imquic_client *	imquic_create_roq_client (const char *name,...)
	Method to create a new RoQ client, using variable arguments to dictate what the client should do (e.g., address to connect to, ALPN, etc.). Variable arguments are in the form of a sequence of name-value started with a IMQUIC_CONFIG_INIT and ended by a IMQUIC_CONFIG_DONE , e.g.:
void	imquic_set_new_roq_connection_cb (imquic_endpoint *endpoint, void(*new_roq_connection)(imquic_connection *conn, void *user_data))
	Configure the callback function to be notified about new RoQ connections on the configured endpoint. For a server, it will be triggered any time a client successfully connects to the server; for a client, it will be triggered when the client successfully connects to the server.
void	imquic_set_rtp_incoming_cb (imquic_endpoint *endpoint, void(*rtp_incoming)(imquic_connection *conn, uint64_t flow_id, uint8_t *bytes, size_t blen))
	Configure the callback function to be notified about incoming RTP packets, independently of the multiplexing mode. The callback function will only include the relevant data, that is the RoQ flow ID and a buffer containing the RTP packet itself.
void	imquic_set_roq_connection_gone_cb (imquic_endpoint *endpoint, void(*roq_connection_gone)(imquic_connection *conn))
	Configure the callback function to be notified when an existing RoQ connection handled by this endpoint has been closed/shut down.
Using the RoQ API
size_t	imquic_roq_send_rtp (imquic_connection *conn, imquic_roq_multiplexing multiplexing, uint64_t flow_id, uint8_t *bytes, size_t blen, gboolean close_stream)
	Helper to send RTP packets over QUIC, using one of the supported imquic_roq_multiplexing modes. The method only requires the flow ID (to allow the recipient to identify the RTP session) and the RTP packet to send (buffer and size). The stack will then internally frame the packet as needed, using the right multiplexing mode and optionally creating a new STREAM for the purpose.

Detailed Description

imquic RoQ public interface (headers)

Author

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

Copyright

MIT License

Public interface to the RTP Over QUIC (RoQ) native support in the imquic library. This is where public functions are callbacks to interact with the RoQ features of the library are defined.

Typedef Documentation

imquic_roq_multiplexing

typedef enum imquic_roq_multiplexing imquic_roq_multiplexing

RTP Over QUIC multiplexing modes.

Enumeration Type Documentation

imquic_roq_multiplexing

enum imquic_roq_multiplexing

RTP Over QUIC multiplexing modes.

Enumerator
IMQUIC_ROQ_DATAGRAM	RTP packet over DATAGRAM.
IMQUIC_ROQ_STREAM	One or more RTP packets over a STREAM.

Function Documentation

imquic_create_roq_client()

imquic_client * imquic_create_roq_client	(	const char *	name,
			... )

Method to create a new RoQ client, using variable arguments to dictate what the client should do (e.g., address to connect to, ALPN, etc.). Variable arguments are in the form of a sequence of name-value started with a IMQUIC_CONFIG_INIT and ended by a IMQUIC_CONFIG_DONE , e.g.:

       imquic_client *client = imquic_create_roq_client("roq-client",
        IMQUIC_CONFIG_INIT,
        IMQUIC_CONFIG_TLS_CERT, cert_pem,
        IMQUIC_CONFIG_TLS_KEY, cert_key,
        IMQUIC_CONFIG_TLS_PASSWORD, cert_pwd,
        IMQUIC_CONFIG_REMOTE_HOST, "127.0.0.1",
        IMQUIC_CONFIG_REMOTE_PORT, 9000,
        IMQUIC_CONFIG_DONE, NULL);

to create a QUIC client that will automatically negotiate RoQ. Again, as with imquic_create_client, this will only create the resource, but not actually start the connection: before doing that, you'll need to configure the callbacks for the events you're interested in (in this case, RoQ specific), and then use imquic_start_endpoint to start the start the QUIC client (which will attempt a connection).

Note

This will create a full, internal, RoQ stack on top of imquic, meaning that the RoQ protocol will be handled natively by imquic for you, providing a high level interface to the features of the protocol itself. If you want to only use imquic as a QUIC/WebTrasport protocol, and implement RoQ yourself, then you'll need to use imquic_create_server or imquic_create_client instead.

Parameters

[in]

name

The endpoint name (if NULL, a default value will be set)

Returns

A pointer to a imquic_client object, if successful, NULL otherwise

imquic_create_roq_server()

imquic_server * imquic_create_roq_server	(	const char *	name,
			... )

Method to create a new RoQ server, using variable arguments to dictate what the server should do (e.g., port to bind to, ALPN, etc.). Variable arguments are in the form of a sequence of name-value started with a IMQUIC_CONFIG_INIT and ended by a IMQUIC_CONFIG_DONE , e.g.:

       imquic_server *server = imquic_create_roq_server("roq-server",
        IMQUIC_CONFIG_INIT,
        IMQUIC_CONFIG_TLS_CERT, cert_pem,
        IMQUIC_CONFIG_TLS_KEY, cert_key,
        IMQUIC_CONFIG_TLS_PASSWORD, cert_pwd,
        IMQUIC_CONFIG_LOCAL_PORT, 9000,
        IMQUIC_CONFIG_DONE, NULL);

to create a QUIC server that will automatically negotiate RoQ. Again, as with imquic_create_server, this will only create the resource, but not actually start the server: before doing that, you'll need to configure the callbacks for the events you're interested in (in this case, RoQ specific), and then use imquic_start_endpoint to start the QUIC server (which will wait for incoming connections).

Note

This will create a full, internal, RoQ stack on top of imquic, meaning that the RoQ protocol will be handled natively by imquic for you, providing a high level interface to the features of the protocol itself. If you want to only use imquic as a QUIC/WebTrasport protocol, and implement RoQ yourself, then you'll need to use imquic_create_server or imquic_create_client instead.

Parameters

[in]

name

The endpoint name (if NULL, a default value will be set)

Returns

A pointer to a imquic_server object, if successful, NULL otherwise

imquic_roq_multiplexing_str()

const char * imquic_roq_multiplexing_str

(

imquic_roq_multiplexing

type

)

Helper function to serialize to string the name of a imquic_roq_multiplexing property.

Parameters

type	The imquic_roq_multiplexing property

Returns

The type name as a string, if valid, or NULL otherwise

imquic_roq_send_rtp()

size_t imquic_roq_send_rtp	(	imquic_connection *	conn,
		imquic_roq_multiplexing	multiplexing,
		uint64_t	flow_id,
		uint8_t *	bytes,
		size_t	blen,
		gboolean	close_stream )

Helper to send RTP packets over QUIC, using one of the supported imquic_roq_multiplexing modes. The method only requires the flow ID (to allow the recipient to identify the RTP session) and the RTP packet to send (buffer and size). The stack will then internally frame the packet as needed, using the right multiplexing mode and optionally creating a new STREAM for the purpose.

Parameters

[in]	conn	The RoQ connection to send the RTP packet on
[in]	multiplexing	The imquic_roq_multiplexing mode to use for sending this packet
[in]	flow_id	The RoQ flow ID
[in]	bytes	The buffer containing the RTP packet
[in]	blen	The size of the buffer to send
[in]	close_stream	Whether the STREAM should be closed after sending this packet (ignored when using DATAGRAM as a multiplexing mode)

Returns

The size of the RoQ message being sent, if successful, or 0 otherwise

imquic_set_new_roq_connection_cb()

void imquic_set_new_roq_connection_cb	(	imquic_endpoint *	endpoint,
		void(*)(imquic_connection *conn, void *user_data)	new_roq_connection )

Configure the callback function to be notified about new RoQ connections on the configured endpoint. For a server, it will be triggered any time a client successfully connects to the server; for a client, it will be triggered when the client successfully connects to the server.

Note

This is a good place to obtain the first reference to a connection.

Parameters

endpoint	The imquic_endpoint (imquic_server or imquic_client) to configure
new_roq_connection	Pointer to the function that will be invoked on the new RoQ connection

imquic_set_roq_connection_gone_cb()

void imquic_set_roq_connection_gone_cb	(	imquic_endpoint *	endpoint,
		void(*)(imquic_connection *conn)	roq_connection_gone )

Configure the callback function to be notified when an existing RoQ connection handled by this endpoint has been closed/shut down.

Note

This is a good place to release the last reference to the connection

Parameters

endpoint	The imquic_endpoint (imquic_server or imquic_client) to configure
roq_connection_gone	Pointer to the function that will be invoked when a RoQ connection is gone

imquic_set_rtp_incoming_cb()

void imquic_set_rtp_incoming_cb	(	imquic_endpoint *	endpoint,
		void(*)(imquic_connection *conn, uint64_t flow_id, uint8_t *bytes, size_t blen)	rtp_incoming )

Configure the callback function to be notified about incoming RTP packets, independently of the multiplexing mode. The callback function will only include the relevant data, that is the RoQ flow ID and a buffer containing the RTP packet itself.

Parameters

endpoint	The imquic_endpoint (imquic_server or imquic_client) to configure
rtp_incoming	Pointer to the function that will be invoked when there's a new incoming RTP packet