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  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef __VALUE_STRING_H__
  12 #define __VALUE_STRING_H__
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif /* __cplusplus */
  17
  18 #include <glib.h>
  19 #include "ws_symbol_export.h"
  20 #include "wmem/wmem.h"
  21
  22 /* VALUE TO STRING MATCHING */
  23
  24 typedef struct _value_string {
  25     guint32      value;
  26     const gchar *strptr;
  27 } value_string;
  28
  29 #if 0
  30   /* -----  VALUE_STRING "Helper" macros ----- */
  31
  32   /* Essentially: Provide the capability to define a list of value_strings once and
  33      then to expand the list as an enum and/or as a value_string array. */
  34
  35   /* Usage: */
  36
  37   /*- define list of value strings -*/
  38      #define foo_VALUE_STRING_LIST(XXX) \
  39         XXX( FOO_A, 1, "aaa" ) \
  40         XXX( FOO_B, 3, "bbb" )
  41
  42   /*- gen enum -*/
  43      VALUE_STRING_ENUM(foo);      /* gen's 'enum {FOO_A=1, FOO_B=3};' */
  44
  45   /*- gen value_string array -*/
  46      /* local */
  47      VALUE_STRING_ARRAY(foo);     /* gen's 'static const value_string foo[] = {{1,"aaa"}, {3,"bbb"}}; */
  48
  49      /* global */
  50      VALUE_STRING_ARRAY_GLOBAL_DEF(foo); /* gen's 'const value_string foo[] = {{1,"aaa"}, {3,"bbb"}}; */
  51      VALUE_STRING_ARRAY_GLOBAL_DCL(foo); /* gen's 'const value_string foo[]; */
  52
  53   /* Alternatively: */
  54      #define bar_VALUE_STRING_LIST(XXX) \
  55         XXX( BAR_A, 1) \
  56         XXX( BAR_B, 3)
  57
  58      VALUE_STRING_ENUM2(bar);     /* gen's 'enum {BAR_A=1, BAR_B=3};' */
  59      VALUE_STRING_ARRAY2(bar);    /* gen's 'static const value_string bar[] = {{1,"BAR_A"}, {3,"BAR_B"}}; */
  60      ...
  61 #endif
  62
  63 /* -- Public -- */
  64 #define VALUE_STRING_ENUM(              array_name) _VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY)
  65 #define VALUE_STRING_ARRAY(             array_name) _VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY, static)
  66 #define VALUE_STRING_ARRAY_GLOBAL_DEF(  array_name) _VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY)
  67 #define VALUE_STRING_ARRAY_GLOBAL_DCL(  array_name) _VS_ARRAY_SC_TYPE_NAME(array_name, extern)
  68
  69 #define VALUE_STRING_ENUM2(             array_name) _VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY2)
  70 #define VALUE_STRING_ARRAY2(            array_name) _VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY2, static)
  71 #define VALUE_STRING_ARRAY2_GLOBAL_DEF( array_name) _VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY2)
  72 #define VALUE_STRING_ARRAY2_GLOBAL_DCL( array_name) _VS_ARRAY_SC_TYPE_NAME(array_name, extern)
  73
  74 /* -- Private -- */
  75 #define _VS_ENUM_XXX(array_name, macro) \
  76 enum { \
  77     array_name##_VALUE_STRING_LIST(macro) \
  78     _##array_name##_ENUM_DUMMY = 0 \
  79 }
  80
  81 #define _VS_ARRAY_SC_XXX(array_name, macro, sc)  \
  82     _VS_ARRAY_SC_TYPE_NAME(array_name, sc) = { \
  83     array_name##_VALUE_STRING_LIST(macro) \
  84     { 0, NULL } \
  85 }
  86
  87 #define _VS_ARRAY_XXX(array_name, macro)  \
  88     _VS_ARRAY_TYPE_NAME(array_name) = { \
  89     array_name##_VALUE_STRING_LIST(macro) \
  90     { 0, NULL } \
  91 }
  92
  93 #define _VS_ARRAY_SC_TYPE_NAME(array_name, sc) sc const value_string array_name[]
  94 #define _VS_ARRAY_TYPE_NAME(array_name) const value_string array_name[]
  95
  96 #define _VS_ENUM_ENTRY( name, value, string) name = value,
  97 #define _VS_ARRAY_ENTRY(name, value, string) { value, string },
  98
  99 #define _VS_ENUM_ENTRY2( name, value) name = value,
 100 #define _VS_ARRAY_ENTRY2(name, value) { value, #name },
 101 /* ----- ----- */
 102
 103 WS_DLL_PUBLIC
 104 const gchar *
 105 val_to_str(const guint32 val, const value_string *vs, const char *fmt)
 106 G_GNUC_PRINTF(3, 0);
 107
 108 WS_DLL_PUBLIC
 109 gchar *
 110 val_to_str_wmem(wmem_allocator_t *scope, const guint32 val, const value_string *vs, const char *fmt)
 111 G_GNUC_PRINTF(4, 0);
 112
 113 WS_DLL_PUBLIC
 114 const gchar *
 115 val_to_str_const(const guint32 val, const value_string *vs, const char *unknown_str);
 116
 117 WS_DLL_PUBLIC
 118 const gchar *
 119 try_val_to_str(const guint32 val, const value_string *vs);
 120
 121 WS_DLL_PUBLIC
 122 const gchar *
 123 try_val_to_str_idx(const guint32 val, const value_string *vs, gint *idx);
 124
 125 /* 64-BIT VALUE TO STRING MATCHING */
 126
 127 typedef struct _val64_string {
 128     guint64      value;
 129     const gchar *strptr;
 130 } val64_string;
 131
 132 WS_DLL_PUBLIC
 133 const gchar *
 134 val64_to_str(const guint64 val, const val64_string *vs, const char *fmt)
 135 G_GNUC_PRINTF(3, 0);
 136
 137 WS_DLL_PUBLIC
 138 const gchar *
 139 val64_to_str_const(const guint64 val, const val64_string *vs, const char *unknown_str);
 140
 141 WS_DLL_PUBLIC
 142 const gchar *
 143 try_val64_to_str(const guint64 val, const val64_string *vs);
 144
 145 WS_DLL_PUBLIC
 146 const gchar *
 147 try_val64_to_str_idx(const guint64 val, const val64_string *vs, gint *idx);
 148
 149 /* STRING TO VALUE MATCHING */
 150
 151 WS_DLL_PUBLIC
 152 guint32
 153 str_to_val(const gchar *val, const value_string *vs, const guint32 err_val);
 154
 155 WS_DLL_PUBLIC
 156 gint
 157 str_to_val_idx(const gchar *val, const value_string *vs);
 158
 159 /* EXTENDED VALUE TO STRING MATCHING */
 160
 161 typedef struct _value_string_ext value_string_ext;
 162 typedef const value_string *(*_value_string_match2_t)(const guint32, value_string_ext*);
 163
 164 struct _value_string_ext {
 165     _value_string_match2_t _vs_match2;
 166     guint32                _vs_first_value; /* first value of the value_string array       */
 167     guint                  _vs_num_entries; /* number of entries in the value_string array */
 168                                             /*  (excluding final {0, NULL})                */
 169     const value_string    *_vs_p;           /* the value string array address              */
 170     const gchar           *_vs_name;        /* vse "Name" (for error messages)             */
 171 };
 172
 173 #define VALUE_STRING_EXT_VS_P(x)           (x)->_vs_p
 174 #define VALUE_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries
 175 #define VALUE_STRING_EXT_VS_NAME(x)        (x)->_vs_name
 176
 177 WS_DLL_PUBLIC
 178 const value_string *
 179 _try_val_to_str_ext_init(const guint32 val, value_string_ext *vse);
 180 #define VALUE_STRING_EXT_INIT(x) { _try_val_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x }
 181
 182 WS_DLL_PUBLIC
 183 value_string_ext *
 184 value_string_ext_new(const value_string *vs, guint vs_tot_num_entries, const gchar *vs_name);
 185
 186 WS_DLL_PUBLIC
 187 void
 188 value_string_ext_free(value_string_ext *vse);
 189
 190 WS_DLL_PUBLIC
 191 const gchar *
 192 val_to_str_ext(const guint32 val, value_string_ext *vse, const char *fmt)
 193 G_GNUC_PRINTF(3, 0);
 194
 195 WS_DLL_PUBLIC
 196 gchar *
 197 val_to_str_ext_wmem(wmem_allocator_t *scope, const guint32 val, value_string_ext *vse, const char *fmt)
 198 G_GNUC_PRINTF(4, 0);
 199
 200 WS_DLL_PUBLIC
 201 const gchar *
 202 val_to_str_ext_const(const guint32 val, value_string_ext *vs, const char *unknown_str);
 203
 204 WS_DLL_PUBLIC
 205 const gchar *
 206 try_val_to_str_ext(const guint32 val, value_string_ext *vse);
 207
 208 WS_DLL_PUBLIC
 209 const gchar *
 210 try_val_to_str_idx_ext(const guint32 val, value_string_ext *vse, gint *idx);
 211
 212 /* EXTENDED 64-BIT VALUE TO STRING MATCHING */
 213
 214 typedef struct _val64_string_ext val64_string_ext;
 215 typedef const val64_string *(*_val64_string_match2_t)(const guint64, val64_string_ext*);
 216
 217 struct _val64_string_ext {
 218     _val64_string_match2_t _vs_match2;
 219     guint64                _vs_first_value; /* first value of the val64_string array       */
 220     guint                  _vs_num_entries; /* number of entries in the val64_string array */
 221                                             /*  (excluding final {0, NULL})                */
 222     const val64_string    *_vs_p;           /* the value string array address              */
 223     const gchar           *_vs_name;        /* vse "Name" (for error messages)             */
 224 };
 225
 226 #define VAL64_STRING_EXT_VS_P(x)           (x)->_vs_p
 227 #define VAL64_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries
 228 #define VAL64_STRING_EXT_VS_NAME(x)        (x)->_vs_name
 229
 230 WS_DLL_PUBLIC
 231 const val64_string *
 232 _try_val64_to_str_ext_init(const guint64 val, val64_string_ext *vse);
 233 #define VAL64_STRING_EXT_INIT(x) { _try_val64_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x }
 234
 235 WS_DLL_PUBLIC
 236 val64_string_ext *
 237 val64_string_ext_new(const val64_string *vs, guint vs_tot_num_entries, const gchar *vs_name);
 238
 239 WS_DLL_PUBLIC
 240 void
 241 val64_string_ext_free(val64_string_ext *vse);
 242
 243 WS_DLL_PUBLIC
 244 const gchar *
 245 val64_to_str_ext(const guint64 val, val64_string_ext *vse, const char *fmt)
 246 G_GNUC_PRINTF(3, 0);
 247
 248 WS_DLL_PUBLIC
 249 gchar *
 250 val64_to_str_ext_wmem(wmem_allocator_t *scope, const guint64 val, val64_string_ext *vse, const char *fmt)
 251 G_GNUC_PRINTF(4, 0);
 252
 253 WS_DLL_PUBLIC
 254 const gchar *
 255 val64_to_str_ext_const(const guint64 val, val64_string_ext *vs, const char *unknown_str);
 256
 257 WS_DLL_PUBLIC
 258 const gchar *
 259 try_val64_to_str_ext(const guint64 val, val64_string_ext *vse);
 260
 261 WS_DLL_PUBLIC
 262 const gchar *
 263 try_val64_to_str_idx_ext(const guint64 val, val64_string_ext *vse, gint *idx);
 264
 265 /* STRING TO STRING MATCHING */
 266
 267 typedef struct _string_string {
 268     const gchar *value;
 269     const gchar *strptr;
 270 } string_string;
 271
 272 WS_DLL_PUBLIC
 273 const gchar *
 274 str_to_str(const gchar *val, const string_string *vs, const char *fmt)
 275 G_GNUC_PRINTF(3, 0);
 276
 277 WS_DLL_PUBLIC
 278 const gchar *
 279 try_str_to_str(const gchar *val, const string_string *vs);
 280
 281 WS_DLL_PUBLIC
 282 const gchar *
 283 try_str_to_str_idx(const gchar *val, const string_string *vs, gint *idx);
 284
 285 /* RANGE TO STRING MATCHING */
 286
 287 typedef struct _range_string {
 288     guint32      value_min;
 289     guint32      value_max;
 290     const gchar *strptr;
 291 } range_string;
 292
 293 WS_DLL_PUBLIC
 294 const gchar *
 295 rval_to_str(const guint32 val, const range_string *rs, const char *fmt)
 296 G_GNUC_PRINTF(3, 0);
 297
 298 WS_DLL_PUBLIC
 299 const gchar *
 300 rval_to_str_const(const guint32 val, const range_string *rs, const char *unknown_str);
 301
 302 WS_DLL_PUBLIC
 303 const gchar *
 304 try_rval_to_str(const guint32 val, const range_string *rs);
 305
 306 WS_DLL_PUBLIC
 307 const gchar *
 308 try_rval_to_str_idx(const guint32 val, const range_string *rs, gint *idx);
 309
 310 WS_DLL_PUBLIC
 311 const gchar *
 312 try_rval64_to_str(const guint64 val, const range_string *rs);
 313
 314 WS_DLL_PUBLIC
 315 const gchar *
 316 try_rval64_to_str_idx(const guint64 val, const range_string *rs, gint *idx);
 317
 318 /* BYTES TO STRING MATCHING */
 319
 320 typedef struct _bytes_string {
 321   const guint8 *value;
 322   const size_t  value_length;
 323   const gchar  *strptr;
 324 } bytes_string;
 325
 326 WS_DLL_PUBLIC
 327 const gchar *
 328 bytesval_to_str(const guint8 *val, const size_t val_len, const bytes_string *bs, const char *fmt)
 329 G_GNUC_PRINTF(4, 0);
 330
 331 WS_DLL_PUBLIC
 332 const gchar *
 333 try_bytesval_to_str(const guint8 *val, const size_t val_len, const bytes_string *bs);
 334
 335 WS_DLL_PUBLIC
 336 const gchar *
 337 bytesprefix_to_str(const guint8 *haystack, const size_t haystack_len, const bytes_string *bs, const char *fmt)
 338 G_GNUC_PRINTF(4, 0);
 339
 340 WS_DLL_PUBLIC
 341 const gchar *
 342 try_bytesprefix_to_str(const guint8 *haystack, const size_t haystack_len, const bytes_string *bs);
 343
 344 /* MISC (generally do not use) */
 345
 346 WS_DLL_LOCAL
 347 gboolean
 348 value_string_ext_validate(const value_string_ext *vse);
 349
 350 WS_DLL_LOCAL
 351 const gchar *
 352 value_string_ext_match_type_str(const value_string_ext *vse);
 353
 354 WS_DLL_LOCAL
 355 gboolean
 356 val64_string_ext_validate(const val64_string_ext *vse);
 357
 358 WS_DLL_LOCAL
 359 const gchar *
 360 val64_string_ext_match_type_str(const val64_string_ext *vse);
 361
 362 #ifdef __cplusplus
 363 }
 364 #endif /* __cplusplus */
 365
 366 #endif /* __VALUE_STRING_H__ */
 367
 368 /*
 369  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 370  *
 371  * Local variables:
 372  * c-basic-offset: 4
 373  * tab-width: 8
 374  * indent-tabs-mode: nil
 375  * End:
 376  *
 377  * vi: set shiftwidth=4 tabstop=8 expandtab:
 378  * :indentSize=4:tabSize=8:noTabs=true:
 379  */