epan/stats_tree.h

   1 /* stats_tree.h
   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  * This program is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU General Public License
  11  * as published by the Free Software Foundation; either version 2
  12  * of the License, or (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  22  */
  23 #ifndef __STATS_TREE_H
  24 #define __STATS_TREE_H
  25
  26 #include <glib.h>
  27 #include <epan/epan.h>
  28 #include <epan/packet_info.h>
  29 #include <epan/tap.h>
  30 #include <epan/stat_groups.h>
  31 #include "../register.h"
  32 #include "ws_symbol_export.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif /* __cplusplus */
  37
  38 #define STAT_TREE_ROOT "root"
  39
  40 #define ST_FLG_AVERAGE      0x10000000  /* Calculate averages for nodes, rather than totals */
  41 #define ST_FLG_ROOTCHILD    0x20000000  /* This node is a direct child of the root node */
  42 #define ST_FLG_DEF_NOEXPAND 0x01000000  /* This node should not be expanded by default */
  43 #define ST_FLG_SORT_DESC    0x00800000  /* When sorting, sort ascending instead of decending */
  44 #define ST_FLG_SORT_TOP     0x00400000  /* When sorting always keep these lines on of list */
  45 #define ST_FLG_SRTCOL_MASK  0x000F0000  /* Mask for sort column ID */
  46 #define ST_FLG_SRTCOL_SHIFT 16          /* Number of bits to shift masked result */
  47
  48 #define ST_FLG_MASK         (ST_FLG_AVERAGE|ST_FLG_ROOTCHILD|ST_FLG_DEF_NOEXPAND| \
  49                              ST_FLG_SORT_TOP|ST_FLG_SORT_DESC|ST_FLG_SRTCOL_MASK)
  50
  51 #define ST_SORT_COL_NAME      1         /* Sort nodes by node names */
  52 #define ST_SORT_COL_COUNT     2         /* Sort nodes by node count */
  53 #define ST_SORT_COL_AVG       3         /* Sort nodes by node average */
  54 #define ST_SORT_COL_MIN       4         /* Sort nodes by minimum node value */
  55 #define ST_SORT_COL_MAX       5         /* Sort nodes by maximum node value */
  56 #define ST_SORT_COL_BURSTRATE 6         /* Sort nodes by burst rate */
  57
  58 /* obscure information regarding the stats_tree */
  59 typedef struct _stats_tree stats_tree;
  60
  61 /* tap packet callback for stats_tree */
  62 typedef int  (*stat_tree_packet_cb)(stats_tree*,
  63                                     packet_info *,
  64                                     epan_dissect_t *,
  65                                     const void *);
  66
  67 /* stats_tree initialization callback */
  68 typedef void  (*stat_tree_init_cb)(stats_tree *);
  69
  70 /* stats_tree cleanup callback */
  71 typedef void  (*stat_tree_cleanup_cb)(stats_tree *);
  72
  73 /* registers a new stats tree with default group REGISTER_STAT_GROUP_UNSORTED
  74  * abbr: protocol abbr
  75  * name: protocol display name
  76  * flags: tap listener flags for per-packet callback
  77  * packet: per packet callback
  78  * init: tree initialization callback
  79  * cleanup: cleanup callback
  80  */
  81 WS_DLL_PUBLIC void stats_tree_register(const gchar *tapname,
  82                                        const gchar *abbr,
  83                                        const gchar *name,
  84                                        guint flags,
  85                                        stat_tree_packet_cb packet,
  86                                        stat_tree_init_cb init,
  87                                        stat_tree_cleanup_cb cleanup);
  88
  89 /* registers a new stats tree with default group REGISTER_STAT_GROUP_UNSORTED from a plugin
  90  * abbr: protocol abbr
  91  * name: protocol display name
  92  * flags: tap listener flags for per-packet callback
  93  * packet: per packet callback
  94  * init: tree initialization callback
  95  * cleanup: cleanup callback
  96  */
  97 WS_DLL_PUBLIC void stats_tree_register_plugin(const gchar *tapname,
  98                                               const gchar *abbr,
  99                                               const gchar *name,
 100                                               guint flags,
 101                                               stat_tree_packet_cb packet,
 102                                               stat_tree_init_cb init,
 103                                               stat_tree_cleanup_cb cleanup);
 104
 105 /* registers a new stats tree
 106  * abbr: protocol abbr
 107  * name: protocol display name
 108  * flags: tap listener flags for per-packet callback
 109  * packet: per packet callback
 110  * init: tree initialization callback
 111  * cleanup: cleanup callback
 112  * stat_group: the group this stat belongs to
 113  */
 114 WS_DLL_PUBLIC void stats_tree_register_with_group(const gchar *tapname,
 115                                                   const gchar *abbr,
 116                                                   const gchar *name,
 117                                                   guint flags,
 118                                                   stat_tree_packet_cb packet,
 119                                                   stat_tree_init_cb init,
 120                                                   stat_tree_cleanup_cb cleanup,
 121                                                   register_stat_group_t stat_group);
 122
 123 WS_DLL_PUBLIC int stats_tree_parent_id_by_name(stats_tree *st, const gchar *parent_name);
 124
 125 /* Creates a node in the tree (to be used in the in init_cb)
 126  * st: the stats_tree in which to create it
 127  * name: the name of the new node
 128  * parent_name: the name of the parent_node (NULL for root)
 129  * with_children: TRUE if this node will have "dynamically created" children
 130  */
 131 WS_DLL_PUBLIC int stats_tree_create_node(stats_tree *st,
 132                                          const gchar *name,
 133                                          int parent_id,
 134                                          gboolean with_children);
 135
 136 /* creates a node using its parent's tree name */
 137 WS_DLL_PUBLIC int stats_tree_create_node_by_pname(stats_tree *st,
 138                                                   const gchar *name,
 139                                                   const gchar *parent_name,
 140                                                   gboolean with_children);
 141
 142 /* creates a node in the tree, that will contain a ranges list.
 143    example:
 144    stats_tree_create_range_node(st,name,parent,
 145    "-99","100-199","200-299","300-399","400-", NULL);
 146 */
 147 WS_DLL_PUBLIC int stats_tree_create_range_node(stats_tree *st,
 148                                                const gchar *name,
 149                                                int parent_id,
 150                                                ...);
 151
 152 WS_DLL_PUBLIC int stats_tree_create_range_node_string(stats_tree *st,
 153                                                       const gchar *name,
 154                                                       int parent_id,
 155                                                       int num_str_ranges,
 156                                                       gchar** str_ranges);
 157
 158 WS_DLL_PUBLIC int stats_tree_range_node_with_pname(stats_tree *st,
 159                                                    const gchar *name,
 160                                                    const gchar *parent_name,
 161                                                    ...);
 162
 163 /* increases by one the ranged node and the sub node to whose range the value belongs */
 164 WS_DLL_PUBLIC int stats_tree_tick_range(stats_tree *st,
 165                                         const gchar *name,
 166                                         int parent_id,
 167                                         int value_in_range);
 168
 169 #define stats_tree_tick_range_by_pname(st,name,parent_name,value_in_range) \
 170     stats_tree_tick_range((st),(name),stats_tree_parent_id_by_name((st),(parent_name),(value_in_range)))
 171
 172 /* */
 173 WS_DLL_PUBLIC int stats_tree_create_pivot(stats_tree *st,
 174                                           const gchar *name,
 175                                           int parent_id);
 176
 177 WS_DLL_PUBLIC int stats_tree_create_pivot_by_pname(stats_tree *st,
 178                                                    const gchar *name,
 179                                                    const gchar *parent_name);
 180
 181 WS_DLL_PUBLIC int stats_tree_tick_pivot(stats_tree *st,
 182                                         int pivot_id,
 183                                         const gchar *pivot_value);
 184
 185 /*
 186  * manipulates the value of the node whose name is given
 187  * if the node does not exist yet it's created (with counter=1)
 188  * using parent_name as parent node (NULL for root).
 189  * with_children=TRUE to indicate that the created node will be a parent
 190  */
 191 typedef enum _manip_node_mode {
 192     MN_INCREASE,
 193     MN_SET,
 194     MN_AVERAGE,
 195     MN_AVERAGE_NOTICK,
 196     MN_SET_FLAGS,
 197     MN_CLEAR_FLAGS
 198 } manip_node_mode;
 199 WS_DLL_PUBLIC int stats_tree_manip_node(manip_node_mode mode,
 200                                         stats_tree *st,
 201                                         const gchar *name,
 202                                         int parent_id,
 203                                         gboolean with_children,
 204                                         gint value);
 205
 206 #define increase_stat_node(st,name,parent_id,with_children,value)       \
 207     (stats_tree_manip_node(MN_INCREASE,(st),(name),(parent_id),(with_children),(value)))
 208
 209 #define tick_stat_node(st,name,parent_id,with_children)                 \
 210     (stats_tree_manip_node(MN_INCREASE,(st),(name),(parent_id),(with_children),1))
 211
 212 #define set_stat_node(st,name,parent_id,with_children,value)            \
 213     (stats_tree_manip_node(MN_SET,(st),(name),(parent_id),(with_children),value))
 214
 215 #define zero_stat_node(st,name,parent_id,with_children)                 \
 216     (stats_tree_manip_node(MN_SET,(st),(name),(parent_id),(with_children),0))
 217
 218 /*
 219  * Add value to average calculation WITHOUT ticking node. Node MUST be ticked separately!
 220  *
 221  * Intention is to allow code to separately tick node (backward compatibility for plugin)
 222  * and set value to use for averages. Older versions without average support will then at
 223  * least show a count instead of 0.
 224  */
 225 #define avg_stat_node_add_value_notick(st,name,parent_id,with_children,value) \
 226     (stats_tree_manip_node(MN_AVERAGE_NOTICK,(st),(name),(parent_id),(with_children),value))
 227
 228 /* Tick node and add a new value to the average calculation for this stats node. */
 229 #define avg_stat_node_add_value(st,name,parent_id,with_children,value)  \
 230     (stats_tree_manip_node(MN_AVERAGE,(st),(name),(parent_id),(with_children),value))
 231
 232 /* Set flags for this node. Node created if it does not yet exist. */
 233 #define stat_node_set_flags(st,name,parent_id,with_children,flags)      \
 234     (stats_tree_manip_node(MN_SET_FLAGS,(st),(name),(parent_id),(with_children),flags))
 235
 236 /* Clear flags for this node. Node created if it does not yet exist. */
 237 #define stat_node_clear_flags(st,name,parent_id,with_children,flags)    \
 238     (stats_tree_manip_node(MN_CLEAR_FLAGS,(st),(name),(parent_id),(with_children),flags))
 239
 240 #ifdef __cplusplus
 241 }
 242 #endif /* __cplusplus */
 243
 244 #endif /* __STATS_TREE_H */
 245
 246 /*
 247  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 248  *
 249  * Local variables:
 250  * c-basic-offset: 4
 251  * tab-width: 8
 252  * indent-tabs-mode: nil
 253  * End:
 254  *
 255  * vi: set shiftwidth=4 tabstop=8 expandtab:
 256  * :indentSize=4:tabSize=8:noTabs=true:
 257  */