Stats_tree enhancements for sorting, averages and burst rate. Bug 9452 (https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=9452)

From Deon van der Westhuysen

- Bug fix: object leak in stats_tree after a tap reset (for example apply statistics preferences with a stats_tree window open)
- Bug fix: correct sample code in README.stats_tree
- Add: slash in plug-in name now creates submenu as docs describe (was a bug?)
- Add: menu separator before the stat_tree registered plug-ins
- Add: stats_tree can now calculate averages for nodes; automatically calculated for range nodes. Add section in README.stats_tree describing averages.
- Add: stats_tree can now calculate burst rate of each node (like rate but with a shorter, sliding time window)
- Add: sorting for stats_tree plug-ins. Can sort on node name, count, average, min, max values and burst rate.
- Add: preferences for stats_tree system (default sort column, burst calc params)
- Add: stats_tree window copy to clipboard and export and plain text, csv and XML.
- Added sample of new functionality in $srcdir/plugins/stats_tree/pinfo_stats_tree.c
- Moved all stats_tree sample plug-ins to "IP Statistics" submenu.

svn path=/trunk/; revision=53657

1 files changed, 36 insertions, 1 deletions

diff --git a/doc/README.stats_tree b/doc/README.stats_tree
index b5b24e42e5..dcaf91cf6a 100644
--- a/doc/README.stats_tree
+++ b/doc/README.stats_tree
@@ -95,7 +95,7 @@ extern int udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to
 	e_udphdr* udphdr = (e_udphdr*) p;
 	
 	/* we increment by one (tick) the root node */
-	stats_tree_tick_node(st, st_udp_term, 0, FALSE);
+	tick_stat_node(st, st_str_udp_term, 0, FALSE);
 	
 	/* we then tick a node for this src_addr:src_port
 	   if the node doesn't exists it will be created */
@@ -192,6 +192,41 @@ sets the value of a stat_node
 zero_stat_node(st,name,parent_id,with_children)
 resets to zero a stat_node
 
+Averages work by tracking both the number of items added to node (the ticking
+action) and the value of each item added to the node. This is done
+automatically for ranged nodes; for other node types you need to call one of
+the functions below to associate item values with each tick. 
+
+avg_stat_node_add_value_notick(st,name,parent_id,with_children,value)
+avg_stat_node_add_value(st,name,parent_id,with_children,value)
+
+The difference between the above functions is whether the item count is
+increased or not. To properly compute the average you need to either call
+avg_stat_node_add_value or avg_stat_node_add_value_notick combined
+tick_stat_node. The later sequence allows for plug-ins which are compatible
+with older wireshark versions which ignores avg_stat_node_add_value because
+it does not understand the command. This would result in 0 counts for all
+nodes. It is preferred to use avg_stat_node_add_value if you are not writing
+a plug-in.
+
+avg_stat_node_add_value is used the same way as tick_stat_node with the
+exception that you now specify an additional value associated with the tick.
+
+Do not mix increase_stat_node, set_stat_node or zero_stat_node
+with avg_stat_node_add_value as this will lead to incorrect results for the
+average value.
+
+stats_tree now also support setting flags per node to control the behaviour
+of these nodes. This can be done using the stat_node_set_flags and 
+stat_node_clear_flags functions. Currently these flags are defined:
+
+	ST_FLG_DEF_NOEXPAND: By default the top-level nodes in a tree are 
+			automatically expanded in the GUI. Setting this flag on
+			such a node	prevents the node from automatically expanding.
+	ST_FLG_SORT_TOP: Nodes with this flag is sorted separately from nodes
+			without this flag (in effect partitioning tree into a top and
+			bottom half. Each half is sorted normally. Top always appear
+			first :)
 
 You can find more examples of these in $srcdir/plugins/stats_tree/pinfo_stats_tree.c