update text to reflect the current implementation (e.g. we don't have normal/sync mode any longer)

svn path=/trunk/; revision=14762

1 files changed, 66 insertions, 32 deletions

diff --git a/doc/README.capture b/doc/README.capture
index bb213a2df5..b0477d6238 100644
--- a/doc/README.capture
+++ b/doc/README.capture
@@ -17,13 +17,21 @@ pcap-util-int.h
 pcap-util-unix.c
 capture-wpcap.c
 capture-wpcap.h
+capture_wpcap_packet.c
+capture_wpcap_packet.h
 
 Capture related source files:
 -----------------------------
 capture.c
 capture.h
+capture_loop.c
+capture_loop.h
+capture_opts.c
 capture-stop-conditions.c
 capture-stop-conditions.h
+capture_sync.c
+capture_ui_utils.c
+capture_ui_utils.h
 conditions.c (XXX: is conditions generic or capture specific?)
 conditions.h
 
@@ -41,7 +49,7 @@ packet capturing.
 
 Capture File
 ------------
-There are some kind of targets to put the capture data into:
+There are some kinds of targets to put the capture data into:
 
 -temporary file
 -user specified "single" capture file
@@ -54,55 +62,81 @@ it will be called the capture file.
 The capture file is stored, using the wiretap library.
 
 
+Overview
+--------
+Capturing is done using a two task model: the currently running (parent) 
+process will spawn a child process to do the real capture work, namely 
+controlling libpcap. This two task model is used because it's necessary 
+to split the capturing process (which should avoid packet drop) from the parent
+process which might need significant time to display the data.
+
+When a capture is started, the parent builds a "command line" and creates a 
+new child process with it. A pipe from the child to the parent is created 
+which is used to transfer control messages. 
+
+The child will init libpcap and send the parent a "new capture file is used"
+control message through the pipe.
+
+The child cyclically takes the packet data from libpcap and saves it to disk. 
+From time to time it will send the parent a "new packets" control message. 
+
+If the parent process receives this "new packets" message and the option 
+"Update list of packets in real time" is used, it will read the packet data 
+from the file, dissect and display it.
+
+
+If the user wants to stop the capture, this can be done in two ways: by 
+menu/toolbar of the parent process or the Stop button of the child processes 
+dialog box (which obviously cannot be used it this dialog is hidden).
+
+The Stop button will stop the capture itself, close the control pipe and then 
+closes itself. The parent will detect this and stop it's part of the capture.
+
+If the menu/toolbar is used, the parent will send a break signal to the child 
+which will lead to the same sequence as described above.
+
+Win32 only: as the windows implementation of signals simply doesn't work, 
+another pipe from the parent to the child is used to send a "close capture" 
+message instead of a signal.
+
+
 Start capture
 -------------
-A capture is started, by specifying at the command line to start the capture, 
-or trigger the ok button in the "Capture Options" dialog box. The capture start 
-is actually done by calling the do_capture() function in capture.c.
+A capture is started, by specifying to start the capture at the command line, 
+trigger the Ok button in the "Capture Options" dialog box and some more. The 
+capture start is actually done by calling the capture_start() function in 
+capture.c.
 
 
-Normal capturing
-----------------
-In normal mode, Ethereal will open the target capture file, prepare pcap things,
-init stop conditions, init the capture statistic dialog and start a loop which 
-is running until the flag ld.go is FALSE.
+Capture child (Loop)
+--------------------
+The capture child will open the target capture file, prepare pcap things,
+init stop conditions, init the capture statistic dialog (if not hidden) and 
+start a loop which is running until the flag ld.go is FALSE.
 
 Inside this loop, 
 
 -gtk main things are updated
 -pcap_dispatch(capture_pcap_cb) is called
 -the capture stop conditions are checked (ld.go is set to FALSE to finish)
--update the capture statistic dialog
+-update the capture statistic dialog (if not hidden)
 
 While this loop is running, the pcap_dispatch() will call capture_pcap_cb() 
 for every packet captured. Inside this, the packet data is converted into 
 wtap (wiretap) format and saved to file. Beside saving, it is trying to 
-do some basic dissecting (for the statistic window), by calling the appropriate 
-capture_xxx function.
+do some basic dissecting (for the statistic window), by calling the 
+appropriate capture_xxx function.
 
-When the stop button in the menu/toolbar or at the statistics dialog is pressed, 
-it will simply set the ld.go flag to FALSE, and the loop will finish.
+When the user triggered a capture stop or one of the capture stop conditions 
+matched, the ld.go flag is set to FALSE, and the loop will stop shortly after.
 
 
-Sync mode
----------
-When the "update list of packets in real time" option is used for capturing, 
-another Ethereal instance is spawned and the two instances linked together 
-using a pipe. To open the pipe, a "command line" is build and a second 
-Ethereal instance (another process) is spawn with it. As the old instance 
-doesn't need it's end of the pipe, the write direction is closed immediately.
-
-The new instance will open the capture statistic dialog, capture the data 
-in the normal way described above and send the captured data through the pipe 
-to the old instance. It will not open a main screen to show packets. 
-When the capture is finished (using the close button in the dialog), 
-the new instance closes it's side of the pipe and exits completely.
-
-In the old instance, the cap_pipe_input_cb() function is called "cyclically" 
+Capture parent
+--------------
+In the capture parent the cap_pipe_input_cb() function is called "cyclically" 
 (unix:waiting for pipe, win32:timer,1000ms) to read data from the pipe and show it 
-on the main screen. While this capture is in progress, no other capture file 
-can be opened. The closing of the pipe indicates the old instance that 
-the capturing is finished.
+on the main screen. While the capture is in progress, no other capture file 
+can be opened.
 
 
 Updating