epan/stats_tree.h

   1 /** @file
   2  * A counter tree API for Wireshark dissectors
   3  * 2005, Luis E. G. Ontanon
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11 #ifndef __STATS_TREE_H
  12 #define __STATS_TREE_H
  13
  14 #include <epan/epan.h>
  15 #include <epan/packet_info.h>
  16 #include <epan/tap.h>
  17 #include <epan/stat_groups.h>
  18 #include "ws_symbol_export.h"
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif /* __cplusplus */
  23
  24 #define STAT_TREE_ROOT "root"
  25 #define STATS_TREE_MENU_SEPARATOR "//"
  26
  27 #define ST_FLG_AVERAGE      0x10000000  /* Calculate averages for nodes, rather than totals */
  28 #define ST_FLG_ROOTCHILD    0x20000000  /* This node is a direct child of the root node */
  29 #define ST_FLG_DEF_NOEXPAND 0x01000000  /* This node should not be expanded by default */
  30 #define ST_FLG_SORT_DESC    0x00800000  /* When sorting, sort ascending instead of descending */
  31 #define ST_FLG_SORT_TOP     0x00400000  /* When sorting always keep these lines on of list */
  32 #define ST_FLG_SRTCOL_MASK  0x000F0000  /* Mask for sort column ID */
  33 #define ST_FLG_SRTCOL_SHIFT 16          /* Number of bits to shift masked result */
  34
  35 #define ST_FLG_MASK         (ST_FLG_AVERAGE|ST_FLG_ROOTCHILD|ST_FLG_DEF_NOEXPAND| \
  36                              ST_FLG_SORT_TOP|ST_FLG_SORT_DESC|ST_FLG_SRTCOL_MASK)
  37
  38 #define ST_SORT_COL_NAME      1         /* Sort nodes by node names */
  39 #define ST_SORT_COL_COUNT     2         /* Sort nodes by node count */
  40 #define ST_SORT_COL_AVG       3         /* Sort nodes by node average */
  41 #define ST_SORT_COL_MIN       4         /* Sort nodes by minimum node value */
  42 #define ST_SORT_COL_MAX       5         /* Sort nodes by maximum node value */
  43 #define ST_SORT_COL_BURSTRATE 6         /* Sort nodes by burst rate */
  44
  45 /* obscure information regarding the stats_tree */
  46 typedef struct _stats_tree stats_tree;
  47
  48 /* tap packet callback for stats_tree */
  49 typedef tap_packet_status (*stat_tree_packet_cb)(stats_tree*,
  50                                                  packet_info *,
  51                                                  epan_dissect_t *,
  52                                                  const void *,
  53                                                  tap_flags_t flags);
  54
  55 /* stats_tree initialization callback */
  56 typedef void  (*stat_tree_init_cb)(stats_tree *);
  57
  58 /* stats_tree cleanup callback */
  59 typedef void  (*stat_tree_cleanup_cb)(stats_tree *);
  60
  61 typedef enum _stat_node_datatype {
  62     STAT_DT_INT,
  63     STAT_DT_FLOAT
  64 } stat_node_datatype;
  65
  66 typedef struct _stats_tree_cfg stats_tree_cfg;
  67
  68 /**
  69  * Registers a new stats tree with default group REGISTER_STAT_GROUP_UNSORTED.
  70  * @param abbr tree abbr (used for tshark -z option)
  71  * @param path tree display name in GUI menu and window (use "//" for submenus)
  72  * @param flags tap listener flags for per-packet callback
  73  * @param packet per packet callback
  74  * @param init tree initialization callback
  75  * @param cleanup cleanup callback
  76  * @return A stats tree configuration pointer.
  77  */
  78 WS_DLL_PUBLIC stats_tree_cfg *stats_tree_register(const char *tapname,
  79                                        const char *abbr,
  80                                        const char *path,
  81                                        unsigned flags,
  82                                        stat_tree_packet_cb packet,
  83                                        stat_tree_init_cb init,
  84                                        stat_tree_cleanup_cb cleanup);
  85
  86 /**
  87  * Registers a new stats tree with default group REGISTER_STAT_GROUP_UNSORTED from a plugin.
  88  * @param abbr tree abbr (used for tshark -z option)
  89  * @param path tree display name in GUI menu and window (use "//" for submenus)
  90  * @param flags tap listener flags for per-packet callback
  91  * @param packet per packet callback
  92  * @param init tree initialization callback
  93  * @param cleanup cleanup callback
  94  * @return A stats tree configuration pointer.
  95  */
  96 WS_DLL_PUBLIC stats_tree_cfg *stats_tree_register_plugin(const char *tapname,
  97                                               const char *abbr,
  98                                               const char *path,
  99                                               unsigned flags,
 100                                               stat_tree_packet_cb packet,
 101                                               stat_tree_init_cb init,
 102                                               stat_tree_cleanup_cb cleanup);
 103
 104 /**
 105  * Set the menu statistics group for a stats tree.
 106  * @param stat_group A menu group.
 107  */
 108 WS_DLL_PUBLIC void stats_tree_set_group(stats_tree_cfg *st_config, register_stat_group_t stat_group);
 109
 110 /**
 111  * Set the name a stats tree's first column.
 112  * Default is "Topic / Item".
 113  * @param column_name The new column name.
 114  */
 115 WS_DLL_PUBLIC void stats_tree_set_first_column_name(stats_tree_cfg *st_config, const char *column_name);
 116
 117
 118 WS_DLL_PUBLIC int stats_tree_parent_id_by_name(stats_tree *st, const char *parent_name);
 119
 120 /* Creates a node in the tree (to be used in the in init_cb)
 121  * st: the stats_tree in which to create it
 122  * name: the name of the new node
 123  * parent_name: the name of the parent_node (NULL for root)
 124  * datatype: datatype used for the value of the node
 125  * with_children: true if this node will have "dynamically created" children
 126  */
 127 WS_DLL_PUBLIC int stats_tree_create_node(stats_tree *st,
 128                                          const char *name,
 129                                          int parent_id,
 130                                          stat_node_datatype datatype,
 131                                          bool with_children);
 132
 133 /* creates a node using its parent's tree name */
 134 WS_DLL_PUBLIC int stats_tree_create_node_by_pname(stats_tree *st,
 135                                                   const char *name,
 136                                                   const char *parent_name,
 137                                                   stat_node_datatype datatype,
 138                                                   bool with_children);
 139
 140 /* creates a node in the tree, that will contain a ranges list.
 141    example:
 142    stats_tree_create_range_node(st,name,parent,
 143    "-99","100-199","200-299","300-399","400-", NULL);
 144 */
 145 WS_DLL_PUBLIC int stats_tree_create_range_node(stats_tree *st,
 146                                                const char *name,
 147                                                int parent_id,
 148                                                ...);
 149
 150 WS_DLL_PUBLIC int stats_tree_create_range_node_string(stats_tree *st,
 151                                                       const char *name,
 152                                                       int parent_id,
 153                                                       int num_str_ranges,
 154                                                       char** str_ranges);
 155
 156 WS_DLL_PUBLIC int stats_tree_range_node_with_pname(stats_tree *st,
 157                                                    const char *name,
 158                                                    const char *parent_name,
 159                                                    ...);
 160
 161 /* increases by one the ranged node and the sub node to whose range the value belongs */
 162 WS_DLL_PUBLIC int stats_tree_tick_range(stats_tree *st,
 163                                         const char *name,
 164                                         int parent_id,
 165                                         int value_in_range);
 166
 167 #define stats_tree_tick_range_by_pname(st,name,parent_name,value_in_range) \
 168     stats_tree_tick_range((st),(name),stats_tree_parent_id_by_name((st),(parent_name),(value_in_range)))
 169
 170 /* */
 171 WS_DLL_PUBLIC int stats_tree_create_pivot(stats_tree *st,
 172                                           const char *name,
 173                                           int parent_id);
 174
 175 WS_DLL_PUBLIC int stats_tree_create_pivot_by_pname(stats_tree *st,
 176                                                    const char *name,
 177                                                    const char *parent_name);
 178
 179 WS_DLL_PUBLIC int stats_tree_tick_pivot(stats_tree *st,
 180                                         int pivot_id,
 181                                         const char *pivot_value);
 182
 183 extern void stats_tree_cleanup(void);
 184
 185
 186 /*
 187  * manipulates the value of the node whose name is given
 188  * if the node does not exist yet it's created (with counter=1)
 189  * using parent_name as parent node (NULL for root).
 190  * with_children=true to indicate that the created node will be a parent
 191  */
 192 typedef enum _manip_node_mode {
 193     MN_INCREASE,
 194     MN_SET,
 195     MN_AVERAGE,
 196     MN_AVERAGE_NOTICK,
 197     MN_SET_FLAGS,
 198     MN_CLEAR_FLAGS
 199 } manip_node_mode;
 200 WS_DLL_PUBLIC int stats_tree_manip_node_int(manip_node_mode mode,
 201                                         stats_tree *st,
 202                                         const char *name,
 203                                         int parent_id,
 204                                         bool with_children,
 205                                         int value);
 206
 207 WS_DLL_PUBLIC int stats_tree_manip_node_float(manip_node_mode mode,
 208                                         stats_tree *st,
 209                                         const char *name,
 210                                         int parent_id,
 211                                         bool with_children,
 212                                         float value);
 213
 214 #define increase_stat_node(st,name,parent_id,with_children,value)       \
 215     (stats_tree_manip_node_int(MN_INCREASE,(st),(name),(parent_id),(with_children),(value)))
 216
 217 #define tick_stat_node(st,name,parent_id,with_children)                 \
 218     (stats_tree_manip_node_int(MN_INCREASE,(st),(name),(parent_id),(with_children),1))
 219
 220 #define set_stat_node(st,name,parent_id,with_children,value)            \
 221     (stats_tree_manip_node_int(MN_SET,(st),(name),(parent_id),(with_children),value))
 222
 223 #define zero_stat_node(st,name,parent_id,with_children)                 \
 224     (stats_tree_manip_node_int(MN_SET,(st),(name),(parent_id),(with_children),0))
 225
 226 /*
 227  * Add value to average calculation WITHOUT ticking node. Node MUST be ticked separately!
 228  *
 229  * Intention is to allow code to separately tick node (backward compatibility for plugin)
 230  * and set value to use for averages. Older versions without average support will then at
 231  * least show a count instead of 0.
 232  */
 233 #define avg_stat_node_add_value_notick(st,name,parent_id,with_children,value) \
 234     (stats_tree_manip_node_int(MN_AVERAGE_NOTICK,(st),(name),(parent_id),(with_children),value))
 235
 236 /* Tick node and add a new value to the average calculation for this stats node. */
 237 #define avg_stat_node_add_value_int(st,name,parent_id,with_children,value)  \
 238     (stats_tree_manip_node_int(MN_AVERAGE,(st),(name),(parent_id),(with_children),value))
 239
 240 #define avg_stat_node_add_value_float(st,name,parent_id,with_children,value)  \
 241     (stats_tree_manip_node_float(MN_AVERAGE,(st),(name),(parent_id),(with_children),value))
 242
 243 /* Set flags for this node. Node created if it does not yet exist. */
 244 #define stat_node_set_flags(st,name,parent_id,with_children,flags)      \
 245     (stats_tree_manip_node_int(MN_SET_FLAGS,(st),(name),(parent_id),(with_children),flags))
 246
 247 /* Clear flags for this node. Node created if it does not yet exist. */
 248 #define stat_node_clear_flags(st,name,parent_id,with_children,flags)    \
 249     (stats_tree_manip_node_int(MN_CLEAR_FLAGS,(st),(name),(parent_id),(with_children),flags))
 250
 251 #ifdef __cplusplus
 252 }
 253 #endif /* __cplusplus */
 254
 255 #endif /* __STATS_TREE_H */
 256
 257 /*
 258  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 259  *
 260  * Local variables:
 261  * c-basic-offset: 4
 262  * tab-width: 8
 263  * indent-tabs-mode: nil
 264  * End:
 265  *
 266  * vi: set shiftwidth=4 tabstop=8 expandtab:
 267  * :indentSize=4:tabSize=8:noTabs=true:
 268  */