imquic public interface More...
#include "imquic/imquic.h"#include "internal/configuration.h"#include "internal/quic.h"#include "internal/loop.h"#include "internal/crypto.h"#include "internal/buffer.h"#include "internal/qlog.h"#include "internal/utils.h"#include "internal/listmap.h"#include "internal/version.h"#include "internal/http3.h"#include "internal/moq.h"#include "internal/roq.h"
Functions | |
| int | imquic_init (const char *secrets_log) | 
| Initialize the imquic library.   | |
| gboolean | imquic_is_inited (void) | 
| Check if the imquic library has already been initialized.   | |
| void | imquic_deinit (void) | 
| Uninitialize the imquic library.   | |
| uint32_t | imquic_get_version (void) | 
| Get the current version of the library as a number.   | |
| int | imquic_get_version_major (void) | 
| Get the current major version of the library as a number.   | |
| int | imquic_get_version_minor (void) | 
| Get the current minor version of the library as a number.   | |
| int | imquic_get_version_patch (void) | 
| Get the current patch version of the library as a number.   | |
| const char * | imquic_get_version_release (void) | 
| Get the current release type of the library as a string.   | |
| const char * | imquic_get_version_string (void) | 
| Get the current version of the library as a string.   | |
| const char * | imquic_get_version_string_full (void) | 
| Get the current version of the library, including release type, as a string.   | |
| const char * | imquic_get_build_time (void) | 
| Get info on when this shared object was built.   | |
| const char * | imquic_get_build_sha (void) | 
| Get info on the git commit was compiled in this build.   | |
| void | imquic_set_log_level (int level) | 
| Set the log level for the library.   | |
| gboolean | imquic_is_qlog_supported (void) | 
| Check if QLOG is supported at runtime.   | |
| void | imquic_set_lock_debugging (gboolean enabled) | 
| Enable or disable lock/mutex debugging.   | |
| void | imquic_set_refcount_debugging (gboolean enabled) | 
| Enable or disable debugging of reference counters.   | |
| const char * | imquic_config_str (imquic_config type) | 
| Helper function to serialize to string the name of a imquic_config property.   | |
| imquic_server * | imquic_create_server (const char *name,...) | 
Method to create a new QUIC 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_client (const char *name,...) | 
Method to create a new QUIC 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.:   | |
| const char * | imquic_get_endpoint_name (imquic_endpoint *endpoint) | 
| Helper function to get the endpoint name of a local client or server.   | |
| gboolean | imquic_is_endpoint_server (imquic_endpoint *endpoint) | 
| Helper function to check whether a local endpoint is a server.   | |
| const char * | imquic_get_endpoint_alpn (imquic_endpoint *endpoint) | 
| Helper function to get the ALPN a local client or server is configured to negotiate.   | |
| const char * | imquic_get_endpoint_subprotocol (imquic_endpoint *endpoint) | 
| Helper function to get the WebTransport protocol a local client or server is configured to negotiate.   | |
| uint16_t | imquic_get_endpoint_port (imquic_endpoint *endpoint) | 
| Helper function to get the local port a client or server is bound to.   | |
| void | imquic_start_endpoint (imquic_endpoint *endpoint) | 
| Start a QUIC stack previously created with imquic_create_server or imquic_create_client. In case of a server, it will start listening for incoming connections; in case of a client, it will attempt to connect to the provided remote address.   | |
| void | imquic_shutdown_endpoint (imquic_endpoint *endpoint) | 
| Shutdown a previously started QUIC endpoint (client or server) In case of a server, it will terminate all client connections it's handling, and stop accepting new ones; in case of a client, it will terminate the active connection, if any.   | |
| void | imquic_set_new_connection_cb (imquic_endpoint *endpoint, void(*new_connection)(imquic_connection *conn, void *user_data)) | 
| Configure the callback function to be notified about new 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_stream_incoming_cb (imquic_endpoint *endpoint, void(*stream_incoming)(imquic_connection *conn, uint64_t stream_id, uint8_t *bytes, uint64_t offset, uint64_t length, gboolean complete)) | 
| Configure the callback function to be notified about incoming STREAM data on an existing connection handled by this endpoint.   | |
| void | imquic_set_datagram_incoming_cb (imquic_endpoint *endpoint, void(*datagram_incoming)(imquic_connection *conn, uint8_t *bytes, uint64_t length)) | 
| Configure the callback function to be notified about incoming DATAGRAM data on an existing connection handled by this endpoint.   | |
| void | imquic_set_connection_gone_cb (imquic_endpoint *endpoint, void(*connection_gone)(imquic_connection *conn)) | 
| Configure the callback function to be notified when an existing connection handled by this endpoint has been closed/shut down.   | |
| int | imquic_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.   | |
| int | imquic_send_on_datagram (imquic_connection *conn, uint8_t *bytes, uint64_t length) | 
| Helper method to send data on a QUIC DATAGRAM.   | |
| const char * | imquic_get_connection_alpn (imquic_connection *conn) | 
| Helper function to get the ALPN of a connection.   | |
| const char * | imquic_get_connection_name (imquic_connection *conn) | 
| Helper function to get the display name of a connection.   | |
| int | imquic_new_stream_id (imquic_connection *conn, gboolean bidirectional, uint64_t *stream_id) | 
| Helper method to ask for the next usable locally originated stream ID on this connection.   | |
| void | imquic_close_connection (imquic_connection *conn, uint64_t error, const char *reason) | 
| Helper method to close a QUIC connection.   | |
| void | imquic_connection_ref (imquic_connection *conn) | 
| Increase a reference to a imquic_connection instance.   | |
| void | imquic_connection_unref (imquic_connection *conn) | 
| Decrease a reference to a imquic_connection instance.   | |
| void | imquic_stream_id_parse (uint64_t stream_id, uint64_t *id, gboolean *client_initiated, gboolean *bidirectional) | 
| Parse a QUIC stream ID to its actual ID and its other properties.   | |
| uint64_t | imquic_stream_id_build (uint64_t id, gboolean client_initiated, gboolean bidirectional) | 
| Build a QUIC stream ID out of its actual ID and its other properties.   | |
| uint64_t | imquic_varint_read (uint8_t *bytes, size_t blen, uint8_t *length) | 
| Read a variable size integer from a buffer.   | |
| uint8_t | imquic_varint_write (uint64_t number, uint8_t *bytes, size_t blen) | 
| Write a variable size integer to a buffer.   | |
| uint64_t | imquic_uint64_random (void) | 
| Helper to generate random 64 bit unsigned integers.   | |
| uint64_t * | imquic_uint64_dup (uint64_t num) | 
| Helper to generate an allocated copy of a uint64_t number.   | |
Variables | |
| int | imquic_log_level = IMQUIC_LOG_VERB | 
| gboolean | imquic_log_timestamps = FALSE | 
| gboolean | imquic_log_colors = TRUE | 
| gboolean | imquic_lock_debug = FALSE | 
| gboolean | imquic_refcount_debug = FALSE | 
| volatile int | initialized = IMQUIC_NOT_INITIALIZED | 
imquic public interface
Public interface to the imquic library. This is where public functions are callbacks to interact with the library are defined.
| void imquic_close_connection | ( | imquic_connection * | conn, | 
| uint64_t | error, | ||
| const char * | reason ) | 
Helper method to close a QUIC connection.
| [in] | conn | The imquic_connection to close | 
| [in] | error | The application error code to send, if any | 
| [in] | reason | A string description of why the connection was closed, if any | 
| const char * imquic_config_str | ( | imquic_config | type | ) | 
Helper function to serialize to string the name of a imquic_config property.
| type | The imquic_config property | 
| void imquic_connection_ref | ( | imquic_connection * | conn | ) | 
Increase a reference to a imquic_connection instance.
| conn | The imquic_connection instance to increase a reference for | 
| void imquic_connection_unref | ( | imquic_connection * | conn | ) | 
Decrease a reference to a imquic_connection instance.
| conn | The imquic_connection instance to decrease a reference for | 
| imquic_client * imquic_create_client | ( | const char * | name, | 
| ... ) | 
Method to create a new QUIC 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_client("echo-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_ALPN, "doq",
        IMQUIC_CONFIG_DONE, NULL);
to create a QUIC client advertising the "doq" (DNS Over QUIC) ALPN. Notice that this will only create the resource, but not actually start it: before doing that, you'll need to configure the callbacks for the events you're interested in, and then use imquic_start_endpoint to start the QUIC client (which will attempt a connection).
| [in] | name | The endpoint name (if NULL, a default value will be set) | 
| imquic_server * imquic_create_server | ( | const char * | name, | 
| ... ) | 
Method to create a new QUIC 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_server("echo-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_ALPN, "doq",
        IMQUIC_CONFIG_DONE, NULL);
to create a QUIC server advertising the "doq" (DNS Over QUIC) ALPN. Notice that this will only create the resource, but not actually start it: before doing that, you'll need to configure the callbacks for the events you're interested in, and then use imquic_start_endpoint to start the QUIC server (which will wait for incoming connections).
| [in] | name | The endpoint name (if NULL, a default value will be set) | 
| void imquic_deinit | ( | void | ) | 
Uninitialize the imquic library.
| const char * imquic_get_build_sha | ( | void | ) | 
Get info on the git commit was compiled in this build.
| const char * imquic_get_build_time | ( | void | ) | 
Get info on when this shared object was built.
| const char * imquic_get_connection_alpn | ( | imquic_connection * | conn | ) | 
Helper function to get the ALPN of a connection.
| conn | The imquic_connection to query | 
| const char * imquic_get_connection_name | ( | imquic_connection * | conn | ) | 
Helper function to get the display name of a connection.
| conn | The imquic_connection to query | 
| const char * imquic_get_endpoint_alpn | ( | imquic_endpoint * | endpoint | ) | 
Helper function to get the ALPN a local client or server is configured to negotiate.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to query | 
| const char * imquic_get_endpoint_name | ( | imquic_endpoint * | endpoint | ) | 
Helper function to get the endpoint name of a local client or server.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to query | 
| uint16_t imquic_get_endpoint_port | ( | imquic_endpoint * | endpoint | ) | 
Helper function to get the local port a client or server is bound to.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to query | 
| const char * imquic_get_endpoint_subprotocol | ( | imquic_endpoint * | endpoint | ) | 
Helper function to get the WebTransport protocol a local client or server is configured to negotiate.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to query | 
| uint32_t imquic_get_version | ( | void | ) | 
Get the current version of the library as a number.
| int imquic_get_version_major | ( | void | ) | 
Get the current major version of the library as a number.
| int imquic_get_version_minor | ( | void | ) | 
Get the current minor version of the library as a number.
| int imquic_get_version_patch | ( | void | ) | 
Get the current patch version of the library as a number.
| const char * imquic_get_version_release | ( | void | ) | 
Get the current release type of the library as a string.
| const char * imquic_get_version_string | ( | void | ) | 
Get the current version of the library as a string.
| const char * imquic_get_version_string_full | ( | void | ) | 
Get the current version of the library, including release type, as a string.
| int imquic_init | ( | const char * | secrets_log | ) | 
Initialize the imquic library.
| secrets_log | File to use to store QUIC secret, e.g., for Wireshark debugging (see SSLKEYLOGFILE) | 
| gboolean imquic_is_endpoint_server | ( | imquic_endpoint * | endpoint | ) | 
Helper function to check whether a local endpoint is a server.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to query | 
| gboolean imquic_is_inited | ( | void | ) | 
Check if the imquic library has already been initialized.
| gboolean imquic_is_qlog_supported | ( | void | ) | 
Check if QLOG is supported at runtime.
| int imquic_new_stream_id | ( | imquic_connection * | conn, | 
| gboolean | bidirectional, | ||
| uint64_t * | stream_id ) | 
Helper method to ask for the next usable locally originated stream ID on this connection.
| [in] | conn | The imquic_connection to query | 
| [in] | bidirectional | Whether the new stream should be bidirectional | 
| [out] | stream_id | Pointer where the new stream ID will be provided | 
| int imquic_send_on_datagram | ( | imquic_connection * | conn, | 
| uint8_t * | bytes, | ||
| uint64_t | length ) | 
Helper method to send data on a QUIC DATAGRAM.
| [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 | 
| int imquic_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.
| [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 | 
| void imquic_set_connection_gone_cb | ( | imquic_endpoint * | endpoint, | 
| void(* | connection_gone )(imquic_connection *conn) ) | 
Configure the callback function to be notified when an existing connection handled by this endpoint has been closed/shut down.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to configure | 
| connection_gone | Pointer to the function that will be invoked when a connection is gone | 
| void imquic_set_datagram_incoming_cb | ( | imquic_endpoint * | endpoint, | 
| void(* | datagram_incoming )(imquic_connection *conn, uint8_t *bytes, uint64_t length) ) | 
Configure the callback function to be notified about incoming DATAGRAM data on an existing connection handled by this endpoint.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to configure | 
| datagram_incoming | Pointer to the function that will be invoked on the new DATAGRAM data | 
| void imquic_set_lock_debugging | ( | gboolean | enabled | ) | 
Enable or disable lock/mutex debugging.
| enabled | Whether debugging should now be enabled | 
| void imquic_set_log_level | ( | int | level | ) | 
Set the log level for the library.
| level | Debugging level to use | 
| void imquic_set_new_connection_cb | ( | imquic_endpoint * | endpoint, | 
| void(* | new_connection )(imquic_connection *conn, void *user_data) ) | 
Configure the callback function to be notified about new 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.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to configure | 
| new_connection | Pointer to the function that will be invoked on the new connection | 
| void imquic_set_refcount_debugging | ( | gboolean | enabled | ) | 
Enable or disable debugging of reference counters.
| enabled | Whether debugging should now be enabled | 
| void imquic_set_stream_incoming_cb | ( | imquic_endpoint * | endpoint, | 
| void(* | stream_incoming )(imquic_connection *conn, uint64_t stream_id, uint8_t *bytes, uint64_t offset, uint64_t length, gboolean complete) ) | 
Configure the callback function to be notified about incoming STREAM data on an existing connection handled by this endpoint.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to configure | 
| stream_incoming | Pointer to the function that will be invoked on the new STREAM data | 
| void imquic_shutdown_endpoint | ( | imquic_endpoint * | endpoint | ) | 
Shutdown a previously started QUIC endpoint (client or server) In case of a server, it will terminate all client connections it's handling, and stop accepting new ones; in case of a client, it will terminate the active connection, if any.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to shutdown | 
| void imquic_start_endpoint | ( | imquic_endpoint * | endpoint | ) | 
Start a QUIC stack previously created with imquic_create_server or imquic_create_client. In case of a server, it will start listening for incoming connections; in case of a client, it will attempt to connect to the provided remote address.
| endpoint | The imquic_endpoint (imquic_server or imquic_client) to start | 
| uint64_t imquic_stream_id_build | ( | uint64_t | id, | 
| gboolean | client_initiated, | ||
| gboolean | bidirectional ) | 
Build a QUIC stream ID out of its actual ID and its other properties.
| [in] | id | The actual client/server uni/bidirectional ID | 
| [in] | client_initiated | Whether this stream is client initiated | 
| [in] | bidirectional | Whether this stream is bidirectional | 
| void imquic_stream_id_parse | ( | uint64_t | stream_id, | 
| uint64_t * | id, | ||
| gboolean * | client_initiated, | ||
| gboolean * | bidirectional ) | 
Parse a QUIC stream ID to its actual ID and its other properties.
| [in] | stream_id | The QUIC stream ID to parse | 
| [out] | id | The actual client/server uni/bidirectional ID | 
| [out] | client_initiated | Whether this stream is client initiated | 
| [out] | bidirectional | Whether this stream is bidirectional | 
| uint64_t * imquic_uint64_dup | ( | uint64_t | num | ) | 
Helper to generate an allocated copy of a uint64_t number.
| num | The uint64_t number to duplicate | 
| uint64_t imquic_uint64_random | ( | void | ) | 
Helper to generate random 64 bit unsigned integers.
| uint64_t imquic_varint_read | ( | uint8_t * | bytes, | 
| size_t | blen, | ||
| uint8_t * | length ) | 
Read a variable size integer from a buffer.
| [in] | bytes | The buffer to read | 
| [in] | blen | The size of the buffer | 
| [out] | length | How many bytes the variable size integer used | 
| uint8_t imquic_varint_write | ( | uint64_t | number, | 
| uint8_t * | bytes, | ||
| size_t | blen ) | 
Write a variable size integer to a buffer.
| [in] | number | The number to write as a variable size integer | 
| [in] | bytes | The buffer to write to | 
| [in] | blen | The size of the buffer | 
| gboolean imquic_lock_debug = FALSE | 
| gboolean imquic_log_colors = TRUE | 
| int imquic_log_level = IMQUIC_LOG_VERB | 
| gboolean imquic_log_timestamps = FALSE | 
| gboolean imquic_refcount_debug = FALSE | 
| volatile int initialized = IMQUIC_NOT_INITIALIZED |