3 * Wireshark Protocol Analyzer Library
5 * Copyright (c) 2001 by Gerald Combs <gerald@wireshark.org>
7 * SPDX-License-Identifier: GPL-2.0-or-later
15 #endif /* __cplusplus */
18 #include <epan/tvbuff.h>
19 #include <epan/prefs.h>
20 #include <epan/frame_data.h>
21 #include <wsutil/plugins.h>
22 #include <epan/register.h>
23 #include "ws_symbol_export.h"
25 typedef struct epan_dissect epan_dissect_t;
28 struct epan_column_info;
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
36 struct packet_provider_data;
39 * Structure containing pointers to functions supplied by the user
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);
50 extern plugins_t *libwireshark_plugins;
54 @section Epan The Enhanced Packet ANalyzer
63 Enhanced Packet ANalyzer, aka the packet analyzing engine. Source code can be found in the epan directory.
65 Protocol-Tree - Keep data of the capture file protocol information.
67 Dissectors - The various protocol dissectors in epan/dissectors.
69 Plugins - Some of the protocol dissectors are implemented as plugins. Source code can be found at plugins.
71 Display-Filters - the display filter engine at epan/dfilter
75 Ref2 for further edits - delete when done
78 This document describes the data structures and the functions exported by the CACE Technologies AirPcap library.
79 The AirPcap library provides low-level access to the AirPcap driver including advanced capabilities such as channel setting,
80 link type control and WEP configuration.<br>
81 This manual includes the following sections:
83 \note throughout this documentation, \e device refers to a physical USB AirPcap device, while \e adapter is an open API
84 instance. Most of the AirPcap API operations are adapter-specific but some of them, like setting the channel, are
85 per-device and will be reflected on all the open adapters. These functions will have "Device" in their name, e.g.
86 AirpcapSetDeviceChannel().
96 * Init the whole epan module.
98 * Must be called only once in a program.
100 * Returns TRUE on success, FALSE on failure.
103 gboolean epan_init(register_cb cb, void *client_data, gboolean load_plugins);
106 * Load all settings, from the current profile, that affect epan.
109 e_prefs *epan_load_settings(void);
111 /** cleanup the whole epan module, this is used to be called only once in a program */
113 void epan_cleanup(void);
118 void (*dissect_init)(epan_dissect_t *);
119 void (*dissect_cleanup)(epan_dissect_t *);
120 void (*cleanup)(void);
121 void (*register_all_protocols)(register_cb, gpointer);
122 void (*register_all_handoffs)(register_cb, gpointer);
125 WS_DLL_PUBLIC void epan_register_plugin(const epan_plugin *plugin);
128 * Initialize the table of conversations. Conversations are identified by
129 * their endpoints; they are used for protocols such as IP, TCP, and UDP,
130 * where packets contain endpoint information but don't contain a single
131 * value indicating to which flow the packet belongs.
133 void epan_conversation_init(void);
135 /** A client will create one epan_t for an entire dissection session.
136 * A single epan_t will be used to analyze the entire sequence of packets,
137 * sequentially, in a single session. A session corresponds to a single
138 * packet trace file. The reasons epan_t exists is that some packets in
139 * some protocols cannot be decoded without knowledge of previous packets.
140 * This inter-packet "state" is stored in the epan_t.
142 typedef struct epan_session epan_t;
144 WS_DLL_PUBLIC epan_t *epan_new(struct packet_provider_data *prov,
145 const struct packet_provider_funcs *funcs);
147 WS_DLL_PUBLIC const char *epan_get_user_comment(const epan_t *session, const frame_data *fd);
149 WS_DLL_PUBLIC const char *epan_get_interface_name(const epan_t *session, guint32 interface_id);
151 WS_DLL_PUBLIC const char *epan_get_interface_description(const epan_t *session, guint32 interface_id);
153 const nstime_t *epan_get_frame_ts(const epan_t *session, guint32 frame_num);
155 WS_DLL_PUBLIC void epan_free(epan_t *session);
157 WS_DLL_PUBLIC const gchar*
158 epan_get_version(void);
160 WS_DLL_PUBLIC void epan_get_version_number(int *major, int *minor, int *micro);
163 * Set/unset the tree to always be visible when epan_dissect_init() is called.
164 * This state change sticks until cleared, rather than being done per function call.
165 * This is currently used when Lua scripts request all fields be generated.
166 * By default it only becomes visible if epan_dissect_init() makes it so, usually
167 * only when a packet is selected.
168 * Setting this overrides that so it's always visible, although it will still not be
169 * created if create_proto_tree is false in the call to epan_dissect_init().
170 * Clearing this reverts the decision to epan_dissect_init() and proto_tree_visible.
172 void epan_set_always_visible(gboolean force);
174 /** initialize an existing single packet dissection */
177 epan_dissect_init(epan_dissect_t *edt, epan_t *session, const gboolean create_proto_tree, const gboolean proto_tree_visible);
179 /** get a new single packet dissection
180 * should be freed using epan_dissect_free() after packet dissection completed
184 epan_dissect_new(epan_t *session, const gboolean create_proto_tree, const gboolean proto_tree_visible);
188 epan_dissect_reset(epan_dissect_t *edt);
190 /** Indicate whether we should fake protocols or not */
193 epan_dissect_fake_protocols(epan_dissect_t *edt, const gboolean fake_protocols);
195 /** run a single packet dissection */
198 epan_dissect_run(epan_dissect_t *edt, int file_type_subtype,
199 wtap_rec *rec, tvbuff_t *tvb, frame_data *fd,
200 struct epan_column_info *cinfo);
204 epan_dissect_run_with_taps(epan_dissect_t *edt, int file_type_subtype,
205 wtap_rec *rec, tvbuff_t *tvb, frame_data *fd,
206 struct epan_column_info *cinfo);
208 /** run a single file packet dissection */
211 epan_dissect_file_run(epan_dissect_t *edt, wtap_rec *rec,
212 tvbuff_t *tvb, frame_data *fd, struct epan_column_info *cinfo);
216 epan_dissect_file_run_with_taps(epan_dissect_t *edt, wtap_rec *rec,
217 tvbuff_t *tvb, frame_data *fd, struct epan_column_info *cinfo);
219 /** Prime an epan_dissect_t's proto_tree using the fields/protocols used in a dfilter. */
222 epan_dissect_prime_with_dfilter(epan_dissect_t *edt, const struct epan_dfilter *dfcode);
224 /** Prime an epan_dissect_t's proto_tree with a field/protocol specified by its hfid */
227 epan_dissect_prime_with_hfid(epan_dissect_t *edt, int hfid);
229 /** Prime an epan_dissect_t's proto_tree with a set of fields/protocols specified by their hfids in a GArray */
232 epan_dissect_prime_with_hfid_array(epan_dissect_t *edt, GArray *hfids);
234 /** fill the dissect run output into the packet list columns */
237 epan_dissect_fill_in_columns(epan_dissect_t *edt, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
239 /** Check whether a dissected packet contains a given named field */
242 epan_dissect_packet_contains_field(epan_dissect_t* edt,
243 const char *field_name);
245 /** releases resources attached to the packet dissection. DOES NOT free the actual pointer */
248 epan_dissect_cleanup(epan_dissect_t* edt);
250 /** free a single packet dissection */
253 epan_dissect_free(epan_dissect_t* edt);
255 /** Sets custom column */
257 epan_custom_set(epan_dissect_t *edt, GSList *ids, gint occurrence,
258 gchar *result, gchar *expr, const int size);
261 * Get compile-time information for libraries used by libwireshark.
265 epan_get_compiled_version_info(GString *str);
268 * Get runtime information for libraries used by libwireshark.
272 epan_get_runtime_version_info(GString *str);
276 #endif /* __cplusplus */
278 #endif /* __EPAN_H__ */