From Dick Gooris: updated lots of comments

git-svn-id: http://anonsvn.wireshark.org/wireshark/trunk@9548 f5534014-38df-0310-8fa8-9805f1628bb7

1 files changed, 180 insertions, 165 deletions

diff --git a/range.c b/range.c
index a4bc36bb9b..c717f540a8 100644
--- a/range.c
+++ b/range.c
@@ -1,7 +1,7 @@
 /* range.c
  * Packet range routines (save, print, ...)
  *
- * $Id: range.c,v 1.2 2003/12/30 22:48:14 guy Exp $
+ * $Id: range.c,v 1.3 2004/01/04 23:32:34 ulfl Exp $
  *
  * Dick Gooris <gooris@lucent.com>
  * Ulf Lamping <ulf.lamping@web.de>
@@ -58,15 +58,18 @@ struct range_admin   GLrange[MaxRange];
 static guint32       max_packets;
 
 void packet_range_init(packet_range_t *range) {
-  guint32       current_count;	
+  guint32       current_count;
   guint32       displayed_count;
-  guint32       mark_low;	
+  guint32       mark_low;
   guint32       mark_high;
   frame_data    *packet;
 
-  /* This is needed to calculate the number of packets for each variation
-   * like the total amount of packets, the number of marked packets, and
-   * the number between the packets. This is for information only
+  /* The next for-loop is used to obtain the amount of packets to be saved
+   * and is used to present the information in the Save/Print As widget.
+   * We have different types of saving : All the packets, the number
+   * of packets of a marked range, a single packet, and a manually 
+   * entered packet range. The last one is not calculated since this
+   * data must be entered in the widget by the user.
    */
 
   /* "enumeration" values */
@@ -76,9 +79,9 @@ void packet_range_init(packet_range_t *range) {
 
   displayed_count   = 0L;
   mark_low          = 0L;
-  mark_high         = 0L;	
-  range->mark_range = 0L;		
-  
+  mark_high         = 0L;
+  range->mark_range = 0L;
+
   current_count = 0;
   for(packet = cfile.plist; packet != NULL; packet = packet->next) {
       current_count++;
@@ -89,19 +92,21 @@ void packet_range_init(packet_range_t *range) {
           displayed_count++;
       }
       if (packet->flags.marked) {
-	    if (mark_low == 0) {
-	       mark_low = current_count;
-	    }
-	    if (current_count > mark_high) {
-	       mark_high = current_count;
-	    }
+            if (mark_low == 0) {
+               mark_low = current_count;
+            }
+            if (current_count > mark_high) {
+               mark_high = current_count;
+            }
       }
   }
+        
   /* in case we marked just one packet, we add 1. */
   if (cfile.marked_count != 0) {
     range->mark_range = mark_high - mark_low + 1;
   }
-  /* make this global, to be used in function conv_str_range()  */
+        
+  /* make this global, to be used in function packet_range_convert_str()  */
   max_packets = cfile.count;
 }
 
@@ -117,71 +122,69 @@ range_process_e packet_range_process(packet_range_t *range, frame_data *fdata) {
     /* do we have to process this packet at all? */
     if (
       (!range->process_filtered && !range->process_marked) ||
-	  (range->process_filtered && fdata->flags.passed_dfilter && !range->process_marked) ||
-	  (range->process_marked && fdata->flags.marked && !range->process_filtered) ||
-	  (range->process_filtered && range->process_marked && fdata->flags.passed_dfilter && fdata->flags.marked) ||
-	  (range->process_curr)  ||	  
-	  (range->process_marked_range) ||
-	  (range->process_manual_range) ||	  
-	  (range->range_active)
+          (range->process_filtered && fdata->flags.passed_dfilter && !range->process_marked) ||
+          (range->process_marked && fdata->flags.marked && !range->process_filtered) ||
+          (range->process_filtered && range->process_marked && fdata->flags.passed_dfilter && fdata->flags.marked) ||
+          (range->process_curr)  ||
+          (range->process_marked_range) ||
+          (range->process_manual_range) ||
+          (range->range_active)
       ) {
         /* yes, we have to */
     } else {
-        return range_process_next;   
+        return range_process_next;
     }
 
-	/* In case we process a manual range, we check the packet number
-	 * with the range as defined in the array GLrange, see file_dlg.c
-	 * If a match is found, we process it, otherwise we simply go to check
-	 * the next packet. 
-	 */
-	if (range->process_manual_range) {
-	   if (range->process_filtered) {
-	      if (fdata->flags.passed_dfilter == FALSE) {
-	         return range_process_next;
-	      }		
-	   }
-           if (packet_is_in_range(fdata->num) == FALSE) { 
-	         return range_process_next;
-	   }
-	} 
-	      
-	/* For processing a marked range, skip the frames not marked in the first place
-	 * until the first marked frame comes by. Then continue processing until we found the
-	 * last marked frame. We set the range_active to FALSE in the first place until
-	 * a marked frame is found (fdata->flags.marked == TRUE) From now on range_active
-	 * is TRUE, and the large 'if' statement will pass by any frame. It will stop doing
-	 * so once the markers count got 0.  process_marked_range got set in gtk/file_dlg.c
-	 */
-	if (range->process_marked_range) {
-	   if (range->markers == 0) {
-	      return range_processing_finished;
-	   }
-	   if (fdata->flags.marked == TRUE) {
-              range->range_active = TRUE;
-  	      range->markers--;		   
-	   }
-	   if (range->process_filtered) {
-	      if (fdata->flags.passed_dfilter == FALSE) {
-	         return range_process_next;
-	      }
-	   }		
-	   if (range->range_active == FALSE ) {
+    /* In case we process a manual range, we check whether the packet number
+     * is in any of the ranges as defined the array GLrange, see file_dlg.c
+     * If a match is found, we process it, else we process the next packet.
+     */
+    if (range->process_manual_range) {
+       if (range->process_filtered) {
+          if (fdata->flags.passed_dfilter == FALSE) {
+             return range_process_next;
+          }
+       }
+       if (packet_is_in_range(fdata->num) == FALSE) {
           return range_process_next;
-	   }
-	} 
-	      
-	/* Only process the selected frame. If accomplished, finish */
-	if (range->process_curr) {
-	   if (range->process_curr_done) {
-	      return range_processing_finished;
-	   }		
-	   if (fdata->num != cfile.current_frame->num) {
-	         return range_process_next;
-	   }
-	   range->process_curr_done = TRUE;
-	} 
+       }
+    }
 
+    /* For processing a marked range, ignore any packet until we get the first marked packet.
+     * At that time we set the range_active to TRUE, and decrement the markers count. Then continue
+     * accepting each packet, until we find the last marker (markers count becomes zero)
+     * We then reset range_active to FALSE to ignore any packet from then on.
+     */
+    if (range->process_marked_range) {
+       if (range->markers == 0) {
+          return range_processing_finished;
+       }
+       if (fdata->flags.marked == TRUE) {
+          range->range_active = TRUE;
+            range->markers--;
+       }
+       if (range->process_filtered) {
+          if (fdata->flags.passed_dfilter == FALSE) {
+             return range_process_next;
+          }
+       }
+       if (range->range_active == FALSE ) {
+          return range_process_next;
+       }
+    }
+
+    /* Only process the selected packet */
+    if (range->process_curr) {
+       if (range->process_curr_done) {
+          return range_processing_finished;
+       }
+       if (fdata->num != cfile.current_frame->num) {
+          return range_process_next;
+       }
+       range->process_curr_done = TRUE;
+    }
+
+    /* We fell through the conditions above, so we accept this packet */
     return range_process_this;
 }
 
@@ -190,201 +193,213 @@ range_process_e packet_range_process(packet_range_t *range, frame_data *fdata) {
 
 /******************** Range Entry Parser *********************************/
 
-/* Convert the entry range string in a fast comparable array of ranges.
- * In the first place get rid of spaces, and any other characters than
- * commas, digits, and hyphens. The parameter es points to the string to be processed
+/* Converts a range string to a fast comparable array of ranges.
+ * The parameter 'es' points to the string to be converted, and is defined in
+ * the Save/Print-As widget.
+ *
+ * This function fills the array GLrange containing low and high values indexed 
+ * by a global variable GLnrange. After having called this function, the function 
+ * packet_is_in_range() determines whether a given (packet) number is within 
+ * the range or not. 
  *
- * This function is only called once when a range string is provided in the Save/Print As
- * widget. This function fills an array of low and high values indexed by a global
- * varaiable GLnrange. After having called this function, the function isin(val) 
- * determines whether the value is with the range or not.
+ * In case of a single packet number, we make a range where low is equal to high. 
+ * We strip any characters other than commas, digits, or hyphens. We take care 
+ * on wrongly entered ranges; opposite order will be taken care of.
+ * 
+ * The following syntax is accepted :
+ *
+ *   1-20,30-40     Range from 1 to 20, and packets 30 to 40
+ *   -20,30         Range from 1 to 20, and packet 30
+ *   20,30,40-      Packet number 20, 30, and the range from 40 to the end
+ *   20-10,30-25    Range from 10 to 20, and from 25 to 30
+ *   -              All packets
  */
 
 void packet_range_convert_str(const gchar *es)
 {
     gchar     EntryStr[255], OrgStr[255], value[255], p;
-    guint     i, j=0; 
-    guint32   tmp, val;		
+    guint     i, j=0;
+    guint32   tmp, val;
     gboolean  hyphenseen;
-	
+
     /* Reset the number of ranges we are going to find */
     GLnrange = 0;
     GLrange[GLnrange].low  = 0L;
     GLrange[GLnrange].high = 0L;
 
     /* Make a copy of the string, and check the validity of the input */
-    strcpy(OrgStr,es);	
+    strcpy(OrgStr,es);
     if (strlen(OrgStr) == 0 ) {
         return;
     }
-	
-    /* only keep digits, commas, and hyphens. */
+
+    /* Only keep digits, commas, and hyphens. */
     for (i=0; i<=strlen(OrgStr); i++) {
       if ( isdigit(OrgStr[i]) || OrgStr[i] == '-' || OrgStr[i] == ',' ) {
-	 EntryStr[j++] = OrgStr[i];
-      }  
+         EntryStr[j++] = OrgStr[i];
+      }
     }
     EntryStr[j] = '\0';
-  
-    /* remove any starting commas */
+
+    /* Remove any starting commas */
     strcpy(OrgStr,EntryStr);
     i = 0;
     while (OrgStr[i] == ',') {
        i++;
     }
     strcpy(EntryStr,OrgStr+i);
- 
-    /* remove any double commas within the entry string */
+
+    /* Remove any double commas */
     strcpy(OrgStr,EntryStr);
     p = ',';
     j = 0;
     for (i=0; i<=strlen(OrgStr); i++) {
       if ( OrgStr[i] != ',' || p != ',') {
-      	 EntryStr[j++] = OrgStr[i];
+         EntryStr[j++] = OrgStr[i];
       }
-      p = OrgStr[i];	 	    
+      p = OrgStr[i];
     }
     EntryStr[j] = '\0';
 
-    /* remove any double hyphens within the entry string */
+    /* Remove any double hyphens */
     strcpy(OrgStr,EntryStr);
     p = '-';
     j = 0;
     for (i=0; i<=strlen(OrgStr); i++) {
       if (OrgStr[i] != '-' || p != '-' || i == 0) {
-      	 EntryStr[j++] = OrgStr[i];
+         EntryStr[j++] = OrgStr[i];
       }
-      p = OrgStr[i];	 	    
+      p = OrgStr[i];
     }
     EntryStr[j] = '\0';
- 
-    /* remove any trailing commas */
+
+    /* Remove any trailing commas */
     i = strlen(EntryStr) - 1;
     while (EntryStr[i] == ',') {
-       EntryStr[i] = '\0';	    
+       EntryStr[i] = '\0';
        i--;
     }
- 
+
     /* The entry string is now filtered, and ready for further parsing */
-    /* printf("str=%s\n",EntryStr); */
+    /* printf("Function : packet_range_convert_str EntryStr = %s\n",EntryStr); */
 
-    /* Now we are going to process the ranges separately until we get a comma, 
-     * or end of string. The following input are interpreted all right :
-     *
-     *   0-20,30-40    -=>   Range from 0 to 20, and packets 30 to 40
-     *   -20,30        -=>   Range from 0 to 20, and packet 30
-     *   20,30,40-     -=>   Packet number 20, 30, and the range from 40 to the end
-     *   20-10,30-25   -=>   Range from 10 to 20, and from 25 to 30
-     *   -             -=>   All packets
+    /* Now we are going to process the ranges separately until we get a comma,
+     * or end of string.
      *
      * We build a structure array called GLrange of high and low values. After the
      * following loop, we have the GLnrange variable which tells how many ranges
-     * are found. 
-     * The number of different ranges is limited to 'MaxRanges'
+     * were found. The number of individual ranges is limited to 'MaxRanges'
      */
 
-    j = 0;    
+    j = 0;
     hyphenseen = FALSE;
     for (i=0; i<=strlen(EntryStr);i++) {
 
-       /* copy the digit string until a no-digit character is seen */
+       /* Copy the digit string until a no-digit character is seen */
        if (isdigit(EntryStr[i])) {
           value[j++] = EntryStr[i];
-	  continue;
+          continue;
        }
-	    
+
        /* Terminate the digit string, and convert it */
        value[j] = '\0';
        val=atol(value);
-       j=0;	       
+       j=0;
 
-       /* treatment in case we see a hyphen */
+       /* In case we see a hyphen, store the value we read in the low part 
+        * of GLrange. In case it is a trailer hyphen, store the low value, and
+        * set the high value to the maximum of packets captured.
+        */
        if (EntryStr[i] == '-') {
-	  /* if this is a trailer hyphen, then treat it in a different
-	   * way, then the high value is the maximum number of packets counted
-	   * and we are ready */
-	  if (i == strlen(EntryStr)-1) {
+          /* If this is a trailer hyphen, then treat it in a different
+           * way, then the high value is the maximum number of packets counted
+           * and we are ready 
+           */
+          if (i == strlen(EntryStr)-1) {
              GLrange[GLnrange].low  = val;
              GLrange[GLnrange].high = max_packets;
-	     GLnrange++;
-	     break;
-	  } else {
-	     /* if no digits were actually seen, the outcome of
-	      * a zeroed string conversion to interger is also 0. */
+             GLnrange++;
+             break;
+          } else {
+             /* Store the low value of the range */
              GLrange[GLnrange].low  = val;
-	  }
-	  hyphenseen=TRUE;
-	  continue;
+          }
+          hyphenseen=TRUE;
+          continue;
        }
-	    
-       /* treatment in case we see a comma, or end of string */
+
+       /* In case we see a comma, or end of string */
        if (EntryStr[i] == ',' || i == strlen(EntryStr)) {
-	  if (hyphenseen) {
-             GLrange[GLnrange].high = val;	
-	  } else {
-	     /* in this case we got a single packet number */
+          if (hyphenseen) {
+             /* Normal treatment: store the high value range in GLrange */
+             GLrange[GLnrange].high = val;
+          } else {
+             /* We did not see a hyphen and we get a comma, then this must
+              * be a single packet number */
              GLrange[GLnrange].low  = val;
              GLrange[GLnrange].high = val;
-	  }
-	  hyphenseen=FALSE;		  	  
+          }
+          hyphenseen=FALSE;
        }
-	    
-       /* Increase the index for ranges found, and protect
-        * against wildly outside array bounds */
+
+       /* Increase the index for the number of ranges we found, and protect
+        * against wildly outside array bound jumps */
        GLnrange++;
        if (GLnrange > MaxRange) {
-	   GLnrange--;
+           GLnrange--;
        }
     }
     GLnrange--;
 
     /*  Now we are going through the low and high values, and check
      *  whether they are in a proper order. Low should be equal or lower
-     *  than high. So, go through the loop and swap if needed
+     *  than high. So, go through the loop and swap if needed.
      */
     for (i=0; i <= GLnrange; i++) {
        if (GLrange[i].low > GLrange[i].high) {
-	  tmp = GLrange[i].low;
-	  GLrange[i].low  = GLrange[i].high;
-	  GLrange[i].high = tmp;
+          tmp = GLrange[i].low;
+          GLrange[i].low  = GLrange[i].high;
+          GLrange[i].high = tmp;
        }
     }
- 
+
     /* In case we want to know what the result ranges are :
-     * 
+     *
      * for (i=0; i <= GLnrange; i++) {
-     *  printf("L=%u\tH=%u\n",GLrange[i].low,GLrange[i].high);
+     *  printf("Function : packet_range_convert_str L=%u \t H=%u\n",GLrange[i].low,GLrange[i].high);
      * }
-     * 
+     *
      */
-    
-    /* End of conv_str_range() */
+
+    /* End of packet_range_convert_str() */
     return;
 }
-	   
-/* This function returns TRUE is the given value is within the range 
- *  of the input range entered via (Save/Print As). This is supposed to
- *  be a tiny and quick procedure since this is called for every packet
- *  to be potentially saved.
+
+/* This function returns TRUE if a given value is within one of the ranges
+ * stored in the GLrange array.
  */
-static gboolean packet_is_in_range(guint32 val) 
+static gboolean packet_is_in_range(guint32 val)
 {
    guint i;
-	
+
    for (i=0; i <= GLnrange; i++) {
       if (val >= GLrange[i].low && val <= GLrange[i].high)
-	 return TRUE;
+         return TRUE;
    }
-   return(FALSE);	
+   return(FALSE);
 }
 
+/* This is a debug function to check the range functionality */
 static void packet_is_in_range_check(guint32 val)
 {
-  printf("Checking %d\t",val);
+
+  /* Print the result for a given value */
+  printf("Function : packet_is_in_range_check Number %u\t",val);
+
   if (packet_is_in_range(val)) {
-     printf("TRUE\n");
+     printf("is in range\n");
   } else {
-     printf("FALSE\n");
+     printf("is not in range\n");
   }
 }