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