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