epan/value_string.h

   1 /* value_string.h
   2  * Definitions for value_string structures and routines
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation; either version 2
  11  * of the License, or (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  21  */
  22
  23 #ifndef __VALUE_STRING_H__
  24 #define __VALUE_STRING_H__
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif /* __cplusplus */
  29
  30 #include <glib.h>
  31 #include "ws_symbol_export.h"
  32 #include "wmem/wmem.h"
  33
  34 /* VALUE TO STRING MATCHING */
  35
  36 typedef struct _value_string {
  37     guint32      value;
  38     const gchar *strptr;
  39 } value_string;
  40
  41 #if 0
  42   /* -----  VALUE_STRING "Helper" macros ----- */
  43
  44   /* Essentially: Provide the capability to define a list of value_strings once and
  45      then to expand the list as an enum and/or as a value_string array. */
  46
  47   /* Usage: */
  48
  49   /*- define list of value strings -*/
  50      #define foo_VALUE_STRING_LIST(XXX) \
  51         XXX( FOO_A, 1, "aaa" ) \
  52         XXX( FOO_B, 3, "bbb" )
  53
  54   /*- gen enum -*/
  55      VALUE_STRING_ENUM(foo);      /* gen's 'enum {FOO_A=1, FOO_B=3};' */
  56
  57   /*- gen value_string array -*/
  58      /* local */
  59      VALUE_STRING_ARRAY(foo);     /* gen's 'static const value_string foo[] = {{1,"aaa"}, {3,"bbb"}}; */
  60
  61      /* global */
  62      VALUE_STRING_ARRAY_GLOBAL_DEF(foo); /* gen's 'const value_string foo[] = {{1,"aaa"}, {3,"bbb"}}; */
  63      VALUE_STRING_ARRAY_GLOBAL_DCL(foo); /* gen's 'const value_string foo[]; */
  64
  65   /* Alternatively: */
  66      #define bar_VALUE_STRING_LIST(XXX) \
  67         XXX( BAR_A, 1) \
  68         XXX( BAR_B, 3)
  69
  70      VALUE_STRING_ENUM2(bar);     /* gen's 'enum {BAR_A=1, BAR_B=3};' */
  71      VALUE_STRING_ARRAY2(bar);    /* gen's 'static const value_string bar[] = {{1,"BAR_A"}, {3,"BAR_B"}}; */
  72      ...
  73 #endif
  74
  75 /* -- Public -- */
  76 #define VALUE_STRING_ENUM(              array_name) _VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY)
  77 #define VALUE_STRING_ARRAY(             array_name) _VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY, static)
  78 #define VALUE_STRING_ARRAY_GLOBAL_DEF(  array_name) _VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY)
  79 #define VALUE_STRING_ARRAY_GLOBAL_DCL(  array_name) _VS_ARRAY_SC_TYPE_NAME(array_name, extern)
  80
  81 #define VALUE_STRING_ENUM2(             array_name) _VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY2)
  82 #define VALUE_STRING_ARRAY2(            array_name) _VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY2, static)
  83 #define VALUE_STRING_ARRAY2_GLOBAL_DEF( array_name) _VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY2)
  84 #define VALUE_STRING_ARRAY2_GLOBAL_DCL( array_name) _VS_ARRAY_SC_TYPE_NAME(array_name, extern)
  85
  86 /* -- Private -- */
  87 #define _VS_ENUM_XXX(array_name, macro) \
  88 enum { \
  89     array_name##_VALUE_STRING_LIST(macro) \
  90     _##array_name##_ENUM_DUMMY = 0 \
  91 }
  92
  93 #define _VS_ARRAY_SC_XXX(array_name, macro, sc)  \
  94     _VS_ARRAY_SC_TYPE_NAME(array_name, sc) = { \
  95     array_name##_VALUE_STRING_LIST(macro) \
  96     { 0, NULL } \
  97 }
  98
  99 #define _VS_ARRAY_XXX(array_name, macro)  \
 100     _VS_ARRAY_TYPE_NAME(array_name) = { \
 101     array_name##_VALUE_STRING_LIST(macro) \
 102     { 0, NULL } \
 103 }
 104
 105 #define _VS_ARRAY_SC_TYPE_NAME(array_name, sc) sc const value_string array_name[]
 106 #define _VS_ARRAY_TYPE_NAME(array_name) const value_string array_name[]
 107
 108 #define _VS_ENUM_ENTRY( name, value, string) name = value,
 109 #define _VS_ARRAY_ENTRY(name, value, string) { value, string },
 110
 111 #define _VS_ENUM_ENTRY2( name, value) name = value,
 112 #define _VS_ARRAY_ENTRY2(name, value) { value, #name },
 113 /* ----- ----- */
 114
 115 WS_DLL_PUBLIC
 116 const gchar *
 117 val_to_str(const guint32 val, const value_string *vs, const char *fmt)
 118 G_GNUC_PRINTF(3, 0);
 119
 120 WS_DLL_PUBLIC
 121 gchar *
 122 val_to_str_wmem(wmem_allocator_t *scope, const guint32 val, const value_string *vs, const char *fmt)
 123 G_GNUC_PRINTF(4, 0);
 124
 125 WS_DLL_PUBLIC
 126 const gchar *
 127 val_to_str_const(const guint32 val, const value_string *vs, const char *unknown_str);
 128
 129 WS_DLL_PUBLIC
 130 const gchar *
 131 try_val_to_str(const guint32 val, const value_string *vs);
 132
 133 WS_DLL_PUBLIC
 134 const gchar *
 135 try_val_to_str_idx(const guint32 val, const value_string *vs, gint *idx);
 136
 137 /* 64-BIT VALUE TO STRING MATCHING */
 138
 139 typedef struct _val64_string {
 140     guint64      value;
 141     const gchar *strptr;
 142 } val64_string;
 143
 144 WS_DLL_PUBLIC
 145 const gchar *
 146 val64_to_str(const guint64 val, const val64_string *vs, const char *fmt)
 147 G_GNUC_PRINTF(3, 0);
 148
 149 WS_DLL_PUBLIC
 150 const gchar *
 151 val64_to_str_const(const guint64 val, const val64_string *vs, const char *unknown_str);
 152
 153 WS_DLL_PUBLIC
 154 const gchar *
 155 try_val64_to_str(const guint64 val, const val64_string *vs);
 156
 157 WS_DLL_PUBLIC
 158 const gchar *
 159 try_val64_to_str_idx(const guint64 val, const val64_string *vs, gint *idx);
 160
 161 /* STRING TO VALUE MATCHING */
 162
 163 WS_DLL_PUBLIC
 164 guint32
 165 str_to_val(const gchar *val, const value_string *vs, const guint32 err_val);
 166
 167 WS_DLL_PUBLIC
 168 gint
 169 str_to_val_idx(const gchar *val, const value_string *vs);
 170
 171 /* EXTENDED VALUE TO STRING MATCHING */
 172
 173 typedef struct _value_string_ext value_string_ext;
 174 typedef const value_string *(*_value_string_match2_t)(const guint32, value_string_ext*);
 175
 176 struct _value_string_ext {
 177     _value_string_match2_t _vs_match2;
 178     guint32                _vs_first_value; /* first value of the value_string array       */
 179     guint                  _vs_num_entries; /* number of entries in the value_string array */
 180                                             /*  (excluding final {0, NULL})                */
 181     const value_string    *_vs_p;           /* the value string array address              */
 182     const gchar           *_vs_name;        /* vse "Name" (for error messages)             */
 183 };
 184
 185 #define VALUE_STRING_EXT_VS_P(x)           (x)->_vs_p
 186 #define VALUE_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries
 187 #define VALUE_STRING_EXT_VS_NAME(x)        (x)->_vs_name
 188
 189 WS_DLL_PUBLIC
 190 const value_string *
 191 _try_val_to_str_ext_init(const guint32 val, value_string_ext *vse);
 192 #define VALUE_STRING_EXT_INIT(x) { _try_val_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x }
 193
 194 WS_DLL_PUBLIC
 195 value_string_ext *
 196 value_string_ext_new(const value_string *vs, guint vs_tot_num_entries, const gchar *vs_name);
 197
 198 WS_DLL_PUBLIC
 199 void
 200 value_string_ext_free(value_string_ext *vse);
 201
 202 WS_DLL_PUBLIC
 203 const gchar *
 204 val_to_str_ext(const guint32 val, value_string_ext *vse, const char *fmt)
 205 G_GNUC_PRINTF(3, 0);
 206
 207 WS_DLL_PUBLIC
 208 gchar *
 209 val_to_str_ext_wmem(wmem_allocator_t *scope, const guint32 val, value_string_ext *vse, const char *fmt)
 210 G_GNUC_PRINTF(4, 0);
 211
 212 WS_DLL_PUBLIC
 213 const gchar *
 214 val_to_str_ext_const(const guint32 val, value_string_ext *vs, const char *unknown_str);
 215
 216 WS_DLL_PUBLIC
 217 const gchar *
 218 try_val_to_str_ext(const guint32 val, value_string_ext *vse);
 219
 220 WS_DLL_PUBLIC
 221 const gchar *
 222 try_val_to_str_idx_ext(const guint32 val, value_string_ext *vse, gint *idx);
 223
 224 /* STRING TO STRING MATCHING */
 225
 226 typedef struct _string_string {
 227     const gchar *value;
 228     const gchar *strptr;
 229 } string_string;
 230
 231 WS_DLL_PUBLIC
 232 const gchar *
 233 str_to_str(const gchar *val, const string_string *vs, const char *fmt)
 234 G_GNUC_PRINTF(3, 0);
 235
 236 WS_DLL_PUBLIC
 237 const gchar *
 238 try_str_to_str(const gchar *val, const string_string *vs);
 239
 240 WS_DLL_PUBLIC
 241 const gchar *
 242 try_str_to_str_idx(const gchar *val, const string_string *vs, gint *idx);
 243
 244 /* RANGE TO STRING MATCHING */
 245
 246 typedef struct _range_string {
 247     guint32      value_min;
 248     guint32      value_max;
 249     const gchar *strptr;
 250 } range_string;
 251
 252 WS_DLL_PUBLIC
 253 const gchar *
 254 rval_to_str(const guint32 val, const range_string *rs, const char *fmt)
 255 G_GNUC_PRINTF(3, 0);
 256
 257 WS_DLL_PUBLIC
 258 const gchar *
 259 rval_to_str_const(const guint32 val, const range_string *rs, const char *unknown_str);
 260
 261 WS_DLL_PUBLIC
 262 const gchar *
 263 try_rval_to_str(const guint32 val, const range_string *rs);
 264
 265 WS_DLL_PUBLIC
 266 const gchar *
 267 try_rval_to_str_idx(const guint32 val, const range_string *rs, gint *idx);
 268
 269 WS_DLL_PUBLIC
 270 const gchar *
 271 try_rval64_to_str(const guint64 val, const range_string *rs);
 272
 273 WS_DLL_PUBLIC
 274 const gchar *
 275 try_rval64_to_str_idx(const guint64 val, const range_string *rs, gint *idx);
 276
 277 /* BYTES TO STRING MATCHING */
 278
 279 typedef struct _bytes_string {
 280   const guint8 *value;
 281   const size_t  value_length;
 282   const gchar  *strptr;
 283 } bytes_string;
 284
 285 WS_DLL_PUBLIC
 286 const gchar *
 287 bytesval_to_str(const guint8 *val, const size_t val_len, const bytes_string *bs, const char *fmt)
 288 G_GNUC_PRINTF(4, 0);
 289
 290 WS_DLL_PUBLIC
 291 const gchar *
 292 try_bytesval_to_str(const guint8 *val, const size_t val_len, const bytes_string *bs);
 293
 294 WS_DLL_PUBLIC
 295 const gchar *
 296 bytesprefix_to_str(const guint8 *haystack, const size_t haystack_len, const bytes_string *bs, const char *fmt)
 297 G_GNUC_PRINTF(4, 0);
 298
 299 WS_DLL_PUBLIC
 300 const gchar *
 301 try_bytesprefix_to_str(const guint8 *haystack, const size_t haystack_len, const bytes_string *bs);
 302
 303 /* MISC (generally do not use) */
 304
 305 WS_DLL_LOCAL
 306 gboolean
 307 value_string_ext_validate(const value_string_ext *vse);
 308
 309 WS_DLL_LOCAL
 310 const gchar *
 311 value_string_ext_match_type_str(const value_string_ext *vse);
 312
 313 #ifdef __cplusplus
 314 }
 315 #endif /* __cplusplus */
 316
 317 #endif /* __VALUE_STRING_H__ */
 318
 319 /*
 320  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 321  *
 322  * Local variables:
 323  * c-basic-offset: 4
 324  * tab-width: 8
 325  * indent-tabs-mode: nil
 326  * End:
 327  *
 328  * vi: set shiftwidth=4 tabstop=8 expandtab:
 329  * :indentSize=4:tabSize=8:noTabs=true:
 330  */