stats_tree.h File Reference

#include <epan/epan.h>
#include <epan/packet_info.h>
#include <epan/tap.h>
#include <epan/stat_groups.h>
#include "ws_symbol_export.h"

Go to the source code of this file.

Macros
#define	STAT_TREE_ROOT   "root"
#define	STATS_TREE_MENU_SEPARATOR   "//"
#define	ST_FLG_AVERAGE   0x10000000 /* Calculate averages for nodes, rather than totals */
#define	ST_FLG_ROOTCHILD   0x20000000 /* This node is a direct child of the root node */
#define	ST_FLG_DEF_NOEXPAND   0x01000000 /* This node should not be expanded by default */
#define	ST_FLG_SORT_TOP   0x00400000 /* When sorting always keep these lines on of list */
#define	ST_FLG_SORT_DESC   0x00800000 /* When sorting, sort descending instead of ascending */
#define	ST_FLG_SRTCOL_MASK   0x000F0000 /* Mask for sort column ID */
#define	ST_FLG_SRTCOL_SHIFT   16 /* Number of bits to shift masked result */
#define	ST_FLG_MASK
#define	ST_SORT_COL_NAME   1 /* Sort nodes by node names */
#define	ST_SORT_COL_COUNT   2 /* Sort nodes by node count */
#define	ST_SORT_COL_AVG   3 /* Sort nodes by node average */
#define	ST_SORT_COL_MIN   4 /* Sort nodes by minimum node value */
#define	ST_SORT_COL_MAX   5 /* Sort nodes by maximum node value */
#define	ST_SORT_COL_BURSTRATE   6 /* Sort nodes by burst rate */
#define	stats_tree_tick_range_by_pname(st, name, parent_name, value_in_range)    stats_tree_tick_range((st),(name),stats_tree_parent_id_by_name((st),(parent_name),(value_in_range)))
#define	increase_stat_node(st, name, parent_id, with_children, value)    (stats_tree_manip_node_int(MN_INCREASE,(st),(name),(parent_id),(with_children),(value)))
#define	tick_stat_node(st, name, parent_id, with_children)    (stats_tree_manip_node_int(MN_INCREASE,(st),(name),(parent_id),(with_children),1))
#define	set_stat_node(st, name, parent_id, with_children, value)    (stats_tree_manip_node_int(MN_SET,(st),(name),(parent_id),(with_children),value))
#define	zero_stat_node(st, name, parent_id, with_children)    (stats_tree_manip_node_int(MN_SET,(st),(name),(parent_id),(with_children),0))
#define	avg_stat_node_add_value_notick(st, name, parent_id, with_children, value)    (stats_tree_manip_node_int(MN_AVERAGE_NOTICK,(st),(name),(parent_id),(with_children),value))
#define	avg_stat_node_add_value_int(st, name, parent_id, with_children, value)    (stats_tree_manip_node_int(MN_AVERAGE,(st),(name),(parent_id),(with_children),value))
#define	avg_stat_node_add_value_float(st, name, parent_id, with_children, value)    (stats_tree_manip_node_float(MN_AVERAGE,(st),(name),(parent_id),(with_children),value))
#define	stat_node_set_flags(st, name, parent_id, with_children, flags)    (stats_tree_manip_node_int(MN_SET_FLAGS,(st),(name),(parent_id),(with_children),flags))
#define	stat_node_clear_flags(st, name, parent_id, with_children, flags)    (stats_tree_manip_node_int(MN_CLEAR_FLAGS,(st),(name),(parent_id),(with_children),flags))

Typedefs
typedef struct _stats_tree	stats_tree
typedef tap_packet_status(*	stat_tree_packet_cb) (stats_tree *, packet_info *, epan_dissect_t *, const void *, tap_flags_t flags)
typedef void(*	stat_tree_init_cb) (stats_tree *)
typedef void(*	stat_tree_cleanup_cb) (stats_tree *)
typedef enum _stat_node_datatype	stat_node_datatype
typedef struct _stats_tree_cfg	stats_tree_cfg
typedef enum _manip_node_mode	manip_node_mode

Enumerations
enum	_stat_node_datatype { STAT_DT_INT , STAT_DT_FLOAT }
enum	_manip_node_mode {   MN_INCREASE , MN_SET , MN_AVERAGE , MN_AVERAGE_NOTICK ,   MN_SET_FLAGS , MN_CLEAR_FLAGS }

Functions
void	stats_tree_init (void)
WS_DLL_PUBLIC stats_tree_cfg *	stats_tree_register (const char *tapname, const char *abbr, const char *path, unsigned flags, stat_tree_packet_cb packet, stat_tree_init_cb init, stat_tree_cleanup_cb cleanup)
WS_DLL_PUBLIC stats_tree_cfg *	stats_tree_register_plugin (const char *tapname, const char *abbr, const char *path, unsigned flags, stat_tree_packet_cb packet, stat_tree_init_cb init, stat_tree_cleanup_cb cleanup)
WS_DLL_PUBLIC void	stats_tree_set_group (stats_tree_cfg *st_config, register_stat_group_t stat_group)
WS_DLL_PUBLIC void	stats_tree_set_first_column_name (stats_tree_cfg *st_config, const char *column_name)
WS_DLL_PUBLIC int	stats_tree_parent_id_by_name (stats_tree *st, const char *parent_name)
	Retrieves the parent ID of a node in the stats tree by its name.
WS_DLL_PUBLIC int	stats_tree_create_node (stats_tree *st, const char *name, int parent_id, stat_node_datatype datatype, bool with_children)
WS_DLL_PUBLIC int	stats_tree_create_node_by_pname (stats_tree *st, const char *name, const char *parent_name, stat_node_datatype datatype, bool with_children)
	Creates a node in the statistics tree.
WS_DLL_PUBLIC int	stats_tree_create_range_node (stats_tree *st, const char *name, int parent_id,...)
	Creates a node in the stats tree that will contain a ranges list.
WS_DLL_PUBLIC int	stats_tree_create_range_node_string (stats_tree *st, const char *name, int parent_id, int num_str_ranges, char **str_ranges)
	Creates a range node in the statistics tree with string ranges.
WS_DLL_PUBLIC int	stats_tree_range_node_with_pname (stats_tree *st, const char *name, const char *parent_name,...)
	Increases by one the ranged node and the sub node to whose range the value belongs.
WS_DLL_PUBLIC int	stats_tree_tick_range (stats_tree *st, const char *name, int parent_id, int value_in_range)
	Increment a statistic in a stats tree within a specified range.
WS_DLL_PUBLIC int	stats_tree_create_pivot (stats_tree *st, const char *name, int parent_id)
	Creates a new pivot node in the statistics tree.
WS_DLL_PUBLIC int	stats_tree_create_pivot_by_pname (stats_tree *st, const char *name, const char *parent_name)
	Creates a pivot node in the statistics tree by name.
WS_DLL_PUBLIC int	stats_tree_tick_pivot (stats_tree *st, int pivot_id, const char *pivot_value)
	Ticks a pivot node in the statistics tree.
void	stats_tree_cleanup (void)
	Cleans up the statistics tree registry.
WS_DLL_PUBLIC int	stats_tree_manip_node_int (manip_node_mode mode, stats_tree *st, const char *name, int parent_id, bool with_children, int value)
	Manipulates a node in a statistics tree by increasing its integer value.
WS_DLL_PUBLIC int	stats_tree_manip_node_float (manip_node_mode mode, stats_tree *st, const char *name, int parent_id, bool with_children, float value)
	Manipulates a node in the statistics tree with a float value.

Detailed Description

A counter tree API for Wireshark dissectors 2005, Luis E. G. Ontanon

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

Macro Definition Documentation

ST_FLG_MASK

#define ST_FLG_MASK

Value:

                             (ST_FLG_AVERAGE|ST_FLG_ROOTCHILD|ST_FLG_DEF_NOEXPAND| \
                             ST_FLG_SORT_TOP|ST_FLG_SORT_DESC|ST_FLG_SRTCOL_MASK)

Function Documentation

stats_tree_cleanup()

void stats_tree_cleanup ( void  )

extern

Cleans up the statistics tree registry.

This function destroys the GHashTable that holds the registry of statistics tree nodes.

stats_tree_create_node_by_pname()

WS_DLL_PUBLIC int stats_tree_create_node_by_pname	(	stats_tree *	st,
		const char *	name,
		const char *	parent_name,
		stat_node_datatype	datatype,
		bool	with_children
	)

Creates a node in the statistics tree.

Parameters

st	Pointer to the statistics tree.
name	Name of the node.

Returns

int ID of the created node, or 0 if creation failed.

stats_tree_create_pivot()

WS_DLL_PUBLIC int stats_tree_create_pivot	(	stats_tree *	st,
		const char *	name,
		int	parent_id
	)

Creates a new pivot node in the statistics tree.

Parameters

st	Pointer to the statistics tree.
name	Name of the new pivot node.
parent_id	ID of the parent node.

Returns

int ID of the newly created pivot node, or 0 if creation failed.

stats_tree_create_pivot_by_pname()

WS_DLL_PUBLIC int stats_tree_create_pivot_by_pname	(	stats_tree *	st,
		const char *	name,
		const char *	parent_name
	)

Creates a pivot node in the statistics tree by name.

Parameters

st	Pointer to the statistics tree.
name	Name of the pivot node to create.
parent_name	Name of the parent node for the pivot node.

Returns

int ID of the created pivot node, or 0 if creation fails.

stats_tree_create_range_node()

WS_DLL_PUBLIC int stats_tree_create_range_node	(	stats_tree *	st,
		const char *	name,
		int	parent_id,
			...
	)

Creates a node in the stats tree that will contain a ranges list.

creates a node in the tree, that will contain a ranges list. example: stats_tree_create_range_node(st,name,parent, "-99","100-199","200-299","300-399","400-", NULL);

Parameters

st	Pointer to the stats tree.
name	Name of the new node.
parent_id	ID of the parent node.

Returns

int ID of the created range node.

stats_tree_create_range_node_string()

WS_DLL_PUBLIC int stats_tree_create_range_node_string	(	stats_tree *	st,
		const char *	name,
		int	parent_id,
		int	num_str_ranges,
		char **	str_ranges
	)

Creates a range node in the statistics tree with string ranges.

Parameters

st	Pointer to the statistics tree.
name	Name of the new range node.
parent_id	ID of the parent node.
num_str_ranges	Number of string ranges.
str_ranges	Array of string ranges.

Returns

int ID of the created range node.

stats_tree_init()

void stats_tree_init ( void  )

extern

Initialize the stats tree system.

stats_tree_manip_node_float()

WS_DLL_PUBLIC int stats_tree_manip_node_float	(	manip_node_mode	mode,
		stats_tree *	st,
		const char *	name,
		int	parent_id,
		bool	with_children,
		float	value
	)

Manipulates a node in the statistics tree with a float value.

Parameters

mode	The operation mode (e.g., increase, average).
st	Pointer to the statistics tree.
name	Name of the node.
parent_id	ID of the parent node.
with_children	Flag indicating if children should be included.
value	Float value to manipulate the node with.

Returns

int Result of the operation.

stats_tree_manip_node_int()

WS_DLL_PUBLIC int stats_tree_manip_node_int	(	manip_node_mode	mode,
		stats_tree *	st,
		const char *	name,
		int	parent_id,
		bool	with_children,
		int	value
	)

Manipulates a node in a statistics tree by increasing its integer value.

Parameters

mode	The manipulation mode (e.g., increase or set).
st	The statistics tree to manipulate.
name	The name of the node to manipulate.
parent_id	The ID of the parent node.
with_children	Indicates if children should be included.
value	The integer value to add to the node's counter.

Returns

The result of the manipulation (0 on success, non-zero on failure).

stats_tree_parent_id_by_name()

WS_DLL_PUBLIC int stats_tree_parent_id_by_name	(	stats_tree *	st,
		const char *	parent_name
	)

Retrieves the parent ID of a node in the stats tree by its name.

Parameters

st	The stats_tree to search within.
parent_name	The name of the parent node. NULL for the root node.

Returns

int The ID of the parent node, or 0 if not found (root).

stats_tree_range_node_with_pname()

WS_DLL_PUBLIC int stats_tree_range_node_with_pname	(	stats_tree *	st,
		const char *	name,
		const char *	parent_name,
			...
	)

Increases by one the ranged node and the sub node to whose range the value belongs.

Parameters

st	The statistics tree.
name	The name of the range node.
parent_name	The name of the parent node.

Returns

int The ID of the range node.

stats_tree_register()

WS_DLL_PUBLIC stats_tree_cfg * stats_tree_register	(	const char *	tapname,
		const char *	abbr,
		const char *	path,
		unsigned	flags,
		stat_tree_packet_cb	packet,
		stat_tree_init_cb	init,
		stat_tree_cleanup_cb	cleanup
	)

Registers a new stats tree with default group REGISTER_STAT_GROUP_UNSORTED.

Parameters

abbr	tree abbr (used for tshark -z option)
path	tree display name in GUI menu and window (use "//" for submenus)
flags	tap listener flags for per-packet callback
packet	per packet callback
init	tree initialization callback
cleanup	cleanup callback

Returns

A stats tree configuration pointer.

stats_tree_register_plugin()

WS_DLL_PUBLIC stats_tree_cfg * stats_tree_register_plugin	(	const char *	tapname,
		const char *	abbr,
		const char *	path,
		unsigned	flags,
		stat_tree_packet_cb	packet,
		stat_tree_init_cb	init,
		stat_tree_cleanup_cb	cleanup
	)

Registers a new stats tree with default group REGISTER_STAT_GROUP_UNSORTED from a plugin.

Parameters

abbr	tree abbr (used for tshark -z option)
path	tree display name in GUI menu and window (use "//" for submenus)
flags	tap listener flags for per-packet callback
packet	per packet callback
init	tree initialization callback
cleanup	cleanup callback

Returns

A stats tree configuration pointer.

stats_tree_set_first_column_name()

WS_DLL_PUBLIC void stats_tree_set_first_column_name	(	stats_tree_cfg *	st_config,
		const char *	column_name
	)

Set the name a stats tree's first column. Default is "Topic / Item".

Parameters

column_name

The new column name.

stats_tree_set_group()

WS_DLL_PUBLIC void stats_tree_set_group	(	stats_tree_cfg *	st_config,
		register_stat_group_t	stat_group
	)

Set the menu statistics group for a stats tree.

Parameters

stat_group

A menu group.

stats_tree_tick_pivot()

WS_DLL_PUBLIC int stats_tree_tick_pivot	(	stats_tree *	st,
		int	pivot_id,
		const char *	pivot_value
	)

Ticks a pivot node in the statistics tree.

Increments the counter of the specified pivot node and updates related statistics.

Parameters

st	Pointer to the stats_tree structure.
pivot_id	ID of the pivot node to tick.
pivot_value	Value associated with the pivot node.

Returns

The pivot_id on success, or an error code on failure.

stats_tree_tick_range()

WS_DLL_PUBLIC int stats_tree_tick_range	(	stats_tree *	st,
		const char *	name,
		int	parent_id,
		int	value_in_range
	)

Increment a statistic in a stats tree within a specified range.

Parameters

st	Pointer to the stats tree.
name	Name of the statistic node.
parent_id	ID of the parent node.
value_in_range	Value indicating if the statistic is within its range.

Returns

int The updated value of the statistic node.