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

1 files changed, 40 insertions, 1 deletions

diff --git a/doc/README.tapping b/doc/README.tapping
index b53120b850..ac3e1abefb 100644
--- a/doc/README.tapping
+++ b/doc/README.tapping
@@ -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
+the capture.
+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
+sequence.
+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
+is dissected.
+
+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
+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 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.
 
 
 TIPS