checkAPIs.pl: support for new-style dissectors in check_hf_entries
[metze/wireshark/wip.git] / epan / expert.h
1 /* expert.h
2  * Collecting of Expert information.
3  *
4  * For further info, see: https://wiki.wireshark.org/Development/ExpertInfo
5  *
6  * Wireshark - Network traffic analyzer
7  * By Gerald Combs <gerald@wireshark.org>
8  * Copyright 1998 Gerald Combs
9  *
10  * SPDX-License-Identifier: GPL-2.0-or-later
11  */
12
13 #ifndef __EXPERT_H__
14 #define __EXPERT_H__
15
16 #include <epan/packet_info.h>
17 #include <epan/proto.h>
18 #include "value_string.h"
19 #include "ws_symbol_export.h"
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif /* __cplusplus */
24
25 /** only for internal and display use. */
26 typedef struct expert_info_s {
27         guint32      packet_num;
28         int          group;
29         int          severity;
30         int          hf_index; /* hf_index of the expert item. Might be -1. */
31         const gchar *protocol;
32         gchar       *summary;
33         proto_item  *pitem;
34 } expert_info_t;
35
36 /* Expert Info and Display hf data */
37 typedef struct expert_field
38 {
39         int ei;
40         int hf;
41 } expert_field;
42
43 #define EI_INIT_EI -1
44 #define EI_INIT_HF -1
45 #define EI_INIT {EI_INIT_EI, EI_INIT_HF}
46
47 typedef struct expert_field_info {
48         /* ---------- set by dissector --------- */
49         const char       *name;
50         int               group;
51         int               severity;
52         const gchar      *summary;
53
54         /* ------- set by register routines (prefilled by EXPFILL macro, see below) ------ */
55         int               id;
56         const gchar      *protocol;
57         int               orig_severity; /* Matches severity when registered, used to restore original severity
58                                           * if UAT severity entry is removed */
59         hf_register_info  hf_info;
60
61 } expert_field_info;
62
63 #define EXPFILL 0, NULL, 0, \
64         {0, {NULL, NULL, FT_NONE, BASE_NONE, NULL, 0, NULL, HFILL}}
65
66 typedef struct ei_register_info {
67         expert_field      *ids;         /**< written to by register() function */
68         expert_field_info  eiinfo;      /**< the field info to be registered */
69 } ei_register_info;
70
71 typedef struct expert_module expert_module_t;
72
73 #define PRE_ALLOC_EXPERT_FIELDS_MEM 5000
74
75 /* "proto_expert" is exported from libwireshark.dll.
76  * Thus we need a special declaration.
77  */
78 WS_DLL_PUBLIC int proto_expert;
79
80 extern void
81 expert_init(void);
82
83 extern void
84 expert_packet_init(void);
85
86 extern void
87 expert_cleanup(void);
88
89 extern void
90 expert_packet_cleanup(void);
91
92 WS_DLL_PUBLIC int
93 expert_get_highest_severity(void);
94
95 WS_DLL_PUBLIC void
96 expert_update_comment_count(guint64 count);
97
98 /** Add an expert info.
99  Add an expert info tree to a protocol item using registered expert info item
100  @param pinfo Packet info of the currently processed packet. May be NULL if
101         pi is supplied
102  @param pi Current protocol item (or NULL)
103  @param eiindex The registered expert info item
104  */
105 WS_DLL_PUBLIC void
106 expert_add_info(packet_info *pinfo, proto_item *pi, expert_field *eiindex);
107
108 /** Add an expert info.
109  Add an expert info tree to a protocol item using registered expert info item,
110  but with a formatted message.
111  @param pinfo Packet info of the currently processed packet. May be NULL if
112         pi is supplied
113  @param pi Current protocol item (or NULL)
114  @param eiindex The registered expert info item
115  @param format Printf-style format string for additional arguments
116  */
117 WS_DLL_PUBLIC void
118 expert_add_info_format(packet_info *pinfo, proto_item *pi, expert_field *eiindex,
119                        const char *format, ...) G_GNUC_PRINTF(4, 5);
120
121 /** Add an expert info associated with some byte data
122  Add an expert info tree to a protocol item using registered expert info item.
123  This function is intended to replace places where a "text only" proto_tree_add_xxx
124  API + expert_add_info would be used.
125  @param tree Current protocol tree (or NULL)
126  @param pinfo Packet info of the currently processed packet. May be NULL if tree is supplied
127  @param eiindex The registered expert info item
128  @param tvb the tv buffer of the current data
129  @param start start of data in tvb
130  @param length length of data in tvb
131  @return the newly created item above expert info tree
132  */
133 WS_DLL_PUBLIC proto_item *
134 proto_tree_add_expert(proto_tree *tree, packet_info *pinfo, expert_field *eiindex,
135         tvbuff_t *tvb, gint start, gint length);
136
137 /** Add an expert info associated with some byte data
138  Add an expert info tree to a protocol item, using registered expert info item,
139  but with a formatted message.
140  Add an expert info tree to a protocol item using registered expert info item.
141  This function is intended to replace places where a "text only" proto_tree_add_xxx
142  API + expert_add_info_format
143  would be used.
144  @param tree Current protocol tree (or NULL)
145  @param pinfo Packet info of the currently processed packet. May be NULL if tree is supplied
146  @param eiindex The registered expert info item
147  @param tvb the tv buffer of the current data
148  @param start start of data in tvb
149  @param length length of data in tvb
150  @param format Printf-style format string for additional arguments
151  @return the newly created item above expert info tree
152  */
153 WS_DLL_PUBLIC proto_item *
154 proto_tree_add_expert_format(proto_tree *tree, packet_info *pinfo, expert_field *eiindex,
155         tvbuff_t *tvb, gint start, gint length, const char *format, ...) G_GNUC_PRINTF(7, 8);
156
157 /*
158  * Register that a protocol has expert info.
159  */
160 WS_DLL_PUBLIC expert_module_t *expert_register_protocol(int id);
161
162 /**
163  * Deregister a expert info.
164  */
165 void expert_deregister_expertinfo (const char *abbrev);
166
167 /**
168  * Deregister expert info from a protocol.
169  */
170 void expert_deregister_protocol (expert_module_t *module);
171
172 /**
173  * Free deregistered expert infos.
174  */
175 void expert_free_deregistered_expertinfos (void);
176
177 /**
178  * Get summary text of an expert_info field.
179  * This is intended for use in expert_add_info_format or proto_tree_add_expert_format
180  * to get the "base" string to then append additional information
181  */
182 WS_DLL_PUBLIC const gchar* expert_get_summary(expert_field *eiindex);
183
184 /** Register a expert field array.
185  @param module the protocol handle from expert_register_protocol()
186  @param ei the ei_register_info array
187  @param num_records the number of records in exp */
188 WS_DLL_PUBLIC void
189 expert_register_field_array(expert_module_t *module, ei_register_info *ei, const int num_records);
190
191 #define EXPERT_CHECKSUM_DISABLED    -2
192 #define EXPERT_CHECKSUM_UNKNOWN     -1
193 #define EXPERT_CHECKSUM_GOOD        0
194 #define EXPERT_CHECKSUM_BAD         1
195
196 WS_DLL_PUBLIC const value_string expert_group_vals[];
197
198 WS_DLL_PUBLIC const value_string expert_severity_vals[];
199
200 WS_DLL_PUBLIC const value_string expert_checksum_vals[];
201
202 #ifdef __cplusplus
203 }
204 #endif /* __cplusplus */
205
206 #endif /* __EXPERT_H__ */
207
208 /*
209  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
210  *
211  * Local variables:
212  * c-basic-offset: 8
213  * tab-width: 8
214  * indent-tabs-mode: t
215  * End:
216  *
217  * vi: set shiftwidth=8 tabstop=8 noexpandtab:
218  * :indentSize=8:tabSize=8:noTabs=false:
219  */