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