|author||Ronnie Sahlberg <firstname.lastname@example.org>||2003-03-06 07:54:24 +0000|
|committer||Ronnie Sahlberg <email@example.com>||2003-03-06 07:54:24 +0000|
Update and added text to README.tapping based on comments in the
contributed RTP tap for voice. Explained when a tap listener is called and somethings to keep in mind when adding taps to protocols that may appear multiple times inside the same packet. svn path=/trunk/; revision=7293
Diffstat (limited to 'doc/README.tapping')
1 files changed, 40 insertions, 1 deletions
diff --git a/doc/README.tapping b/doc/README.tapping
index b53120b850..ac3e1abefb 100644
@@ -1,4 +1,4 @@
-$Id: README.tapping,v 1.4 2002/11/28 20:29:46 guy Exp $
+$Id: README.tapping,v 1.5 2003/03/06 07:54:24 sahlberg Exp $
The TAP system in ethereal is a powerful and flexible mechanism to get event
driven notification on packets matching certain protocols and/or filters.
@@ -140,6 +140,45 @@ then just make ethereal call register_tap_listener() when you want to tap
and call remove_tap_listener() when you are finished.
+WHEN DOES TAP LISTENERS GET CALLED?
+Tap listeners are only called when ethereal reads anew capture for
+the first time or whenever ethereal needs to rescan/redissect
+Redissection occurs when you apply a new display filter or if you
+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
+to receive tap data during the dissection of the frame will be called in
+The order of which the tap listeners will be called is not defined.
+Not until all tap listeners for the frame has been called and returned
+will ethereal continue to dissect the next packet.
+This is why it is important to make the *_packet() callbacks execute as
+quickly as possible, else we create an extra delay until the next packet
+Keep in mind though: for some protocols, such as IP, the protocol can
+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
+tap_queue_packet() is using its own instance of private struct variable
+so they dont overwrite eachother.
+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
+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 likelyhood 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.