qlog.h File Reference

QLOG support (headers) More...

#include <glib.h>
#include <jansson.h>
#include "refcount.h"

Include dependency graph for qlog.h:

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

Go to the source code of this file.

Data Structures
struct	imquic_qlog
	QLOG instance. More...

Functions
gboolean	imquic_qlog_is_supported (void)
	Helper method to check if QLOG is supported at runtime.
QLOG events tracing
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_append_event (imquic_qlog *qlog, json_t *event)
	Helper to add a complete event object to an existing QLOG instance.

QLOG management
typedef struct imquic_qlog	imquic_qlog
	QLOG instance.
imquic_qlog *	imquic_qlog_create (char *id, char *cid, char *folder, gboolean sequential, gboolean is_server, gboolean http3, gboolean roq, gboolean roq_packets, gboolean moq, gboolean moq_messages, gboolean moq_objects)
	Helper method to initialize a new QLOG instance.
int	imquic_qlog_save_to_file (imquic_qlog *qlog)
	Save the current status of the QLOG structure to JSON.
void	imquic_qlog_destroy (imquic_qlog *qlog)
	Helper method to destroy an existing QLOG instance.

Detailed Description

QLOG support (headers)

Author

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

Copyright

MIT License

Implementation of QLOG support (JSON serialization) via the Jansson library. This implementation only allows to create QLOG files for the HTTP/3, RoQ and MoQ layers: QUIC QLOG files will be created, in a separate file, by picoquic instead, when required.

Note

Jansson is an optional dependency, meaning that the functionality exposed by this code may not be available at runtime. When attempting to enable QLOG usage in that case, a warning will be shown on the console.

Typedef Documentation

imquic_qlog

typedef struct imquic_qlog imquic_qlog

QLOG instance.

Function Documentation

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

imquic_qlog * imquic_qlog_create	(	char *	id,
		char *	cid,
		char *	folder,
		gboolean	sequential,
		gboolean	is_server,
		gboolean	http3,
		gboolean	roq,
		gboolean	roq_packets,
		gboolean	moq,
		gboolean	moq_messages,
		gboolean	moq_objects )

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)
cid	Initial Connection ID
folder	Path to the folder where the JSON file should be saved
sequential	Whether sequential JSON should be used, instead of regular JSON
is_server	Whether this is for a client or server connection
http3	Whether HTTP/3 events should be added to the QLOG
roq	Whether RoQ events should be added to the QLOG
roq_packets	Whether RoQ packets should be added to the QLOG
moq	Whether MoQT events should be added to the QLOG
moq_messages	Whether MoQT messages should be added to the QLOG
moq_objects	Whether MoQT objects 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_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_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