epan/column-utils.h

   1 /** @file
   2  * Definitions for column utility structures and routines
   3  * Utility routines used by packet*.c
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __COLUMN_UTILS_H__
  13 #define __COLUMN_UTILS_H__
  14
  15 #include "packet_info.h"
  16 #include "ws_symbol_export.h"
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif /* __cplusplus */
  21
  22 #define COL_MAX_LEN 2048
  23 #define COL_MAX_INFO_LEN 4096
  24
  25 /* A regex to split possibly multifield custom columns into components
  26  *
  27  * Split on operator "||" (with optional space around it) and on "or"
  28  * (which must have space around it to avoid matching in the middle of
  29  * a word, field in the "synphasor" protocol, etc. This is somewhat too
  30  * strict, as "or" adjacent to parentheses ought to be fine so long
  31  * as the filter matches the grammar, like "(tcp.port)or(udp.port)",
  32  * but that's the cost of using regex instead of the real parser.)
  33  * Also split on space at the beginning or end of the expression (in
  34  * lieu of always stripping whitespace at the beginning and end, but it
  35  * does mean that we have to ignore any empty tokens in the result.)
  36  *
  37  * Use negative lookahead to avoid matching "||" or "or" that are contained
  38  * within parentheses. Don't match if a close parenthesis comes before an
  39  * open parenthesis. The regex doesn't help with unmatched parentheses, but
  40  * such an expression already won't satisfy the grammar and won't compile.
  41  */
  42 #define COL_CUSTOM_PRIME_REGEX "(?:^ *| *\\|\\| *| +or +| *$)(?![^(]*\\))"
  43
  44 struct epan_dissect;
  45
  46 /**
  47  *  Helper routines for column utility structures and routines.
  48  */
  49
  50 struct epan_column_info;
  51 typedef struct epan_column_info column_info;
  52
  53 /**
  54  * All of the possible columns in summary listing.
  55  *
  56  * NOTE1: The entries MUST remain in this order, or else you need to reorder
  57  *        the slist[] and dlist[] arrays in column.c to match!
  58  *
  59  * NOTE2: Please add the COL_XYZ entry in the appropriate spot, such that the
  60  *        dlist[] array remains in alphabetical order!
  61  */
  62 enum {
  63   COL_ABS_YMD_TIME,   /**< 0) Absolute date, as YYYY-MM-DD, and time */
  64   COL_ABS_YDOY_TIME,  /**< 1) Absolute date, as YYYY/DOY, and time */
  65   COL_ABS_TIME,       /**< 2) Absolute time */
  66   COL_CUMULATIVE_BYTES, /**< 3) Cumulative number of bytes */
  67   COL_CUSTOM,         /**< 4) Custom column (any filter name's contents) */
  68   COL_DELTA_TIME,     /**< 5) Delta time */
  69   COL_DELTA_TIME_DIS, /**< 6) Delta time displayed*/
  70   COL_RES_DST,        /**< 7) Resolved dest */
  71   COL_UNRES_DST,      /**< 8) Unresolved dest */
  72   COL_RES_DST_PORT,   /**< 9) Resolved dest port */
  73   COL_UNRES_DST_PORT, /**< 10) Unresolved dest port */
  74   COL_DEF_DST,        /**< 11) Destination address */
  75   COL_DEF_DST_PORT,   /**< 12) Destination port */
  76   COL_EXPERT,         /**< 13) Expert Info */
  77   COL_IF_DIR,         /**< 14) FW-1 monitor interface/direction */
  78   COL_FREQ_CHAN,      /**< 15) IEEE 802.11 (and WiMax?) - Channel */
  79   COL_DEF_DL_DST,     /**< 16) Data link layer dest address */
  80   COL_DEF_DL_SRC,     /**< 17) Data link layer source address */
  81   COL_RES_DL_DST,     /**< 18) Resolved DL dest */
  82   COL_UNRES_DL_DST,   /**< 19) Unresolved DL dest */
  83   COL_RES_DL_SRC,     /**< 20) Resolved DL source */
  84   COL_UNRES_DL_SRC,   /**< 21) Unresolved DL source */
  85   COL_RSSI,           /**< 22) IEEE 802.11 - received signal strength */
  86   COL_TX_RATE,        /**< 23) IEEE 802.11 - TX rate in Mbps */
  87   COL_DSCP_VALUE,     /**< 24) IP DSCP Value */
  88   COL_INFO,           /**< 25) Description */
  89   COL_RES_NET_DST,    /**< 26) Resolved net dest */
  90   COL_UNRES_NET_DST,  /**< 27) Unresolved net dest */
  91   COL_RES_NET_SRC,    /**< 28) Resolved net source */
  92   COL_UNRES_NET_SRC,  /**< 29) Unresolved net source */
  93   COL_DEF_NET_DST,    /**< 30) Network layer dest address */
  94   COL_DEF_NET_SRC,    /**< 31) Network layer source address */
  95   COL_NUMBER,         /**< 32) Packet list item number */
  96   COL_NUMBER_DIS,     /**< 33) Packet list item number displayed */
  97   COL_PACKET_LENGTH,  /**< 34) Packet length in bytes */
  98   COL_PROTOCOL,       /**< 35) Protocol */
  99   COL_REL_TIME,       /**< 36) Relative time */
 100   COL_DEF_SRC,        /**< 37) Source address */
 101   COL_DEF_SRC_PORT,   /**< 38) Source port */
 102   COL_RES_SRC,        /**< 39) Resolved source */
 103   COL_UNRES_SRC,      /**< 40) Unresolved source */
 104   COL_RES_SRC_PORT,   /**< 41) Resolved source port */
 105   COL_UNRES_SRC_PORT, /**< 42) Unresolved source port */
 106   COL_UTC_YMD_TIME,   /**< 43) UTC date, as YYYY-MM-DD, and time */
 107   COL_UTC_YDOY_TIME,  /**< 44) UTC date, as YYYY/DOY, and time */
 108   COL_UTC_TIME,       /**< 45) UTC time */
 109   COL_CLS_TIME,       /**< 46) Command line-specified time (default relative) */
 110   NUM_COL_FMTS        /**< 47) Should always be last */
 111 };
 112
 113 /** Are the columns writable?
 114  *
 115  * @param cinfo the current packet row
 116  * @param col the writable column, -1 for checking the state of all columns
 117  * @return true if it's writable, false if not
 118  */
 119 WS_DLL_PUBLIC bool col_get_writable(column_info *cinfo, const int col);
 120
 121 /** Set the columns writable.
 122  *
 123  * @param cinfo the current packet row
 124  * @param col the column to set, -1 for all
 125  * @param writable true if it's writable, false if not
 126  */
 127 WS_DLL_PUBLIC void col_set_writable(column_info *cinfo, const int col, const bool writable);
 128
 129 /** Sets a fence for the current column content,
 130  * so this content won't be affected by further col_... function calls.
 131  *
 132  * This can be useful if a protocol is more than once in a single packet,
 133  * e.g. multiple HTTP calls in a single TCP packet.
 134  *
 135  * @param cinfo the current packet row
 136  * @param col the column to use, e.g. COL_INFO
 137  */
 138 WS_DLL_PUBLIC void col_set_fence(column_info *cinfo, const int col);
 139
 140 /** Clears a fence for the current column content
 141  *
 142  * This can be useful if a protocol wants to remove whatever
 143  * a previous protocol has added to the column.
 144  *
 145  * @param cinfo the current packet row
 146  * @param col the column to use, e.g. COL_INFO
 147  */
 148 WS_DLL_PUBLIC void col_clear_fence(column_info *cinfo, const int col);
 149
 150 /** Gets the text of a column element.
 151  *
 152  * @param cinfo the current packet row
 153  * @param col the column to use, e.g. COL_INFO
 154  *
 155  * @return the text string
 156  */
 157 WS_DLL_PUBLIC const char *col_get_text(column_info *cinfo, const int col);
 158
 159 /** Clears the text of a column element.
 160  *
 161  * @param cinfo the current packet row
 162  * @param col the column to use, e.g. COL_INFO
 163  */
 164 WS_DLL_PUBLIC void col_clear(column_info *cinfo, const int col);
 165
 166 /** Set (replace) the text of a column element, the text won't be formatted or copied.
 167  *
 168  * Use this for simple static strings like protocol names. Don't use for untrusted strings
 169  * or strings that may contain unprintable characters.
 170  *
 171  * Usually used to set const strings!
 172  *
 173  * @param cinfo the current packet row
 174  * @param col the column to use, e.g. COL_INFO
 175  * @param str the string to set
 176  */
 177 WS_DLL_PUBLIC void col_set_str(column_info *cinfo, const int col, const char * str);
 178
 179 /** Add (replace) the text of a column element, the text will be formatted and copied.
 180  *
 181  * Unprintable characters according to g_ascii_isprint() are escaped.
 182  *
 183  * @param cinfo the current packet row
 184  * @param col the column to use, e.g. COL_INFO
 185  * @param str the string to add
 186  */
 187 WS_DLL_PUBLIC void col_add_str(column_info *cinfo, const int col, const char *str);
 188
 189 /* terminator argument for col_add_lstr() function */
 190 #define COL_ADD_LSTR_TERMINATOR (const char *) -1
 191
 192 WS_DLL_PUBLIC void col_add_lstr(column_info *cinfo, const int el, const char *str, ...);
 193
 194 /** Add (replace) the text of a column element, the text will be formatted and copied.
 195  *
 196  * Unprintable characters according to g_ascii_isprint() are escaped.
 197  *
 198  * Same function as col_add_str() but using a printf-like format string.
 199  *
 200  * @param cinfo the current packet row
 201  * @param col the column to use, e.g. COL_INFO
 202  * @param format the format string
 203  * @param ... the variable number of parameters
 204  */
 205 WS_DLL_PUBLIC void col_add_fstr(column_info *cinfo, const int col, const char *format, ...)
 206     G_GNUC_PRINTF(3, 4);
 207
 208 /** Append the given text to a column element, the text will be formatted and copied.
 209  *
 210  * Unprintable characters according to g_ascii_isprint() are escaped.
 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 append
 215  */
 216 WS_DLL_PUBLIC void col_append_str(column_info *cinfo, const int col, const char *str);
 217
 218 /** Append <abbrev>=<val> to a column element, the text will be copied.
 219  *
 220  * @param cinfo the current packet row
 221  * @param col the column to use, e.g. COL_INFO
 222  * @param abbrev the string to append
 223  * @param val the value to append
 224  * @param sep an optional separator to _prepend_ to abbrev
 225  */
 226 WS_DLL_PUBLIC void col_append_str_uint(column_info *cinfo, const int col, const char *abbrev, uint32_t val, const char *sep);
 227
 228 /** Append a transport port pair to a column element, the text will be copied.
 229  *
 230  * @param cinfo the current packet row
 231  * @param col the column to use, e.g. COL_INFO
 232  * @param typ the port type to resolve, e.g. PT_UDP
 233  * @param src the source port value to append
 234  * @param dst the destination port value to append
 235  */
 236 WS_DLL_PUBLIC void col_append_ports(column_info *cinfo, const int col, port_type typ, uint16_t src, uint16_t dst);
 237
 238 /** Append a frame number and signal that we have updated
 239  * column information.
 240  *
 241  * @param pinfo the current packet info
 242  * @param col the column to use, e.g. COL_INFO
 243  * @param fmt_str format string, e.g. "reassembled in %u".
 244  * @param frame_num frame number
 245  */
 246 WS_DLL_PUBLIC void col_append_frame_number(packet_info *pinfo, const int col, const char *fmt_str, unsigned frame_num);
 247
 248 /* Append the given strings (terminated by COL_ADD_LSTR_TERMINATOR) to a column element,
 249  *
 250  * Same result as col_append_str() called for every string element.
 251  */
 252 WS_DLL_PUBLIC void col_append_lstr(column_info *cinfo, const int el, const char *str, ...);
 253
 254 /** Append the given text to a column element, the text will be formatted and copied.
 255  *
 256  * Unprintable characters according to g_ascii_isprint() are escaped.
 257  *
 258  * Same function as col_append_str() but using a printf-like format string.
 259  *
 260  * @param cinfo the current packet row
 261  * @param col the column to use, e.g. COL_INFO
 262  * @param format the format string
 263  * @param ... the variable number of parameters
 264  */
 265 WS_DLL_PUBLIC void col_append_fstr(column_info *cinfo, const int col, const char *format, ...)
 266     G_GNUC_PRINTF(3, 4);
 267
 268 /** Prepend the given text to a column element, the text will be formatted and copied.
 269  *
 270  * Unprintable characters according to g_ascii_isprint() are escaped.
 271  *
 272  * @param cinfo the current packet row
 273  * @param col the column to use, e.g. COL_INFO
 274  * @param format the format string
 275  * @param ... the variable number of parameters
 276  */
 277 WS_DLL_PUBLIC void col_prepend_fstr(column_info *cinfo, const int col, const char *format, ...)
 278     G_GNUC_PRINTF(3, 4);
 279
 280 /** Prepend the given text to a column element, the text will be formatted and copied.
 281  *
 282  * Unprintable characters according to g_ascii_isprint() are escaped.
 283  *
 284  * This function is similar to col_prepend_fstr() but this function will
 285  * unconditionally set a fence to the end of the prepended data even if there
 286  * were no fence before.
 287  * The col_prepend_fstr() will only prepend the data before the fence IF
 288  * there is already a fence created. This function will create a fence in case
 289  * it does not yet exist.
 290  */
 291 WS_DLL_PUBLIC void col_prepend_fence_fstr(column_info *cinfo, const int col, const char *format, ...)
 292     G_GNUC_PRINTF(3, 4);
 293
 294 /** Append the given text (prepended by a separator) to a column element.
 295  *
 296  * Unprintable characters according to g_ascii_isprint() are escaped.
 297  *
 298  * Much like col_append_str() but will prepend the given separator if the column isn't empty.
 299  *
 300  * @param cinfo the current packet row
 301  * @param col the column to use, e.g. COL_INFO
 302  * @param sep the separator string or NULL for default: ", "
 303  * @param str the string to append
 304  */
 305 WS_DLL_PUBLIC void col_append_sep_str(column_info *cinfo, const int col, const char *sep,
 306                 const char *str);
 307
 308 /** Append the given text (prepended by a separator) to a column element.
 309  *
 310  * Unprintable characters according to g_ascii_isprint() are escaped.
 311  *
 312  * Much like col_append_fstr() but will prepend the given separator if the column isn't empty.
 313  *
 314  * @param cinfo the current packet row
 315  * @param col the column to use, e.g. COL_INFO
 316  * @param sep the separator string or NULL for default: ", "
 317  * @param format the format string
 318  * @param ... the variable number of parameters
 319  */
 320 WS_DLL_PUBLIC void col_append_sep_fstr(column_info *cinfo, const int col, const char *sep,
 321                 const char *format, ...)
 322     G_GNUC_PRINTF(4, 5);
 323
 324 /** Set the given (relative) time to a column element.
 325  *
 326  * Used by dissectors to set the time in a column
 327  *
 328  * @param cinfo         the current packet row
 329  * @param col           the column to use, e.g. COL_INFO
 330  * @param ts            the time to set in the column
 331  * @param fieldname     the fieldname to use for creating a filter (when
 332  *                        applying/preparing/copying as filter)
 333  */
 334 WS_DLL_PUBLIC void col_set_time(column_info *cinfo, const int col,
 335                         const nstime_t *ts, const char *fieldname);
 336
 337 WS_DLL_PUBLIC void set_fd_time(const struct epan_session *epan, frame_data *fd, char *buf);
 338
 339 #ifdef __cplusplus
 340 }
 341 #endif /* __cplusplus */
 342
 343 #endif /* __COLUMN_UTILS_H__ */