#include <epan/tvbuff.h>
#include "ws_symbol_export.h"

Classes
struct	_tvbparse_wanted_t
	Describes a parsing rule or expectation for a tvbuff parser. More...

struct	_tvbparse_t
	Represents an instance of a per-packet parser for tvbuff data. More...

struct	_tvbparse_elem_t
	Represents a single token matched by the tvbuff parser, forming part of a linked tree of parse results. More...

Macros
#define	tvbparse_one_or_more(id, private_data, before_cb, after_cb, wanted) tvbparse_some(id, 1, INT_MAX, private_data, before_cb, after_cb, wanted)

Typedefs
typedef struct _tvbparse_elem_t	tvbparse_elem_t

typedef struct _tvbparse_wanted_t	tvbparse_wanted_t

typedef struct _tvbparse_t	tvbparse_t

typedef void(*	tvbparse_action_t) (void tvbparse_data, const void wanted_data, struct _tvbparse_elem_t *elem)

typedef int(*	tvbparse_condition_t) (tvbparse_t , const int, const tvbparse_wanted_t , tvbparse_elem_t **)

Enumerations
enum	until_mode_t { TP_UNTIL_INCLUDE , TP_UNTIL_SPEND , TP_UNTIL_LEAVE }
	Controls how a parser consumes the terminal element when scanning up to the last token. More...

Functions
WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_char (const int id, const char needles, const void private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
	Create a single-character match element.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_not_char (const int id, const char needle, const void private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
	Create a single-character exclusion match element.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_chars (const int id, const unsigned min_len, const unsigned max_len, const char needles, const void private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
	Create a multi-character span match element.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_not_chars (const int id, const unsigned min_len, const unsigned max_len, const char needles, const void private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
	Create a multi-character exclusion span match element.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_string (const int id, const char string, const void private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
	Create a case-sensitive literal string match element.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_casestring (const int id, const char str, const void data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
	Create a case-insensitive literal string match element.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_until (const int id, const void private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb, const tvbparse_wanted_t ending, until_mode_t until_mode)
	Create an "until" match element that consumes bytes up to a terminator.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_set_oneof (const int id, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb,...)
	Create a one-of alternation element.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_hashed (const int id, const void data, tvbparse_action_t before_cb, tvbparse_action_t after_cb, tvbparse_wanted_t key, tvbparse_wanted_t *other,...)
	Create a hash-dispatch element that selects a sub-element by key.

WS_DLL_PUBLIC void	tvbparse_hashed_add (tvbparse_wanted_t *w,...)
	Adds a hashed element to the wanted list.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_set_seq (const int id, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb,...)
	Create a sequential composition element.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_some (const int id, const unsigned min, const unsigned max, const void data, tvbparse_action_t before_cb, tvbparse_action_t after_cb, const tvbparse_wanted_t wanted)
	Creates a parsing element that matches a given candidate a specified number of times.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_handle (tvbparse_wanted_t **handle)
	Create an indirect reference element for recursive grammars.

WS_DLL_PUBLIC tvbparse_wanted_t *	tvbparse_quoted (const int id, const void *data, tvbparse_action_t before_cb, tvbparse_action_t after_cb, const char quote, const char escape)
	Parses quoted strings in a given data buffer.

WS_DLL_PUBLIC void	tvbparse_shrink_token_cb (void tvbparse_data, const void wanted_data, tvbparse_elem_t *tok)
	Callback function to shrink token length and offset.

WS_DLL_PUBLIC tvbparse_t *	tvbparse_init (wmem_allocator_t scope, tvbuff_t tvb, const int offset, int len, void private_data, const tvbparse_wanted_t ignore)
	Initialize a new TVB parser.

WS_DLL_PUBLIC bool	tvbparse_reset (tvbparse_t *tt, const unsigned offset, unsigned len)
	Resets the token buffer parser to a new offset and length.

WS_DLL_PUBLIC unsigned	tvbparse_curr_offset (tvbparse_t *tt)
	Get the current offset in the TVB parse structure.

unsigned	tvbparse_len_left (tvbparse_t *tt)
	Get the number of bytes left to parse in the TVB parse structure.

WS_DLL_PUBLIC bool	tvbparse_peek (tvbparse_t tt, const tvbparse_wanted_t wanted)
	Peeks at the next token in the buffer without advancing the parser.

WS_DLL_PUBLIC tvbparse_elem_t *	tvbparse_get (tvbparse_t tt, const tvbparse_wanted_t wanted)
	Retrieves a token based on the specified conditions.

WS_DLL_PUBLIC tvbparse_elem_t *	tvbparse_find (tvbparse_t tt, const tvbparse_wanted_t wanted)
	Finds an element in a TVB parse structure based on a given condition.

WS_DLL_PUBLIC void	tvbparse_tree_add_elem (proto_tree tree, tvbparse_elem_t curr)
	Adds an element to a protocol tree.

Detailed Description

an API for text tvb parsers

SPDX-License-Identifier: GPL-2.0-or-later

Enumeration Type Documentation

◆ until_mode_t

enum until_mode_t

Controls how a parser consumes the terminal element when scanning up to the last token.

Enumerator
TP_UNTIL_INCLUDE	The last element is included in the result and its span is consumed by the parser
TP_UNTIL_SPEND	The last element is excluded from the result but its span is still consumed by the parser
TP_UNTIL_LEAVE	The last element is excluded from the result and its span is left unconsumed for the next parse step

Function Documentation

◆ tvbparse_casestring()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_casestring	(	const int	id,
		const char *	str,
		const void *	data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb
	)

Create a case-insensitive literal string match element.

When looked for it returns a simple element if we have a matching string at the current offset

Parameters

id	Caller-assigned identifier stored in the returned element.
str	The literal string to match case-insensitively.
data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.

Returns: A newly allocated tvbparse_wanted_t describing this element.

◆ tvbparse_char()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_char	(	const int	id,
		const char *	needles,
		const void *	private_data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb
	)

Create a single-character match element.

Matches exactly one byte at the current parser offset if that byte is present in needles. On success returns a simple element one byte long.

Parameters

id	Caller-assigned identifier stored in the returned element.
needles	A string whose characters form the set of accepted bytes.
private_data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.

Returns: A newly allocated tvbparse_wanted_t describing this element.

◆ tvbparse_chars()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_chars	(	const int	id,
		const unsigned	min_len,
		const unsigned	max_len,
		const char *	needles,
		const void *	private_data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb
	)

Create a multi-character span match element.

When looked for it returns a simple element one or more characters long if one or more char(s) starting from the current offset match one of the needles. An element will be returned if at least min_len chars are given (1 if it's 0) It will get at most max_len chars or as much as it can if max_len is 0.

Parameters

id	Caller-assigned identifier stored in the returned element.
min_len	Minimum number of matching bytes required for success; treated as 1 if 0.
max_len	Maximum number of bytes to consume; 0 means unlimited.
needles	A string whose characters form the set of accepted bytes.
private_data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.

Returns: A newly allocated tvbparse_wanted_t describing this element.

◆ tvbparse_curr_offset()

WS_DLL_PUBLIC unsigned tvbparse_curr_offset ( tvbparse_t * tt )

Get the current offset in the TVB parse structure.

Parameters

tt	Pointer to the TVB parse structure.

Returns: The current offset.

◆ tvbparse_find()

WS_DLL_PUBLIC tvbparse_elem_t * tvbparse_find	(	tvbparse_t *	tt,
		const tvbparse_wanted_t *	wanted
	)

Finds an element in a TVB parse structure based on a given condition.

Like tvbparse_get but this will look for a wanted token even beyond the current offset. This function is slow.

Parameters

tt	Pointer to the TVB parse structure.
wanted	Pointer to the wanted element description, including the condition function.

Returns: Pointer to the found element if successful, NULL otherwise.

◆ tvbparse_get()

WS_DLL_PUBLIC tvbparse_elem_t * tvbparse_get	(	tvbparse_t *	tt,
		const tvbparse_wanted_t *	wanted
	)

Retrieves a token based on the specified conditions.

This will look for the wanted token at the current offset or after any given number of ignored tokens returning NULL if there's no match. if there is a match it will set the offset of the current parser after the end of the token

Parameters

tt	Pointer to the TVB parse context.
wanted	Pointer to the structure containing the conditions for the desired token.

Returns: Pointer to the retrieved token if successful, NULL otherwise.

◆ tvbparse_handle()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_handle ( tvbparse_wanted_t ** handle )

Create an indirect reference element for recursive grammars.

this is a pointer to a pointer to a wanted element (that might have not been initialized yet) so that recursive structures

Parameters

handle Pointer to the tvbparse_wanted_t* that will be resolved at match time. The pointed-to value must be non-NULL before the first call to tvbparse_get() or tvbparse_find() that may reach this element.

Returns: A newly allocated tvbparse_wanted_t that indirects through handle when matched.

◆ tvbparse_hashed()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_hashed	(	const int	id,
		const void *	data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb,
		tvbparse_wanted_t *	key,
		tvbparse_wanted_t *	other,
			...
	)

Create a hash-dispatch element that selects a sub-element by key.

Parameters

id	Caller-assigned identifier stored in the returned element.
data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.
key	The element used to extract the dispatch key string.
other	Fallback element used when the key has no hash entry; NULL to fail the match when no entry is found.
...	Optional additional NULL-terminated alternating pairs of `char` key name and `tvbparse_wanted_t` element.

Returns: A newly allocated tvbparse_wanted_t describing this element.

◆ tvbparse_hashed_add()

WS_DLL_PUBLIC void tvbparse_hashed_add	(	tvbparse_wanted_t *	w,
			...
	)

Adds a hashed element to the wanted list.

Parameters

w	Pointer to the tvbparse_wanted_t structure.
...	Variable arguments, alternating between name (char) and element (tvbparse_wanted_t).

◆ tvbparse_init()

WS_DLL_PUBLIC tvbparse_t * tvbparse_init	(	wmem_allocator_t *	scope,
		tvbuff_t *	tvb,
		const int	offset,
		int	len,
		void *	private_data,
		const tvbparse_wanted_t *	ignore
	)

Initialize a new TVB parser.

initialize the parser (at every packet) scope: memory scope/pool tvb: what are we parsing? offset: from where len: for how many bytes private_data: will be passed to the action callbacks ignore: a wanted token type to be ignored (the associated cb WILL be called when it matches)

Parameters

scope	Memory allocation scope for the parser.
tvb	The input tvbuff to parse.
offset	Starting offset within the tvbuff.
len	Length of data to parse, or -1 to use the entire captured length.
private_data	Private data to associate with the parser.
ignore	Configuration for ignored elements during parsing.

Returns: Pointer to the initialized tvbparse_t structure.

◆ tvbparse_len_left()

unsigned tvbparse_len_left ( tvbparse_t * tt )

Get the number of bytes left to parse in the TVB parse structure.

Parameters

tt	Pointer to the TVB parse structure.

Returns: The number of bytes left to parse.

◆ tvbparse_not_char()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_not_char	(	const int	id,
		const char *	needle,
		const void *	private_data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb
	)

Create a single-character exclusion match element.

When looked for it returns a simple element one character long if the char at the current offset does not match one of the needles.

Parameters

id	Caller-assigned identifier stored in the returned element.
needle	A string whose characters form the set of rejected bytes.
private_data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.

Returns: A newly allocated tvbparse_wanted_t describing this element.

◆ tvbparse_not_chars()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_not_chars	(	const int	id,
		const unsigned	min_len,
		const unsigned	max_len,
		const char *	needles,
		const void *	private_data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb
	)

Create a multi-character exclusion span match element.

When looked for it returns a simple element one or more characters long if one or more char(s) starting from the current offset do not match one of the needles. An element will be returned if at least min_len chars are given (1 if it's 0) It will get at most max_len chars or as much as it can if max_len is 0.

Parameters

id	Caller-assigned identifier stored in the returned element.
min_len	Minimum number of non-matching bytes required for success; treated as 1 if 0.
max_len	Maximum number of bytes to consume; 0 means unlimited.
needles	A string whose characters form the set of rejected bytes.
private_data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.

Returns: A newly allocated tvbparse_wanted_t describing this element.

◆ tvbparse_peek()

WS_DLL_PUBLIC bool tvbparse_peek	(	tvbparse_t *	tt,
		const tvbparse_wanted_t *	wanted
	)

Peeks at the next token in the buffer without advancing the parser.

This will look for the wanted token at the current offset or after any given number of ignored tokens returning false if there's no match or true if there is a match. The parser will be left in its original state and no callbacks will be called.

Parameters

tt	Pointer to the tvbparse_t structure representing the parser state.
wanted	Pointer to the tvbparse_wanted_t structure describing the token to look for.

Returns: True if a match is found, false otherwise.

◆ tvbparse_quoted()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_quoted	(	const int	id,
		const void *	data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb,
		const char	quote,
		const char	escape
	)

Parses quoted strings in a given data buffer.

this is a composed candidate, that will try to match a quoted string (included the quotes) including into it every escaped quote.

C strings are matched with tvbparse_quoted(-1,NULL,NULL,NULL,"\"","\\")

Parameters

id	Identifier for the parsed token.
data	Pointer to the data buffer containing the quoted strings.
before_cb	Callback function to be invoked before parsing.
after_cb	Callback function to be invoked after parsing.
quote	Character used as the quote delimiter.
escape	Character used for escaping special characters within quotes.

Returns: A tvbparse_wanted_t structure representing the parsed quoted strings.

◆ tvbparse_reset()

WS_DLL_PUBLIC bool tvbparse_reset	(	tvbparse_t *	tt,
		const unsigned	offset,
		unsigned	len
	)

Resets the token buffer parser to a new offset and length.

Parameters

tt	Pointer to the tvbparse_t structure.
offset	The new starting offset for parsing.
len	The new length of data to parse.

Returns: true if the reset is successful, false otherwise.

◆ tvbparse_set_oneof()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_set_oneof	(	const int	id,
		const void *	private_data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb,
			...
	)

Create a one-of alternation element.

When looked for it will try to match to the given candidates and return a composed element whose subelement is the first match.

The list of candidates is terminated with a NULL

Parameters

id	Caller-assigned identifier stored in the returned element.
private_data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.
...	NULL-terminated list of `tvbparse_wanted_t*` candidates to try in order.

Returns: A newly allocated tvbparse_wanted_t describing this alternation.

◆ tvbparse_set_seq()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_set_seq	(	const int	id,
		const void *	private_data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb,
			...
	)

Create a sequential composition element.

When looked for it will try to match in order all the given candidates. If every candidate is found in the given order it will return a composed element whose subelements are the matched elements.

The list of candidates is terminated with a NULL.

Parameters

id	Caller-assigned identifier stored in the returned element.
private_data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the sequence is consumed, or NULL.
after_cb	Callback invoked after the sequence is consumed, or NULL.
...	NULL-terminated list of `tvbparse_wanted_t*` candidates to match in order.

Returns: A newly allocated tvbparse_wanted_t describing this sequence.

◆ tvbparse_shrink_token_cb()

WS_DLL_PUBLIC void tvbparse_shrink_token_cb	(	void *	tvbparse_data,
		const void *	wanted_data,
		tvbparse_elem_t *	tok
	)

Callback function to shrink token length and offset.

This callback is invoked before or after an element has been processed. It adjusts the token's offset and length by incrementing the offset and decrementing the length by 2.

Parameters

tvbparse_data	User data passed to the callback (not used).
wanted_data	Wanted data for the element (not used).
tok	Pointer to the current token being processed.

◆ tvbparse_some()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_some	(	const int	id,
		const unsigned	min,
		const unsigned	max,
		const void *	data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb,
		const tvbparse_wanted_t *	wanted
	)

Creates a parsing element that matches a given candidate a specified number of times.

When looked for it will try to match the given candidate at least min times and at most max times. If the given candidate is matched at least min times a composed element is returned.

Parameters

id	Identifier for the parsing element.
min	Minimum number of times the candidate should be matched.
max	Maximum number of times the candidate should be matched.
data	User-defined data to be associated with the parsing element.
before_cb	Callback function to be called before parsing the element.
after_cb	Callback function to be called after parsing the element.
wanted	The candidate element to be matched repeatedly.

Returns: A pointer to a tvbparse_wanted_t structure representing the parsing element.

◆ tvbparse_string()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_string	(	const int	id,
		const char *	string,
		const void *	private_data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb
	)

Create a case-sensitive literal string match element.

When looked for it returns a simple element if we have the given string at the current offset

Parameters

id	Caller-assigned identifier stored in the returned element.
string	The literal byte sequence to match.
private_data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.

Returns: A newly allocated tvbparse_wanted_t describing this element.

◆ tvbparse_tree_add_elem()

WS_DLL_PUBLIC void tvbparse_tree_add_elem	(	proto_tree *	tree,
		tvbparse_elem_t *	curr
	)

Adds an element to a protocol tree.

Parameters

tree	The protocol tree to which the element will be added.
curr	The current element being processed.

◆ tvbparse_until()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_until	(	const int	id,
		const void *	private_data,
		tvbparse_action_t	before_cb,
		tvbparse_action_t	after_cb,
		const tvbparse_wanted_t *	ending,
		until_mode_t	until_mode
	)

Create an "until" match element that consumes bytes up to a terminator.

When looked for it returns a simple element containing all the characters found until the first match of the ending element if the ending element is

When looking for until elements it calls tvbparse_find so it can be very slow.

It won't have a subelement, the ending's callbacks won't get called. op_mode values determine how the terminating element and the current offset of the parser are handled

Parameters

id	Caller-assigned identifier stored in the returned element.
private_data	Opaque caller data passed to the callbacks.
before_cb	Callback invoked before the match is consumed, or NULL.
after_cb	Callback invoked after the match is consumed, or NULL.
ending	The terminating element to search for.
until_mode	Controls how the terminator affects the returned element and parser offset.

Returns: A newly allocated tvbparse_wanted_t describing this element.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ until_mode_t

Function Documentation

◆ tvbparse_casestring()

◆ tvbparse_char()

◆ tvbparse_chars()

◆ tvbparse_curr_offset()

◆ tvbparse_find()

◆ tvbparse_get()

◆ tvbparse_handle()

◆ tvbparse_hashed()

◆ tvbparse_hashed_add()

◆ tvbparse_init()

◆ tvbparse_len_left()

◆ tvbparse_not_char()

◆ tvbparse_not_chars()

◆ tvbparse_peek()

◆ tvbparse_quoted()

◆ tvbparse_reset()

◆ tvbparse_set_oneof()

◆ tvbparse_set_seq()

◆ tvbparse_shrink_token_cb()

◆ tvbparse_some()

◆ tvbparse_string()

◆ tvbparse_tree_add_elem()

◆ tvbparse_until()