#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include "tlv_internals.h"
#include "buffer.h"

Include dependency graph for tlv_library.h:

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

Classes
struct	tlv_data_s

struct	_internal_tlv_handler_t

Macros
#define	DEFINE_TLV_PARSER(TAG_LIST, COMMON_HANDLER, PARSE_FUNCTION_NAME)
	Creates a parser function for a given TLV use case.

#define	TLV_CHECK_RECEIVED_TAGS(received, ...)

Typedefs
typedef struct tlv_data_s	tlv_data_t

typedef bool()	tlv_handler_cb_t(const tlv_data_t data, void tlv_extracted)

typedef TLV_reception_internal_t	TLV_reception_t

typedef enum tag_unicity_e	tag_unicity_t

Enumerations
enum	tag_unicity_e { ENFORCE_UNIQUE_TAG , ALLOW_MULTIPLE_TAG }

Functions
bool	tlv_enforce_u8_value (const tlv_data_t *data, uint8_t expected_value)
	Enforce that a TLV data contains the expected uint8 value.

bool	get_uint64_t_from_tlv_data (const tlv_data_t data, uint64_t value)
	Extract a uint64_t value from TLV data.

bool	get_uint32_t_from_tlv_data (const tlv_data_t data, uint32_t value)
	Extract a uint32_t value from TLV data.

bool	get_uint16_t_from_tlv_data (const tlv_data_t data, uint16_t value)
	Extract a uint16_t value from TLV data.

bool	get_uint8_t_from_tlv_data (const tlv_data_t data, uint8_t value)
	Extract a uint8_t value from TLV data.

bool	get_bool_from_tlv_data (const tlv_data_t data, bool value)
	Extract a boolean value from TLV data.

bool	get_buffer_from_tlv_data (const tlv_data_t data, buffer_t out, uint16_t min_size, uint16_t max_size)
	Extract a sized buffer from TLV data (zero-copy).

bool	get_string_from_tlv_data (const tlv_data_t data, char out, uint16_t min_length, uint16_t out_size)
	Copy a NUL-terminated string from TLV data.

bool	tlv_check_received_tags (TLV_reception_t received, const TLV_tag_t *tags, size_t tag_count)
	Check that every tag in `tags` was received during parsing.

bool	_parse_tlv_internal (const _internal_tlv_handler_t handlers, uint8_t handlers_count, tlv_handler_cb_t common_handler, tag_to_flag_function_t tag_to_flag_function, const buffer_t payload, void tlv_out, TLV_reception_t received_tags_flags)
	Parse a raw TLV payload using a pre-built handler table.

Macro Definition Documentation

◆ DEFINE_TLV_PARSER

#define DEFINE_TLV_PARSER	(	TAG_LIST,
		COMMON_HANDLER,
		PARSE_FUNCTION_NAME
	)

Creates a parser function for a given TLV use case.

Parameters

TAG_LIST	A X-macro of TAG and associated handles of the following format: TAG_LIST(X) \ X(<uint32_t>, TAG_NAME, <tlv_handler_cb_t>, <tag_unicity_t>) tag_unicity_t enum tag_unicity_e tag_unicity_t tlv_handler_cb_t bool() tlv_handler_cb_t(const tlv_data_t data, void tlv_extracted) Definition tlv_library.h:102
COMMON_HANDLER	An optional handler to call for all tags in addition to the specific one
PARSE_FUNCTION_NAME	Name of the function that will parse the TAG_LIST

Example:

#define MY_TAGS(X) \
    X(0x0A, TAG_A, my_handler_1, ALLOW_MULTIPLE_TAG) \
    X(0x1F, TAG_B, my_handler_2, ENFORCE_UNIQUE_TAG) \
    X(0x77, TAG_C, my_handler_2, ENFORCE_UNIQUE_TAG)
 
DEFINE_TLV_PARSER(MY_TAGS, NULL, my_tlv_parser)

Expands to:

enum { TAG_A = 0x0A, TAG_B = 0x1F, TAG_C = 0x77};
enum { TAG_A_INDEX, TAG_B_INDEX, TAG_C_INDEX, my_tlv_parser_TAG_COUNT };
enum { TAG_A_FLAG = 1 << 0, TAG_B_FLAG = 1 << 1, TAG_C_FLAG = 1 << 2 };
my_tlv_parser_tag_to_flag()
my_tlv_parser()

Definition at line 144 of file tlv_library.h.

◆ TLV_CHECK_RECEIVED_TAGS

#define TLV_CHECK_RECEIVED_TAGS	(	received,
		...
	)

Value:

    tlv_check_received_tags(received,                   \
                            (TLV_tag_t[]){__VA_ARGS__}, \
                            sizeof((TLV_tag_t[]){__VA_ARGS__}) / sizeof(TLV_tag_t))

Macro wrapper of the above function to accept a list of tags as argument.

Definition at line 225 of file tlv_library.h.

Typedef Documentation

◆ tag_unicity_t

typedef enum tag_unicity_e tag_unicity_t

◆ tlv_data_t

typedef struct tlv_data_s tlv_data_t

◆ tlv_handler_cb_t

typedef bool() tlv_handler_cb_t(const tlv_data_t *data, void *tlv_extracted)

Definition at line 102 of file tlv_library.h.

◆ TLV_reception_t

typedef TLV_reception_internal_t TLV_reception_t

Definition at line 106 of file tlv_library.h.

Enumeration Type Documentation

◆ tag_unicity_e

enum tag_unicity_e

Enumerator
ENFORCE_UNIQUE_TAG
ALLOW_MULTIPLE_TAG

Definition at line 108 of file tlv_library.h.

Function Documentation

◆ _parse_tlv_internal()

bool _parse_tlv_internal	(	const _internal_tlv_handler_t *	handlers,
		uint8_t	handlers_count,
		tlv_handler_cb_t *	common_handler,
		tag_to_flag_function_t *	tag_to_flag_function,
		const buffer_t *	payload,
		void *	tlv_out,
		TLV_reception_t *	received_tags_flags
	)

Parse a raw TLV payload using a pre-built handler table.

This is the internal engine behind every parser generated by DEFINE_TLV_PARSER. Prefer using the generated wrapper for your use case rather than calling this directly.

Parameters

[in]	handlers	Array of per-tag handlers
[in]	handlers_count	Number of entries in `handlers`
[in]	common_handler	Optional handler called for every tag before the specific one (may be NULL)
[in]	tag_to_flag_function	Maps a tag value to its reception flag bit
[in]	payload	Raw TLV bytes to parse
[out]	tlv_out	Output struct written into by the handlers
[out]	received_tags_flags	Reception tracker updated as tags are processed

Returns: true on success, false on any parse error or handler failure

Definition at line 408 of file tlv_library.c.

◆ get_bool_from_tlv_data()

bool get_bool_from_tlv_data	(	const tlv_data_t *	data,
		bool *	value
	)

Extract a boolean value from TLV data.

The TLV value must be exactly 1 byte with value 0 or 1. Any other value causes the function to return false.

Parameters

[in]	data	TLV data to read from
[out]	value	Parsed boolean value

Returns: true on success, false if data is NULL, the length is invalid, or the byte is neither 0 nor 1

Definition at line 169 of file tlv_library.c.

◆ get_buffer_from_tlv_data()

bool get_buffer_from_tlv_data	(	const tlv_data_t *	data,
		buffer_t *	out,
		uint16_t	min_size,
		uint16_t	max_size
	)

Extract a sized buffer from TLV data (zero-copy).

Populates out with a pointer into the TLV payload and its length. No data is copied; the caller must not outlive the original payload.

Parameters

[in]	data	TLV data to read from
[out]	out	`buffer_t` pointing into the TLV value bytes
[in]	min_size	Minimum acceptable length (0 to skip the lower-bound check)
[in]	max_size	Maximum acceptable length (0 to skip the upper-bound check)

Returns: true on success, false if data is NULL or the length is outside the allowed range

Definition at line 195 of file tlv_library.c.

◆ get_string_from_tlv_data()

bool get_string_from_tlv_data	(	const tlv_data_t *	data,
		char *	out,
		uint16_t	min_length,
		uint16_t	out_size
	)

Copy a NUL-terminated string from TLV data.

Copies the TLV bytes into out and appends a NUL terminator. The function rejects payloads that contain embedded NUL bytes.

Parameters

[in]	data	TLV data to read from
[out]	out	Destination buffer (must hold at least `value.size + 1` bytes)
[in]	min_length	Minimum acceptable string length in bytes, excluding NUL (0 to skip the lower-bound check)
[in]	out_size	Size of `out` in bytes including the NUL terminator (0 to skip the upper-bound check)

Returns: true on success, false if data is NULL, an embedded NUL is found, or the length is outside the allowed range

Definition at line 233 of file tlv_library.c.

◆ get_uint16_t_from_tlv_data()

bool get_uint16_t_from_tlv_data	(	const tlv_data_t *	data,
		uint16_t *	value
	)

Extract a uint16_t value from TLV data.

Delegates to get_uint64_t_from_tlv_data() and rejects values exceeding UINT16_MAX.

Parameters

[in]	data	TLV data to read from
[out]	value	Parsed uint16_t value

Returns: true on success, false if data is NULL, the length is invalid, or the value overflows uint16_t

Definition at line 120 of file tlv_library.c.

◆ get_uint32_t_from_tlv_data()

bool get_uint32_t_from_tlv_data	(	const tlv_data_t *	data,
		uint32_t *	value
	)

Extract a uint32_t value from TLV data.

Delegates to get_uint64_t_from_tlv_data() and rejects values exceeding UINT32_MAX.

Parameters

[in]	data	TLV data to read from
[out]	value	Parsed uint32_t value

Returns: true on success, false if data is NULL, the length is invalid, or the value overflows uint32_t

Definition at line 96 of file tlv_library.c.

◆ get_uint64_t_from_tlv_data()

bool get_uint64_t_from_tlv_data	(	const tlv_data_t *	data,
		uint64_t *	value
	)

Extract a uint64_t value from TLV data.

The value is interpreted as a big-endian unsigned integer. The TLV length must be between 1 and 8 bytes; shorter payloads are zero-padded. See also https://en.wikipedia.org/wiki/X.690 for DER encoding rules.

Parameters

[in]	data	TLV data to read from
[out]	value	Parsed uint64_t value

Returns: true on success, false if data is NULL or the length is out of range

Definition at line 64 of file tlv_library.c.

◆ get_uint8_t_from_tlv_data()

bool get_uint8_t_from_tlv_data	(	const tlv_data_t *	data,
		uint8_t *	value
	)

Extract a uint8_t value from TLV data.

Delegates to get_uint64_t_from_tlv_data() and rejects values exceeding UINT8_MAX.

Parameters

[in]	data	TLV data to read from
[out]	value	Parsed uint8_t value

Returns: true on success, false if data is NULL, the length is invalid, or the value overflows uint8_t

Definition at line 144 of file tlv_library.c.

◆ tlv_check_received_tags()

bool tlv_check_received_tags	(	TLV_reception_t	received,
		const TLV_tag_t *	tags,
		size_t	tag_count
	)

Check that every tag in tags was received during parsing.

Prefer the variadic macro TLV_CHECK_RECEIVED_TAGS which wraps this function.

Warning: Do not mix tags belonging to different TLV use cases; the flag mapping is use-case-specific and results would be undefined.

Parameters

[in]	received	Tag-reception tracker filled in by the parser
[in]	tags	Array of tag values that must have been received
[in]	tag_count	Number of entries in `tags`

Returns: true if every listed tag was received, false if any is missing

Definition at line 349 of file tlv_library.c.

◆ tlv_enforce_u8_value()

bool tlv_enforce_u8_value	(	const tlv_data_t *	data,
		uint8_t	expected_value
	)

Enforce that a TLV data contains the expected uint8 value.

Parameters

[in]	data	TLV data to check
[in]	expected_value	Expected uint8 value

Returns: true if the value matches, false otherwise

Definition at line 38 of file tlv_library.c.

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ DEFINE_TLV_PARSER

◆ TLV_CHECK_RECEIVED_TAGS

Typedef Documentation

◆ tag_unicity_t

◆ tlv_data_t

◆ tlv_handler_cb_t

◆ TLV_reception_t

Enumeration Type Documentation

◆ tag_unicity_e

Function Documentation

◆ _parse_tlv_internal()

◆ get_bool_from_tlv_data()

◆ get_buffer_from_tlv_data()

◆ get_string_from_tlv_data()

◆ get_uint16_t_from_tlv_data()

◆ get_uint32_t_from_tlv_data()

◆ get_uint64_t_from_tlv_data()

◆ get_uint8_t_from_tlv_data()

◆ tlv_check_received_tags()

◆ tlv_enforce_u8_value()