epan/column-utils.h

   1 /* column-utils.h
   2  * Definitions for column utility structures and routines
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation; either version 2
  11  * of the License, or (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  21  */
  22
  23 #ifndef __COLUMN_UTILS_H__
  24 #define __COLUMN_UTILS_H__
  25
  26 #include <glib.h>
  27
  28 #include "packet_info.h"
  29 #include "ws_symbol_export.h"
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif /* __cplusplus */
  34
  35 struct epan_dissect;
  36
  37 /**
  38  *  Helper routines for column utility structures and routines.
  39  */
  40
  41 struct epan_column_info;
  42 typedef struct epan_column_info column_info;
  43
  44 /**
  45  * All of the possible columns in summary listing.
  46  *
  47  * NOTE1: The entries MUST remain in this order, or else you need to reorder
  48  *        the slist[] and dlist[] arrays in column.c to match!
  49  *
  50  * NOTE2: Please add the COL_XYZ entry in the appropriate spot, such that the
  51  *        dlist[] array remains in alphabetical order!
  52  */
  53 enum {
  54   COL_8021Q_VLAN_ID,  /**< 0) 802.1Q vlan ID */
  55   COL_ABS_YMD_TIME,   /**< 1) Absolute date, as YYYY-MM-DD, and time */
  56   COL_ABS_YDOY_TIME,  /**< 2) Absolute date, as YYYY/DOY, and time */
  57   COL_ABS_TIME,       /**< 3) Absolute time */
  58   COL_VSAN,           /**< 4) VSAN - Cisco MDS-specific */
  59   COL_CUMULATIVE_BYTES, /**< 5) Cumulative number of bytes */
  60   COL_CUSTOM,         /**< 6) Custom column (any filter name's contents) */
  61   COL_DCE_CALL,       /**< 7) DCE/RPC connection oriented call id OR datagram sequence number */
  62   COL_DELTA_TIME,     /**< 8) Delta time */
  63   COL_DELTA_TIME_DIS, /**< 9) Delta time displayed*/
  64   COL_RES_DST,        /**< 10) Resolved dest */
  65   COL_UNRES_DST,      /**< 11) Unresolved dest */
  66   COL_RES_DST_PORT,   /**< 12) Resolved dest port */
  67   COL_UNRES_DST_PORT, /**< 13) Unresolved dest port */
  68   COL_DEF_DST,        /**< 14) Destination address */
  69   COL_DEF_DST_PORT,   /**< 15) Destination port */
  70   COL_EXPERT,         /**< 16) Expert Info */
  71   COL_IF_DIR,         /**< 17) FW-1 monitor interface/direction */
  72   COL_FREQ_CHAN,      /**< 18) IEEE 802.11 (and WiMax?) - Channel */
  73   COL_DEF_DL_DST,     /**< 19) Data link layer dest address */
  74   COL_DEF_DL_SRC,     /**< 20) Data link layer source address */
  75   COL_RES_DL_DST,     /**< 21) Resolved DL dest */
  76   COL_UNRES_DL_DST,   /**< 22) Unresolved DL dest */
  77   COL_RES_DL_SRC,     /**< 23) Resolved DL source */
  78   COL_UNRES_DL_SRC,   /**< 24) Unresolved DL source */
  79   COL_RSSI,           /**< 25) IEEE 802.11 - received signal strength */
  80   COL_TX_RATE,        /**< 26) IEEE 802.11 - TX rate in Mbps */
  81   COL_DSCP_VALUE,     /**< 27) IP DSCP Value */
  82   COL_INFO,           /**< 28) Description */
  83   COL_RES_NET_DST,    /**< 29) Resolved net dest */
  84   COL_UNRES_NET_DST,  /**< 30) Unresolved net dest */
  85   COL_RES_NET_SRC,    /**< 31) Resolved net source */
  86   COL_UNRES_NET_SRC,  /**< 32) Unresolved net source */
  87   COL_DEF_NET_DST,    /**< 33) Network layer dest address */
  88   COL_DEF_NET_SRC,    /**< 34) Network layer source address */
  89   COL_NUMBER,         /**< 35) Packet list item number */
  90   COL_PACKET_LENGTH,  /**< 36) Packet length in bytes */
  91   COL_PROTOCOL,       /**< 37) Protocol */
  92   COL_REL_TIME,       /**< 38) Relative time */
  93   COL_DEF_SRC,        /**< 39) Source address */
  94   COL_DEF_SRC_PORT,   /**< 40) Source port */
  95   COL_RES_SRC,        /**< 41) Resolved source */
  96   COL_UNRES_SRC,      /**< 42) Unresolved source */
  97   COL_RES_SRC_PORT,   /**< 43) Resolved source port */
  98   COL_UNRES_SRC_PORT, /**< 44) Unresolved source port */
  99   COL_TEI,            /**< 45) Q.921 TEI */
 100   COL_UTC_YMD_TIME,   /**< 46) UTC date, as YYYY-MM-DD, and time */
 101   COL_UTC_YDOY_TIME,  /**< 47) UTC date, as YYYY/DOY, and time */
 102   COL_UTC_TIME,       /**< 48) UTC time */
 103   COL_CLS_TIME,       /**< 49) Command line-specified time (default relative) */
 104   NUM_COL_FMTS        /**< 50) Should always be last */
 105 };
 106
 107 /** Allocate all the data structures for constructing column data, given
 108  * the number of columns.
 109  *
 110  * Internal, don't use this in dissectors!
 111  */
 112 WS_DLL_PUBLIC void      col_setup(column_info *cinfo, const gint num_cols);
 113
 114 /** Cleanup all the data structures for constructing column data;
 115  * undoes the alocations that col_setup() does.
 116  *
 117  * Internal, don't use this in dissectors!
 118  */
 119 WS_DLL_PUBLIC void      col_cleanup(column_info *cinfo);
 120
 121 /** Initialize the data structures for constructing column data.
 122  *
 123  * Internal, don't use this in dissectors!
 124  */
 125 extern void     col_init(column_info *cinfo, const struct epan_session *epan);
 126
 127 /** Fill in all columns of the given packet which are based on values from frame_data.
 128  *
 129  * Internal, don't use this in dissectors!
 130  */
 131 WS_DLL_PUBLIC void col_fill_in_frame_data(const frame_data *fd, column_info *cinfo, const gint col, gboolean const fill_col_exprs);
 132
 133 /** Fill in all columns of the given packet.
 134  *
 135  * Internal, don't use this in dissectors!
 136  */
 137 WS_DLL_PUBLIC void      col_fill_in(packet_info *pinfo, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
 138
 139 /** Fill in columns if we got an error reading the packet.
 140  * We set most columns to "???", and set the Info column to an error
 141  * message.
 142  *
 143  * Internal, don't use this in dissectors!
 144  */
 145 WS_DLL_PUBLIC void      col_fill_in_error(column_info *cinfo, frame_data *fdata, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
 146
 147 /* Utility routines used by packet*.c */
 148
 149 /** Are the columns writable?
 150  *
 151  * @param cinfo the current packet row
 152  * @return TRUE if it's writable, FALSE if not
 153  */
 154 WS_DLL_PUBLIC gboolean  col_get_writable(column_info *cinfo);
 155
 156 /** Set the columns writable.
 157  *
 158  * @param cinfo the current packet row
 159  * @param writable TRUE if it's writable, FALSE if not
 160  */
 161 WS_DLL_PUBLIC void      col_set_writable(column_info *cinfo, const gboolean writable);
 162
 163 /** Sets a fence for the current column content,
 164  * so this content won't be affected by further col_... function calls.
 165  *
 166  * This can be useful if a protocol is more than once in a single packet,
 167  * e.g. multiple HTTP calls in a single TCP packet.
 168  *
 169  * @param cinfo the current packet row
 170  * @param col the column to use, e.g. COL_INFO
 171  */
 172 WS_DLL_PUBLIC void      col_set_fence(column_info *cinfo, const gint col);
 173
 174 /** Clears a fence for the current column content
 175  *
 176  * This can be useful if a protocol wants to remove whatever
 177  * a previous protocol has added to the column.
 178  *
 179  * @param cinfo the current packet row
 180  * @param col the column to use, e.g. COL_INFO
 181  */
 182 WS_DLL_PUBLIC void      col_clear_fence(column_info *cinfo, const gint col);
 183
 184 /** Gets the text of a column element.
 185  *
 186  * @param cinfo the current packet row
 187  * @param col the column to use, e.g. COL_INFO
 188  *
 189  * @return the text string
 190  */
 191 WS_DLL_PUBLIC const gchar *col_get_text(column_info *cinfo, const gint col);
 192
 193 /** Clears the text of a column element.
 194  *
 195  * @param cinfo the current packet row
 196  * @param col the column to use, e.g. COL_INFO
 197  */
 198 WS_DLL_PUBLIC void      col_clear(column_info *cinfo, const gint col);
 199
 200 /** Set (replace) the text of a column element, the text won't be copied.
 201  *
 202  * Usually used to set const strings!
 203  *
 204  * @param cinfo the current packet row
 205  * @param col the column to use, e.g. COL_INFO
 206  * @param str the string to set
 207  */
 208 WS_DLL_PUBLIC void      col_set_str(column_info *cinfo, const gint col, const gchar * str);
 209
 210 /** Add (replace) the text of a column element, the text will be copied.
 211  *
 212  * @param cinfo the current packet row
 213  * @param col the column to use, e.g. COL_INFO
 214  * @param str the string to add
 215  */
 216 WS_DLL_PUBLIC void      col_add_str(column_info *cinfo, const gint col, const gchar *str);
 217
 218 /* terminator argument for col_add_lstr() function */
 219 #define COL_ADD_LSTR_TERMINATOR (const char *) -1
 220 WS_DLL_PUBLIC void      col_add_lstr(column_info *cinfo, const gint el, const gchar *str, ...);
 221
 222 /** Add (replace) the text of a column element, the text will be formatted and copied.
 223  *
 224  * Same function as col_add_str() but using a printf-like format string.
 225  *
 226  * @param cinfo the current packet row
 227  * @param col the column to use, e.g. COL_INFO
 228  * @param format the format string
 229  * @param ... the variable number of parameters
 230  */
 231 WS_DLL_PUBLIC void      col_add_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 232     G_GNUC_PRINTF(3, 4);
 233
 234 /** For internal Wireshark use only.  Not to be called from dissectors. */
 235 void col_custom_set_edt(struct epan_dissect *edt, column_info *cinfo);
 236
 237 /** For internal Wireshark use only.  Not to be called from dissectors. */
 238 WS_DLL_PUBLIC
 239 void col_custom_prime_edt(struct epan_dissect *edt, column_info *cinfo);
 240
 241 /** For internal Wireshark use only.  Not to be called from dissectors. */
 242 WS_DLL_PUBLIC
 243 gboolean have_custom_cols(column_info *cinfo);
 244
 245 /** For internal Wireshark use only.  Not to be called from dissectors. */
 246 WS_DLL_PUBLIC
 247 gboolean have_field_extractors(void);
 248
 249 /** For internal Wireshark use only.  Not to be called from dissectors. */
 250 WS_DLL_PUBLIC
 251 gboolean col_has_time_fmt(column_info *cinfo, const gint col);
 252 /** For internal Wireshark use only.  Not to be called from dissectors. */
 253 WS_DLL_PUBLIC
 254 gboolean col_based_on_frame_data(column_info *cinfo, const gint col);
 255
 256 /** Append the given text to a column element, the text will be copied.
 257  *
 258  * @param cinfo the current packet row
 259  * @param col the column to use, e.g. COL_INFO
 260  * @param str the string to append
 261  */
 262 WS_DLL_PUBLIC void      col_append_str(column_info *cinfo, const gint col, const gchar *str);
 263
 264 /** Append <abbrev>=<val> to a column element, the text will be copied.
 265  *
 266  * @param cinfo the current packet row
 267  * @param col the column to use, e.g. COL_INFO
 268  * @param abbrev the string to append
 269  * @param val the value to append
 270  * @param sep an optional separator to _prepend_ to abbrev
 271  */
 272 WS_DLL_PUBLIC void col_append_str_uint(column_info *cinfo, const gint col, const gchar *abbrev, guint32 val, const gchar *sep);
 273
 274 /** Append a transport port pair to a column element, the text will be copied.
 275  *
 276  * @param cinfo the current packet row
 277  * @param col the column to use, e.g. COL_INFO
 278  * @param typ the port type to resolve, e.g. PT_UDP
 279  * @param src the source port value to append
 280  * @param dst the destination port value to append
 281  */
 282 WS_DLL_PUBLIC void col_append_ports(column_info *cinfo, const gint col, port_type typ, guint16 src, guint16 dst);
 283
 284 /* Append the given strings (terminated by COL_ADD_LSTR_TERMINATOR) to a column element,
 285  *
 286  * Same result as col_append_str() called for every string element.
 287  */
 288 WS_DLL_PUBLIC void      col_append_lstr(column_info *cinfo, const gint el, const gchar *str, ...);
 289
 290 /** Append the given text to a column element, the text will be formatted and copied.
 291  *
 292  * Same function as col_append_str() but using a printf-like format string.
 293  *
 294  * @param cinfo the current packet row
 295  * @param col the column to use, e.g. COL_INFO
 296  * @param format the format string
 297  * @param ... the variable number of parameters
 298  */
 299 WS_DLL_PUBLIC void      col_append_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 300     G_GNUC_PRINTF(3, 4);
 301
 302 /** Prepend the given text to a column element, the text will be formatted and copied.
 303  *
 304  * @param cinfo the current packet row
 305  * @param col the column to use, e.g. COL_INFO
 306  * @param format the format string
 307  * @param ... the variable number of parameters
 308  */
 309 WS_DLL_PUBLIC void      col_prepend_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 310     G_GNUC_PRINTF(3, 4);
 311
 312 /**Prepend the given text to a column element, the text will be formatted and copied.
 313  * This function is similar to col_prepend_fstr() but this function will
 314  * unconditionally set a fence to the end of the prepended data even if there
 315  * were no fence before.
 316  * The col_prepend_fstr() will only prepend the data before the fence IF
 317  * there is already a fence created. This function will create a fence in case
 318  * it does not yet exist.
 319  */
 320 WS_DLL_PUBLIC void      col_prepend_fence_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 321     G_GNUC_PRINTF(3, 4);
 322
 323 /** Append the given text (prepended by a separator) to a column element.
 324  *
 325  * Much like col_append_str() but will prepend the given separator if the column isn't empty.
 326  *
 327  * @param cinfo the current packet row
 328  * @param col the column to use, e.g. COL_INFO
 329  * @param sep the separator string or NULL for default: ", "
 330  * @param str the string to append
 331  */
 332 WS_DLL_PUBLIC void      col_append_sep_str(column_info *cinfo, const gint col, const gchar *sep,
 333                 const gchar *str);
 334
 335 /** Append the given text (prepended by a separator) to a column element.
 336  *
 337  * Much like col_append_fstr() but will prepend the given separator if the column isn't empty.
 338  *
 339  * @param cinfo the current packet row
 340  * @param col the column to use, e.g. COL_INFO
 341  * @param sep the separator string or NULL for default: ", "
 342  * @param format the format string
 343  * @param ... the variable number of parameters
 344  */
 345 WS_DLL_PUBLIC void      col_append_sep_fstr(column_info *cinfo, const gint col, const gchar *sep,
 346                 const gchar *format, ...)
 347     G_GNUC_PRINTF(4, 5);
 348
 349 /** Set the given (relative) time to a column element.
 350  *
 351  * Used by dissectors to set the time in a column
 352  *
 353  * @param cinfo         the current packet row
 354  * @param col           the column to use, e.g. COL_INFO
 355  * @param ts            the time to set in the column
 356  * @param fieldname     the fieldname to use for creating a filter (when
 357  *                        applying/preparing/copying as filter)
 358  */
 359 WS_DLL_PUBLIC void      col_set_time(column_info *cinfo, const int col,
 360                         const nstime_t *ts, const char *fieldname);
 361
 362 WS_DLL_PUBLIC void set_fd_time(const struct epan_session *epan, frame_data *fd, gchar *buf);
 363
 364 #ifdef __cplusplus
 365 }
 366 #endif /* __cplusplus */
 367
 368 #endif /* __COLUMN_UTILS_H__ */