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  */