various (minor) capture code cleanup

svn path=/trunk/; revision=13957

8 files changed, 61 insertions, 82 deletions

diff --git a/capture.c b/capture.c
index d1ccfb2dbd..cd5e485ae6 100644
--- a/capture.c
+++ b/capture.c
@@ -1,5 +1,5 @@
 /* capture.c
- * Routines for packet capture windows
+ * Routines for packet capture
  *
  * $Id$
  *
@@ -67,14 +67,14 @@
 #include "ui_util.h"
 
 
-static void stop_capture_signal_handler(int signo);
 
-
-
-/* start a capture */
-/* Returns TRUE if the capture starts successfully, FALSE otherwise. */
+/** 
+ * Start a capture.
+ *
+ * @return TRUE if the capture starts successfully, FALSE otherwise.
+ */
 gboolean
-do_capture(capture_options *capture_opts)
+capture_start(capture_options *capture_opts)
 {
   gboolean ret;
 
@@ -99,7 +99,7 @@ do_capture(capture_options *capture_opts)
 }
 
 
-/* we've succeeded a capture, try to read it into a new capture file */
+/* We've succeeded a (non real-time) capture, try to read it into a new capture file */
 static gboolean
 capture_input_read_all(capture_options *capture_opts, gboolean is_tempfile, gboolean drops_known,
 guint32 drops)
@@ -107,7 +107,7 @@ guint32 drops)
     int err;
 
 
-    /* Capture succeeded; attempt to read in the capture file. */
+    /* Capture succeeded; attempt to open the capture file. */
     if (cf_open(capture_opts->cf, capture_opts->save_file, is_tempfile, &err) != CF_OK) {
       /* We're not doing a capture any more, so we don't have a save
 	 file. */
@@ -149,6 +149,8 @@ guint32 drops)
          supplies, allowing us to display only the ones it does. */
       cf_set_drops(capture_opts->cf, drops);
     }
+
+    /* read in the packet data */
     switch (cf_read(capture_opts->cf)) {
 
     case CF_READ_OK:
@@ -159,8 +161,8 @@ guint32 drops)
       break;
 
     case CF_READ_ABORTED:
-      /* Exit by leaving the main loop, so that any quit functions
-         we registered get called. */
+      /* User wants to quit program. Exit by leaving the main loop, 
+         so that any quit functions we registered get called. */
       main_window_nested_quit();
       return FALSE;
     }
@@ -188,7 +190,7 @@ capture_input_new_file(capture_options *capture_opts, gchar *new_file)
 
       /*g_warning("New capture file: %s", new_file);*/
 
-      /* save the new filename */
+      /* free the old filename */
       if(capture_opts->save_file != NULL) {
         /* we start a new capture file, simply close the old one */
         /* XXX - is it enough to call cf_close here? */
@@ -201,18 +203,19 @@ capture_input_new_file(capture_options *capture_opts, gchar *new_file)
         is_tempfile = TRUE;
         cf_set_tempfile(capture_opts->cf, TRUE);
       }
+
+      /* save the new filename */
       capture_opts->save_file = g_strdup(new_file);
 
-      /* if we are in real-time mode, open the new file */
+      /* if we are in real-time mode, open the new file now */
     if(capture_opts->real_time_mode) {
-        /* The child process started a capture.
-           Attempt to open the capture file and set up to read it. */
+        /* Attempt to open the capture file and set up to read from it. */
         switch(cf_start_tail(capture_opts->cf, capture_opts->save_file, is_tempfile, &err)) {
         case CF_OK:
             break;
         case CF_ERROR:
-            /* Don't unlink the save file - leave it around, for debugging
-            purposes. */
+            /* Don't unlink (delete) the save file - leave it around, 
+               for debugging purposes. */
             g_free(capture_opts->save_file);
             capture_opts->save_file = NULL;
             return FALSE;
@@ -302,40 +305,10 @@ capture_input_closed(capture_options *capture_opts)
 }
 
 
-#ifndef _WIN32
-static void
-capture_child_stop_signal_handler(int signo _U_)
-{
-  capture_loop_stop();
-}
-#endif
-
-
-int  
-capture_child_start(capture_options *capture_opts, gboolean *stats_known, struct pcap_stat *stats)
-{
-#ifndef _WIN32
-  /*
-   * Catch SIGUSR1, so that we exit cleanly if the parent process
-   * kills us with it due to the user selecting "Capture->Stop".
-   */
-    signal(SIGUSR1, capture_child_stop_signal_handler);
-#endif
-
-  return capture_loop_start(capture_opts, stats_known, stats);
-}
-
-void
-capture_child_stop(capture_options *capture_opts)
-{
-  /* stop the capture loop */
-  capture_loop_stop();
-}
-
 void
 capture_stop(capture_options *capture_opts)
 {
-  /* stop the capture child, if we have one */
+  /* stop the capture child gracefully, if we have one */
   sync_pipe_stop(capture_opts);
 }
 
diff --git a/capture.h b/capture.h
index dfdc747ec9..8ca2a4df47 100644
--- a/capture.h
+++ b/capture.h
@@ -93,13 +93,18 @@ extern void
 capture_opts_add_opt(capture_options *capture_opts, const char *appname, int opt, const char *optarg, gboolean *start_capture);
 
 /** 
- * Open a specified file, or create a temporary file, and start a capture
- * to the file in question.  
+ * Start a capture session.
  *
  * @param capture_opts the numerous capture options
  * @return TRUE if the capture starts successfully, FALSE otherwise.
  */
-extern gboolean do_capture(capture_options *capture_opts);
+extern gboolean capture_start(capture_options *capture_opts);
+
+/** Stop a capture session (usually from a menu item). */
+extern void capture_stop(capture_options *capture_opts);
+
+/** Terminate the capture child cleanly when exiting. */
+extern void capture_kill_child(capture_options *capture_opts);
 
 /**
  * Capture child told us, we have a new (or the first) capture file.
@@ -116,26 +121,13 @@ extern void capture_input_new_packets(capture_options *capture_opts, int to_read
  */
 extern void capture_input_closed(capture_options *capture_opts);
 
-/** Stop a capture (usually from a menu item). */
-extern void capture_stop(capture_options *capture_opts);
-
-/** Terminate the capture child cleanly when exiting. */
-extern void capture_kill_child(capture_options *capture_opts);
-
 
 
 /** Do the low-level work of a capture (start the capture child).
  *  Returns TRUE if it succeeds, FALSE otherwise. */
-extern int  capture_child_start(capture_options *capture_opts, gboolean *stats_known, struct pcap_stat *stats);
-
-/** Stop a capture child (usually from a menu item). */
-extern void capture_child_stop(capture_options *capture_opts);
-
-/** Do the low-level work of a capture.
- *  Returns TRUE if it succeeds, FALSE otherwise. */
 extern int  capture_loop_start(capture_options *capture_opts, gboolean *stats_known, struct pcap_stat *stats);
 
-/** Stop a low-level capture. */
+/** Stop a low-level capture (stops the capture child). */
 extern void capture_loop_stop(void);
 
 
diff --git a/capture_loop.c b/capture_loop.c
index c65d166f4c..a7c8e882ae 100644
--- a/capture_loop.c
+++ b/capture_loop.c
@@ -1019,6 +1019,14 @@ capture_loop_open_output(capture_options *capture_opts, int *save_file_fd) {
 }
 
 
+#ifndef _WIN32
+static void
+capture_loop_stop_signal_handler(int signo _U_)
+{
+  capture_loop_stop();
+}
+#endif
+
 
 /*
  * This needs to be static, so that the SIGUSR1 handler can clear the "go"
@@ -1077,6 +1085,14 @@ capture_loop_start(capture_options *capture_opts, gboolean *stats_known, struct
   ld.pcap_fd            = 0;
 #endif
 
+#ifndef _WIN32
+  /*
+   * Catch SIGUSR1, so that we exit cleanly if the parent process
+   * kills us with it due to the user selecting "Capture->Stop".
+   */
+    signal(SIGUSR1, capture_loop_stop_signal_handler);
+#endif
+
   /* We haven't yet gotten the capture statistics. */
   *stats_known      = FALSE;
 
diff --git a/capture_sync.h b/capture_sync.h
index 084fcc2e1c..5a52552663 100644
--- a/capture_sync.h
+++ b/capture_sync.h
@@ -27,21 +27,19 @@
  *  
  *  Sync mode capture (internal interface).
  *
- *  Will start a new Ethereal instance which will do the actual capture work.
- *  This is only used, if the "Update list of packets in real time" option is 
- *  used.
+ *  Will start a new Ethereal child instance which will do the actual capture work.
  */
 
 #ifndef __CAPTURE_SYNC_H__
 #define __CAPTURE_SYNC_H__
 
 /** 
- * Start a new synced capture session.
+ * Start a new capture session.
  *  Create a capture child which is doing the real capture work.
  *
  *  Most of the parameters are passed through the global capture_opts.
  *
- *  @param capture_opts the options (formerly global)
+ *  @param capture_opts the options
  *  @param is_tempfile  TRUE if the current cfile is a tempfile
  *  @return             TRUE if a capture could be started, FALSE if not
  */
@@ -52,7 +50,7 @@ sync_pipe_do_capture(capture_options *capture_opts, gboolean is_tempfile);
 extern void
 sync_pipe_stop(capture_options *capture_opts);
 
-/** We want to stop the program, just kill the child as soon as possible */
+/** User wants to stop the program, just kill the child as soon as possible */
 extern void
 sync_pipe_kill(capture_options *capture_opts);
 
@@ -61,6 +59,10 @@ sync_pipe_kill(capture_options *capture_opts);
 extern void
 sync_pipe_capstart_to_parent(void);
 
+/** the child has opened a new capture file, notify the parent */
+extern void
+sync_pipe_filename_to_parent(const char *filename);
+
 /** the child captured some new packets, notify the parent */
 extern void
 sync_pipe_packet_count_to_parent(int packet_count);
@@ -69,10 +71,6 @@ sync_pipe_packet_count_to_parent(int packet_count);
 extern void
 sync_pipe_drops_to_parent(int drops);
 
-/** the child has opened a new capture file, notify the parent */
-extern void
-sync_pipe_filename_to_parent(const char *filename);
-
 /** the child encountered an error, notify the parent */
 extern void 
 sync_pipe_errmsg_to_parent(const char *errmsg);
diff --git a/gtk/capture_dlg.c b/gtk/capture_dlg.c
index 005fe4ead5..246ba922a4 100644
--- a/gtk/capture_dlg.c
+++ b/gtk/capture_dlg.c
@@ -1470,7 +1470,7 @@ capture_prep_ok_cb(GtkWidget *ok_bt _U_, gpointer parent_w) {
 
   window_destroy(GTK_WIDGET(parent_w));
 
-  if (do_capture(capture_opts)) {
+  if (capture_start(capture_opts)) {
     /* The capture succeeded, which means the capture filter syntax is
        valid; add this capture filter to the recent capture filter list. */
     cfilter_combo_add_recent(capture_opts->cfilter);
diff --git a/gtk/capture_if_dlg.c b/gtk/capture_if_dlg.c
index f591e175a8..331c070f5e 100644
--- a/gtk/capture_if_dlg.c
+++ b/gtk/capture_if_dlg.c
@@ -117,7 +117,7 @@ capture_do_cb(GtkWidget *capture_bt _U_, gpointer if_data)
     g_free(capture_opts->save_file);
   capture_opts->save_file = NULL;
 
-  do_capture(capture_opts);
+  capture_start(capture_opts);
 }
 
 
diff --git a/gtk/capture_info_dlg.c b/gtk/capture_info_dlg.c
index 4e54210d3d..e241781c3d 100644
--- a/gtk/capture_info_dlg.c
+++ b/gtk/capture_info_dlg.c
@@ -75,7 +75,7 @@ pct(gint num, gint denom) {
 
 static void
 capture_info_delete_cb(GtkWidget *w _U_, GdkEvent *event _U_, gpointer data _U_) {
-  capture_child_stop(capture_opts);
+  capture_loop_stop();
 }
 
 
diff --git a/gtk/main.c b/gtk/main.c
index a0f4a19aeb..47308d603c 100644
--- a/gtk/main.c
+++ b/gtk/main.c
@@ -2219,10 +2219,10 @@ main(int argc, char *argv[])
      capture box to let us stop the capture, and run a capture
      to a file that our parent will read? */
   if (capture_child) {
-    /* This is the child process for a sync mode or fork mode capture,
+    /* This is the child process of a capture session,
        so just do the low-level work of a capture - don't create
        a temporary file and fork off *another* child process (so don't
-       call "do_capture()"). */
+       call "capture_start()"). */
 
     /* Pop up any queued-up alert boxes. */
     display_queued_messages();
@@ -2231,7 +2231,7 @@ main(int argc, char *argv[])
        After the capture is done; there's nothing more for us to do. */
 
     /* XXX - hand these stats to the parent process */
-    if(capture_child_start(capture_opts, &stats_known, &stats) == TRUE) {
+    if(capture_loop_start(capture_opts, &stats_known, &stats) == TRUE) {
         /* capture ok */
         gtk_exit(0);
     } else {
@@ -2365,7 +2365,7 @@ main(int argc, char *argv[])
       }
       /* "-k" was specified; start a capture. */
       show_main_window(TRUE);
-      if (do_capture(capture_opts)) {
+      if (capture_start(capture_opts)) {
         /* The capture started.  Open tap windows; we do so after creating
            the main window, to avoid GTK warnings, and after starting the
            capture, so we know we have something to tap. */