qlog.c File Reference

#include <stdlib.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <inttypes.h>
#include <unistd.h>
#include "internal/qlog.h"
#include "internal/connection.h"
#include "internal/version.h"
#include "imquic/debug.h"

Include dependency graph for qlog.c:

Functions
gboolean	imquic_qlog_is_supported (void)
	Helper method to check if QLOG is supported at runtime.
imquic_qlog *	imquic_qlog_create (char *id, gboolean sequential, gboolean is_server, char *filename, gboolean quic, gboolean http3, gboolean roq, gboolean moq)
	Helper method to initialize a new QLOG instance.
void	imquic_qlog_set_odcid (imquic_qlog *qlog, void *odcid)
	Set/update the Original Destination Connection ID.
void	imquic_qlog_destroy (imquic_qlog *qlog)
	Helper method to destroy an existing QLOG instance.
int	imquic_qlog_save_to_file (imquic_qlog *qlog)
	Save the current status of the QLOG structure to JSON.
json_t *	imquic_qlog_event_prepare (const char *name)
	Helper to create a new QLOG event by name.
json_t *	imquic_qlog_event_add_data (json_t *event)
	Helper to add a data object to an event and return a pointer to it.
void	imquic_qlog_event_add_raw (json_t *parent, const char *name, uint8_t *bytes, size_t length)
	Helper to add/append a raw object to the specified object or array.
void	imquic_qlog_event_add_path_endpoint_info (json_t *parent, const char *name, const char *ip, uint16_t port)
	Helper to add/append a PathEndpointInfo object to the specified object or array.
void	imquic_qlog_append_event (imquic_qlog *qlog, json_t *event)
	Helper to add a complete event object to an existing QLOG instance.
void	imquic_qlog_connection_started (imquic_qlog *qlog, const char *local_ip, uint16_t local_port, const char *remote_ip, uint16_t remote_port)
	Add a connection_started event.
void	imquic_qlog_connection_closed (imquic_qlog *qlog, gboolean local, uint32_t cc_code, uint32_t app_code, const char *reason)
	Add a connection_closed event.
void	imquic_qlog_version_information (imquic_qlog *qlog, uint32_t version, uint32_t chosen)
	Add a version_information event.
void	imquic_qlog_alpn_information (imquic_qlog *qlog, uint8_t *server_alpn, size_t server_alpn_len, uint8_t *client_alpn, size_t client_alpn_len, char *chosen)
	Add a alpn_information event.
json_t *	imquic_qlog_prepare_parameters_set (imquic_qlog *qlog, gboolean local, gboolean resumption, gboolean early_data)
	Prepare a parameters_set object, but don't add it yet.
void	imquic_qlog_parameters_set (imquic_qlog *qlog, json_t *params)
	Add a parameters_set event.
json_t *	imquic_qlog_prepare_packet_header (const char *type, void *scid, void *dcid)
	Prepare a header object, but don't add it yet.
json_t *	imquic_qlog_prepare_packet_frame (const char *type)
	Prepare a frames object, but don't add it yet.
void	imquic_qlog_packet_sent (imquic_qlog *qlog, json_t *header, json_t *frames, uint32_t id, size_t length)
	Add a packet_sent event.
void	imquic_qlog_packet_received (imquic_qlog *qlog, json_t *header, json_t *frames, uint32_t id, size_t length)
	Add a packet_received event.
void	imquic_qlog_packet_dropped (imquic_qlog *qlog, json_t *header, uint32_t id, size_t length, const char *trigger)
	Add a packet_dropped event.
void	imquic_qlog_udp_datagrams_sent (imquic_qlog *qlog, uint32_t id, size_t length)
	Add a udp_datagrams_sent event.
void	imquic_qlog_udp_datagrams_received (imquic_qlog *qlog, uint32_t id, size_t length)
	Add a udp_datagrams_received event.
void	imquic_qlog_udp_datagrams_dropped (imquic_qlog *qlog, uint32_t id, size_t length)
	Add a udp_datagrams_dropped event.
void	imquic_qlog_stream_state_updated (imquic_qlog *qlog, uint64_t id, const char *type, const char *side, const char *state)
	Add a stream_state_updated event.
void	imquic_qlog_key_updated (imquic_qlog *qlog, const char *type, uint8_t *key, size_t key_len, uint64_t key_phase)
	Add a key_updated event.

Function Documentation

imquic_qlog_alpn_information()

void imquic_qlog_alpn_information	(	imquic_qlog *	qlog,
		uint8_t *	server_alpn,
		size_t	server_alpn_len,
		uint8_t *	client_alpn,
		size_t	client_alpn_len,
		char *	chosen )

Add a alpn_information event.

Parameters

qlog	The imquic_qlog instance to add the event to
server_alpn	The buffer containing the list of server ALPNs, if any
server_alpn_len	The size of the server ALPN buffer
client_alpn	The buffer containing the list of client ALPNs, if any
client_alpn_len	The size of the client ALPN buffer
chosen	The chosen ALPN

imquic_qlog_append_event()

void imquic_qlog_append_event	(	imquic_qlog *	qlog,
		json_t *	event )

Helper to add a complete event object to an existing QLOG instance.

Parameters

qlog	The imquic_qlog instance to add the event to
event	The event to add to the QLOG instance

imquic_qlog_connection_closed()

void imquic_qlog_connection_closed	(	imquic_qlog *	qlog,
		gboolean	local,
		uint32_t	cc_code,
		uint32_t	app_code,
		const char *	reason )

Add a connection_closed event.

Parameters

qlog	The imquic_qlog instance to add the event to
local	Whether this is a local or remote event
cc_code	The connection code in the Connection Close message, if any
app_code	The application code in the Connection Close message, if any
reason	The reason text in the Connection Close message, if any

imquic_qlog_connection_started()

void imquic_qlog_connection_started	(	imquic_qlog *	qlog,
		const char *	local_ip,
		uint16_t	local_port,
		const char *	remote_ip,
		uint16_t	remote_port )

Add a connection_started event.

Parameters

qlog	The imquic_qlog instance to add the event to
local_ip	The local address the connection
local_port	The local port the connection
remote_ip	The remote address the connection
remote_port	The remote port the connection

imquic_qlog_create()

imquic_qlog * imquic_qlog_create	(	char *	id,
		gboolean	sequential,
		gboolean	is_server,
		char *	filename,
		gboolean	quic,
		gboolean	http3,
		gboolean	roq,
		gboolean	moq )

Helper method to initialize a new QLOG instance.

Note

This method will try to create the file right away, and will fail and give up immediately if that doesn't succeed for whatever reason. It will not create the folders part of the filename if the related folders don't exist already, which means those should be created by the application using the library, in case

Parameters

id	ID of the log (ends in the title property)
sequential	Whether sequential JSON should be used, instead of regular JSON
is_server	Whether this is for a client or server connection
filename	Path to where the JSON file should be saved
quic	Whether QUIC events should be added to the QLOG
http3	Whether HTTP/3 events should be added to the QLOG
roq	Whether RoQ events should be added to the QLOG
moq	Whether MoQT events should be added to the QLOG

Returns

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

imquic_qlog_destroy()

void imquic_qlog_destroy

(

imquic_qlog *

qlog

)

Helper method to destroy an existing QLOG instance.

Note

Destroying the instance will write the file to disk

Parameters

qlog	The imquic_qlog instance to destroy

imquic_qlog_event_add_data()

json_t * imquic_qlog_event_add_data

(

json_t *

event

)

Helper to add a data object to an event and return a pointer to it.

Parameters

event

The event to add the data object to

Returns

A pointer to the data object, if successful, or NULL otherwise

imquic_qlog_event_add_path_endpoint_info()

void imquic_qlog_event_add_path_endpoint_info	(	json_t *	parent,
		const char *	name,
		const char *	ip,
		uint16_t	port )

Helper to add/append a PathEndpointInfo object to the specified object or array.

Note

The method automatically fills in either the v4 or v6 info by looking at the address

Parameters

parent	The object or array to add/append the info to
name	Name to give to the object, if the parent is an object (ignored for arrays)
ip	The IP address
port	The port

imquic_qlog_event_add_raw()

void imquic_qlog_event_add_raw	(	json_t *	parent,
		const char *	name,
		uint8_t *	bytes,
		size_t	length )

Helper to add/append a raw object to the specified object or array.

Parameters

parent	The object or array to add/append the raw info to
name	Name to give to the raw object, if the parent is an object (ignored for arrays)
bytes	The content of the raw data, if needed
length	The size of the raw data

imquic_qlog_event_prepare()

json_t * imquic_qlog_event_prepare

(

const char *

name

)

Helper to create a new QLOG event by name.

Note

This automatically fills in the time property

Parameters

name	The name of the event

Returns

An event instance to fill in before appending it, if successful, or NULL otherwise

imquic_qlog_is_supported()

gboolean imquic_qlog_is_supported

(

void

)

Helper method to check if QLOG is supported at runtime.

Returns

TRUE if supported, FALSE otherwise

imquic_qlog_key_updated()

void imquic_qlog_key_updated	(	imquic_qlog *	qlog,
		const char *	type,
		uint8_t *	key,
		size_t	key_len,
		uint64_t	key_phase )

Add a key_updated event.

Parameters

qlog	The imquic_qlog instance to add the event to
type	The key type
key	Pointer to the key value
key_len	Size of the key value
key_phase	The key phase

imquic_qlog_packet_dropped()

void imquic_qlog_packet_dropped	(	imquic_qlog *	qlog,
		json_t *	header,
		uint32_t	id,
		size_t	length,
		const char *	trigger )

Add a packet_dropped event.

Parameters

qlog	The imquic_qlog instance to add the event to
header	The QUIC packet header info, if any
id	The ID of the datagram, if any
length	The size of the datagram that was received
trigger	What caused the packet to be dropped

imquic_qlog_packet_received()

void imquic_qlog_packet_received	(	imquic_qlog *	qlog,
		json_t *	header,
		json_t *	frames,
		uint32_t	id,
		size_t	length )

Add a packet_received event.

Parameters

qlog	The imquic_qlog instance to add the event to
header	The QUIC packet header info
frames	The QUIC packet frames, if any
id	The ID of the datagram, if any
length	The size of the datagram that was received

imquic_qlog_packet_sent()

void imquic_qlog_packet_sent	(	imquic_qlog *	qlog,
		json_t *	header,
		json_t *	frames,
		uint32_t	id,
		size_t	length )

Add a packet_sent event.

Parameters

qlog	The imquic_qlog instance to add the event to
header	The QUIC packet header info, if any
frames	The QUIC packet frames, if any
id	The ID of the datagram, if any
length	The size of the datagram that was sent

imquic_qlog_parameters_set()

void imquic_qlog_parameters_set	(	imquic_qlog *	qlog,
		json_t *	params )

Add a parameters_set event.

Parameters

qlog	The imquic_qlog instance to add the event to
params	Pointer to a previously filled parameters set data object

imquic_qlog_prepare_packet_frame()

json_t * imquic_qlog_prepare_packet_frame

(

const char *

type

)

Prepare a frames object, but don't add it yet.

Note

This is needed to prepare an object that can be filled in externally, and then be passed to events that involve packets

Parameters

type	The frame type

Returns

A pointer to the new object, if successful, or NULL otherwise

imquic_qlog_prepare_packet_header()

json_t * imquic_qlog_prepare_packet_header	(	const char *	type,
		void *	scid,
		void *	dcid )

Prepare a header object, but don't add it yet.

Note

This is needed to prepare an object that calls that can be filled in externally, and then be passed to events that involve packets

Parameters

type	The packet type
scid	Opaque pointer to the source imquic_connection_id, if any
dcid	Opaque pointer to the destination imquic_connection_id, if any

Returns

A pointer to the header object, if successful, or NULL otherwise

imquic_qlog_prepare_parameters_set()

json_t * imquic_qlog_prepare_parameters_set	(	imquic_qlog *	qlog,
		gboolean	local,
		gboolean	resumption,
		gboolean	early_data )

Prepare a parameters_set object, but don't add it yet.

Note

This is needed to prepare an object that calls that can be filled in externally, and then be passed to imquic_qlog_parameters_set

Parameters

qlog	The imquic_qlog instance to prepare the data for
local	Whether this is a local or remote parameters set
resumption	Whether the resumption_allowed property should be set to TRUE
early_data	Whether the early_data_enabled property should be set to TRUE

Returns

A pointer to the parameters set object, if successful, or NULL otherwise

imquic_qlog_save_to_file()

int imquic_qlog_save_to_file

(

imquic_qlog *

qlog

)

Save the current status of the QLOG structure to JSON.

Note

This does not close the file, as other events may arrive later. This function is called automatically before destroying the instance

Parameters

qlog	The imquic_qlog instance to save to file

Returns

0 if successful, a negative integer otherwise

imquic_qlog_set_odcid()

void imquic_qlog_set_odcid	(	imquic_qlog *	qlog,
		void *	odcid )

Set/update the Original Destination Connection ID.

Parameters

qlog	The imquic_qlog instance to update
odcid	The Original Destination Connection ID to write, as a imquic_connection_id instance

imquic_qlog_stream_state_updated()

void imquic_qlog_stream_state_updated	(	imquic_qlog *	qlog,
		uint64_t	id,
		const char *	type,
		const char *	side,
		const char *	state )

Add a stream_state_updated event.

Parameters

qlog	The imquic_qlog instance to add the event to
id	The ID of the stream
type	The stream type (bidirectional/unidirectional), if any
side	The stream side (sending/receiving), if any
state	The new stream state, if any

imquic_qlog_udp_datagrams_dropped()

void imquic_qlog_udp_datagrams_dropped	(	imquic_qlog *	qlog,
		uint32_t	id,
		size_t	length )

Add a udp_datagrams_dropped event.

Parameters

qlog	The imquic_qlog instance to add the event to
id	The ID of the datagram, if any
length	The size of the datagram that was dropped

imquic_qlog_udp_datagrams_received()

void imquic_qlog_udp_datagrams_received	(	imquic_qlog *	qlog,
		uint32_t	id,
		size_t	length )

Add a udp_datagrams_received event.

Parameters

qlog	The imquic_qlog instance to add the event to
id	The ID of the datagram, if any
length	The size of the datagram that was sent

imquic_qlog_udp_datagrams_sent()

void imquic_qlog_udp_datagrams_sent	(	imquic_qlog *	qlog,
		uint32_t	id,
		size_t	length )

Add a udp_datagrams_sent event.

Parameters

qlog	The imquic_qlog instance to add the event to
id	The ID of the datagram, if any
length	The size of the datagram that was sent

imquic_qlog_version_information()

void imquic_qlog_version_information	(	imquic_qlog *	qlog,
		uint32_t	version,
		uint32_t	chosen )

Add a version_information event.

Parameters

qlog	The imquic_qlog instance to add the event to
version	The version we support (just one, right now)
chosen	The chosen version