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