tvbparse.h File Reference

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

Go to the source code of this file.

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

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 }

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)
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)
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)
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)
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)
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)
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)
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,...)
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,...)
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,...)
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)
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)
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

Copyright 2005, Luis E. Garcia Ontanon luis@.nosp@m.onta.nosp@m.non.o.nosp@m.rg

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

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

Function Documentation

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_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_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_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.

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.