imquic-roq.c File Reference

imquic RoQ public interface More...

#include "imquic/roq.h"
#include "internal/configuration.h"
#include "internal/connection.h"
#include "internal/roq.h"

Include dependency graph for imquic-roq.c:

Macros
#define	IMQUIC_ROQ_ALPN   "roq-10"

Functions
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.
const char *	imquic_roq_multiplexing_str (imquic_roq_multiplexing multiplexing)
	Helper function to serialize to string the name of a imquic_roq_multiplexing property.

Detailed Description

imquic RoQ public interface

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.

Macro Definition Documentation

IMQUIC_ROQ_ALPN

#define IMQUIC_ROQ_ALPN   "roq-10"

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