2 * Definitions for column utility structures and routines
4 * Wireshark - Network traffic analyzer
5 * By Gerald Combs <gerald@wireshark.org>
6 * Copyright 1998 Gerald Combs
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.
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.
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.
23 #ifndef __COLUMN_UTILS_H__
24 #define __COLUMN_UTILS_H__
28 #include "packet_info.h"
29 #include "ws_symbol_export.h"
33 #endif /* __cplusplus */
38 * Helper routines for column utility structures and routines.
41 struct epan_column_info;
42 typedef struct epan_column_info column_info;
45 * All of the possible columns in summary listing.
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!
50 * NOTE2: Please add the COL_XYZ entry in the appropriate spot, such that the
51 * dlist[] array remains in alphabetical order!
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 */
107 /** Allocate all the data structures for constructing column data, given
108 * the number of columns.
110 * Internal, don't use this in dissectors!
112 WS_DLL_PUBLIC void col_setup(column_info *cinfo, const gint num_cols);
114 /** Cleanup all the data structures for constructing column data;
115 * undoes the alocations that col_setup() does.
117 * Internal, don't use this in dissectors!
119 WS_DLL_PUBLIC void col_cleanup(column_info *cinfo);
121 /** Initialize the data structures for constructing column data.
123 * Internal, don't use this in dissectors!
125 extern void col_init(column_info *cinfo, const struct epan_session *epan);
127 /** Fill in all columns of the given packet which are based on values from frame_data.
129 * Internal, don't use this in dissectors!
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);
133 /** Fill in all columns of the given packet.
135 * Internal, don't use this in dissectors!
137 WS_DLL_PUBLIC void col_fill_in(packet_info *pinfo, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
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
143 * Internal, don't use this in dissectors!
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);
147 /* Utility routines used by packet*.c */
149 /** Are the columns writable?
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
155 WS_DLL_PUBLIC gboolean col_get_writable(column_info *cinfo, const gint col);
157 /** Set the columns writable.
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
163 WS_DLL_PUBLIC void col_set_writable(column_info *cinfo, const gint col, const gboolean writable);
165 /** Sets a fence for the current column content,
166 * so this content won't be affected by further col_... function calls.
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.
171 * @param cinfo the current packet row
172 * @param col the column to use, e.g. COL_INFO
174 WS_DLL_PUBLIC void col_set_fence(column_info *cinfo, const gint col);
176 /** Clears a fence for the current column content
178 * This can be useful if a protocol wants to remove whatever
179 * a previous protocol has added to the column.
181 * @param cinfo the current packet row
182 * @param col the column to use, e.g. COL_INFO
184 WS_DLL_PUBLIC void col_clear_fence(column_info *cinfo, const gint col);
186 /** Gets the text of a column element.
188 * @param cinfo the current packet row
189 * @param col the column to use, e.g. COL_INFO
191 * @return the text string
193 WS_DLL_PUBLIC const gchar *col_get_text(column_info *cinfo, const gint col);
195 /** Clears the text of a column element.
197 * @param cinfo the current packet row
198 * @param col the column to use, e.g. COL_INFO
200 WS_DLL_PUBLIC void col_clear(column_info *cinfo, const gint col);
202 /** Set (replace) the text of a column element, the text won't be copied.
204 * Usually used to set const strings!
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
210 WS_DLL_PUBLIC void col_set_str(column_info *cinfo, const gint col, const gchar * str);
212 /** Add (replace) the text of a column element, the text will be copied.
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
218 WS_DLL_PUBLIC void col_add_str(column_info *cinfo, const gint col, const gchar *str);
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, ...);
224 /** Add (replace) the text of a column element, the text will be formatted and copied.
226 * Same function as col_add_str() but using a printf-like format string.
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
233 WS_DLL_PUBLIC void col_add_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
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);
239 /** For internal Wireshark use only. Not to be called from dissectors. */
241 void col_custom_prime_edt(struct epan_dissect *edt, column_info *cinfo);
243 /** For internal Wireshark use only. Not to be called from dissectors. */
245 gboolean have_custom_cols(column_info *cinfo);
247 /** For internal Wireshark use only. Not to be called from dissectors. */
249 gboolean have_field_extractors(void);
251 /** For internal Wireshark use only. Not to be called from dissectors. */
253 gboolean col_has_time_fmt(column_info *cinfo, const gint col);
254 /** For internal Wireshark use only. Not to be called from dissectors. */
256 gboolean col_based_on_frame_data(column_info *cinfo, const gint col);
258 /** Append the given text to a column element, the text will be copied.
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
264 WS_DLL_PUBLIC void col_append_str(column_info *cinfo, const gint col, const gchar *str);
266 /** Append <abbrev>=<val> to a column element, the text will be copied.
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
274 WS_DLL_PUBLIC void col_append_str_uint(column_info *cinfo, const gint col, const gchar *abbrev, guint32 val, const gchar *sep);
276 /** Append a transport port pair to a column element, the text will be copied.
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
284 WS_DLL_PUBLIC void col_append_ports(column_info *cinfo, const gint col, port_type typ, guint16 src, guint16 dst);
286 /* Append the given strings (terminated by COL_ADD_LSTR_TERMINATOR) to a column element,
288 * Same result as col_append_str() called for every string element.
290 WS_DLL_PUBLIC void col_append_lstr(column_info *cinfo, const gint el, const gchar *str, ...);
292 /** Append the given text to a column element, the text will be formatted and copied.
294 * Same function as col_append_str() but using a printf-like format string.
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
301 WS_DLL_PUBLIC void col_append_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
304 /** Prepend the given text to a column element, the text will be formatted and copied.
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
311 WS_DLL_PUBLIC void col_prepend_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
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.
322 WS_DLL_PUBLIC void col_prepend_fence_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
325 /** Append the given text (prepended by a separator) to a column element.
327 * Much like col_append_str() but will prepend the given separator if the column isn't empty.
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
334 WS_DLL_PUBLIC void col_append_sep_str(column_info *cinfo, const gint col, const gchar *sep,
337 /** Append the given text (prepended by a separator) to a column element.
339 * Much like col_append_fstr() but will prepend the given separator if the column isn't empty.
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
347 WS_DLL_PUBLIC void col_append_sep_fstr(column_info *cinfo, const gint col, const gchar *sep,
348 const gchar *format, ...)
351 /** Set the given (relative) time to a column element.
353 * Used by dissectors to set the time in a column
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)
361 WS_DLL_PUBLIC void col_set_time(column_info *cinfo, const int col,
362 const nstime_t *ts, const char *fieldname);
364 WS_DLL_PUBLIC void set_fd_time(const struct epan_session *epan, frame_data *fd, gchar *buf);
368 #endif /* __cplusplus */
370 #endif /* __COLUMN_UTILS_H__ */