utils.h File Reference

Generic utilities (headers) More...

#include <glib.h>

Include dependency graph for utils.h:

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

Go to the source code of this file.

Data Structures
struct	imquic_data
	Generic data buffer. More...
struct	imquic_data_fixed
	Generic fixed size data buffer. More...
struct	imquic_bitstream
	Bitstream abstraction. More...

Macros
#define	htonll(x)   ((1==htonl(1)) ? (x) : ((guint64)htonl((x) & 0xFFFFFFFF) << 32) | htonl((x) >> 32))
#define	ntohll(x)   ((1==ntohl(1)) ? (x) : ((guint64)ntohl((x) & 0xFFFFFFFF) << 32) | ntohl((x) >> 32))
#define	BYTE_TO_BINARY_PATTERN   "%c%c%c%c%c%c%c%c"
#define	BYTE_TO_BINARY(byte)

Functions
uint64_t	imquic_full_packet_number (uint64_t largest, uint64_t pn_pkt, uint8_t p_len)
	Helper method to reconstruct a full QUIC packet number.
void	imquic_print_hex (int level, uint8_t *buf, size_t buflen)
	Helper method mostly used for debugging: prints the content of a hex buffer.
String utilities
size_t	imquic_strlcat (char *dest, const char *src, size_t dest_size)
	Helper method to concatenate strings and log an error if truncation occurred.
int	imquic_strlcat_fast (char *dest, const char *src, size_t dest_size, size_t *offset)
	Alternative helper method to concatenate strings and log an error if truncation occurred, which uses memccpy instead of g_strlcat and so is supposed to be faster.
64-bit unsigned integers utilities
uint64_t	imquic_random_uint64 (void)
	Helper to generate random 64 bit unsigned integers.
uint64_t *	imquic_dup_uint64 (uint64_t num)
	Helper to generate an allocated copy of a uint64_t number.
Variable size integers
uint64_t	imquic_read_varint (uint8_t *bytes, size_t blen, uint8_t *length)
	Read a variable size integer from a buffer.
uint8_t	imquic_write_varint (uint64_t number, uint8_t *bytes, size_t blen)
	Write a variable size integer to a buffer.
uint64_t	imquic_read_pfxint (uint8_t n, uint8_t *bytes, size_t blen, uint8_t *length)
	Read a prefixed integer from a buffer (QPACK only)
uint8_t	imquic_write_pfxint (uint64_t number, uint8_t n, uint8_t *bytes, size_t blen)
	Write a prefixed integer to a buffer (QPACK only)

Generic data buffer
typedef struct imquic_data	imquic_data
	Generic data buffer.
typedef struct imquic_data_fixed	imquic_data_fixed
	Generic fixed size data buffer.
imquic_data *	imquic_data_create (uint8_t *buffer, size_t length)
	Helper method to create a data buffer out of existing data.
gboolean	imquic_data_equal (const void *a, const void *b)
	Helper comparator function, to check if two buffers contain the same data.
void	imquic_data_destroy (imquic_data *data)
	Helper method to free an existing data buffer.

Bitstream (currently only used for Huffman in QPACK)
typedef struct imquic_bitstream	imquic_bitstream
	Bitstream abstraction.
uint8_t	imquic_bitstream_peek (imquic_bitstream *bs, uint8_t *len)
	Helper method to peek 8 bit in the bitstream.
size_t	imquic_bitstream_write (imquic_bitstream *bs, uint32_t value, uint8_t bits)
	Helper method to add bits to a bitstream buffer.

Detailed Description

Generic utilities (headers)

Author

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

Copyright

MIT License

Implementation of a few more generic functionality that is useful in the QUIC stack internals (e.g., varint support).

Macro Definition Documentation

BYTE_TO_BINARY

#define BYTE_TO_BINARY

(

byte

)

Value:

        ((byte) & 0x80 ? '1' : '0'), \
        ((byte) & 0x40 ? '1' : '0'), \
        ((byte) & 0x20 ? '1' : '0'), \
        ((byte) & 0x10 ? '1' : '0'), \
        ((byte) & 0x08 ? '1' : '0'), \
        ((byte) & 0x04 ? '1' : '0'), \
        ((byte) & 0x02 ? '1' : '0'), \
        ((byte) & 0x01 ? '1' : '0')

BYTE_TO_BINARY_PATTERN

#define BYTE_TO_BINARY_PATTERN   "%c%c%c%c%c%c%c%c"

htonll

#define htonll

(

x

)

((1==htonl(1)) ? (x) : ((guint64)htonl((x) & 0xFFFFFFFF) << 32) | htonl((x) >> 32))

ntohll

#define ntohll

(

x

)

((1==ntohl(1)) ? (x) : ((guint64)ntohl((x) & 0xFFFFFFFF) << 32) | ntohl((x) >> 32))

Typedef Documentation

imquic_bitstream

typedef struct imquic_bitstream imquic_bitstream

Bitstream abstraction.

imquic_data

typedef struct imquic_data imquic_data

Generic data buffer.

imquic_data_fixed

typedef struct imquic_data_fixed imquic_data_fixed

Generic fixed size data buffer.

Function Documentation

imquic_bitstream_peek()

uint8_t imquic_bitstream_peek	(	imquic_bitstream *	bs,
		uint8_t *	len )

Helper method to peek 8 bit in the bitstream.

Note

This method only peeks at the data, but doesn't advance the offset position in the bitstream. There's no function to "consume" data, as that can be done by simply modifying the offset property, which is what the QPACK stack does when decoding Huffman codes internally.

Parameters

[in]	bs	The bitstream instance to peek
[out]	len	How many bits were actually put in the byte

Returns

A byte containing up to 8 bits from the bitstream, without advancing the offset

imquic_bitstream_write()

size_t imquic_bitstream_write	(	imquic_bitstream *	bs,
		uint32_t	value,
		uint8_t	bits )

Helper method to add bits to a bitstream buffer.

Parameters

bs	The bitstream instance to update
value	Integer containing the data to write
bits	Number of bits from the integer to actually write

Returns

The number of bits written to the buffer

imquic_data_create()

imquic_data * imquic_data_create	(	uint8_t *	buffer,
		size_t	length )

Helper method to create a data buffer out of existing data.

Parameters

buffer	The data to copy in the new buffer
length	How many bytes to copy from the original data

Returns

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

imquic_data_destroy()

void imquic_data_destroy

(

imquic_data *

data

)

Helper method to free an existing data buffer.

Parameters

data	The data buffer to free

imquic_data_equal()

gboolean imquic_data_equal	(	const void *	a,
		const void *	b )

Helper comparator function, to check if two buffers contain the same data.

Note

Helpful as a callback comparator function

Parameters

a	Opaque pointer to the first data buffer to compare
b	Opaque pointer to the second data buffer to compare

Returns

TRUE if the two buffers contain the same data, FALSE otherwise

imquic_dup_uint64()

uint64_t * imquic_dup_uint64

(

uint64_t

num

)

Helper to generate an allocated copy of a uint64_t number.

Note

While apparently silly, this is needed in order to make sure uint64_t values used as keys in GHashTable operations are not lost: using temporary uint64_t numbers in a g_hash_table_insert, for instance, will cause the key to contain garbage as soon as the temporary variable is lost, and all opererations on the key to fail

Parameters

num	The uint64_t number to duplicate

Returns

A pointer to a uint64_t number, if successful, NULL otherwise

imquic_full_packet_number()

uint64_t imquic_full_packet_number	(	uint64_t	largest,
		uint64_t	pn_pkt,
		uint8_t	p_len )

Helper method to reconstruct a full QUIC packet number.

Parameters

largest	The largest packet number received so far at this encryption level
pn_pkt	The received packet number
p_len	How many bytes the received packet number used as a variable size integer

Returns

The full reconstructed packet number

imquic_print_hex()

void imquic_print_hex	(	int	level,
		uint8_t *	buf,
		size_t	buflen )

Helper method mostly used for debugging: prints the content of a hex buffer.

Parameters

level	Log level at which this should be printed
buf	Buffer whose content need to be printed
buflen	How many bytes in the buffer should be printed

imquic_random_uint64()

uint64_t imquic_random_uint64

(

void

)

Helper to generate random 64 bit unsigned integers.

Note

This will fall back to a non-cryptographically safe PRNG in case the crypto library RAND_bytes() call fails.

Returns

A (mostly crypto-safe) random 64-bit unsigned integer

imquic_read_pfxint()

uint64_t imquic_read_pfxint	(	uint8_t	n,
		uint8_t *	bytes,
		size_t	blen,
		uint8_t *	length )

Read a prefixed integer from a buffer (QPACK only)

Note

You can use the return value to know how many bytes to skip in the buffer to read the next value. In case of issues in the parsing, length will have value 0.

Parameters

[in]	n	The N prefix
[in]	bytes	The buffer to read
[in]	blen	The size of the buffer
[out]	length	How many bytes the variable size integer used

Returns

The prefixed integer, if length is higher than 0

imquic_read_varint()

uint64_t imquic_read_varint	(	uint8_t *	bytes,
		size_t	blen,
		uint8_t *	length )

Read a variable size integer from a buffer.

Note

You can use the return value to know how many bytes to skip in the buffer to read the next value. In case of issues in the parsing, length will have value 0.

Parameters

[in]	bytes	The buffer to read
[in]	blen	The size of the buffer
[out]	length	How many bytes the variable size integer used

Returns

The variable size integer, if length is higher than 0

imquic_strlcat()

size_t imquic_strlcat	(	char *	dest,
		const char *	src,
		size_t	dest_size )

Helper method to concatenate strings and log an error if truncation occurred.

Parameters

[in]	dest	Destination buffer, already containing one nul-terminated string
[in]	src	Source buffer
[in]	dest_size	Length of dest buffer in bytes (not length of existing string inside dest)

Returns

Size of attempted result, if retval >= dest_size, truncation occurred (and an error will be logged).

imquic_strlcat_fast()

int imquic_strlcat_fast	(	char *	dest,
		const char *	src,
		size_t	dest_size,
		size_t *	offset )

Alternative helper method to concatenate strings and log an error if truncation occurred, which uses memccpy instead of g_strlcat and so is supposed to be faster.

Note

The offset attribute is input/output, and updated any time the method is called

Parameters

[in]	dest	Destination buffer, already containing one nul-terminated string
[in]	src	Source buffer
[in]	dest_size	Length of dest buffer in bytes (not length of existing string inside dest)
[in]	offset	Offset of where to start appending, in the destination buffer

Returns

0 in case of success, a negative integer otherwise

imquic_write_pfxint()

uint8_t imquic_write_pfxint	(	uint64_t	number,
		uint8_t	n,
		uint8_t *	bytes,
		size_t	blen )

Write a prefixed integer to a buffer (QPACK only)

Note

You can use the return value to know how many bytes to skip in the buffer to write the next value. In case of issues in the writing, length will have value 0.

Parameters

[in]	number	The number to write as a variable size integer
[in]	n	The N prefix
[in]	bytes	The buffer to write to
[in]	blen	The size of the buffer

Returns

How many bytes the variable size integer used, if successful, 0 otherwise

imquic_write_varint()

uint8_t imquic_write_varint	(	uint64_t	number,
		uint8_t *	bytes,
		size_t	blen )

Write a variable size integer to a buffer.

Note

You can use the return value to know how many bytes to skip in the buffer to write the next value. In case of issues in the writing, length will have value 0.

Parameters

[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

Returns

How many bytes the variable size integer used, if successful, 0 otherwise