forked from osmocom/wireshark
improved the developer documentation
* tvb_*_length mentioned in README.dissector * fixed typos in README.dissector * using stats_tree_register_plugin in the stats_tree examples both in README.stats_tree and the dev guide * removed the version information and the #endif from the stats tree section in README.dissector Change-Id: I27df0b5dfd66a7c0ac5b0fe1bdc882b3e9ffda74 Reviewed-on: https://code.wireshark.org/review/12908 Reviewed-by: Alexis La Goutte <alexis.lagoutte@gmail.com> Petri-Dish: Alexis La Goutte <alexis.lagoutte@gmail.com> Reviewed-by: Michael Mann <mmann78@netscape.net>
This commit is contained in:
parent
d1b46d9d54
commit
cef51084f2
4
AUTHORS
4
AUTHORS
|
@ -3669,6 +3669,10 @@ Guillaume Autran <gautran[AT]clearpathrobotics.com> {
|
||||||
TCPROS support
|
TCPROS support
|
||||||
}
|
}
|
||||||
|
|
||||||
|
Barbu Paul - Gheorghe <barbu.paul.gheorghe[AT]gmail.com> {
|
||||||
|
Developer documentation improvements
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
and by:
|
and by:
|
||||||
|
|
||||||
|
|
|
@ -41,6 +41,7 @@ Laurent Deniel <laurent.deniel[AT]free.fr>
|
||||||
Gerald Combs <gerald[AT]wireshark.org>
|
Gerald Combs <gerald[AT]wireshark.org>
|
||||||
Guy Harris <guy[AT]alum.mit.edu>
|
Guy Harris <guy[AT]alum.mit.edu>
|
||||||
Ulf Lamping <ulf.lamping[AT]web.de>
|
Ulf Lamping <ulf.lamping[AT]web.de>
|
||||||
|
Barbu Paul - Gheorghe <barbu.paul.gheorghe[AT]gmail.com>
|
||||||
|
|
||||||
1. Setting up your protocol dissector code.
|
1. Setting up your protocol dissector code.
|
||||||
|
|
||||||
|
@ -405,6 +406,16 @@ Pointer-retrieval:
|
||||||
*/
|
*/
|
||||||
guint8* tvb_get_ptr(tvbuff_t *tvb, gint offset, gint length);
|
guint8* tvb_get_ptr(tvbuff_t *tvb, gint offset, gint length);
|
||||||
|
|
||||||
|
Length query:
|
||||||
|
Get amount of captured data in the buffer (which is *NOT* necessarily the
|
||||||
|
length of the packet). You probably want tvb_reported_length instead:
|
||||||
|
|
||||||
|
guint tvb_captured_length(const tvbuff_t *tvb);
|
||||||
|
|
||||||
|
Get reported length of buffer:
|
||||||
|
|
||||||
|
guint tvb_reported_length(const tvbuff_t *tvb);
|
||||||
|
|
||||||
|
|
||||||
1.4 Functions to handle columns in the traffic summary window.
|
1.4 Functions to handle columns in the traffic summary window.
|
||||||
|
|
||||||
|
@ -2695,7 +2706,7 @@ upon the conversation index and values inside the request packets.
|
||||||
NOTE: This sections assumes that all information is available to
|
NOTE: This sections assumes that all information is available to
|
||||||
create a complete conversation, source port/address and
|
create a complete conversation, source port/address and
|
||||||
destination port/address. If either the destination port or
|
destination port/address. If either the destination port or
|
||||||
address is know, see section 2.4 Dynamic server port dissector
|
address is known, see section 2.4 Dynamic server port dissector
|
||||||
registration.
|
registration.
|
||||||
|
|
||||||
For protocols that negotiate a secondary port connection, for example
|
For protocols that negotiate a secondary port connection, for example
|
||||||
|
|
|
@ -17,11 +17,11 @@ The init callback routine:
|
||||||
which will be executed before any packet is passed to the tap. Here you
|
which will be executed before any packet is passed to the tap. Here you
|
||||||
should create the "static" nodes of your tree. As well as initialize your
|
should create the "static" nodes of your tree. As well as initialize your
|
||||||
data.
|
data.
|
||||||
|
|
||||||
The (per)packet callback routine:
|
The (per)packet callback routine:
|
||||||
As the tap_packet callback is going to be called for every packet, it
|
As the tap_packet callback is going to be called for every packet, it
|
||||||
should be used to increment the counters.
|
should be used to increment the counters.
|
||||||
|
|
||||||
The cleanup callback:
|
The cleanup callback:
|
||||||
It is called at the destruction of the stats_tree and might be used to
|
It is called at the destruction of the stats_tree and might be used to
|
||||||
free ....
|
free ....
|
||||||
|
@ -79,21 +79,21 @@ static gchar* st_str_udp_term = "UDP terminations";
|
||||||
/* this one initializes the tree, creating the root nodes */
|
/* this one initializes the tree, creating the root nodes */
|
||||||
extern void udp_term_stats_tree_init(stats_tree* st) {
|
extern void udp_term_stats_tree_init(stats_tree* st) {
|
||||||
/* we create a node under which we'll add every termination */
|
/* we create a node under which we'll add every termination */
|
||||||
st_udp_term = stats_tree_create_node(st, st_str_udp_term, 0, TRUE);
|
st_udp_term = stats_tree_create_node(st, st_str_udp_term, 0, TRUE);
|
||||||
}
|
}
|
||||||
|
|
||||||
/* this one will be called with every udp packet */
|
/* this one will be called with every udp packet */
|
||||||
extern int udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to us */
|
extern int udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to us */
|
||||||
packet_info *pinfo, /* we'll fetch the addresses from here */
|
packet_info *pinfo, /* we'll fetch the addresses from here */
|
||||||
epan_dissect_t *edt _U_, /* unused */
|
epan_dissect_t *edt _U_, /* unused */
|
||||||
const void *p) /* we'll use this to fetch the ports */
|
const void *p) /* we'll use this to fetch the ports */
|
||||||
{
|
{
|
||||||
static guint8 str[128];
|
static guint8 str[128];
|
||||||
e_udphdr* udphdr = (e_udphdr*) p;
|
e_udphdr* udphdr = (e_udphdr*) p;
|
||||||
|
|
||||||
/* we increment by one (tick) the root node */
|
/* we increment by one (tick) the root node */
|
||||||
tick_stat_node(st, st_str_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
|
/* we then tick a node for this src_addr:src_port
|
||||||
if the node doesn't exists it will be created */
|
if the node doesn't exists it will be created */
|
||||||
g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_src),udphdr->sport);
|
g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_src),udphdr->sport);
|
||||||
|
@ -102,7 +102,7 @@ extern int udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to
|
||||||
/* same thing for dst */
|
/* same thing for dst */
|
||||||
g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_dst),udphdr->dport);
|
g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_dst),udphdr->dport);
|
||||||
tick_stat_node(st, str, st_udp_term, FALSE);
|
tick_stat_node(st, str, st_udp_term, FALSE);
|
||||||
|
|
||||||
return 1;
|
return 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -111,13 +111,13 @@ WS_DLL_PUBLIC_DEF const gchar version[] = "0.0";
|
||||||
|
|
||||||
WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void) {
|
WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void) {
|
||||||
|
|
||||||
stats_tree_register("udp", /* the proto we are going to "tap" */
|
stats_tree_register_plugin("udp", /* the proto we are going to "tap" */
|
||||||
"udp_terms", /* the abbreviation for this tree (to be used as -z udp_terms,tree) */
|
"udp_terms", /* the abbreviation for this tree (to be used as -z udp_terms,tree) */
|
||||||
st_str_udp_term, /* the name of the menu and window (use "/" for sub menus)*/
|
st_str_udp_term, /* the name of the menu and window (use "/" for sub menus)*/
|
||||||
0, /* tap listener flags for per-packet callback */
|
0, /* tap listener flags for per-packet callback */
|
||||||
udp_term_stats_tree_packet, /* the per packet callback */
|
udp_term_stats_tree_packet, /* the per packet callback */
|
||||||
udp_term_stats_tree_init, /* the init callback */
|
udp_term_stats_tree_init, /* the init callback */
|
||||||
NULL ); /* the cleanup callback (in this case there isn't) */
|
NULL ); /* the cleanup callback (in this case there isn't) */
|
||||||
|
|
||||||
}
|
}
|
||||||
#endif
|
#endif
|
||||||
|
@ -132,8 +132,11 @@ the stats_tree API
|
||||||
stats_tree_register( tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb);
|
stats_tree_register( tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb);
|
||||||
registers a new stats tree
|
registers a new stats tree
|
||||||
|
|
||||||
|
stats_tree_register_plugin(tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb);
|
||||||
|
registers a new stats tree from a plugin
|
||||||
|
|
||||||
stats_tree_parent_id_by_name( st, parent_name)
|
stats_tree_parent_id_by_name( st, parent_name)
|
||||||
returns the id of a candidate parent node given its name
|
returns the id of a candidate parent node given its name
|
||||||
|
|
||||||
|
|
||||||
Node functions
|
Node functions
|
||||||
|
@ -192,7 +195,7 @@ resets to zero a stat_node
|
||||||
Averages work by tracking both the number of items added to node (the ticking
|
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
|
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
|
automatically for ranged nodes; for other node types you need to call one of
|
||||||
the functions below to associate item values with each tick.
|
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_notick(st,name,parent_id,with_children,value)
|
||||||
avg_stat_node_add_value(st,name,parent_id,with_children,value)
|
avg_stat_node_add_value(st,name,parent_id,with_children,value)
|
||||||
|
@ -214,10 +217,10 @@ with avg_stat_node_add_value as this will lead to incorrect results for the
|
||||||
average value.
|
average value.
|
||||||
|
|
||||||
stats_tree now also support setting flags per node to control the behaviour
|
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
|
of these nodes. This can be done using the stat_node_set_flags and
|
||||||
stat_node_clear_flags functions. Currently these flags are defined:
|
stat_node_clear_flags functions. Currently these flags are defined:
|
||||||
|
|
||||||
ST_FLG_DEF_NOEXPAND: By default the top-level nodes in a tree are
|
ST_FLG_DEF_NOEXPAND: By default the top-level nodes in a tree are
|
||||||
automatically expanded in the GUI. Setting this flag on
|
automatically expanded in the GUI. Setting this flag on
|
||||||
such a node prevents the node from automatically expanding.
|
such a node prevents the node from automatically expanding.
|
||||||
ST_FLG_SORT_TOP: Nodes with this flag is sorted separately from nodes
|
ST_FLG_SORT_TOP: Nodes with this flag is sorted separately from nodes
|
||||||
|
|
|
@ -1060,18 +1060,14 @@ Here is a mechanism to produce statistics from the above TAP interface.
|
||||||
----
|
----
|
||||||
/* register all http trees */
|
/* register all http trees */
|
||||||
static void register_foo_stat_trees(void) {
|
static void register_foo_stat_trees(void) {
|
||||||
stats_tree_register("foo", "foo", "Foo/Packet Types",
|
stats_tree_register_plugin("foo", "foo", "Foo/Packet Types", 0,
|
||||||
foo_stats_tree_packet, foo_stats_tree_init, NULL);
|
foo_stats_tree_packet, foo_stats_tree_init, NULL);
|
||||||
}
|
}
|
||||||
|
|
||||||
WS_DLL_PUBLIC_DEF const gchar version[] = "0.0";
|
|
||||||
|
|
||||||
WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void)
|
WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void)
|
||||||
{
|
{
|
||||||
register_foo_stat_trees();
|
register_foo_stat_trees();
|
||||||
}
|
}
|
||||||
|
|
||||||
#endif
|
|
||||||
----
|
----
|
||||||
====
|
====
|
||||||
|
|
||||||
|
@ -1079,8 +1075,8 @@ Working from the bottom up, first the plugin interface entry point is defined,
|
||||||
+plugin_register_tap_listener()+. This simply calls the initialisation function
|
+plugin_register_tap_listener()+. This simply calls the initialisation function
|
||||||
+register_foo_stat_trees()+.
|
+register_foo_stat_trees()+.
|
||||||
|
|
||||||
This in turn calls the +stats_tree_register()+ function, which takes three
|
This in turn calls the +stats_tree_register_plugin()+ function, which takes three
|
||||||
strings, and three functions.
|
strings, an integer, and three callback functions.
|
||||||
|
|
||||||
. This is the tap name that is registered.
|
. This is the tap name that is registered.
|
||||||
|
|
||||||
|
@ -1088,6 +1084,8 @@ strings, and three functions.
|
||||||
|
|
||||||
. The name of the stats module. A $$'/'$$ character can be used to make sub menus.
|
. The name of the stats module. A $$'/'$$ character can be used to make sub menus.
|
||||||
|
|
||||||
|
. Flags for per-packet callback
|
||||||
|
|
||||||
. The function that will called to generate the stats.
|
. The function that will called to generate the stats.
|
||||||
|
|
||||||
. A function that can be called to initialise the stats data.
|
. A function that can be called to initialise the stats data.
|
||||||
|
|
Loading…
Reference in New Issue