epan/expert.h

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