$Id$
-The TAP system in Wireshark is a powerful and flexible mechanism to get event
+The TAP system in Wireshark is a powerful and flexible mechanism to get event
driven notification on packets matching certain protocols and/or filters.
In order to use the tapping system, very little knowledge of Wireshark
internals are required.
-As examples on how to use the tap system see the implementation of
+As examples on how to use the tap system see the implementation of
tap-rpcstat.c (tshark version)
gtk/rpc_stat.c (gtk-wireshark version)
application for and check if that protocol has already got a tap installed
in it.
If it already has a tap device installed then you don't have to do anything.
-If not, then you have to add a tap but don't worry, this is extremely easy to
+If not, then you have to add a tap but don't worry, this is extremely easy to
do and is done in four easy steps;
(see packet-rpc.c and search for tap for an example)
-1, We need tap.h so just add '#include "tap.h"' to the includes.
+1, We need tap.h so just add '#include "tap.h"' (preceded by packet.h) to
+the includes.
2, We need a tap handler so just add 'static int <protocol>_tap = -1;'
4, In the actual dissector for that protocol, after any child dissectors
have returned, just add 'tap_queue_packet(<protocol>_tap, pinfo, <pointer>);'
-<pointer> is used if the tap has any special additional data to provide to
-the tap listeners. What this points to is dependent on the protocol that
-is tapped, or if there are no useful extra data to provide just specify NULL.
-For packet-rpc.c what we specify there is the persistent structure 'rpc_call'
-which contains lots of useful information the rpc layer that a listener might
+<pointer> is used if the tap has any special additional data to provide to the
+tap listeners. What this points to is dependent on the protocol that is tapped,
+or if there are no useful extra data to provide just specify NULL. For
+packet-rpc.c what we specify there is the persistent structure 'rpc_call' which
+contains lots of useful information from the rpc layer that a listener might
need.
TAP LISTENER
============
(see tap-rpcstat.c as an example)
-sInterfacing your application is not that much harder either.
+Interfacing your application is not that much harder either.
Only 3 callbacks and two functions.
The two functions to start or stop tapping are
-register_tap_listener(char *tapname, void *tapdata, char *fstring,
- void (*reset)(void *tapdata), int (*packet)(void *tapdata,
- packet_info *pinfo, epan_dissect_t *edt, const void *<pointer>),
+register_tap_listener(const char *tapname, void *tapdata, const char *fstring,
+ guint flags,
+ void (*reset)(void *tapdata),
+ gboolean (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *<pointer>),
void (*draw)(void *tapdata));
remove_tap_listener(void *tapdata);
register_tap_listener() is used to register an instance of a tap application
to the tap system.
-*tapname
+*tapname
is the name of the tap we want to listen to. I.e. the name used in
step 3 above.
-*tapdata
+*tapdata
is the instance identifier. The tap system uses the value of this
pointer to distinguish between different instances of a tap.
Just make sure that it is unique by letting it be the pointer to a struct
g_malloc() and use that pointer.
(tap-rpcstat.c use this technique to allow multiple simultaneous instances)
-*fstring
-is a pointer to a filter string.
+*fstring
+is a pointer to a filter string.
If this is NULL, then the tap system will provide ALL packets passing the
tapped protocol to your listener.
If you specify a filter string here the tap system will first try
to specify a filter string.
ONLY use a filter string if no other option exist.
+flags
+is a set of flags for the tap listener. The flags that can be set are:
+
+ TL_REQUIRES_PROTO_TREE
+
+ set if your tap listener "packet" routine requires a protocol
+ tree to be built. It will require a protocol tree to be
+ built if either
+
+ 1) it looks at the protocol tree in edt->tree
+
+ or
+
+ 2) the tap-specific data passed to it is constructed only if
+ the protocol tree is being built.
+
+ TL_REQUIRES_COLUMNS
+
+ set if your tap listener "packet" routine requires the column
+ strings to be constructed.
+
void (*reset)(void *tapdata)
This callback is called whenever Wireshark wants to inform your
listener that it is about to start [re]reading a capture file or a new capture
from an interface and that your application should reset any state it has
in the *tapdata instance.
-int (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, void *data)
+gboolean (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, void *data)
This callback is used whenever a new packet has arrived at the tap and that
it has passed the filter (if there were a filter).
The *data structure type is specific to each tap.
-This function returns an int and it should return
- 1, if the data in the packet caused state to be updated
- (and thus a redraw of the window would later be required)
- 0, if we don't need to redraw the window.
+This function returns an gboolean and it should return
+ TRUE, if the data in the packet caused state to be updated
+ (and thus a redraw of the window would later be required)
+ FALSE, if we don't need to redraw the window.
NOTE: that (*packet) should be as fast and efficient as possible. Use this
function ONLY to store data for later and do the CPU-intensive processing
or GUI updates down in (*draw) instead.
-
+
void (*draw)(void *tapdata)
This callback is used when Wireshark wants your application to redraw its
output. It will usually not be called unless your application has received
new data through the (*packet) callback.
-On some ports of Wireshark (gtk2) (*draw) will be called asynchronously
+On some ports of Wireshark (gtk2) (*draw) will be called asynchronously
from a separate thread up to once every 2-3 seconds.
On other ports it might only be called once when the capture is finished
or the file has been [re]read completely.
change and Save/Apply a preference setting that might affect how
packets are dissected.
After each individual packet has been completely dissected and all
-dissectors have returned, all the tap listeners that has been flagged
+dissectors have returned, all the tap listeners that have been flagged
to receive tap data during the dissection of the frame will be called in
sequence.
-The order of which the tap listeners will be called is not defined.
+The order in which the tap listeners will be called is not defined.
Not until all tap listeners for the frame has been called and returned
will Wireshark continue to dissect the next packet.
This is why it is important to make the *_packet() callbacks execute as
appear multiple times in different layers inside the same packet.
For example, IP encapsulated over IP which will call the ip dissector
twice for the same packet.
-IF the tap is going to return private data using the last parameter to
-tap_queue_packet() and IF the protocol can appear multiple times inside the
-same packet, you will have to make sure that each instance of
+IF the tap is going to return private data using the last parameter to
+tap_queue_packet() and IF the protocol can appear multiple times inside the
+same packet, you will have to make sure that each instance of
tap_queue_packet() is using its own instance of private struct variable
so they don't overwrite each other.
-See packet-ip.c which has a simple solution to the problem. It just
-uses a static struct of 4 instances of the ip header struct and
-cycles through them each time the dissector is called.
-4 is just a number taken out of the blue but it should be enough for most
-cases.
-Of course, if someone would generate a capture with IP encapsulated
-over IP over IP over IP over IP, so that there would be more than 4 IP headers
-in the same packet, yes then this would fail. The likelihood of this
-happening in real life is probably very low. If it turns out to be a problem
-we can just increase the cycle length when that happens.
+See packet-ip.c which has a simple solution to the problem. It creates
+a unique instance of the IP header using ep_alloc().
+Previous versions used a static struct of 4 instances of the IP header
+struct and cycled through them each time the dissector was called. (4
+was just a number taken out of the blue but it should be enough for most
+cases.) This would fail if there were more than 4 IP headers in the same
+packet, but that was unlikely.
TIPS
====
Of course, there is nothing that forces you to make (*draw) draw stuff
-on the screen.
+on the screen.
You can hand register_tap_listener() NULL for both (*draw) and (*reset)
(well also for (*packet) but that would be a very boring extension).
Let struct contain an email address?
Then you have something simple that will make Wireshark send an email
- out automagically for each and every time it dissects
+ out automagically for each and every time it dissects
a packet containing TCP traffic to port 57.
Please put in some rate limitation if you do this.
See tap-rpcstat.c for an example
-See tap.c as well. It contains lots of comments and descriptions on the tap
+See tap.c as well. It contains lots of comments and descriptions on the tap
system.
git.samba.org / obnox / wireshark / wip.git / blobdiff