epan/stats_tree.h

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