epan/expert.h

   1 /* expert.h
   2  * Collecting of Expert information.
   3  *
   4  * For further info, see: http://wiki.wireshark.org/Development/ExpertInfo
   5  *
   6  * $Id$
   7  *
   8  * Wireshark - Network traffic analyzer
   9  * By Gerald Combs <gerald@wireshark.org>
  10  * Copyright 1998 Gerald Combs
  11  *
  12  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License
  14  * as published by the Free Software Foundation; either version 2
  15  * of the License, or (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  25  */
  26
  27 #ifndef __EXPERT_H__
  28 #define __EXPERT_H__
  29
  30 #include <epan/packet_info.h>
  31 #include <epan/proto.h>
  32 #include "value_string.h"
  33 #include "ws_symbol_export.h"
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif /* __cplusplus */
  38
  39 /** only for internal and display use. */
  40 typedef struct expert_info_s {
  41         guint32 packet_num;
  42         int group;
  43         int severity;
  44         const gchar *protocol;
  45         gchar *summary;
  46         proto_item *pitem;
  47 } expert_info_t;
  48
  49 /* Expert Info and Display hf data */
  50 typedef struct expert_field
  51 {
  52         int ei;
  53         int hf;
  54 } expert_field;
  55
  56 #define EI_INIT {-1, -1}
  57
  58 typedef struct expert_field_info {
  59         /* ---------- set by dissector --------- */
  60         const char *name;
  61         int group;
  62         int severity;
  63         const gchar *summary;
  64
  65         /* ------- set by register routines (prefilled by EXPFILL macro, see below) ------ */
  66         int id;
  67         const gchar *protocol;
  68         hf_register_info hf_info;
  69
  70 } expert_field_info;
  71
  72 #define EXPFILL 0, NULL, \
  73         {0, {"Expert Info", NULL, FT_NONE, BASE_NONE, NULL, 0, NULL, HFILL}}
  74
  75 typedef struct ei_register_info {
  76         expert_field      *ids;         /**< written to by register() function */
  77         expert_field_info eiinfo;      /**< the field info to be registered */
  78 } ei_register_info;
  79
  80 typedef struct expert_module expert_module_t;
  81
  82 static const value_string expert_group_vals[] = {
  83         { PI_CHECKSUM,          "Checksum" },
  84         { PI_SEQUENCE,          "Sequence" },
  85         { PI_RESPONSE_CODE,     "Response" },
  86         { PI_REQUEST_CODE,      "Request" },
  87         { PI_UNDECODED,         "Undecoded" },
  88         { PI_REASSEMBLE,        "Reassemble" },
  89         { PI_MALFORMED,         "Malformed" },
  90         { PI_DEBUG,             "Debug" },
  91         { PI_PROTOCOL,          "Protocol" },
  92         { PI_SECURITY,          "Security" },
  93         { PI_COMMENTS_GROUP,    "Comment" },
  94         { 0, NULL }
  95 };
  96
  97 static const value_string expert_severity_vals[] = {
  98         { PI_ERROR,             "Error" },
  99         { PI_WARN,              "Warn" },
 100         { PI_NOTE,              "Note" },
 101         { PI_CHAT,              "Chat" },
 102         { PI_COMMENT,           "Comment" },
 103         { 0,                    "Ok" },
 104         { 0, NULL }
 105 };
 106
 107 #define PRE_ALLOC_EXPERT_FIELDS_MEM 5000
 108
 109 /* "proto_expert" is exported from libwireshark.dll.
 110  * Thus we need a special declaration.
 111  */
 112 WS_DLL_PUBLIC int proto_expert;
 113
 114 extern void
 115 expert_init(void);
 116
 117 extern void
 118 expert_packet_init(void);
 119
 120 extern void
 121 expert_cleanup(void);
 122
 123 extern void
 124 expert_packet_cleanup(void);
 125
 126 WS_DLL_PUBLIC int
 127 expert_get_highest_severity(void);
 128
 129 WS_DLL_PUBLIC void
 130 expert_update_comment_count(guint64 count);
 131
 132 /** Add an expert info.
 133  Add an expert info tree to a protocol item using registered expert info item
 134  @param pinfo Packet info of the currently processed packet. May be NULL if
 135         pi is supplied
 136  @param pi Current protocol item (or NULL)
 137  @param eiindex The registered expert info item
 138  */
 139 WS_DLL_PUBLIC void
 140 expert_add_info(packet_info *pinfo, proto_item *pi, expert_field* eiindex);
 141
 142 /** Add an expert info. FOR INTERNAL (NON-DISSECTOR) USE ONLY!!!
 143  Add an expert info tree to a protocol item, with classification and message.
 144  @param pinfo Packet info of the currently processed packet. May be NULL if
 145         pi is supplied
 146  @param pi Current protocol item (or NULL)
 147  @param group The expert group (like PI_CHECKSUM - see: proto.h)
 148  @param severity The expert severity (like PI_WARN - see: proto.h)
 149  @param format Printf-style format string for additional arguments
 150  */
 151 WS_DLL_PUBLIC void
 152 expert_add_info_format_internal(packet_info *pinfo, proto_item *pi, int group,
 153         int severity, const char *format, ...)
 154         G_GNUC_PRINTF(5, 6);
 155
 156 /** Add an expert info.
 157  Add an expert info tree to a protocol item, using registered expert info item,
 158  but with a formatted message.
 159  @param pinfo Packet info of the currently processed packet. May be NULL if
 160         pi is supplied
 161  @param pi Current protocol item (or NULL)
 162  @param eiindex The registered expert info item
 163  @param format Printf-style format string for additional arguments
 164  */
 165 WS_DLL_PUBLIC void
 166 expert_add_info_format(packet_info *pinfo, proto_item *pi, expert_field *eiindex,
 167         const char *format, ...) G_GNUC_PRINTF(4, 5);
 168
 169 /** Add an expert info associated with some byte data
 170  Add an expert info tree to a protocol item using registered expert info item.
 171  This function is intended to replace places where
 172  proto_tree_add_text or proto_tree_add_none_format + expert_add_info
 173  would be used.
 174  @param tree Current protocol item (or NULL)
 175  @param pinfo Packet info of the currently processed packet. May be NULL if
 176         pi is supplied
 177  @param eiindex The registered expert info item
 178  @param tvb the tv buffer of the current data
 179  @param start start of data in tvb
 180  @param length length of data in tvb
 181  @return the newly created item above expert info tree
 182  */
 183 WS_DLL_PUBLIC proto_item *
 184 proto_tree_add_expert(proto_tree *tree, packet_info *pinfo, expert_field* eiindex,
 185         tvbuff_t *tvb, gint start, gint length);
 186
 187 /** Add an expert info associated with some byte data
 188  Add an expert info tree to a protocol item, using registered expert info item,
 189  but with a formatted message.
 190  This function is intended to replace places where
 191  proto_tree_add_text or proto_tree_add_none_format + expert_add_info_format
 192  would be used.
 193  @param tree Current protocol item (or NULL)
 194  @param pinfo Packet info of the currently processed packet. May be NULL if tree is supplied
 195  @param eiindex The registered expert info item
 196  @param tvb the tv buffer of the current data
 197  @param start start of data in tvb
 198  @param length length of data in tvb
 199  @return the newly created item above expert info tree
 200  */
 201 WS_DLL_PUBLIC proto_item *
 202 proto_tree_add_expert_format(proto_tree *tree, packet_info *pinfo, expert_field* eiindex,
 203         tvbuff_t *tvb, gint start, gint length, const char *format, ...) G_GNUC_PRINTF(7, 8);
 204
 205 /*
 206  * Register that a protocol has expert info.
 207  */
 208 WS_DLL_PUBLIC expert_module_t *expert_register_protocol(int id);
 209
 210 /** Register a expert field array.
 211  @param module the protocol handle from expert_register_protocol()
 212  @param ei the ei_register_info array
 213  @param num_records the number of records in exp */
 214 WS_DLL_PUBLIC void
 215 expert_register_field_array(expert_module_t* module, ei_register_info *ei, const int num_records);
 216
 217 #define EXPERT_CHECKSUM_DISABLED    -2
 218 #define EXPERT_CHECKSUM_UNKNOWN     -1
 219 #define EXPERT_CHECKSUM_GOOD        0
 220 #define EXPERT_CHECKSUM_BAD         1
 221
 222 WS_DLL_PUBLIC const value_string expert_checksum_vals[];
 223
 224 #ifdef __cplusplus
 225 }
 226 #endif /* __cplusplus */
 227
 228 #endif /* __EXPERT_H__ */