| Wireshark 4.7.3 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
json-dictionary.h
1/* json-dictionary.h
2 * JSON dictionary parsing for JSON protocol dissector
3 * Copyright 2026, Mark Stout <mark.stout@markstout.com>
4 *
5 * Wireshark - Network traffic analyzer
6 * By Gerald Combs <gerald@wireshark.org>
7 * Copyright 1998 Gerald Combs
8 *
9 * SPDX-License-Identifier: GPL-2.0-or-later
10 */
11
12#ifndef __JSON_DICTIONARY_H__
13#define __JSON_DICTIONARY_H__
14
15#include <glib.h>
16#include <libxml/parser.h>
17#include <epan/wmem_scopes.h>
18#include <epan/packet.h>
19#include <wsutil/value_string.h>
20#include <wsutil/wsjson.h>
21
22// Field type enumeration
23 typedef enum {
24 JSON_FIELD_STRING,
25 JSON_FIELD_INTEGER,
26 JSON_FIELD_UNSIGNED,
27 JSON_FIELD_FLOAT,
28 JSON_FIELD_BOOLEAN,
29 JSON_FIELD_OBJECT,
30 JSON_FIELD_ARRAY,
31 JSON_FIELD_NULL
32} json_field_type_t;
33
34// Display type enumeration for special formatting
35 typedef enum {
36 JSON_DISPLAY_NONE,
37 JSON_DISPLAY_IPV4,
38 JSON_DISPLAY_IPV6,
39 JSON_DISPLAY_ETHER,
40 JSON_DISPLAY_ABSOLUTE_TIME,
41 JSON_DISPLAY_RELATIVE_TIME,
42 JSON_DISPLAY_HEX2DEC
43} json_display_type_t;
44
45 typedef struct _json_field_t json_field_t;
46
47/* Field definition structure */
48 struct _json_field_t {
49 char *name; /* Display name */
50 char *path; /* JSON path (e.g., "user.profile.age") */
51 unsigned path_hash; /* Hash for O(1) lookup */
52 json_field_type_t type; /* Field type */
53 json_display_type_t display_type; /* Special display formatting */
54 int hf_value; /* Wireshark header field index */
55 int *ett; /* Pointer to subtree index (for objects/arrays) */
56 value_string *enum_values; /* For enumerated fields */
57 wmem_tree_t *child_fields; /* Child fields (for objects/arrays) */
58 void *type_data; /* Type-specific data */
59 char *info_label; /* Custom label for Info column (NULL = don't show) */
60 char *parser; /* External parser script path (relative to parsers/ dir) */
61 char *parser_args; /* Additional arguments for parser */
62 wmem_tree_t *parser_child_hf; /* Dynamic header fields from parser (filter → hf_index) */
63 bool case_insensitive; /* Enable case-insensitive path matching */
64 GSList *wildcard_fields; /* Ordered list of json_wildcard_field_t* (NULL if none) */
65};
66
67// Forward declaration to keep wsutil/regex.h optional for callers
68 struct _ws_regex;
69
70/* Runtime wildcard field — one per <wildcardfield> element */
71 typedef struct _json_wildcard_field_t json_wildcard_field_t;
72 struct _json_wildcard_field_t {
73 char *name; /* display name */
74 char *path; /* full path string */
75 char *alias; /* last segment of path — substituted for runtime key */
76 char *display_value; /* label for key-value string field */
77 struct _ws_regex *match_re; /* compiled PCRE2 regex */
78 wmem_tree_t *child_fields; /* child json_field_t entries keyed by path */
79 GSList *child_wildcards; /* nested json_wildcard_field_t entries (ordered) */
80 int hf_key_value; /* hf index for the auto key-value string field */
81 int *ett; /* subtree index */
82};
83
84// Dictionary structure
85 typedef struct _json_dictionary_t {
86 wmem_tree_t *fields; // Field definitions (path hash → json_field_t)
87 wmem_tree_t *protocols; // Protocol definitions (port → json_protocol_t)
88 value_string_ext *types; // Type name → type enum mapping
89 bool has_case_insensitive_fields; // Optimization flag: true if any field is case-insensitive
90 GSList *path_matchers; // List of json_protocol_t* with non-NULL path_regex (HTTP/2 :path dispatch)
91 GSList *all_protocols; // List of every json_protocol_t* loaded. Used at cleanup to free
92 // heap-allocated fields (path_regex, port_list nodes) that aren't
93 // wmem-managed.
94 bool has_any_protocol; // True if at least one <protocol> with port= or path= was loaded.
95 // When true, field-level dictionary parsing is gated on a
96 // per-packet protocol match. When false (no protocols defined),
97 // dictionary fields are applied globally for backward compat.
98 GSList *wildcard_regexes; // List of struct _ws_regex* compiled for <wildcardfield> match= attrs.
99 // Freed at shutdown by json_dictionary_cleanup().
100} json_dictionary_t;
101
102/* Protocol definition */
103 typedef struct _json_protocol_t {
104 char *name; // Protocol nam
105 char *display_name; // Custom display name for Protocol column
106 unsigned port; // Default port
107 char *transport; // tcp or udp
108 char **content_types; // Array of content-type strings
109 struct _ws_regex *path_regex; // Compiled regex (NULL if no path= or compile failed)
110 bool path_case_sensitive; // True if path matching is case-sensitive
111 bool require_all; // condition="and": when BOTH port and path are set, both must match.
112 // When only one is set, this is a no-op (the single condition is checked).
113 GSList *port_list; // List of unsigned* port numbers this protocol is bound to.
114 // Stored on the protocol so dispatch can verify port membership when
115 // checking the AND condition. Owned via wmem_epan_scope().
116 wmem_tree_t *fields; // Protocol-scoped field tree (path → json_field_t*). NULL when
117 // this protocol's file defined no <field> elements, or when the
118 // file had no <protocol> at all. Populated by parse_dictionary_file()
119 // after all fields are created. Shares json_field_t* pointers with
120 // the global dict->fields — no duplication.
121 bool has_case_insensitive_fields; // True if any field in this protocol's tree is case_insensitive.
122 int hf_proto_present; // FT_BOOLEAN hf index for "json.<sanitized-name>". Set to -1
123 // until registration; used to mark matched packets filterable.
124} json_protocol_t;
125
126/* Dictionary XML element names */
127#define XML_ELEMENT_DICTIONARY "json-dictionary"
128#define XML_ELEMENT_BASE "base"
129#define XML_ELEMENT_TYPEDEFN "typedefn"
130#define XML_ELEMENT_PROTOCOL "protocol"
131#define XML_ELEMENT_FIELD "field"
132#define XML_ELEMENT_ARRAY_ELEMENT "array-element"
133#define XML_ELEMENT_ENUM "enum"
134#define XML_ELEMENT_CONTENT_TYPE "content-type"
135#define XML_ELEMENT_WILDCARDFIELD "wildcardfield"
136
137/* XML attribute names */
138#define XML_ATTR_NAME "name"
139#define XML_ATTR_VERSION "version"
140#define XML_ATTR_TYPE_NAME "type-name"
141#define XML_ATTR_BASE_TYPE "base-type"
142#define XML_ATTR_DISPLAY "display"
143#define XML_ATTR_DISPLAY_NAME "displayName"
144#define XML_ATTR_PORT "port"
145#define XML_ATTR_TRANSPORT "transport"
146#define XML_ATTR_PATH "path"
147#define XML_ATTR_TYPE "type"
148#define XML_ATTR_DESCRIPTION "description"
149#define XML_ATTR_VALUE "value"
150#define XML_ATTR_CODE "code"
151#define XML_ATTR_INFO "info"
152#define XML_ATTR_DF "df"
153#define XML_ATTR_PARSER "parser"
154#define XML_ATTR_PARSER_ARGS "parser-args"
155#define XML_ATTR_CASE "case"
156#define XML_ATTR_CONDITION "condition"
157#define XML_ATTR_DISPLAY_VALUE "displayvalue"
158#define XML_ATTR_MATCH "match"
159
160// Temporary structures for XML parsing
161 typedef struct _dict_type_def {
162 xmlChar *type_name;
163 xmlChar *base_type;
164 xmlChar *display;
165} dict_type_def_t;
166
167 typedef struct _dict_enum_def {
168 xmlChar *value;
169 unsigned code;
170 xmlChar *description;
171} dict_enum_def_t;
172
173 typedef struct _dict_wildcardfield_def_t dict_wildcardfield_def_t;
174 struct _dict_wildcardfield_def_t {
175 xmlChar *name; // display name
176 xmlChar *path; // full path (e.g. "dnnConfigurations.apn")
177 xmlChar *alias; // last segment of path (e.g. "apn") — derived at parse time
178 xmlChar *display_value; // label for the key-value string field (default "key")
179 xmlChar *match; // PCRE2 regex string matched against runtime key
180 GSList *child_fields; // List of dict_field_def_t (regular children)
181 GSList *child_wildcards; // List of dict_wildcardfield_def_t (nested wildcards)
182};
183
184 typedef struct _dict_field_def {
185 xmlChar *name;
186 xmlChar *path;
187 xmlChar *type;
188 xmlChar *description;
189 GSList *child_fields; // List of dict_field_def_t
190 GSList *enum_values; // List of dict_enum_def_t
191 GSList *wildcard_children; // List of dict_wildcardfield_def_t
192 bool is_array_element;
193 xmlChar *info_label; // Custom label for Info column (NULL = don't show)
194 xmlChar *display_filter; // Custom display filter name (NULL = use path-based name)
195 xmlChar *parser; // External parser script path
196 xmlChar *parser_args; // Additional arguments for parser
197 xmlChar *case_attr; // "sensitive" or "insensitive" - case sensitivity for path matching
198} dict_field_def_t;
199
200 typedef struct _dict_protocol_def {
201 xmlChar *name;
202 xmlChar *display_name; // Custom display name for Protocol column
203 GSList *ports; // List of unsigned port numbers - supports comma-separated ports
204 xmlChar *transport;
205 GSList *content_types; // List of xmlChar*
206 GSList *fields; // List of dict_field_def_t
207 xmlChar *path; // Regex pattern matched against HTTP/2 :path (NULL if none)
208 xmlChar *case_attr; // "sensitive" or "insensitive" — default sensitive
209 xmlChar *condition_attr; // "and" (default) or "or" — combines port and path conditions
210} dict_protocol_def_t;
211
212/* Free regex objects and port-list nodes owned by the dictionary. Walks
213 * dict->path_matchers to release each ws_regex_t, then dict->all_protocols to
214 * release each port_list, then frees both lists. Called from packet-json.c via
215 * register_shutdown_routine at program exit. */
216 void json_dictionary_cleanup(json_dictionary_t *dict);
217
218/* Load dictionary from XML files
219 * Returns true if successful, false otherwise
220 */
221 bool load_json_dictionary(wmem_array_t *hf_array, GPtrArray *ett_array,
222 json_dictionary_t *dict);
223
224// Cleanup functions for temporary structures
225 void dict_type_def_free(dict_type_def_t *type_def);
226 void dict_enum_def_free(dict_enum_def_t *enum_def);
227 void dict_field_def_free(dict_field_def_t *field_def);
228 void dict_protocol_def_free(dict_protocol_def_t *proto_def);
229
230#endif /* __JSON_DICTIONARY_H__ */
231
232/*
233 * Editor modelines - https://www.wireshark.org/tools/modelines.html
234 *
235 * Local variables:
236 * c-basic-offset: 8
237 * tab-width: 8
238 * indent-tabs-mode: t
239 * End:
240 *
241 * vi: set shiftwidth=8 tabstop=8 noexpandtab:
242 * :indentSize=8:tabSize=8:noTabs=false:
243 */
wmem_array_t
struct _wmem_array_t wmem_array_t
Opaque type representing a dynamically resizable array in the wmem system.
Definition wmem_array.h:42
wmem_tree_t
struct _wmem_tree_t wmem_tree_t
Opaque type representing a red-black tree in the wmem system.
Definition wmem_tree.h:49
packet.h
_dict_enum_def
Definition json-dictionary.h:167
_dict_field_def
Definition json-dictionary.h:184
_dict_protocol_def
Definition json-dictionary.h:200
_dict_type_def
Definition json-dictionary.h:161
_dict_wildcardfield_def_t
Definition json-dictionary.h:174
_json_dictionary_t
Definition json-dictionary.h:85
_json_field_t
Definition json-dictionary.h:48
_json_protocol_t
Definition json-dictionary.h:103
_json_wildcard_field_t
Definition json-dictionary.h:72
_ws_regex
Definition regex.c:17
value_string.h
value_string
struct _value_string value_string
Mapping between a 32-bit integer value and its string representation.
wmem_scopes.h
wsjson.h