column-utils.h File Reference

#include "packet_info.h"
#include "ws_symbol_export.h"

Go to the source code of this file.

Macros
#define	COL_MAX_LEN   2048
#define	COL_MAX_INFO_LEN   4096
#define	COL_CUSTOM_PRIME_REGEX   "(?:^ *| *\\|\\| *| +or +| *$)(?![^(]*\\‍))"
#define	COL_ADD_LSTR_TERMINATOR   (const char *) -1

Typedefs
typedef struct epan_column_info	column_info

Enumerations
enum	{   COL_ABS_YMD_TIME , COL_ABS_YDOY_TIME , COL_ABS_TIME , COL_CUMULATIVE_BYTES ,   COL_CUSTOM , COL_DELTA_TIME , COL_DELTA_TIME_DIS , COL_RES_DST ,   COL_UNRES_DST , COL_RES_DST_PORT , COL_UNRES_DST_PORT , COL_DEF_DST ,   COL_DEF_DST_PORT , COL_EXPERT , COL_IF_DIR , COL_FREQ_CHAN ,   COL_DEF_DL_DST , COL_DEF_DL_SRC , COL_RES_DL_DST , COL_UNRES_DL_DST ,   COL_RES_DL_SRC , COL_UNRES_DL_SRC , COL_RSSI , COL_TX_RATE ,   COL_DSCP_VALUE , COL_INFO , COL_RES_NET_DST , COL_UNRES_NET_DST ,   COL_RES_NET_SRC , COL_UNRES_NET_SRC , COL_DEF_NET_DST , COL_DEF_NET_SRC ,   COL_NUMBER , COL_NUMBER_DIS , COL_PACKET_LENGTH , COL_PROTOCOL ,   COL_REL_TIME , COL_REL_CAP_TIME , COL_DEF_SRC , COL_DEF_SRC_PORT ,   COL_RES_SRC , COL_UNRES_SRC , COL_RES_SRC_PORT , COL_UNRES_SRC_PORT ,   COL_UTC_YMD_TIME , COL_UTC_YDOY_TIME , COL_UTC_TIME , COL_CLS_TIME ,   COL_USER_NAME , NUM_COL_FMTS }

Functions
WS_DLL_PUBLIC bool	col_get_writable (column_info *cinfo, const int col)
	Check if a column is writable.
WS_DLL_PUBLIC void	col_set_writable (column_info *cinfo, const int col, const bool writable)
	Set writability for either all columns or a specific column.
WS_DLL_PUBLIC void	col_set_fence (column_info *cinfo, const int col)
	Sets a fence for the current column content, so this content won't be affected by further col_... function calls.
WS_DLL_PUBLIC void	col_clear_fence (column_info *cinfo, const int col)
	Clears a fence for the current column content.
WS_DLL_PUBLIC const char *	col_get_text (column_info *cinfo, const int col)
	Gets the text of a column element.
WS_DLL_PUBLIC void	col_clear (column_info *cinfo, const int col)
	Clears the text of a column element.
WS_DLL_PUBLIC void	col_set_str (column_info *cinfo, const int col, const char *str)
	Set (replace) the text of a column element, the text won't be formatted or copied.
WS_DLL_PUBLIC void	col_add_str (column_info *cinfo, const int col, const char *str)
	Add (replace) the text of a column element, the text will be formatted and copied.
WS_DLL_PUBLIC void	col_add_lstr (column_info *cinfo, const int el, const char *str,...)
	Add (replace) the text of a column element using a printf-like format string.
WS_DLL_PUBLIC void	col_add_fstr (column_info *cinfo, const int col, const char *format,...)
	Add (replace) the text of a column element, the text will be formatted and copied.
WS_DLL_PUBLIC void	col_append_str (column_info *cinfo, const int col, const char *str)
	Append the given text to a column element, the text will be formatted and copied.
WS_DLL_PUBLIC void	col_append_str_uint (column_info *cinfo, const int col, const char *abbrev, uint32_t val, const char *sep)
	Append <abbrev>=<val> to a column element, the text will be copied.
WS_DLL_PUBLIC void	col_append_ports (column_info *cinfo, const int col, port_type typ, uint16_t src, uint16_t dst)
	Append a transport port pair to a column element, the text will be copied.
WS_DLL_PUBLIC void	col_append_frame_number (packet_info *pinfo, const int col, const char *fmt_str, unsigned frame_num)
	Append a frame number and signal that we have updated column information.
WS_DLL_PUBLIC void	col_append_lstr (column_info *cinfo, const int el, const char *str,...)
	Append the given strings (terminated by COL_ADD_LSTR_TERMINATOR) to a column element,.
WS_DLL_PUBLIC void	col_append_fstr (column_info *cinfo, const int col, const char *format,...)
	Append the given text to a column element, the text will be formatted and copied.
WS_DLL_PUBLIC void	col_prepend_fstr (column_info *cinfo, const int col, const char *format,...)
	Prepend the given text to a column element, the text will be formatted and copied.
WS_DLL_PUBLIC void	col_prepend_fence_fstr (column_info *cinfo, const int col, const char *format,...)
	Prepend the given text to a column element, the text will be formatted and copied.
WS_DLL_PUBLIC void	col_append_sep_str (column_info *cinfo, const int col, const char *sep, const char *str)
	Append the given text (prepended by a separator) to a column element.
WS_DLL_PUBLIC void	col_append_sep_fstr (column_info *cinfo, const int col, const char *sep, const char *format,...)
	Append the given text (prepended by a separator) to a column element.
WS_DLL_PUBLIC void	col_set_time (column_info *cinfo, const int col, const nstime_t *ts, const char *fieldname)
	Set the given (relative) time to a column element.
WS_DLL_PUBLIC void	set_fd_time (const struct epan_session *epan, frame_data *fd, char *buf)
	Set the time for a frame data structure.

Detailed Description

Definitions for column utility structures and routines Utility routines used by packet*.c

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Enumeration Type Documentation

anonymous enum

anonymous enum

All of the possible columns in summary listing.

NOTE1: The entries MUST remain in this order, or else you need to reorder the slist[] and dlist[] arrays in column.c to match!

NOTE2: Please add the COL_XYZ entry in the appropriate spot, such that the dlist[] array remains in alphabetical order!

Enumerator
COL_ABS_YMD_TIME	0) Absolute date, as YYYY-MM-DD, and time
COL_ABS_YDOY_TIME	1) Absolute date, as YYYY/DOY, and time
COL_ABS_TIME	2) Absolute time
COL_CUMULATIVE_BYTES	3) Cumulative number of bytes
COL_CUSTOM	4) Custom column (any filter name's contents)
COL_DELTA_TIME	5) Delta time
COL_DELTA_TIME_DIS	6) Delta time displayed
COL_RES_DST	7) Resolved dest
COL_UNRES_DST	8) Unresolved dest
COL_RES_DST_PORT	9) Resolved dest port
COL_UNRES_DST_PORT	10) Unresolved dest port
COL_DEF_DST	11) Destination address
COL_DEF_DST_PORT	12) Destination port
COL_EXPERT	13) Expert Info
COL_IF_DIR	14) FW-1 monitor interface/direction
COL_FREQ_CHAN	15) IEEE 802.11 (and WiMax?) - Channel
COL_DEF_DL_DST	16) Data link layer dest address
COL_DEF_DL_SRC	17) Data link layer source address
COL_RES_DL_DST	18) Resolved DL dest
COL_UNRES_DL_DST	19) Unresolved DL dest
COL_RES_DL_SRC	20) Resolved DL source
COL_UNRES_DL_SRC	21) Unresolved DL source
COL_RSSI	22) IEEE 802.11 - received signal strength
COL_TX_RATE	23) IEEE 802.11 - TX rate in Mbps
COL_DSCP_VALUE	24) IP DSCP Value
COL_INFO	25) Description
COL_RES_NET_DST	26) Resolved net dest
COL_UNRES_NET_DST	27) Unresolved net dest
COL_RES_NET_SRC	28) Resolved net source
COL_UNRES_NET_SRC	29) Unresolved net source
COL_DEF_NET_DST	30) Network layer dest address
COL_DEF_NET_SRC	31) Network layer source address
COL_NUMBER	32) Packet list item number
COL_NUMBER_DIS	33) Packet list item number displayed
COL_PACKET_LENGTH	34) Packet length in bytes
COL_PROTOCOL	35) Protocol
COL_REL_TIME	36) Relative time
COL_REL_CAP_TIME	37) Relative time to capture start
COL_DEF_SRC	38) Source address
COL_DEF_SRC_PORT	39) Source port
COL_RES_SRC	40) Resolved source
COL_UNRES_SRC	41) Unresolved source
COL_RES_SRC_PORT	42) Resolved source port
COL_UNRES_SRC_PORT	43) Unresolved source port
COL_UTC_YMD_TIME	44) UTC date, as YYYY-MM-DD, and time
COL_UTC_YDOY_TIME	45) UTC date, as YYYY/DOY, and time
COL_UTC_TIME	46) UTC time
COL_CLS_TIME	47) Command line-specified time (default relative)
COL_USER_NAME	48) User name
NUM_COL_FMTS	49) Should always be last

Function Documentation

col_add_fstr()

WS_DLL_PUBLIC void col_add_fstr	(	column_info *	cinfo,
		const int	col,
		const char *	format,
			...
	)

Add (replace) the text of a column element, the text will be formatted and copied.

Unprintable characters according to g_ascii_isprint() are escaped.

Same function as col_add_str() but using a printf-like format string.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
format	the format string
...	the variable number of parameters

col_add_lstr()

WS_DLL_PUBLIC void col_add_lstr	(	column_info *	cinfo,
		const int	el,
		const char *	str,
			...
	)

Add (replace) the text of a column element using a printf-like format string.

Parameters

cinfo	Pointer to the column information structure.
el	Column element index.
str	Format string followed by variable arguments.

col_add_str()

WS_DLL_PUBLIC void col_add_str	(	column_info *	cinfo,
		const int	col,
		const char *	str
	)

Add (replace) the text of a column element, the text will be formatted and copied.

Unprintable characters according to g_ascii_isprint() are escaped.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
str	the string to add

col_append_frame_number()

WS_DLL_PUBLIC void col_append_frame_number	(	packet_info *	pinfo,
		const int	col,
		const char *	fmt_str,
		unsigned	frame_num
	)

Append a frame number and signal that we have updated column information.

Parameters

pinfo	the current packet info
col	the column to use, e.g. COL_INFO
fmt_str	format string, e.g. "reassembled in %u".
frame_num	frame number

col_append_fstr()

WS_DLL_PUBLIC void col_append_fstr	(	column_info *	cinfo,
		const int	col,
		const char *	format,
			...
	)

Append the given text to a column element, the text will be formatted and copied.

Unprintable characters according to g_ascii_isprint() are escaped.

Same function as col_append_str() but using a printf-like format string.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
format	the format string
...	the variable number of parameters

col_append_lstr()

WS_DLL_PUBLIC void col_append_lstr	(	column_info *	cinfo,
		const int	el,
		const char *	str,
			...
	)

Append the given strings (terminated by COL_ADD_LSTR_TERMINATOR) to a column element,.

Same result as col_append_str() called for every string element.

col_append_ports()

WS_DLL_PUBLIC void col_append_ports	(	column_info *	cinfo,
		const int	col,
		port_type	typ,
		uint16_t	src,
		uint16_t	dst
	)

Append a transport port pair to a column element, the text will be copied.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
typ	the port type to resolve, e.g. PT_UDP
src	the source port value to append
dst	the destination port value to append

col_append_sep_fstr()

WS_DLL_PUBLIC void col_append_sep_fstr	(	column_info *	cinfo,
		const int	col,
		const char *	sep,
		const char *	format,
			...
	)

Append the given text (prepended by a separator) to a column element.

Unprintable characters according to g_ascii_isprint() are escaped.

Much like col_append_fstr() but will prepend the given separator if the column isn't empty.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
sep	the separator string or NULL for default: ", "
format	the format string
...	the variable number of parameters

col_append_sep_str()

WS_DLL_PUBLIC void col_append_sep_str	(	column_info *	cinfo,
		const int	col,
		const char *	sep,
		const char *	str
	)

Append the given text (prepended by a separator) to a column element.

Unprintable characters according to g_ascii_isprint() are escaped.

Much like col_append_str() but will prepend the given separator if the column isn't empty.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
sep	the separator string or NULL for default: ", "
str	the string to append

col_append_str()

WS_DLL_PUBLIC void col_append_str	(	column_info *	cinfo,
		const int	col,
		const char *	str
	)

Append the given text to a column element, the text will be formatted and copied.

Unprintable characters according to g_ascii_isprint() are escaped.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
str	the string to append

col_append_str_uint()

WS_DLL_PUBLIC void col_append_str_uint	(	column_info *	cinfo,
		const int	col,
		const char *	abbrev,
		uint32_t	val,
		const char *	sep
	)

Append <abbrev>=<val> to a column element, the text will be copied.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
abbrev	the string to append
val	the value to append
sep	an optional separator to prepend to abbrev

col_clear()

WS_DLL_PUBLIC void col_clear	(	column_info *	cinfo,
		const int	col
	)

Clears the text of a column element.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO

col_clear_fence()

WS_DLL_PUBLIC void col_clear_fence	(	column_info *	cinfo,
		const int	col
	)

Clears a fence for the current column content.

This can be useful if a protocol wants to remove whatever a previous protocol has added to the column.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO

col_get_text()

WS_DLL_PUBLIC const char * col_get_text	(	column_info *	cinfo,
		const int	col
	)

Gets the text of a column element.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO

Returns

the text string

col_get_writable()

WS_DLL_PUBLIC bool col_get_writable	(	column_info *	cinfo,
		const int	col
	)

Check if a column is writable.

Parameters

cinfo	the current packet row
col	the writable column, -1 for checking the state of all columns

Returns

true if it's writable, false if not

col_prepend_fence_fstr()

WS_DLL_PUBLIC void col_prepend_fence_fstr	(	column_info *	cinfo,
		const int	col,
		const char *	format,
			...
	)

Prepend the given text to a column element, the text will be formatted and copied.

Unprintable characters according to g_ascii_isprint() are escaped.

This function is similar to col_prepend_fstr() but this function will unconditionally set a fence to the end of the prepended data even if there were no fence before. The col_prepend_fstr() will only prepend the data before the fence IF there is already a fence created. This function will create a fence in case it does not yet exist.

col_prepend_fstr()

WS_DLL_PUBLIC void col_prepend_fstr	(	column_info *	cinfo,
		const int	col,
		const char *	format,
			...
	)

Prepend the given text to a column element, the text will be formatted and copied.

Unprintable characters according to g_ascii_isprint() are escaped.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
format	the format string
...	the variable number of parameters

col_set_fence()

WS_DLL_PUBLIC void col_set_fence	(	column_info *	cinfo,
		const int	col
	)

Sets a fence for the current column content, so this content won't be affected by further col_... function calls.

This can be useful if a protocol is more than once in a single packet, e.g. multiple HTTP calls in a single TCP packet.

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO

col_set_str()

WS_DLL_PUBLIC void col_set_str	(	column_info *	cinfo,
		const int	col,
		const char *	str
	)

Set (replace) the text of a column element, the text won't be formatted or copied.

Use this for simple static strings like protocol names. Don't use for untrusted strings, strings that may contain unprintable characters, or strings which are freed before the packet_info (and hence column_info) struct.

Usually used to set const strings!

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
str	the string to set

col_set_time()

WS_DLL_PUBLIC void col_set_time	(	column_info *	cinfo,
		const int	col,
		const nstime_t *	ts,
		const char *	fieldname
	)

Set the given (relative) time to a column element.

Used by dissectors to set the time in a column

Parameters

cinfo	the current packet row
col	the column to use, e.g. COL_INFO
ts	the time to set in the column
fieldname	the fieldname to use for creating a filter (when applying/preparing/copying as filter)

Todo:

TODO: We don't respect fd->ref_time (no way to access 'fd') COL_CHECK_REF_TIME(fd, buf);

col_set_writable()

WS_DLL_PUBLIC void col_set_writable	(	column_info *	cinfo,
		const int	col,
		const bool	writable
	)

Set writability for either all columns or a specific column.

Parameters

cinfo	the current packet row
col	the column to set, -1 for all
writable	true to be writable, false to not be writable

set_fd_time()

WS_DLL_PUBLIC void set_fd_time	(	const struct epan_session *	epan,
		frame_data *	fd,
		char *	buf
	)

Set the time for a frame data structure.

Parameters

epan	The current epan session.
fd	The frame data structure to set the time for.
buf	Buffer containing the time string.