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