Wireshark 4.7.0
The Wireshark network protocol analyzer
Loading...
Searching...
No Matches
value_string.h
Go to the documentation of this file.
1
11#ifndef __VALUE_STRING_H__
12#define __VALUE_STRING_H__
13
14#include <stdint.h>
15
16#include "ws_symbol_export.h"
17
18#include <wsutil/nstime.h>
19
20#ifdef __cplusplus
21extern "C" {
22#endif /* __cplusplus */
23
24/* VALUE TO STRING MATCHING */
25
33typedef struct _value_string {
34 uint32_t value;
35 const char *strptr;
37
38
39#if 0
40 /* ----- VALUE_STRING "Helper" macros ----- */
41
42 /* Essentially: Provide the capability to define a list of value_strings once and
43 then to expand the list as an enum and/or as a value_string array. */
44
45 /* Usage: */
46
47 /*- define list of value strings -*/
48 #define foo_VALUE_STRING_LIST(XXX) \
49 XXX( FOO_A, 1, "aaa" ) \
50 XXX( FOO_B, 3, "bbb" )
51
52 /*- gen enum -*/
53 VALUE_STRING_ENUM(foo); /* gen's 'enum {FOO_A=1, FOO_B=3};' */
54
55 /*- gen value_string array -*/
56 /* local */
57 VALUE_STRING_ARRAY(foo); /* gen's 'static const value_string foo[] = {{1,"aaa"}, {3,"bbb"}}; */
58
59 /* global */
60 VALUE_STRING_ARRAY_GLOBAL_DEF(foo); /* gen's 'const value_string foo[] = {{1,"aaa"}, {3,"bbb"}}; */
61 VALUE_STRING_ARRAY_GLOBAL_DCL(foo); /* gen's 'const value_string foo[]; */
62
63 /* Alternatively: */
64 #define bar_VALUE_STRING_LIST(XXX) \
65 XXX( BAR_A, 1) \
66 XXX( BAR_B, 3)
67
68 VALUE_STRING_ENUM2(bar); /* gen's 'enum {BAR_A=1, BAR_B=3};' */
69 VALUE_STRING_ARRAY2(bar); /* gen's 'static const value_string bar[] = {{1,"BAR_A"}, {3,"BAR_B"}}; */
70 ...
71#endif
72
73/* -- Public -- */
74#define VALUE_STRING_ENUM( array_name) _VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY)
75#define VALUE_STRING_ARRAY( array_name) _VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY, static)
76#define VALUE_STRING_ARRAY_GLOBAL_DEF( array_name) _VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY)
77#define VALUE_STRING_ARRAY_GLOBAL_DCL( array_name) _VS_ARRAY_SC_TYPE_NAME(array_name, extern)
78
79#define VALUE_STRING_ENUM2( array_name) _VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY2)
80#define VALUE_STRING_ARRAY2( array_name) _VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY2, static)
81#define VALUE_STRING_ARRAY2_GLOBAL_DEF( array_name) _VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY2)
82#define VALUE_STRING_ARRAY2_GLOBAL_DCL( array_name) _VS_ARRAY_SC_TYPE_NAME(array_name, extern)
83
84/* -- Private -- */
85#define _VS_ENUM_XXX(array_name, macro) \
86enum { \
87 array_name##_VALUE_STRING_LIST(macro) \
88 _##array_name##_ENUM_DUMMY = 0 \
89}
90
91#define _VS_ARRAY_SC_XXX(array_name, macro, sc) \
92 _VS_ARRAY_SC_TYPE_NAME(array_name, sc) = { \
93 array_name##_VALUE_STRING_LIST(macro) \
94 { 0, NULL } \
95}
96
97#define _VS_ARRAY_XXX(array_name, macro) \
98 _VS_ARRAY_TYPE_NAME(array_name) = { \
99 array_name##_VALUE_STRING_LIST(macro) \
100 { 0, NULL } \
101}
102
103#define _VS_ARRAY_SC_TYPE_NAME(array_name, sc) sc const value_string array_name[]
104#define _VS_ARRAY_TYPE_NAME(array_name) const value_string array_name[]
105
106#define _VS_ENUM_ENTRY( name, value, string) name = value,
107#define _VS_ARRAY_ENTRY(name, value, string) { value, string },
108
109#define _VS_ENUM_ENTRY2( name, value) name = value,
110#define _VS_ARRAY_ENTRY2(name, value) { value, #name },
111/* ----- ----- */
112
127WS_DLL_PUBLIC
128char *
129val_to_str(wmem_allocator_t *scope, const uint32_t val, const value_string *vs, const char *fmt)
130G_GNUC_PRINTF(4, 0);
131
147WS_DLL_PUBLIC
148const char *
149val_to_str_const(const uint32_t val, const value_string *vs, const char *unknown_str);
150
164WS_DLL_PUBLIC
165const char *
166try_val_to_str(const uint32_t val, const value_string *vs);
167
183WS_DLL_PUBLIC
184const char *
185try_val_to_str_idx(const uint32_t val, const value_string *vs, int *idx);
186
187/* 64-BIT VALUE TO STRING MATCHING */
188
196typedef struct _val64_string {
197 uint64_t value;
198 const char *strptr;
200
215WS_DLL_PUBLIC
216const char *
217val64_to_str_wmem(wmem_allocator_t* scope, const uint64_t val, const val64_string *vs, const char *fmt)
218G_GNUC_PRINTF(4, 0);
219
235WS_DLL_PUBLIC
236const char *
237val64_to_str_const(const uint64_t val, const val64_string *vs, const char *unknown_str);
238
252WS_DLL_PUBLIC
253const char *
254try_val64_to_str(const uint64_t val, const val64_string *vs);
255
271WS_DLL_PUBLIC
272const char *
273try_val64_to_str_idx(const uint64_t val, const val64_string *vs, int *idx);
274
275/* STRING TO VALUE MATCHING */
276
291WS_DLL_PUBLIC
292uint32_t
293str_to_val(const char *val, const value_string *vs, const uint32_t err_val);
294
309WS_DLL_PUBLIC
310int
311str_to_val_idx(const char *val, const value_string *vs);
312
313/* EXTENDED VALUE TO STRING MATCHING */
314
316typedef const value_string *(*_value_string_match2_t)(const uint32_t, value_string_ext*);
317
326 _value_string_match2_t _vs_match2;
330 const char *_vs_name;
332};
333
334
335#define VALUE_STRING_EXT_VS_P(x) (x)->_vs_p
336#define VALUE_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries
337#define VALUE_STRING_EXT_VS_NAME(x) (x)->_vs_name
338
351WS_DLL_PUBLIC
352const value_string *
353_try_val_to_str_ext_init(const uint32_t val, value_string_ext *vse);
354#define VALUE_STRING_EXT_INIT(x) { _try_val_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x, NULL }
355
368WS_DLL_PUBLIC
370value_string_ext_new(wmem_allocator_t* scope, const value_string *vs, unsigned vs_tot_num_entries, const char *vs_name);
371
381WS_DLL_PUBLIC
382void
384
402WS_DLL_PUBLIC
403char *
404val_to_str_ext(wmem_allocator_t *scope, const uint32_t val, value_string_ext *vse, const char *fmt)
405G_GNUC_PRINTF(4, 0);
406
422WS_DLL_PUBLIC
423const char *
424val_to_str_ext_const(const uint32_t val, value_string_ext *vs, const char *unknown_str);
425
439WS_DLL_PUBLIC
440const char *
441try_val_to_str_ext(const uint32_t val, value_string_ext *vse);
442
459WS_DLL_PUBLIC
460const char *
461try_val_to_str_idx_ext(const uint32_t val, value_string_ext *vse, int *idx);
462
463/* EXTENDED 64-BIT VALUE TO STRING MATCHING */
464
466typedef const val64_string *(*_val64_string_match2_t)(const uint64_t, val64_string_ext*);
467
475 _val64_string_match2_t _vs_match2;
479 const char *_vs_name;
481};
482
483#define VAL64_STRING_EXT_VS_P(x) (x)->_vs_p
484#define VAL64_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries
485#define VAL64_STRING_EXT_VS_NAME(x) (x)->_vs_name
486
498WS_DLL_PUBLIC
499int
500value_str_value_compare(const void* a, const void* b);
501
518WS_DLL_PUBLIC
519const val64_string *
520_try_val64_to_str_ext_init(const uint64_t val, val64_string_ext *vse);
521#define VAL64_STRING_EXT_INIT(x) { _try_val64_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x, NULL }
522
523WS_DLL_PUBLIC
525val64_string_ext_new(wmem_allocator_t* scope, const val64_string *vs, unsigned vs_tot_num_entries, const char *vs_name);
526
527WS_DLL_PUBLIC
528void
529val64_string_ext_free(val64_string_ext *vse);
530
531WS_DLL_PUBLIC
532char *
533val64_to_str_ext_wmem(wmem_allocator_t *scope, const uint64_t val, val64_string_ext *vse, const char *fmt)
534G_GNUC_PRINTF(4, 0);
535
536WS_DLL_PUBLIC
537const char *
538val64_to_str_ext_const(const uint64_t val, val64_string_ext *vs, const char *unknown_str);
539
540WS_DLL_PUBLIC
541const char *
542try_val64_to_str_ext(const uint64_t val, val64_string_ext *vse);
543
544WS_DLL_PUBLIC
545const char *
546try_val64_to_str_idx_ext(const uint64_t val, val64_string_ext *vse, int *idx);
547
548/* STRING TO STRING MATCHING */
549
550typedef struct _string_string {
551 const char *value;
552 const char *strptr;
554
555WS_DLL_PUBLIC
556const char *
557str_to_str_wmem(wmem_allocator_t* scope, const char *val, const string_string *vs, const char *fmt)
558G_GNUC_PRINTF(4, 0);
559
560WS_DLL_PUBLIC
561const char *
562try_str_to_str(const char *val, const string_string *vs);
563
564WS_DLL_PUBLIC
565const char *
566try_str_to_str_idx(const char *val, const string_string *vs, int *idx);
567
568/* RANGE TO STRING MATCHING */
569
570typedef struct _range_string {
571 uint64_t value_min;
572 uint64_t value_max;
573 const char *strptr;
575
576WS_DLL_PUBLIC
577const char *
578rval_to_str_wmem(wmem_allocator_t* scope, const uint32_t val, const range_string *rs, const char *fmt)
579G_GNUC_PRINTF(4, 0);
580
581WS_DLL_PUBLIC
582const char *
583rval_to_str_const(const uint32_t val, const range_string *rs, const char *unknown_str);
584
585WS_DLL_PUBLIC
586const char *
587try_rval_to_str(const uint32_t val, const range_string *rs);
588
589WS_DLL_PUBLIC
590const char *
591try_rval_to_str_idx(const uint32_t val, const range_string *rs, int *idx);
592
593WS_DLL_PUBLIC
594const char *
595try_rval64_to_str(const uint64_t val, const range_string *rs);
596
597WS_DLL_PUBLIC
598const char *
599try_rval64_to_str_idx(const uint64_t val, const range_string *rs, int *idx);
600
601/* TIME TO STRING MATCHING */
602
603typedef struct _time_value_string {
604 nstime_t value;
605 const char *strptr;
607
608WS_DLL_PUBLIC
609const char *
610try_time_val_to_str(const nstime_t *val, const time_value_string *vs);
611
612/* BYTES TO STRING MATCHING */
613
614typedef struct _bytes_string {
615 const uint8_t *value;
616 const size_t value_length;
617 const char *strptr;
619
620WS_DLL_PUBLIC
621const char *
622bytesval_to_str_wmem(wmem_allocator_t* scope, const uint8_t *val, const size_t val_len, const bytes_string *bs, const char *fmt)
623G_GNUC_PRINTF(5, 0);
624
625WS_DLL_PUBLIC
626const char *
627try_bytesval_to_str(const uint8_t *val, const size_t val_len, const bytes_string *bs);
628
629WS_DLL_PUBLIC
630const char *
631bytesprefix_to_str(wmem_allocator_t* scope, const uint8_t *haystack, const size_t haystack_len, const bytes_string *bs, const char *fmt)
632G_GNUC_PRINTF(5, 0);
633
634WS_DLL_PUBLIC
635const char *
636try_bytesprefix_to_str(const uint8_t *haystack, const size_t haystack_len, const bytes_string *bs);
637
638WS_DLL_PUBLIC
639void register_external_value_string(const char* name, const value_string* vs);
640
641WS_DLL_PUBLIC
642value_string* get_external_value_string(const char* name);
643
644WS_DLL_PUBLIC
645void register_external_value_string_ext(const char* name, const value_string_ext* vse);
646
647WS_DLL_PUBLIC
648value_string_ext* get_external_value_string_ext(const char* name);
649
650/* MISC (generally do not use) */
651
652WS_DLL_PUBLIC
653void value_string_externals_init(void);
654
655WS_DLL_PUBLIC
656void value_string_externals_cleanup(void);
657
658WS_DLL_PUBLIC
659bool
660value_string_ext_validate(const value_string_ext *vse);
661
662WS_DLL_PUBLIC
663const char *
664value_string_ext_match_type_str(const value_string_ext *vse);
665
666WS_DLL_PUBLIC
667bool
668val64_string_ext_validate(const val64_string_ext *vse);
669
670WS_DLL_PUBLIC
671const char *
672val64_string_ext_match_type_str(const val64_string_ext *vse);
673
674#ifdef __cplusplus
675}
676#endif /* __cplusplus */
677
678#endif /* __VALUE_STRING_H__ */
679
680/*
681 * Editor modelines - https://www.wireshark.org/tools/modelines.html
682 *
683 * Local variables:
684 * c-basic-offset: 4
685 * tab-width: 8
686 * indent-tabs-mode: nil
687 * End:
688 *
689 * vi: set shiftwidth=4 tabstop=8 expandtab:
690 * :indentSize=4:tabSize=8:noTabs=true:
691 */
Definition value_string.h:614
Definition value_string.h:570
Definition value_string.h:550
Definition value_string.h:603
Extended metadata for a 64-bit value-string mapping array.
Definition value_string.h:474
const char * _vs_name
Definition value_string.h:479
uint64_t _vs_first_value
Definition value_string.h:476
unsigned _vs_num_entries
Definition value_string.h:477
_val64_string_match2_t _vs_match2
Definition value_string.h:475
wmem_allocator_t * _scope
Definition value_string.h:480
const val64_string * _vs_p
Definition value_string.h:478
Mapping between a 64-bit integer value and its string representation.
Definition value_string.h:196
uint64_t value
Definition value_string.h:197
const char * strptr
Definition value_string.h:198
Extended metadata for a value_string array.
Definition value_string.h:325
const value_string * _vs_p
Definition value_string.h:329
const char * _vs_name
Definition value_string.h:330
unsigned _vs_num_entries
Definition value_string.h:328
uint32_t _vs_first_value
Definition value_string.h:327
_value_string_match2_t _vs_match2
Definition value_string.h:326
wmem_allocator_t * _scope
Definition value_string.h:331
Mapping between a 32-bit integer value and its string representation.
Definition value_string.h:33
const char * strptr
Definition value_string.h:35
uint32_t value
Definition value_string.h:34
Definition wmem_allocator.h:27
Definition nstime.h:26
WS_DLL_PUBLIC value_string_ext * value_string_ext_new(wmem_allocator_t *scope, const value_string *vs, unsigned vs_tot_num_entries, const char *vs_name)
Create a new extended value-string mapping structure.
Definition value_string.c:258
WS_DLL_PUBLIC const char * try_val_to_str_idx(const uint32_t val, const value_string *vs, int *idx)
Attempt to convert a numeric value to a string and retrieve its index.
Definition value_string.c:90
WS_DLL_PUBLIC const char * try_val_to_str_ext(const uint32_t val, value_string_ext *vse)
Attempt to convert a numeric value to a string using an extended value-string mapping.
Definition value_string.c:289
WS_DLL_PUBLIC char * val_to_str_ext(wmem_allocator_t *scope, const uint32_t val, value_string_ext *vse, const char *fmt) G_GNUC_PRINTF(4
Convert a numeric value to a string using an extended value-string mapping.
struct _val64_string val64_string
Mapping between a 64-bit integer value and its string representation.
WS_DLL_PUBLIC int value_str_value_compare(const void *a, const void *b)
Compare two value_string entries by their numeric value.
Definition value_string.c:32
WS_DLL_PUBLIC char WS_DLL_PUBLIC const char * val_to_str_const(const uint32_t val, const value_string *vs, const char *unknown_str)
Convert a numeric value to a constant string using a value-string mapping.
Definition value_string.c:70
WS_DLL_PUBLIC char WS_DLL_PUBLIC const char * val_to_str_ext_const(const uint32_t val, value_string_ext *vs, const char *unknown_str)
Convert a numeric value to a constant string using an extended value-string mapping.
Definition value_string.c:335
WS_DLL_PUBLIC const char * try_val_to_str(const uint32_t val, const value_string *vs)
Attempt to convert a numeric value to a string using a value-string mapping.
Definition value_string.c:112
WS_DLL_PUBLIC void value_string_ext_free(value_string_ext *vse)
Free an extended value-string mapping structure.
Definition value_string.c:282
WS_DLL_PUBLIC char * val_to_str(wmem_allocator_t *scope, const uint32_t val, const value_string *vs, const char *fmt) G_GNUC_PRINTF(4
Convert a numeric value to a string using a value-string mapping.
WS_DLL_PUBLIC const char * try_val_to_str_idx_ext(const uint32_t val, value_string_ext *vse, int *idx)
Attempt to convert a numeric value to a string and retrieve its index from an extended mapping.
Definition value_string.c:304
WS_DLL_PUBLIC const char * try_val64_to_str(const uint64_t val, const val64_string *vs)
Attempt to convert a 64-bit value to a string using a value-string mapping.
Definition value_string.c:173
WS_DLL_PUBLIC const char * val64_to_str_wmem(wmem_allocator_t *scope, const uint64_t val, const val64_string *vs, const char *fmt) G_GNUC_PRINTF(4
Convert a 64-bit value to a string using a value-string mapping.
WS_DLL_PUBLIC int str_to_val_idx(const char *val, const value_string *vs)
Retrieve the index of a string in a value-string mapping array.
Definition value_string.c:200
struct _value_string value_string
Mapping between a 32-bit integer value and its string representation.
WS_DLL_PUBLIC const value_string * _try_val_to_str_ext_init(const uint32_t val, value_string_ext *vse)
Attempt to initialize and retrieve a value-string entry from an extended mapping.
Definition value_string.c:402
WS_DLL_PUBLIC const val64_string * _try_val64_to_str_ext_init(const uint64_t val, val64_string_ext *vse)
Attempt to initialize and retrieve a 64-bit value-string entry from an extended mapping.
Definition value_string.c:673
WS_DLL_PUBLIC const char * try_val64_to_str_idx(const uint64_t val, const val64_string *vs, int *idx)
Attempt to convert a 64-bit value to a string and retrieve its index.
Definition value_string.c:152
WS_DLL_PUBLIC const char WS_DLL_PUBLIC const char * val64_to_str_const(const uint64_t val, const val64_string *vs, const char *unknown_str)
Convert a 64-bit value to a constant string using a value-string mapping.
Definition value_string.c:136
WS_DLL_PUBLIC uint32_t str_to_val(const char *val, const value_string *vs, const uint32_t err_val)
Convert a string to its corresponding numeric value using a value-string mapping.
Definition value_string.c:185