epan/range.h

   1 /* range.h
   2  * Range routines
   3  *
   4  * Dick Gooris <gooris@lucent.com>
   5  * Ulf Lamping <ulf.lamping@web.de>
   6  *
   7  * Wireshark - Network traffic analyzer
   8  * By Gerald Combs <gerald@wireshark.org>
   9  * Copyright 1998 Gerald Combs
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * as published by the Free Software Foundation; either version 2
  14  * of the License, or (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, write to the Free Software
  23  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  24  */
  25
  26 #ifndef __RANGE_H__
  27 #define __RANGE_H__
  28
  29 #include <glib.h>
  30 #include "ws_symbol_export.h"
  31 #include <epan/wmem/wmem.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif /* __cplusplus */
  36
  37 /** @file
  38  * Range strings a variant of value_strings
  39  */
  40
  41 /**@todo where's the best place for these? */
  42 #define MAX_SCTP_PORT 65535
  43 #define MAX_TCP_PORT 65535
  44 #define MAX_UDP_PORT 65535
  45 #define MAX_DCCP_PORT 65535
  46
  47 typedef struct range_admin_tag {
  48     guint32 low;
  49     guint32 high;
  50 } range_admin_t;
  51 #define RANGE_ADMIN_T_INITIALIZER { 0, 0 }
  52
  53 /** user specified range(s) */
  54 typedef struct epan_range {
  55     guint           nranges;   /**< number of entries in ranges */
  56     range_admin_t   ranges[1]; /**< variable-length array */
  57 } range_t;
  58
  59 /**
  60  * Return value from range_convert_str().
  61  */
  62 typedef enum {
  63     CVT_NO_ERROR,
  64     CVT_SYNTAX_ERROR,
  65     CVT_NUMBER_TOO_BIG
  66 } convert_ret_t;
  67
  68 WS_DLL_PUBLIC range_t *range_empty(wmem_allocator_t *scope);
  69
  70
  71 /*** Converts a range string to a fast comparable array of ranges.
  72  * This function allocates a range_t large enough to hold the number
  73  * of ranges specified, and fills the array range->ranges containing
  74  * low and high values with the number of ranges being range->nranges.
  75  * After having called this function, the function value_is_in_range()
  76  * determines whether a given number is within the range or not.<BR>
  77  * In case of a single number, we make a range where low is equal to high.
  78  * We take care on wrongly entered ranges; opposite order will be taken
  79  * care of.
  80  *
  81  * The following syntax is accepted :
  82  *
  83  *   1-20,30-40     Range from 1 to 20, and packets 30 to 40
  84  *   -20,30         Range from 1 to 20, and packet 30
  85  *   20,30,40-      20, 30, and the range from 40 to the end
  86  *   20-10,30-25    Range from 10 to 20, and from 25 to 30
  87  *   -              All values
  88  * @param scope memory scope for the range
  89  * @param range the range
  90  * @param es points to the string to be converted.
  91  * @param max_value specifies the maximum value in a range.
  92  * @return convert_ret_t
  93  */
  94 WS_DLL_PUBLIC convert_ret_t range_convert_str(wmem_allocator_t *scope, range_t **range, const gchar *es,
  95     guint32 max_value);
  96
  97 WS_DLL_PUBLIC convert_ret_t range_convert_str_work(wmem_allocator_t *scope, range_t **range, const gchar *es,
  98     guint32 max_value, gboolean err_on_max);
  99
 100 /** This function returns TRUE if a given value is within one of the ranges
 101  * stored in the ranges array.
 102  * @param range the range
 103  * @param val the value to check
 104  * @return TRUE if the value is in range
 105  */
 106 WS_DLL_PUBLIC gboolean value_is_in_range(range_t *range, guint32 val);
 107
 108 /** This function returns TRUE if val has successfully been added to
 109  * a range.  This may extend an existing range or create a new one
 110  * @param scope memory scope of range (in case of reallocation)
 111  * @param range to add value
 112  * @param val value to add to range
 113  * @return TRUE if the value is successsfully added to range
 114  */
 115 WS_DLL_PUBLIC gboolean range_add_value(wmem_allocator_t *scope, range_t **range, guint32 val);
 116
 117 /** This function returns TRUE if val has successfully been removed from
 118  * a range.  This may remove an existing range.
 119  * @param scope memory scope of range (in case of reallocation)
 120  * @param range to remove value
 121  * @param val value to remove within range
 122  * @return TRUE if the value is successsfully removed to range
 123  */
 124 WS_DLL_PUBLIC gboolean range_remove_value(wmem_allocator_t *scope, range_t **range, guint32 val);
 125
 126 /** This function returns TRUE if the two given range_t's are equal.
 127  * @param a first range
 128  * @param b second range
 129  * @return TRUE if the value is in range
 130  */
 131 WS_DLL_PUBLIC gboolean ranges_are_equal(range_t *a, range_t *b);
 132
 133 /** This function calls the provided callback function for each value in
 134  * in the range. Takes a pointer argument, which is passed to the
 135  * callback, along with the value in the range.
 136  * @param range the range
 137  * @param callback the callback function
 138  * @param ptr pointer passed to the callback
 139  */
 140 WS_DLL_PUBLIC void range_foreach(range_t *range, void (*callback)(guint32 val, gpointer ptr), gpointer ptr);
 141
 142 /**
 143  * This function converts a range_t to a (wmem_alloc()-allocated) string.
 144  */
 145 WS_DLL_PUBLIC char *range_convert_range(wmem_allocator_t *scope, const range_t *range);
 146
 147 /**
 148  * Create a (wmem-alloc()ed) copy of a range
 149  * @param scope memory scope for the copied range
 150  * @param src the range to copy
 151  * @return ep allocated copy of the range
 152  */
 153 WS_DLL_PUBLIC range_t *range_copy(wmem_allocator_t *scope, range_t *src);
 154
 155 #ifdef __cplusplus
 156 }
 157 #endif /* __cplusplus */
 158
 159 #endif /* __RANGE_H__ */