epan/epan.h

   1 /* epan.h
   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 #ifdef __cplusplus
  14 extern "C" {
  15 #endif /* __cplusplus */
  16
  17 #include <glib.h>
  18 #include <epan/tvbuff.h>
  19 #include <epan/prefs.h>
  20 #include <epan/frame_data.h>
  21 #include <wsutil/plugins.h>
  22 #include "register.h"
  23 #include "ws_symbol_export.h"
  24
  25 typedef struct epan_dissect epan_dissect_t;
  26
  27 struct epan_dfilter;
  28 struct epan_column_info;
  29
  30 /*
  31  * Opaque structure provided when an epan_t is created; it contains
  32  * information needed to allow the user of libwireshark to provide
  33  * time stamps, comments, and other information outside the packet
  34  * data itself.
  35  */
  36 struct packet_provider_data;
  37
  38 /*
  39  * Structure containing pointers to functions supplied by the user
  40  * of libwireshark.
  41  */
  42 struct packet_provider_funcs {
  43         const nstime_t *(*get_frame_ts)(struct packet_provider_data *prov, guint32 frame_num);
  44         const char *(*get_interface_name)(struct packet_provider_data *prov, guint32 interface_id);
  45         const char *(*get_interface_description)(struct packet_provider_data *prov, guint32 interface_id);
  46         const char *(*get_user_comment)(struct packet_provider_data *prov, const frame_data *fd);
  47 };
  48
  49 #ifdef HAVE_PLUGINS
  50 extern plugins_t *libwireshark_plugins;
  51 #endif
  52
  53 /**
  54         @mainpage Wireshark EPAN the packet analyzing engine. Source code can be found in the epan directory
  55
  56         @section Introduction
  57
  58         XXX
  59
  60         @b Sections:
  61 */
  62 /*
  63 Ref 1
  64 Epan
  65 Ethereal Packet ANalyzer (XXX - is this correct?) the packet analyzing engine. Source code can be found in the epan directory.
  66
  67 Protocol-Tree - Keep data of the capture file protocol information.
  68
  69 Dissectors - The various protocol dissectors in epan/dissectors.
  70
  71 Plugins - Some of the protocol dissectors are implemented as plugins. Source code can be found at plugins.
  72
  73 Display-Filters - the display filter engine at epan/dfilter
  74
  75
  76
  77 Ref2 for further edits - delete when done
  78         \section Introduction
  79
  80         This document describes the data structures and the functions exported by the CACE Technologies AirPcap library.
  81         The AirPcap library provides low-level access to the AirPcap driver including advanced capabilities such as channel setting,
  82         link type control and WEP configuration.<br>
  83         This manual includes the following sections:
  84
  85         \note throughout this documentation, \e device refers to a physical USB AirPcap device, while \e adapter is an open API
  86         instance. Most of the AirPcap API operations are adapter-specific but some of them, like setting the channel, are
  87         per-device and will be reflected on all the open adapters. These functions will have "Device" in their name, e.g.
  88         AirpcapSetDeviceChannel().
  89
  90         \b Sections:
  91
  92         - \ref airpcapfuncs
  93         - \ref airpcapdefs
  94         - \ref radiotap
  95 */
  96
  97 /**
  98  * Init the whole epan module.
  99  *
 100  * Must be called only once in a program.
 101  *
 102  * Returns TRUE on success, FALSE on failure.
 103  */
 104 WS_DLL_PUBLIC
 105 gboolean epan_init(void (*register_all_protocols_func)(register_cb cb, gpointer client_data),
 106                    void (*register_all_handoffs_func)(register_cb cb, gpointer client_data),
 107                    register_cb cb, void *client_data);
 108
 109 /**
 110  * Load all settings, from the current profile, that affect epan.
 111  */
 112 WS_DLL_PUBLIC
 113 e_prefs *epan_load_settings(void);
 114
 115 /** cleanup the whole epan module, this is used to be called only once in a program */
 116 WS_DLL_PUBLIC
 117 void epan_cleanup(void);
 118
 119 #ifdef HAVE_PLUGINS
 120 typedef struct {
 121         void (*init)(void);
 122         void (*dissect_init)(epan_dissect_t *);
 123         void (*dissect_cleanup)(epan_dissect_t *);
 124         void (*cleanup)(void);
 125         void (*register_all_protocols)(register_cb, gpointer);
 126         void (*register_all_handoffs)(register_cb, gpointer);
 127 } epan_plugin;
 128
 129 WS_DLL_PUBLIC void epan_register_plugin(const epan_plugin *plugin);
 130 #endif
 131 /**
 132  * Initialize the table of conversations.  Conversations are identified by
 133  * their endpoints; they are used for protocols such as IP, TCP, and UDP,
 134  * where packets contain endpoint information but don't contain a single
 135  * value indicating to which flow the packet belongs.
 136  */
 137 void epan_conversation_init(void);
 138
 139 /** A client will create one epan_t for an entire dissection session.
 140  * A single epan_t will be used to analyze the entire sequence of packets,
 141  * sequentially, in a single session. A session corresponds to a single
 142  * packet trace file. The reasons epan_t exists is that some packets in
 143  * some protocols cannot be decoded without knowledge of previous packets.
 144  * This inter-packet "state" is stored in the epan_t.
 145  */
 146 typedef struct epan_session epan_t;
 147
 148 WS_DLL_PUBLIC epan_t *epan_new(struct packet_provider_data *prov,
 149     const struct packet_provider_funcs *funcs);
 150
 151 WS_DLL_PUBLIC const char *epan_get_user_comment(const epan_t *session, const frame_data *fd);
 152
 153 WS_DLL_PUBLIC const char *epan_get_interface_name(const epan_t *session, guint32 interface_id);
 154
 155 WS_DLL_PUBLIC const char *epan_get_interface_description(const epan_t *session, guint32 interface_id);
 156
 157 const nstime_t *epan_get_frame_ts(const epan_t *session, guint32 frame_num);
 158
 159 WS_DLL_PUBLIC void epan_free(epan_t *session);
 160
 161 WS_DLL_PUBLIC const gchar*
 162 epan_get_version(void);
 163
 164 WS_DLL_PUBLIC void epan_get_version_number(int *major, int *minor, int *micro);
 165
 166 /**
 167  * Set/unset the tree to always be visible when epan_dissect_init() is called.
 168  * This state change sticks until cleared, rather than being done per function call.
 169  * This is currently used when Lua scripts request all fields be generated.
 170  * By default it only becomes visible if epan_dissect_init() makes it so, usually
 171  * only when a packet is selected.
 172  * Setting this overrides that so it's always visible, although it will still not be
 173  * created if create_proto_tree is false in the call to epan_dissect_init().
 174  * Clearing this reverts the decision to epan_dissect_init() and proto_tree_visible.
 175  */
 176 void epan_set_always_visible(gboolean force);
 177
 178 /** initialize an existing single packet dissection */
 179 WS_DLL_PUBLIC
 180 void
 181 epan_dissect_init(epan_dissect_t *edt, epan_t *session, const gboolean create_proto_tree, const gboolean proto_tree_visible);
 182
 183 /** get a new single packet dissection
 184  * should be freed using epan_dissect_free() after packet dissection completed
 185  */
 186 WS_DLL_PUBLIC
 187 epan_dissect_t*
 188 epan_dissect_new(epan_t *session, const gboolean create_proto_tree, const gboolean proto_tree_visible);
 189
 190 WS_DLL_PUBLIC
 191 void
 192 epan_dissect_reset(epan_dissect_t *edt);
 193
 194 /** Indicate whether we should fake protocols or not */
 195 WS_DLL_PUBLIC
 196 void
 197 epan_dissect_fake_protocols(epan_dissect_t *edt, const gboolean fake_protocols);
 198
 199 /** run a single packet dissection */
 200 WS_DLL_PUBLIC
 201 void
 202 epan_dissect_run(epan_dissect_t *edt, int file_type_subtype,
 203         wtap_rec *rec, tvbuff_t *tvb, frame_data *fd,
 204         struct epan_column_info *cinfo);
 205
 206 WS_DLL_PUBLIC
 207 void
 208 epan_dissect_run_with_taps(epan_dissect_t *edt, int file_type_subtype,
 209         wtap_rec *rec, tvbuff_t *tvb, frame_data *fd,
 210         struct epan_column_info *cinfo);
 211
 212 /** run a single file packet dissection */
 213 WS_DLL_PUBLIC
 214 void
 215 epan_dissect_file_run(epan_dissect_t *edt, wtap_rec *rec,
 216         tvbuff_t *tvb, frame_data *fd, struct epan_column_info *cinfo);
 217
 218 WS_DLL_PUBLIC
 219 void
 220 epan_dissect_file_run_with_taps(epan_dissect_t *edt, wtap_rec *rec,
 221         tvbuff_t *tvb, frame_data *fd, struct epan_column_info *cinfo);
 222
 223 /** Prime an epan_dissect_t's proto_tree using the fields/protocols used in a dfilter. */
 224 WS_DLL_PUBLIC
 225 void
 226 epan_dissect_prime_with_dfilter(epan_dissect_t *edt, const struct epan_dfilter *dfcode);
 227
 228 /** Prime an epan_dissect_t's proto_tree with a field/protocol specified by its hfid */
 229 WS_DLL_PUBLIC
 230 void
 231 epan_dissect_prime_with_hfid(epan_dissect_t *edt, int hfid);
 232
 233 /** Prime an epan_dissect_t's proto_tree with a set of fields/protocols specified by their hfids in a GArray */
 234 WS_DLL_PUBLIC
 235 void
 236 epan_dissect_prime_with_hfid_array(epan_dissect_t *edt, GArray *hfids);
 237
 238 /** fill the dissect run output into the packet list columns */
 239 WS_DLL_PUBLIC
 240 void
 241 epan_dissect_fill_in_columns(epan_dissect_t *edt, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
 242
 243 /** Check whether a dissected packet contains a given named field */
 244 WS_DLL_PUBLIC
 245 gboolean
 246 epan_dissect_packet_contains_field(epan_dissect_t* edt,
 247                                    const char *field_name);
 248
 249 /** releases resources attached to the packet dissection. DOES NOT free the actual pointer */
 250 WS_DLL_PUBLIC
 251 void
 252 epan_dissect_cleanup(epan_dissect_t* edt);
 253
 254 /** free a single packet dissection */
 255 WS_DLL_PUBLIC
 256 void
 257 epan_dissect_free(epan_dissect_t* edt);
 258
 259 /** Sets custom column */
 260 const gchar *
 261 epan_custom_set(epan_dissect_t *edt, GSList *ids, gint occurrence,
 262                                 gchar *result, gchar *expr, const int size);
 263
 264 /**
 265  * Get compile-time information for libraries used by libwireshark.
 266  */
 267 WS_DLL_PUBLIC
 268 void
 269 epan_get_compiled_version_info(GString *str);
 270
 271 /**
 272  * Get runtime information for libraries used by libwireshark.
 273  */
 274 WS_DLL_PUBLIC
 275 void
 276 epan_get_runtime_version_info(GString *str);
 277
 278 #ifdef __cplusplus
 279 }
 280 #endif /* __cplusplus */
 281
 282 #endif /* __EPAN_H__ */