+$Id$
+
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 win32 gtk
-port of ethereal.
+port of wireshark.
-XXX: when ongoing file reorganisation will be completed, the following
+XXX: when ongoing file reorganization will be completed, the following
two lists maybe won't be needed any longer!
libpcap related source files:
-----------------------------
-pcap-util.c
-pcap-util.h
-pcap-util-int.h
-pcap-util-unix.c
+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_wpcap_packet.c
+capture_wpcap_packet.h
Capture related source files:
-----------------------------
-capture.c (XXX: parts of this should be seperated and moved to the gtk dir)
+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
Capture driver
--------------
-Etheral doesn't have direct access to the capture hardware. Instead of this,
+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 g_module_open("wpcap") is called
+On Win32, in capture-wpcap.c the function ws_module_open("wpcap.dll") is called
to load the wpcap.dll. This dll includes all functions needed for
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
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,
-I will call it the capture file.
+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 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.
-
-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.
+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.
-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_file_input_cb() function is called cyclically
-(unix: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.
+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 it's own task.
+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.
+pcap_dispatch() function.
git.samba.org / obnox / wireshark / wip.git / blobdiff