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  * @param col the writable column, -1 for checking the state of all columns
 153  * @return TRUE if it's writable, FALSE if not
 154  */
 155 WS_DLL_PUBLIC gboolean  col_get_writable(column_info *cinfo, const gint col);
 156
 157 /** Set the columns writable.
 158  *
 159  * @param cinfo the current packet row
 160  * @param col the column to set, -1 for all
 161  * @param writable TRUE if it's writable, FALSE if not
 162  */
 163 WS_DLL_PUBLIC void      col_set_writable(column_info *cinfo, const gint col, const gboolean writable);
 164
 165 /** Sets a fence for the current column content,
 166  * so this content won't be affected by further col_... function calls.
 167  *
 168  * This can be useful if a protocol is more than once in a single packet,
 169  * e.g. multiple HTTP calls in a single TCP packet.
 170  *
 171  * @param cinfo the current packet row
 172  * @param col the column to use, e.g. COL_INFO
 173  */
 174 WS_DLL_PUBLIC void      col_set_fence(column_info *cinfo, const gint col);
 175
 176 /** Clears a fence for the current column content
 177  *
 178  * This can be useful if a protocol wants to remove whatever
 179  * a previous protocol has added to the column.
 180  *
 181  * @param cinfo the current packet row
 182  * @param col the column to use, e.g. COL_INFO
 183  */
 184 WS_DLL_PUBLIC void      col_clear_fence(column_info *cinfo, const gint col);
 185
 186 /** Gets the text of a column element.
 187  *
 188  * @param cinfo the current packet row
 189  * @param col the column to use, e.g. COL_INFO
 190  *
 191  * @return the text string
 192  */
 193 WS_DLL_PUBLIC const gchar *col_get_text(column_info *cinfo, const gint col);
 194
 195 /** Clears the text of a column element.
 196  *
 197  * @param cinfo the current packet row
 198  * @param col the column to use, e.g. COL_INFO
 199  */
 200 WS_DLL_PUBLIC void      col_clear(column_info *cinfo, const gint col);
 201
 202 /** Set (replace) the text of a column element, the text won't be copied.
 203  *
 204  * Usually used to set const strings!
 205  *
 206  * @param cinfo the current packet row
 207  * @param col the column to use, e.g. COL_INFO
 208  * @param str the string to set
 209  */
 210 WS_DLL_PUBLIC void      col_set_str(column_info *cinfo, const gint col, const gchar * str);
 211
 212 /** Add (replace) the text of a column element, the text will be copied.
 213  *
 214  * @param cinfo the current packet row
 215  * @param col the column to use, e.g. COL_INFO
 216  * @param str the string to add
 217  */
 218 WS_DLL_PUBLIC void      col_add_str(column_info *cinfo, const gint col, const gchar *str);
 219
 220 /* terminator argument for col_add_lstr() function */
 221 #define COL_ADD_LSTR_TERMINATOR (const char *) -1
 222 WS_DLL_PUBLIC void      col_add_lstr(column_info *cinfo, const gint el, const gchar *str, ...);
 223
 224 /** Add (replace) the text of a column element, the text will be formatted and copied.
 225  *
 226  * Same function as col_add_str() but using a printf-like format string.
 227  *
 228  * @param cinfo the current packet row
 229  * @param col the column to use, e.g. COL_INFO
 230  * @param format the format string
 231  * @param ... the variable number of parameters
 232  */
 233 WS_DLL_PUBLIC void      col_add_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 234     G_GNUC_PRINTF(3, 4);
 235
 236 /** For internal Wireshark use only.  Not to be called from dissectors. */
 237 void col_custom_set_edt(struct epan_dissect *edt, column_info *cinfo);
 238
 239 /** For internal Wireshark use only.  Not to be called from dissectors. */
 240 WS_DLL_PUBLIC
 241 void col_custom_prime_edt(struct epan_dissect *edt, column_info *cinfo);
 242
 243 /** For internal Wireshark use only.  Not to be called from dissectors. */
 244 WS_DLL_PUBLIC
 245 gboolean have_custom_cols(column_info *cinfo);
 246
 247 /** For internal Wireshark use only.  Not to be called from dissectors. */
 248 WS_DLL_PUBLIC
 249 gboolean have_field_extractors(void);
 250
 251 /** For internal Wireshark use only.  Not to be called from dissectors. */
 252 WS_DLL_PUBLIC
 253 gboolean col_has_time_fmt(column_info *cinfo, const gint col);
 254 /** For internal Wireshark use only.  Not to be called from dissectors. */
 255 WS_DLL_PUBLIC
 256 gboolean col_based_on_frame_data(column_info *cinfo, const gint col);
 257
 258 /** Append the given text to a column element, the text will be copied.
 259  *
 260  * @param cinfo the current packet row
 261  * @param col the column to use, e.g. COL_INFO
 262  * @param str the string to append
 263  */
 264 WS_DLL_PUBLIC void      col_append_str(column_info *cinfo, const gint col, const gchar *str);
 265
 266 /** Append <abbrev>=<val> to a column element, the text will be copied.
 267  *
 268  * @param cinfo the current packet row
 269  * @param col the column to use, e.g. COL_INFO
 270  * @param abbrev the string to append
 271  * @param val the value to append
 272  * @param sep an optional separator to _prepend_ to abbrev
 273  */
 274 WS_DLL_PUBLIC void col_append_str_uint(column_info *cinfo, const gint col, const gchar *abbrev, guint32 val, const gchar *sep);
 275
 276 /** Append a transport port pair to a column element, the text will be copied.
 277  *
 278  * @param cinfo the current packet row
 279  * @param col the column to use, e.g. COL_INFO
 280  * @param typ the port type to resolve, e.g. PT_UDP
 281  * @param src the source port value to append
 282  * @param dst the destination port value to append
 283  */
 284 WS_DLL_PUBLIC void col_append_ports(column_info *cinfo, const gint col, port_type typ, guint16 src, guint16 dst);
 285
 286 /* Append the given strings (terminated by COL_ADD_LSTR_TERMINATOR) to a column element,
 287  *
 288  * Same result as col_append_str() called for every string element.
 289  */
 290 WS_DLL_PUBLIC void      col_append_lstr(column_info *cinfo, const gint el, const gchar *str, ...);
 291
 292 /** Append the given text to a column element, the text will be formatted and copied.
 293  *
 294  * Same function as col_append_str() but using a printf-like format string.
 295  *
 296  * @param cinfo the current packet row
 297  * @param col the column to use, e.g. COL_INFO
 298  * @param format the format string
 299  * @param ... the variable number of parameters
 300  */
 301 WS_DLL_PUBLIC void      col_append_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 302     G_GNUC_PRINTF(3, 4);
 303
 304 /** Prepend the given text to a column element, the text will be formatted and copied.
 305  *
 306  * @param cinfo the current packet row
 307  * @param col the column to use, e.g. COL_INFO
 308  * @param format the format string
 309  * @param ... the variable number of parameters
 310  */
 311 WS_DLL_PUBLIC void      col_prepend_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 312     G_GNUC_PRINTF(3, 4);
 313
 314 /**Prepend the given text to a column element, the text will be formatted and copied.
 315  * This function is similar to col_prepend_fstr() but this function will
 316  * unconditionally set a fence to the end of the prepended data even if there
 317  * were no fence before.
 318  * The col_prepend_fstr() will only prepend the data before the fence IF
 319  * there is already a fence created. This function will create a fence in case
 320  * it does not yet exist.
 321  */
 322 WS_DLL_PUBLIC void      col_prepend_fence_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 323     G_GNUC_PRINTF(3, 4);
 324
 325 /** Append the given text (prepended by a separator) to a column element.
 326  *
 327  * Much like col_append_str() but will prepend the given separator if the column isn't empty.
 328  *
 329  * @param cinfo the current packet row
 330  * @param col the column to use, e.g. COL_INFO
 331  * @param sep the separator string or NULL for default: ", "
 332  * @param str the string to append
 333  */
 334 WS_DLL_PUBLIC void      col_append_sep_str(column_info *cinfo, const gint col, const gchar *sep,
 335                 const gchar *str);
 336
 337 /** Append the given text (prepended by a separator) to a column element.
 338  *
 339  * Much like col_append_fstr() but will prepend the given separator if the column isn't empty.
 340  *
 341  * @param cinfo the current packet row
 342  * @param col the column to use, e.g. COL_INFO
 343  * @param sep the separator string or NULL for default: ", "
 344  * @param format the format string
 345  * @param ... the variable number of parameters
 346  */
 347 WS_DLL_PUBLIC void      col_append_sep_fstr(column_info *cinfo, const gint col, const gchar *sep,
 348                 const gchar *format, ...)
 349     G_GNUC_PRINTF(4, 5);
 350
 351 /** Set the given (relative) time to a column element.
 352  *
 353  * Used by dissectors to set the time in a column
 354  *
 355  * @param cinfo         the current packet row
 356  * @param col           the column to use, e.g. COL_INFO
 357  * @param ts            the time to set in the column
 358  * @param fieldname     the fieldname to use for creating a filter (when
 359  *                        applying/preparing/copying as filter)
 360  */
 361 WS_DLL_PUBLIC void      col_set_time(column_info *cinfo, const int col,
 362                         const nstime_t *ts, const char *fieldname);
 363
 364 WS_DLL_PUBLIC void set_fd_time(const struct epan_session *epan, frame_data *fd, gchar *buf);
 365
 366 #ifdef __cplusplus
 367 }
 368 #endif /* __cplusplus */
 369
 370 #endif /* __COLUMN_UTILS_H__ */