| Wireshark 4.7.3 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Macros | Typedefs | Enumerations | Functions
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)
#define | increase_stat_node(st, name, parent_id, with_children, value)
#define | tick_stat_node(st, name, parent_id, with_children)
#define | set_stat_node(st, name, parent_id, with_children, value)
#define | zero_stat_node(st, name, parent_id, with_children)
#define | avg_stat_node_add_value_notick(st, name, parent_id, with_children, value)
#define | avg_stat_node_add_value_int(st, name, parent_id, with_children, value)
#define | avg_stat_node_add_value_float(st, name, parent_id, with_children, value)
#define | stat_node_set_flags(st, name, parent_id, with_children, flags)
#define | stat_node_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
| Numeric data type stored in a statistics tree node's accumulator.
typedef struct _stats_tree_cfg | stats_tree_cfg
typedef enum _manip_node_mode | manip_node_mode
| Operation applied to a statistics tree node's value when it is manipulated.

## Enumerations
enum | _stat_node_datatype { STAT_DT_INT , STAT_DT_FLOAT }
| Numeric data type stored in a statistics tree node's accumulator. More...
enum | _manip_node_mode { MN_INCREASE , MN_SET , MN_AVERAGE , MN_AVERAGE_NOTICK , MN_SET_FLAGS , MN_CLEAR_FLAGS }
| Operation applied to a statistics tree node's value when it is manipulated. More...

## 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)
| Creates a node in the tree (to be used in the in init_cb).
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 using its parent's tree name.
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

## ◆ avg_stat_node_add_value_float

#define avg_stat_node_add_value_float | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children,
|  |  | value )

Value:
(stats_tree_manip_node_float(MN_AVERAGE,(st),(name),(parent_id),(with_children),value))
MN_AVERAGE
@ MN_AVERAGE
Definition stats_tree.h:294

## ◆ avg_stat_node_add_value_int

#define avg_stat_node_add_value_int | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children,
|  |  | value )

Value:
(stats_tree_manip_node_int(MN_AVERAGE,(st),(name),(parent_id),(with_children),value))

## ◆ avg_stat_node_add_value_notick

#define avg_stat_node_add_value_notick | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children,
|  |  | value )

Value:
(stats_tree_manip_node_int(MN_AVERAGE_NOTICK,(st),(name),(parent_id),(with_children),value))
MN_AVERAGE_NOTICK
@ MN_AVERAGE_NOTICK
Definition stats_tree.h:295

## ◆ increase_stat_node

#define increase_stat_node | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children,
|  |  | value )

Value:
(stats_tree_manip_node_int(MN_INCREASE,(st),(name),(parent_id),(with_children),(value)))
MN_INCREASE
@ MN_INCREASE
Definition stats_tree.h:292

## ◆ set_stat_node

#define set_stat_node | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children,
|  |  | value )

Value:
(stats_tree_manip_node_int(MN_SET,(st),(name),(parent_id),(with_children),value))
MN_SET
@ MN_SET
Definition stats_tree.h:293

## ◆ 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)

## ◆ stat_node_clear_flags

#define stat_node_clear_flags | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children,
|  |  | flags )

Value:
(stats_tree_manip_node_int(MN_CLEAR_FLAGS,(st),(name),(parent_id),(with_children),flags))
MN_CLEAR_FLAGS
@ MN_CLEAR_FLAGS
Definition stats_tree.h:297

## ◆ stat_node_set_flags

#define stat_node_set_flags | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children,
|  |  | flags )

Value:
(stats_tree_manip_node_int(MN_SET_FLAGS,(st),(name),(parent_id),(with_children),flags))
MN_SET_FLAGS
@ MN_SET_FLAGS
Definition stats_tree.h:296

## ◆ stats_tree_tick_range_by_pname

#define stats_tree_tick_range_by_pname | ( |  | st,
|  |  | name,
|  |  | parent_name,
|  |  | value_in_range )

Value:
stats_tree_tick_range((st),(name),stats_tree_parent_id_by_name((st),(parent_name),(value_in_range)))

## ◆ tick_stat_node

#define tick_stat_node | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children )

Value:
(stats_tree_manip_node_int(MN_INCREASE,(st),(name),(parent_id),(with_children),1))

## ◆ zero_stat_node

#define zero_stat_node | ( |  | st,
|  |  | name,
|  |  | parent_id,
|  |  | with_children )

Value:
(stats_tree_manip_node_int(MN_SET,(st),(name),(parent_id),(with_children),0))

## Typedef Documentation

## ◆ manip_node_mode

typedef enum _manip_node_mode manip_node_mode

Operation applied to a statistics tree node's value when it is manipulated.

If the target node does not exist it is created with a counter of 1. Pass the parent node name (or NULL for root) and with_children=true to indicate that the created node will itself serve as a parent.

## Enumeration Type Documentation

## ◆ _manip_node_mode

enum _manip_node_mode

Operation applied to a statistics tree node's value when it is manipulated.

If the target node does not exist it is created with a counter of 1. Pass the parent node name (or NULL for root) and with_children=true to indicate that the created node will itself serve as a parent.

Enumerator
MN_INCREASE | Increment the node's counter by the given value
MN_SET | Set the node's value to an explicit value
MN_AVERAGE | Update the node's running average and tick the sample count
MN_AVERAGE_NOTICK | Update the node's running average without incrementing the sample count
MN_SET_FLAGS | Bitwise OR the given flags into the node's flags field
MN_CLEAR_FLAGS | Bitwise AND-NOT the given flags from the node's flags field

## ◆ _stat_node_datatype

enum _stat_node_datatype

Numeric data type stored in a statistics tree node's accumulator.

Enumerator
STAT_DT_INT | Node accumulates a signed integer value
STAT_DT_FLOAT | Node accumulates a floating-point value

## 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()

WS_DLL_PUBLIC int stats_tree_create_node | ( | stats_tree * | st,
|  | const char * | name,
|  | int | parent_id,
|  | stat_node_datatype | datatype,
|  | bool | with_children )

Creates a node in the tree (to be used in the in init_cb).

Parameters

  st | Pointer to the statistics tree structure.
  name | Name of the new node.
  parent_id | ID of the parent node. (NULL for root)
  datatype | Data type of the node.
  with_children | true if this node will have "dynamically created" children.

Returns
  ID of the created node, or 0 on failure.

## ◆ 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 using its parent's tree name.

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.