Adding upstream version 4.2.2.upstream/4.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 138 insertions, 0 deletions

diff --git a/doc/README.capture b/doc/README.capture
new file mode 100644
index 00000000..9191316c
--- /dev/null
+++ b/doc/README.capture
@@ -0,0 +1,138 @@
+This document is an attempt, to bring some light to the things done, when
+packet capturing is performed. There might be things missing, and others
+maybe wrong :-( The following will concentrate a bit on the Windows
+port of Wireshark.
+
+
+XXX: when ongoing file reorganization will be completed, the following
+two lists maybe won't be needed any longer!
+
+libpcap related source files:
+-----------------------------
+capture-pcap-util.c
+capture-pcap-util.h
+capture-pcap-util-int.h
+capture-pcap-util-unix.c
+capture-wpcap.c
+capture-wpcap.h
+
+Capture related source files:
+-----------------------------
+capture.c
+capture.h
+capture_loop.c
+capture_loop.h
+capture_opts.c
+capture_sync.c
+capture_ui_utils.c
+capture_ui_utils.h
+
+
+Capture driver
+--------------
+Wireshark doesn't have direct access to the capture hardware. Instead of this,
+it uses the Libpcap/Winpcap library to capture data from network cards.
+
+On Win32, in capture-wpcap.c the function load_wpcap_module() is called
+to load the wpcap.dll. This dll includes all functions needed for
+packet capturing.
+
+
+
+Capture File
+------------
+There are some kinds of targets to put the capture data into:
+
+-temporary file
+-user specified "single" capture file
+-user specified "ringbuffer" capture file
+
+Which kind of file is used depends on the user settings. In principle there
+is no difference in handling these files, so if not otherwise notified,
+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 its 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 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.
+
+
+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,
+
+-Qt 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 (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.
+
+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.
+
+
+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 the capture is in progress, no other capture file
+can be opened.
+
+
+Updating
+--------
+The actual packet capturing inside the libpcap is done using its own task.
+Catching and processing the packet data from the libpcap is done using the
+pcap_dispatch() function.