epan/value_string.h

   1 /* value_string.h
   2  * Definitions for value_string structures and routines
   3  *
   4  * $Id$
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public License
  12  * as published by the Free Software Foundation; either version 2
  13  * of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  23  */
  24
  25 #ifndef __VALUE_STRING_H__
  26 #define __VALUE_STRING_H__
  27
  28 #include <glib.h>
  29
  30 /* Struct for the val_to_str, match_strval_idx, and match_strval functions */
  31
  32 typedef struct _value_string {
  33   guint32  value;
  34   const gchar   *strptr;
  35 } value_string;
  36
  37 /* Struct for the str_to_str, match_strstr_idx, and match_strstr functions */
  38
  39 typedef struct _string_string {
  40   const gchar   *value;
  41   const gchar   *strptr;
  42 } string_string;
  43
  44 /* Struct for the rval_to_str, match_strrval_idx, and match_strrval functions */
  45 typedef struct _range_string {
  46   guint32        value_min;
  47   guint32        value_max;
  48   const gchar   *strptr;
  49 } range_string;
  50
  51 /* #define VS_DEF(x) { x, #x } */
  52 /* #define VS_END    { 0, NULL } */
  53
  54 /* Tries to match val against each element in the value_string array vs.
  55    Returns the associated string ptr, and sets "*idx" to the index in
  56    that table, on a match, and returns NULL, and sets "*idx" to -1,
  57    on failure. */
  58 extern const gchar* match_strval_idx(const guint32 val, const value_string *vs, gint *idx);
  59
  60 /* Like match_strval_idx(), but doesn't return the index. */
  61 extern const gchar* match_strval(const guint32 val, const value_string *vs);
  62
  63 /* Tries to match val against each element in the value_string array vs.
  64    Returns the associated string ptr on a match.
  65    Formats val with fmt, and returns the resulting string, on failure. */
  66 extern const gchar* val_to_str(const guint32 val, const value_string *vs, const char *fmt);
  67
  68
  69 /* Tries to match val against each element in the value_string array vs.
  70    Returns the associated string ptr on a match.
  71    Returns 'unknown_str', on failure. */
  72 extern const gchar* val_to_str_const(const guint32 val, const value_string *vs, const char *unknown_str);
  73
  74 /* Tries to match val against each element in the string_string array vs.
  75    Returns the associated string ptr, and sets "*idx" to the index in
  76    that table, on a match, and returns NULL, and sets "*idx" to -1,
  77    on failure. */
  78 extern const gchar* match_strstr_idx(const gchar *val, const string_string *vs, gint *idx);
  79
  80 /* Like match_strstr_idx(), but doesn't return the index. */
  81 extern const gchar* match_strstr(const gchar *val, const string_string *vs);
  82
  83 /* Tries to match val against each element in the string_string array vs.
  84    Returns the associated string ptr on a match.
  85    Formats val with fmt, and returns the resulting string, on failure. */
  86 extern const gchar* str_to_str(const gchar *val, const string_string *vs, const char *fmt);
  87
  88 /* --------------------------------------------------------------------*/
  89 /* value_string_ext functions
  90  *
  91  *   Extended value strings allow fast(er) value_string array lookups by
  92  *    using (if possible) direct access or a binary search of the array.
  93  *
  94  *    If the values in the value_string array are a contiguous range of values
  95  *    from min to max, the value will be used as as a direct index into the array.
  96  *
  97  *    If the values in the array are not contiguous (ie: there are "gaps"),
  98  *    but are in assending order a binary search will be used.
  99  *
 100  *    If direct access or binary search cannot be used, then a linear search
 101  *    is used.
 102  *
 103  *    Note that the value_string array used with VALUE_STRING_EXT_INIT
 104  *     *must* be terminated with {0, NULL}).
 105  *
 106  *    Extended value strings are defined at compile time as follows:
 107  *      static const value_string vs[] = { {value1, "string1"}, {value2, "string2"}, ..., {0, NULL}};
 108  *      static value_string_ext vse = VALUE_STRING_EXT_INIT(vs);
 109  *
 110  *    Extended value strings can be created at runtime by calling
 111  *      value_string_ext_new(<ptr to value_string array>,
 112  *                           <total number of entries in the value_string_array>,
 113  *                           <value_string_name>);
 114  *      Note: <total number of entries in the value_string_array> should include the {0, NULL} entry
 115  */
 116 /* --------------------------------------------------------------------*/
 117 struct _value_string_ext;
 118 typedef const value_string *(*_value_string_match2_t)(const guint32, const struct _value_string_ext *);
 119
 120 typedef struct _value_string_ext {
 121   _value_string_match2_t _vs_match2;
 122   guint32 _vs_first_value;    /* first value of the value_string array       */
 123   guint   _vs_num_entries;    /* number of entries in the value_string array */
 124                               /*  (excluding final {0, NULL})                */
 125   const value_string *_vs_p;  /* the value string array address              */
 126   const gchar *_vs_name;      /* vse "Name" (for error messages)             */
 127 } value_string_ext;
 128
 129 /* "Accessors" */
 130 #define VALUE_STRING_EXT_VS_P(x) (x)->_vs_p
 131 #define VALUE_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries
 132 #define VALUE_STRING_EXT_VS_NAME(x) (x)->_vs_name
 133
 134 /* (Fcns for use by proto_registrar_dump_values() [See proto.c]) */
 135 gboolean value_string_ext_validate(const value_string_ext *vse);
 136 const gchar *value_string_ext_match_type_str(const value_string_ext *vse);
 137 /* --- --- */
 138
 139 extern const value_string *_match_strval_ext_init(const guint32 val, const value_string_ext *vse);
 140 #define VALUE_STRING_EXT_INIT(x) { _match_strval_ext_init, 0, array_length(x)-1, x, #x }
 141
 142 /* Create a value_string_ext given a ptr to a value_string array and the total number of entries. */
 143 /* Note: vs_tot_num_entries should include the required {0, NULL} terminating entry of the array. */
 144 /* Return: a pointer to a gmalloc'd and initialized value_string_ext struct.                      */
 145 extern value_string_ext *value_string_ext_new(value_string *vs, guint vs_tot_num_entries, gchar *vs_name);
 146
 147 /* Looks up val in a value_string array using access method (direct, binary search
 148  *  or linear) determined at rutime during the initial access); (see _match_strval_ext_init)
 149  * Returns the associated string ptr on a match or NULL on failure.
 150  */
 151 extern const gchar* match_strval_ext(const guint32 val, const value_string_ext *vse);
 152
 153 /* Tries to match val against each element in the value_string array vs.
 154  *  Returns the associated string ptr, and sets "*idx" to the index in
 155  *  that table, on a match, and returns NULL, and sets "*idx" to -1,
 156  *  on failure.
 157  */
 158 extern const gchar* match_strval_idx_ext(const guint32 val, value_string_ext *vse, gint *idx);
 159
 160 /* Similar to match_strval_ext except that on failure
 161  * Formats val with fmt, and returns the resulting string
 162  */
 163 extern const gchar* val_to_str_ext(const guint32 val, const value_string_ext *vs, const char *fmt);
 164
 165 /* Similar to match_strval_ext except that on failure
 166  *  Returns 'unknown_str'
 167  */
 168 extern const gchar* val_to_str_ext_const(const guint32 val, const value_string_ext *vs, const char *unknown_str);
 169
 170 /* ---- ---- */
 171
 172 /* Generate a string describing an enumerated bitfield (an N-bit field
 173    with various specific values having particular names). */
 174 extern const char *decode_enumerated_bitfield(const guint32 val, const guint32 mask,
 175   const int width, const value_string *tab, const char *fmt);
 176
 177 /* Generate a string describing an enumerated bitfield (an N-bit field
 178    with various specific values having particular names). */
 179 extern const char *decode_enumerated_bitfield_shifted(const guint32 val, const guint32 mask,
 180   const int width, const value_string *tab, const char *fmt);
 181
 182
 183 /* ranges aware versions */
 184
 185 /* Tries to match val against each range in the range_string array rs.
 186    Returns the associated string ptr on a match.
 187    Formats val with fmt, and returns the resulting string, on failure. */
 188 extern const gchar* rval_to_str(const guint32 val, const range_string *rs, const char *fmt);
 189
 190 /* Tries to match val against each range in the range_string array rs.
 191    Returns the associated string ptr, and sets "*idx" to the index in
 192    that table, on a match, and returns NULL, and sets "*idx" to -1,
 193    on failure. */
 194 extern const gchar *match_strrval_idx(const guint32 val, const range_string *rs, gint *idx);
 195
 196 /* Like match_strrval_idx(), but doesn't return the index. */
 197 extern const gchar *match_strrval(const guint32 val, const range_string *rs);
 198
 199 #endif /* __VALUE_STRING_H__ */