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  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation; either version 2
  10  * of the License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20  */
  21
  22 #ifndef __EPAN_H__
  23 #define __EPAN_H__
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif /* __cplusplus */
  28
  29 #include <glib.h>
  30 #include <epan/tvbuff.h>
  31 #include <epan/frame_data.h>
  32 #include "register.h"
  33 #include "ws_symbol_export.h"
  34
  35 typedef struct epan_dissect epan_dissect_t;
  36
  37 struct epan_dfilter;
  38 struct epan_column_info;
  39
  40 /**
  41         @mainpage Wireshark EPAN the packet analyzing engine. Source code can be found in the epan directory
  42
  43         @section Introduction
  44
  45         XXX
  46
  47         @b Sections:
  48 */
  49 /*
  50 Ref 1
  51 Epan
  52 Ethereal Packet ANalyzer (XXX - is this correct?) the packet analyzing engine. Source code can be found in the epan directory.
  53
  54 Protocol-Tree - Keep data of the capture file protocol information.
  55
  56 Dissectors - The various protocol dissectors in epan/dissectors.
  57
  58 Plugins - Some of the protocol dissectors are implemented as plugins. Source code can be found at plugins.
  59
  60 Display-Filters - the display filter engine at epan/dfilter
  61
  62
  63
  64 Ref2 for further edits - delete when done
  65         \section Introduction
  66
  67         This document describes the data structures and the functions exported by the CACE Technologies AirPcap library.
  68         The AirPcap library provides low-level access to the AirPcap driver including advanced capabilities such as channel setting,
  69         link type control and WEP configuration.<br>
  70         This manual includes the following sections:
  71
  72         \note throughout this documentation, \e device refers to a physical USB AirPcap device, while \e adapter is an open API
  73         instance. Most of the AirPcap API operations are adapter-specific but some of them, like setting the channel, are
  74         per-device and will be reflected on all the open adapters. These functions will have "Device" in their name, e.g.
  75         AirpcapSetDeviceChannel().
  76
  77         \b Sections:
  78
  79         - \ref airpcapfuncs
  80         - \ref airpcapdefs
  81         - \ref radiotap
  82 */
  83 /*
  84  * Register all the plugin types that are part of libwireshark.
  85  *
  86  * Must be called before init_plugins(), which must be called before
  87  * any registration routines are called, i.e. before epan_init().
  88  *
  89  * Must be called only once in a program.
  90  */
  91 WS_DLL_PUBLIC void epan_register_plugin_types(void);
  92
  93 /**
  94  * Init the whole epan module.
  95  *
  96  * Must be called only once in a program.
  97  *
  98  * Returns TRUE on success, FALSE on failure.
  99  */
 100 WS_DLL_PUBLIC
 101 gboolean epan_init(void (*register_all_protocols_func)(register_cb cb, gpointer client_data),
 102                    void (*register_all_handoffs_func)(register_cb cb, gpointer client_data),
 103                    register_cb cb, void *client_data);
 104
 105 /** cleanup the whole epan module, this is used to be called only once in a program */
 106 WS_DLL_PUBLIC
 107 void epan_cleanup(void);
 108
 109 /**
 110  * Initialize the table of conversations.  Conversations are identified by
 111  * their endpoints; they are used for protocols such as IP, TCP, and UDP,
 112  * where packets contain endpoint information but don't contain a single
 113  * value indicating to which flow the packet belongs.
 114  */
 115 void epan_conversation_init(void);
 116 void epan_conversation_cleanup(void);
 117
 118 /**
 119  * Initialize the table of circuits.  Circuits are identified by a
 120  * circuit ID; they are used for protocols where packets *do* contain
 121  * a circuit ID value indicating to which flow the packet belongs.
 122  *
 123  * We might want to make a superclass for both endpoint-specified
 124  * conversations and circuit ID-specified circuits, so we can attach
 125  * information either to a circuit or a conversation with common
 126  * code.
 127  */
 128 void epan_circuit_init(void);
 129 void epan_circuit_cleanup(void);
 130
 131 /** A client will create one epan_t for an entire dissection session.
 132  * A single epan_t will be used to analyze the entire sequence of packets,
 133  * sequentially, in a single session. A session corresponds to a single
 134  * packet trace file. The reaons epan_t exists is that some packets in
 135  * some protocols cannot be decoded without knowledge of previous packets.
 136  * This inter-packet "state" is stored in the epan_t.
 137  */
 138 typedef struct epan_session epan_t;
 139
 140 WS_DLL_PUBLIC epan_t *epan_new(void);
 141
 142 WS_DLL_PUBLIC const char *epan_get_user_comment(const epan_t *session, const frame_data *fd);
 143
 144 WS_DLL_PUBLIC const char *epan_get_interface_name(const epan_t *session, guint32 interface_id);
 145
 146 const nstime_t *epan_get_frame_ts(const epan_t *session, guint32 frame_num);
 147
 148 WS_DLL_PUBLIC void epan_free(epan_t *session);
 149
 150 WS_DLL_PUBLIC const gchar*
 151 epan_get_version(void);
 152
 153 /**
 154  * Set/unset the tree to always be visible when epan_dissect_init() is called.
 155  * This state change sticks until cleared, rather than being done per function call.
 156  * This is currently used when Lua scripts request all fields be generated.
 157  * By default it only becomes visible if epan_dissect_init() makes it so, usually
 158  * only when a packet is selected.
 159  * Setting this overrides that so it's always visible, although it will still not be
 160  * created if create_proto_tree is false in the call to epan_dissect_init().
 161  * Clearing this reverts the decision to epan_dissect_init() and proto_tree_visible.
 162  */
 163 void epan_set_always_visible(gboolean force);
 164
 165 /** initialize an existing single packet dissection */
 166 WS_DLL_PUBLIC
 167 epan_dissect_t*
 168 epan_dissect_init(epan_dissect_t *edt, epan_t *session, const gboolean create_proto_tree, const gboolean proto_tree_visible);
 169
 170 /** get a new single packet dissection
 171  * should be freed using epan_dissect_free() after packet dissection completed
 172  */
 173 WS_DLL_PUBLIC
 174 epan_dissect_t*
 175 epan_dissect_new(epan_t *session, const gboolean create_proto_tree, const gboolean proto_tree_visible);
 176
 177 WS_DLL_PUBLIC
 178 void
 179 epan_dissect_reset(epan_dissect_t *edt);
 180
 181 /** Indicate whether we should fake protocols or not */
 182 WS_DLL_PUBLIC
 183 void
 184 epan_dissect_fake_protocols(epan_dissect_t *edt, const gboolean fake_protocols);
 185
 186 /** run a single packet dissection */
 187 WS_DLL_PUBLIC
 188 void
 189 epan_dissect_run(epan_dissect_t *edt, int file_type_subtype,
 190         struct wtap_pkthdr *phdr, tvbuff_t *tvb, frame_data *fd,
 191         struct epan_column_info *cinfo);
 192
 193 WS_DLL_PUBLIC
 194 void
 195 epan_dissect_run_with_taps(epan_dissect_t *edt, int file_type_subtype,
 196         struct wtap_pkthdr *phdr, tvbuff_t *tvb, frame_data *fd,
 197         struct epan_column_info *cinfo);
 198
 199 /** run a single file packet dissection */
 200 WS_DLL_PUBLIC
 201 void
 202 epan_dissect_file_run(epan_dissect_t *edt, struct wtap_pkthdr *phdr,
 203         tvbuff_t *tvb, frame_data *fd, struct epan_column_info *cinfo);
 204
 205 WS_DLL_PUBLIC
 206 void
 207 epan_dissect_file_run_with_taps(epan_dissect_t *edt, struct wtap_pkthdr *phdr,
 208         tvbuff_t *tvb, frame_data *fd, struct epan_column_info *cinfo);
 209
 210 /** Prime an epan_dissect_t's proto_tree using the fields/protocols used in a dfilter. */
 211 WS_DLL_PUBLIC
 212 void
 213 epan_dissect_prime_dfilter(epan_dissect_t *edt, const struct epan_dfilter *dfcode);
 214
 215 /** Prime an epan_dissect_t's proto_tree with a field/protocol specified by its hfid */
 216 WS_DLL_PUBLIC
 217 void
 218 epan_dissect_prime_hfid(epan_dissect_t *edt, int hfid);
 219
 220 /** fill the dissect run output into the packet list columns */
 221 WS_DLL_PUBLIC
 222 void
 223 epan_dissect_fill_in_columns(epan_dissect_t *edt, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
 224
 225 /** Check whether a dissected packet contains a given named field */
 226 WS_DLL_PUBLIC
 227 gboolean
 228 epan_dissect_packet_contains_field(epan_dissect_t* edt,
 229                                    const char *field_name);
 230
 231 /** releases resources attached to the packet dissection. DOES NOT free the actual pointer */
 232 WS_DLL_PUBLIC
 233 void
 234 epan_dissect_cleanup(epan_dissect_t* edt);
 235
 236 /** free a single packet dissection */
 237 WS_DLL_PUBLIC
 238 void
 239 epan_dissect_free(epan_dissect_t* edt);
 240
 241 /** Sets custom column */
 242 const gchar *
 243 epan_custom_set(epan_dissect_t *edt, GSList *ids, gint occurrence,
 244                                 gchar *result, gchar *expr, const int size);
 245
 246 /**
 247  * Get compile-time information for libraries used by libwireshark.
 248  */
 249 WS_DLL_PUBLIC
 250 void
 251 epan_get_compiled_version_info(GString *str);
 252
 253 /**
 254  * Get runtime information for libraries used by libwireshark.
 255  */
 256 WS_DLL_PUBLIC
 257 void
 258 epan_get_runtime_version_info(GString *str);
 259
 260 #ifdef __cplusplus
 261 }
 262 #endif /* __cplusplus */
 263
 264 #endif /* __EPAN_H__ */