Wireshark  2.9.0-477-g68ec514b
The Wireshark network protocol analyzer
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 
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 /* STRING TO STRING MATCHING */
213 
214 typedef struct _string_string {
215  const gchar *value;
216  const gchar *strptr;
217 } string_string;
218 
219 WS_DLL_PUBLIC
220 const gchar *
221 str_to_str(const gchar *val, const string_string *vs, const char *fmt)
222 G_GNUC_PRINTF(3, 0);
223 
224 WS_DLL_PUBLIC
225 const gchar *
226 try_str_to_str(const gchar *val, const string_string *vs);
227 
228 WS_DLL_PUBLIC
229 const gchar *
230 try_str_to_str_idx(const gchar *val, const string_string *vs, gint *idx);
231 
232 /* RANGE TO STRING MATCHING */
233 
234 typedef struct _range_string {
235  guint32 value_min;
236  guint32 value_max;
237  const gchar *strptr;
238 } range_string;
239 
240 WS_DLL_PUBLIC
241 const gchar *
242 rval_to_str(const guint32 val, const range_string *rs, const char *fmt)
243 G_GNUC_PRINTF(3, 0);
244 
245 WS_DLL_PUBLIC
246 const gchar *
247 rval_to_str_const(const guint32 val, const range_string *rs, const char *unknown_str);
248 
249 WS_DLL_PUBLIC
250 const gchar *
251 try_rval_to_str(const guint32 val, const range_string *rs);
252 
253 WS_DLL_PUBLIC
254 const gchar *
255 try_rval_to_str_idx(const guint32 val, const range_string *rs, gint *idx);
256 
257 WS_DLL_PUBLIC
258 const gchar *
259 try_rval64_to_str(const guint64 val, const range_string *rs);
260 
261 WS_DLL_PUBLIC
262 const gchar *
263 try_rval64_to_str_idx(const guint64 val, const range_string *rs, gint *idx);
264 
265 /* BYTES TO STRING MATCHING */
266 
267 typedef struct _bytes_string {
268  const guint8 *value;
269  const size_t value_length;
270  const gchar *strptr;
271 } bytes_string;
272 
273 WS_DLL_PUBLIC
274 const gchar *
275 bytesval_to_str(const guint8 *val, const size_t val_len, const bytes_string *bs, const char *fmt)
276 G_GNUC_PRINTF(4, 0);
277 
278 WS_DLL_PUBLIC
279 const gchar *
280 try_bytesval_to_str(const guint8 *val, const size_t val_len, const bytes_string *bs);
281 
282 WS_DLL_PUBLIC
283 const gchar *
284 bytesprefix_to_str(const guint8 *haystack, const size_t haystack_len, const bytes_string *bs, const char *fmt)
285 G_GNUC_PRINTF(4, 0);
286 
287 WS_DLL_PUBLIC
288 const gchar *
289 try_bytesprefix_to_str(const guint8 *haystack, const size_t haystack_len, const bytes_string *bs);
290 
291 /* MISC (generally do not use) */
292 
293 WS_DLL_LOCAL
294 gboolean
295 value_string_ext_validate(const value_string_ext *vse);
296 
297 WS_DLL_LOCAL
298 const gchar *
299 value_string_ext_match_type_str(const value_string_ext *vse);
300 
301 #ifdef __cplusplus
302 }
303 #endif /* __cplusplus */
304 
305 #endif /* __VALUE_STRING_H__ */
306 
307 /*
308  * Editor modelines - http://www.wireshark.org/tools/modelines.html
309  *
310  * Local variables:
311  * c-basic-offset: 4
312  * tab-width: 8
313  * indent-tabs-mode: nil
314  * End:
315  *
316  * vi: set shiftwidth=4 tabstop=8 expandtab:
317  * :indentSize=4:tabSize=8:noTabs=true:
318  */
Definition: value_string.h:234
Definition: value_string.h:127
Definition: value_string.h:267
Definition: wmem_allocator.h:26
Definition: value_string.h:214
Definition: value_string.h:24
Definition: value_string.h:164