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  * SPDX-License-Identifier: GPL-2.0-or-later
  12  */
  13
  14 #ifndef __RANGE_H__
  15 #define __RANGE_H__
  16
  17 #include "ws_symbol_export.h"
  18 #include <epan/wmem_scopes.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif /* __cplusplus */
  23
  24 /** @file
  25  * Range strings a variant of value_strings
  26  */
  27
  28 /**@todo where's the best place for these? */
  29 #define MAX_SCTP_PORT 65535
  30 #define MAX_TCP_PORT 65535
  31 #define MAX_UDP_PORT 65535
  32 #define MAX_DCCP_PORT 65535
  33
  34 typedef struct range_admin_tag {
  35     uint32_t low;
  36     uint32_t high;
  37 } range_admin_t;
  38 #define RANGE_ADMIN_T_INITIALIZER { 0, 0 }
  39
  40 /** user specified range(s) */
  41 typedef struct epan_range {
  42     unsigned        nranges;   /**< number of entries in ranges */
  43     range_admin_t   ranges[];  /**< flexible array of range entries */
  44 } range_t;
  45
  46 /**
  47  * Return value from range_convert_str().
  48  */
  49 typedef enum {
  50     CVT_NO_ERROR,
  51     CVT_SYNTAX_ERROR,
  52     CVT_NUMBER_TOO_BIG
  53 } convert_ret_t;
  54
  55 WS_DLL_PUBLIC range_t *range_empty(wmem_allocator_t *scope);
  56
  57
  58 /*** Converts a range string to a fast comparable array of ranges.
  59  * This function allocates a range_t large enough to hold the number
  60  * of ranges specified, and fills the array range->ranges containing
  61  * low and high values with the number of ranges being range->nranges.
  62  * After having called this function, the function value_is_in_range()
  63  * determines whether a given number is within the range or not.<BR>
  64  * In case of a single number, we make a range where low is equal to high.
  65  * We take care on wrongly entered ranges; opposite order will be taken
  66  * care of.
  67  *
  68  * The following syntax is accepted :
  69  *
  70  *   1-20,30-40     Range from 1 to 20, and packets 30 to 40
  71  *   -20,30         Range from 1 to 20, and packet 30
  72  *   20,30,40-      20, 30, and the range from 40 to the end
  73  *   20-10,30-25    Range from 10 to 20, and from 25 to 30
  74  *   -              All values
  75  * @param scope memory scope for the range
  76  * @param range the range
  77  * @param es points to the string to be converted.
  78  * @param max_value specifies the maximum value in a range.
  79  * @return convert_ret_t
  80  */
  81 WS_DLL_PUBLIC convert_ret_t range_convert_str(wmem_allocator_t *scope, range_t **range, const char *es,
  82     uint32_t max_value);
  83
  84 WS_DLL_PUBLIC convert_ret_t range_convert_str_work(wmem_allocator_t *scope, range_t **range, const char *es,
  85     uint32_t max_value, bool err_on_max);
  86
  87 /** This function returns true if a given value is within one of the ranges
  88  * stored in the ranges array.
  89  * @param range the range
  90  * @param val the value to check
  91  * @return true if the value is in range
  92  */
  93 WS_DLL_PUBLIC bool value_is_in_range(const range_t *range, uint32_t val);
  94
  95 /** This function returns true if val has successfully been added to
  96  * a range.  This may extend an existing range or create a new one
  97  * @param scope memory scope of range (in case of reallocation)
  98  * @param range to add value
  99  * @param val value to add to range
 100  * @return true if the value is successfully added to range
 101  */
 102 WS_DLL_PUBLIC bool range_add_value(wmem_allocator_t *scope, range_t **range, uint32_t val);
 103
 104 /** This function returns true if val has successfully been removed from
 105  * a range.  This may remove an existing range.
 106  * @param scope memory scope of range (in case of reallocation)
 107  * @param range to remove value
 108  * @param val value to remove within range
 109  * @return true if the value is successfully removed to range
 110  */
 111 WS_DLL_PUBLIC bool range_remove_value(wmem_allocator_t *scope, range_t **range, uint32_t val);
 112
 113 /** This function returns true if the two given range_t's are equal.
 114  * @param a first range
 115  * @param b second range
 116  * @return true if the value is in range
 117  */
 118 WS_DLL_PUBLIC bool ranges_are_equal(const range_t *a, const range_t *b);
 119
 120 /** This function calls the provided callback function for each value in
 121  * in the range. Takes a pointer argument, which is passed to the
 122  * callback, along with the value in the range.
 123  * @param range the range
 124  * @param callback the callback function
 125  * @param ptr pointer passed to the callback
 126  */
 127 WS_DLL_PUBLIC void range_foreach(range_t *range, void (*callback)(uint32_t val, void *ptr), void *ptr);
 128
 129 /**
 130  * This function converts a range_t to a (wmem_alloc()-allocated) string.
 131  */
 132 WS_DLL_PUBLIC char *range_convert_range(wmem_allocator_t *scope, const range_t *range);
 133
 134 /**
 135  * Create a (wmem-alloc()ed) copy of a range
 136  * @param scope memory scope for the copied range
 137  * @param src the range to copy
 138  * @return ep allocated copy of the range
 139  */
 140 WS_DLL_PUBLIC range_t *range_copy(wmem_allocator_t *scope, const range_t *src);
 141
 142 #ifdef __cplusplus
 143 }
 144 #endif /* __cplusplus */
 145
 146 #endif /* __RANGE_H__ */