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