epan/epan.h

   1 /** @file
   2  *
   3  * Wireshark Protocol Analyzer Library
   4  *
   5  * Copyright (c) 2001 by Gerald Combs <gerald@wireshark.org>
   6  *
   7  * SPDX-License-Identifier: GPL-2.0-or-later
   8  */
   9
  10 #ifndef __EPAN_H__
  11 #define __EPAN_H__
  12
  13 #include <wsutil/feature_list.h>
  14 #include <epan/tvbuff.h>
  15 #include <epan/prefs.h>
  16 #include <epan/frame_data.h>
  17 #include <epan/register.h>
  18 #include <wiretap/wtap_opttypes.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif /* __cplusplus */
  23
  24 /** Global variable holding the content of the corresponding environment variable
  25  * to save fetching it repeatedly.
  26  */
  27 extern bool wireshark_abort_on_dissector_bug;
  28 extern bool wireshark_abort_on_too_many_items;
  29
  30 typedef struct epan_dissect epan_dissect_t;
  31
  32 struct epan_dfilter;
  33 struct epan_column_info;
  34
  35 /**
  36  * Opaque structure provided when an epan_t is created; it contains
  37  * information needed to allow the user of libwireshark to provide
  38  * time stamps, comments, and other information outside the packet
  39  * data itself.
  40  */
  41 struct packet_provider_data;
  42
  43 /**
  44  * Structure containing pointers to functions supplied by the user
  45  * of libwireshark.
  46  */
  47 struct packet_provider_funcs {
  48         const nstime_t *(*get_frame_ts)(struct packet_provider_data *prov, uint32_t frame_num);
  49         const char *(*get_interface_name)(struct packet_provider_data *prov, uint32_t interface_id, unsigned section_number);
  50         const char *(*get_interface_description)(struct packet_provider_data *prov, uint32_t interface_id, unsigned section_number);
  51         wtap_block_t (*get_modified_block)(struct packet_provider_data *prov, const frame_data *fd);
  52 };
  53
  54 /**
  55         @section Epan The Enhanced Packet ANalyzer
  56
  57         XXX
  58
  59         @b Sections:
  60 */
  61 /*
  62 Ref 1
  63 Epan
  64 Enhanced Packet ANalyzer, aka the packet analyzing engine. Source code can be found in the epan directory.
  65
  66 Protocol-Tree - Keep data of the capture file protocol information.
  67
  68 Dissectors - The various protocol dissectors in epan/dissectors.
  69
  70 Plugins - Some of the protocol dissectors are implemented as plugins. Source code can be found at plugins.
  71
  72 Display-Filters - the display filter engine at epan/dfilter
  73
  74 */
  75
  76 /**
  77  * Init the whole epan module.
  78  *
  79  * Must be called only once in a program.
  80  *
  81  * Returns true on success, false on failure.
  82  */
  83 WS_DLL_PUBLIC
  84 bool epan_init(register_cb cb, void *client_data, bool load_plugins);
  85
  86 /**
  87  * Load all settings, from the current profile, that affect epan.
  88  */
  89 WS_DLL_PUBLIC
  90 e_prefs *epan_load_settings(void);
  91
  92 /** cleanup the whole epan module, this is used to be called only once in a program */
  93 WS_DLL_PUBLIC
  94 void epan_cleanup(void);
  95
  96 typedef struct {
  97         void (*init)(void);             /* Called before proto_init() */
  98         void (*post_init)(void);        /* Called at the end of epan_init() */
  99         void (*dissect_init)(epan_dissect_t *);
 100         void (*dissect_cleanup)(epan_dissect_t *);
 101         void (*cleanup)(void);
 102         void (*register_all_protocols)(register_cb, void *);
 103         void (*register_all_handoffs)(register_cb, void *);
 104         void (*register_all_tap_listeners)(void);
 105 } epan_plugin;
 106
 107 WS_DLL_PUBLIC void epan_register_plugin(const epan_plugin *plugin);
 108
 109 /** Returns_
 110  *     0 if plugins can be loaded for all of libwireshark (tap, dissector, epan).
 111  *     1 if plugins are not supported by the platform.
 112  *    -1 if plugins were disabled in the build configuration.
 113  */
 114 WS_DLL_PUBLIC int epan_plugins_supported(void);
 115
 116 /**
 117  * Initialize the table of conversations.  Conversations are identified by
 118  * their endpoints; they are used for protocols such as IP, TCP, and UDP,
 119  * where packets contain endpoint information but don't contain a single
 120  * value indicating to which flow the packet belongs.
 121  */
 122 void epan_conversation_init(void);
 123
 124 /** A client will create one epan_t for an entire dissection session.
 125  * A single epan_t will be used to analyze the entire sequence of packets,
 126  * sequentially, in a single session. A session corresponds to a single
 127  * packet trace file. The reasons epan_t exists is that some packets in
 128  * some protocols cannot be decoded without knowledge of previous packets.
 129  * This inter-packet "state" is stored in the epan_t.
 130  */
 131 typedef struct epan_session epan_t;
 132
 133 WS_DLL_PUBLIC epan_t *epan_new(struct packet_provider_data *prov,
 134     const struct packet_provider_funcs *funcs);
 135
 136 WS_DLL_PUBLIC wtap_block_t epan_get_modified_block(const epan_t *session, const frame_data *fd);
 137
 138 WS_DLL_PUBLIC const char *epan_get_interface_name(const epan_t *session, uint32_t interface_id, unsigned section_number);
 139
 140 WS_DLL_PUBLIC const char *epan_get_interface_description(const epan_t *session, uint32_t interface_id, unsigned section_number);
 141
 142 const nstime_t *epan_get_frame_ts(const epan_t *session, uint32_t frame_num);
 143
 144 WS_DLL_PUBLIC void epan_free(epan_t *session);
 145
 146 WS_DLL_PUBLIC const char*
 147 epan_get_version(void);
 148
 149 WS_DLL_PUBLIC void epan_get_version_number(int *major, int *minor, int *micro);
 150
 151 /**
 152  * Set/unset the tree to always be visible when epan_dissect_init() is called.
 153  * This state change sticks until cleared, rather than being done per function call.
 154  * This is currently used when Lua scripts request all fields be generated.
 155  * By default it only becomes visible if epan_dissect_init() makes it so, usually
 156  * only when a packet is selected.
 157  * Setting this overrides that so it's always visible, although it will still not be
 158  * created if create_proto_tree is false in the call to epan_dissect_init().
 159  * Clearing this reverts the decision to epan_dissect_init() and proto_tree_visible.
 160  */
 161 WS_DLL_PUBLIC
 162 void epan_set_always_visible(bool force);
 163
 164 /** initialize an existing single packet dissection */
 165 WS_DLL_PUBLIC
 166 void
 167 epan_dissect_init(epan_dissect_t *edt, epan_t *session, const bool create_proto_tree, const bool proto_tree_visible);
 168
 169 /** get a new single packet dissection
 170  * should be freed using epan_dissect_free() after packet dissection completed
 171  */
 172 WS_DLL_PUBLIC
 173 epan_dissect_t*
 174 epan_dissect_new(epan_t *session, const bool create_proto_tree, const bool proto_tree_visible);
 175
 176 WS_DLL_PUBLIC
 177 void
 178 epan_dissect_reset(epan_dissect_t *edt);
 179
 180 /** Indicate whether we should fake protocols or not */
 181 WS_DLL_PUBLIC
 182 void
 183 epan_dissect_fake_protocols(epan_dissect_t *edt, const bool fake_protocols);
 184
 185 /** run a single packet dissection */
 186 WS_DLL_PUBLIC
 187 void
 188 epan_dissect_run(epan_dissect_t *edt, int file_type_subtype,
 189         wtap_rec *rec, tvbuff_t *tvb, frame_data *fd,
 190         struct epan_column_info *cinfo);
 191
 192 WS_DLL_PUBLIC
 193 void
 194 epan_dissect_run_with_taps(epan_dissect_t *edt, int file_type_subtype,
 195         wtap_rec *rec, tvbuff_t *tvb, frame_data *fd,
 196         struct epan_column_info *cinfo);
 197
 198 /** run a single file packet dissection */
 199 WS_DLL_PUBLIC
 200 void
 201 epan_dissect_file_run(epan_dissect_t *edt, wtap_rec *rec,
 202         tvbuff_t *tvb, frame_data *fd, struct epan_column_info *cinfo);
 203
 204 WS_DLL_PUBLIC
 205 void
 206 epan_dissect_file_run_with_taps(epan_dissect_t *edt, wtap_rec *rec,
 207         tvbuff_t *tvb, frame_data *fd, struct epan_column_info *cinfo);
 208
 209 /** Prime an epan_dissect_t's proto_tree using the fields/protocols used in a dfilter. */
 210 WS_DLL_PUBLIC
 211 void
 212 epan_dissect_prime_with_dfilter(epan_dissect_t *edt, const struct epan_dfilter *dfcode);
 213
 214 /** Prime an epan_dissect_t's proto_tree using the fields/protocols used in a dfilter, marked for print. */
 215 WS_DLL_PUBLIC
 216 void
 217 epan_dissect_prime_with_dfilter_print(epan_dissect_t *edt, const struct epan_dfilter *dfcode);
 218
 219 /** Prime an epan_dissect_t's proto_tree with a field/protocol specified by its hfid */
 220 WS_DLL_PUBLIC
 221 void
 222 epan_dissect_prime_with_hfid(epan_dissect_t *edt, int hfid);
 223
 224 /** Prime an epan_dissect_t's proto_tree with a set of fields/protocols specified by their hfids in a GArray */
 225 WS_DLL_PUBLIC
 226 void
 227 epan_dissect_prime_with_hfid_array(epan_dissect_t *edt, GArray *hfids);
 228
 229 /** fill the dissect run output into the packet list columns */
 230 WS_DLL_PUBLIC
 231 void
 232 epan_dissect_fill_in_columns(epan_dissect_t *edt, const bool fill_col_exprs, const bool fill_fd_colums);
 233
 234 /** Check whether a dissected packet contains a given named field */
 235 WS_DLL_PUBLIC
 236 bool
 237 epan_dissect_packet_contains_field(epan_dissect_t* edt,
 238                                    const char *field_name);
 239
 240 /** releases resources attached to the packet dissection. DOES NOT free the actual pointer */
 241 WS_DLL_PUBLIC
 242 void
 243 epan_dissect_cleanup(epan_dissect_t* edt);
 244
 245 /** free a single packet dissection */
 246 WS_DLL_PUBLIC
 247 void
 248 epan_dissect_free(epan_dissect_t* edt);
 249
 250 /** Sets custom column */
 251 const char *
 252 epan_custom_set(epan_dissect_t *edt, GSList *ids, int occurrence, bool display_details,
 253                                 char *result, char *expr, const int size);
 254
 255 /**
 256  * Get compile-time information for libraries used by libwireshark.
 257  */
 258 WS_DLL_PUBLIC
 259 void
 260 epan_gather_compile_info(feature_list l);
 261
 262 /**
 263  * Get runtime information for libraries used by libwireshark.
 264  */
 265 WS_DLL_PUBLIC
 266 void
 267 epan_gather_runtime_info(feature_list l);
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif /* __cplusplus */
 272
 273 #endif /* __EPAN_H__ */