epan/column-utils.h

   1 /* column-utils.h
   2  * Definitions for column utility structures and routines
   3  *
   4  * $Id$
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public License
  12  * as published by the Free Software Foundation; either version 2
  13  * of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  23  */
  24
  25 #ifndef __COLUMN_UTILS_H__
  26 #define __COLUMN_UTILS_H__
  27
  28 #include <glib.h>
  29
  30 #include "column_info.h"
  31 #include "packet_info.h"
  32 #include <epan/epan.h>
  33 #include "ws_symbol_export.h"
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif /* __cplusplus */
  38
  39 /** @file
  40  *  Helper routines for column utility structures and routines.
  41  */
  42
  43 /** Allocate all the data structures for constructing column data, given
  44  * the number of columns.
  45  *
  46  * Internal, don't use this in dissectors!
  47  */
  48 WS_DLL_PUBLIC void      col_setup(column_info *cinfo, const gint num_cols);
  49
  50 /** Cleanup all the data structures for constructing column data;
  51  * undoes the alocations that col_setup() does.
  52  *
  53  * Internal, don't use this in dissectors!
  54  */
  55 WS_DLL_PUBLIC void      col_cleanup(column_info *cinfo);
  56
  57 /** Initialize the data structures for constructing column data.
  58  *
  59  * Internal, don't use this in dissectors!
  60  */
  61 extern void     col_init(column_info *cinfo, const struct epan_session *epan);
  62
  63 /** Fill in all columns of the given packet which are based on values from frame_data.
  64  *
  65  * Internal, don't use this in dissectors!
  66  */
  67 WS_DLL_PUBLIC void col_fill_in_frame_data(const frame_data *fd, column_info *cinfo, const gint col, gboolean const fill_col_exprs);
  68
  69 /** Fill in all columns of the given packet.
  70  *
  71  * Internal, don't use this in dissectors!
  72  */
  73 WS_DLL_PUBLIC void      col_fill_in(packet_info *pinfo, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
  74
  75 /** Fill in columns if we got an error reading the packet.
  76  * We set most columns to "???", and set the Info column to an error
  77  * message.
  78  *
  79  * Internal, don't use this in dissectors!
  80  */
  81 WS_DLL_PUBLIC void      col_fill_in_error(column_info *cinfo, frame_data *fdata, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
  82
  83 /* Utility routines used by packet*.c */
  84
  85 /** Are the columns writable?
  86  *
  87  * @param cinfo the current packet row
  88  * @return TRUE if it's writable, FALSE if not
  89  */
  90 WS_DLL_PUBLIC gboolean  col_get_writable(column_info *cinfo);
  91
  92 /** Set the columns writable.
  93  *
  94  * @param cinfo the current packet row
  95  * @param writable TRUE if it's writable, FALSE if not
  96  */
  97 WS_DLL_PUBLIC void      col_set_writable(column_info *cinfo, const gboolean writable);
  98
  99 /**
 100  * Checks if the given column can be filled with data.
 101  *
 102  * @param cinfo the current packet row
 103  * @param col the column to use, e.g. COL_INFO
 104  *
 105  * @deprecated Not needed in new code the check is done in
 106  * in the column function calls.
 107  */
 108 WS_DLL_PUBLIC gint      check_col(column_info *cinfo, const gint col);
 109
 110 /** Sets a fence for the current column content,
 111  * so this content won't be affected by further col_... function calls.
 112  *
 113  * This can be useful if a protocol is more than once in a single packet,
 114  * e.g. multiple HTTP calls in a single TCP packet.
 115  *
 116  * @param cinfo the current packet row
 117  * @param col the column to use, e.g. COL_INFO
 118  */
 119 WS_DLL_PUBLIC void      col_set_fence(column_info *cinfo, const gint col);
 120
 121 /** Gets the text of a column element.
 122  *
 123  * @param cinfo the current packet row
 124  * @param col the column to use, e.g. COL_INFO
 125  *
 126  * @return the text string
 127  */
 128 extern const gchar *col_get_text(column_info *cinfo, const gint col);
 129
 130 /** Clears the text of a column element.
 131  *
 132  * @param cinfo the current packet row
 133  * @param col the column to use, e.g. COL_INFO
 134  */
 135 WS_DLL_PUBLIC void      col_clear(column_info *cinfo, const gint col);
 136
 137 /** Set (replace) the text of a column element, the text won't be copied.
 138  *
 139  * Usually used to set const strings!
 140  *
 141  * @param cinfo the current packet row
 142  * @param col the column to use, e.g. COL_INFO
 143  * @param str the string to set
 144  */
 145 WS_DLL_PUBLIC void      col_set_str(column_info *cinfo, const gint col, const gchar * str);
 146
 147 /** Add (replace) the text of a column element, the text will be copied.
 148  *
 149  * @param cinfo the current packet row
 150  * @param col the column to use, e.g. COL_INFO
 151  * @param str the string to add
 152  */
 153 WS_DLL_PUBLIC void      col_add_str(column_info *cinfo, const gint col, const gchar *str);
 154
 155 /** Add (replace) the text of a column element, the text will be formatted and copied.
 156  *
 157  * Same function as col_add_str() but using a printf-like format string.
 158  *
 159  * @param cinfo the current packet row
 160  * @param col the column to use, e.g. COL_INFO
 161  * @param format the format string
 162  * @param ... the variable number of parameters
 163  */
 164 WS_DLL_PUBLIC void      col_add_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 165     G_GNUC_PRINTF(3, 4);
 166
 167 /** For internal Wireshark use only.  Not to be called from dissectors. */
 168 void col_custom_set_edt(epan_dissect_t *edt, column_info *cinfo);
 169
 170 /** For internal Wireshark use only.  Not to be called from dissectors. */
 171 WS_DLL_PUBLIC
 172 void col_custom_prime_edt(epan_dissect_t *edt, column_info *cinfo);
 173
 174 /** For internal Wireshark use only.  Not to be called from dissectors. */
 175 WS_DLL_PUBLIC
 176 gboolean have_custom_cols(column_info *cinfo);
 177 /** For internal Wireshark use only.  Not to be called from dissectors. */
 178 WS_DLL_PUBLIC
 179 gboolean col_has_time_fmt(column_info *cinfo, const gint col);
 180 /** For internal Wireshark use only.  Not to be called from dissectors. */
 181 WS_DLL_PUBLIC
 182 gboolean col_based_on_frame_data(column_info *cinfo, const gint col);
 183
 184 /** Append the given text to a column element, the text will be copied.
 185  *
 186  * @param cinfo the current packet row
 187  * @param col the column to use, e.g. COL_INFO
 188  * @param str the string to append
 189  */
 190 WS_DLL_PUBLIC void      col_append_str(column_info *cinfo, const gint col, const gchar *str);
 191
 192 /** Append the given text to a column element, the text will be formatted and copied.
 193  *
 194  * Same function as col_append_str() but using a printf-like format string.
 195  *
 196  * @param cinfo the current packet row
 197  * @param col the column to use, e.g. COL_INFO
 198  * @param format the format string
 199  * @param ... the variable number of parameters
 200  */
 201 WS_DLL_PUBLIC void      col_append_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 202     G_GNUC_PRINTF(3, 4);
 203
 204 /** Prepend the given text to a column element, the text will be formatted and copied.
 205  *
 206  * @param cinfo the current packet row
 207  * @param col the column to use, e.g. COL_INFO
 208  * @param format the format string
 209  * @param ... the variable number of parameters
 210  */
 211 WS_DLL_PUBLIC void      col_prepend_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 212     G_GNUC_PRINTF(3, 4);
 213
 214 /**Prepend the given text to a column element, the text will be formatted and copied.
 215  * This function is similar to col_prepend_fstr() but this function will
 216  * unconditionally set a fence to the end of the prepended data even if there
 217  * were no fence before.
 218  * The col_prepend_fstr() will only prepend the data before the fence IF
 219  * there is already a fence created. This function will create a fence in case
 220  * it does not yet exist.
 221  */
 222 WS_DLL_PUBLIC void      col_prepend_fence_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 223     G_GNUC_PRINTF(3, 4);
 224
 225 /** Append the given text (prepended by a separator) to a column element.
 226  *
 227  * Much like col_append_str() but will prepend the given separator if the column isn't empty.
 228  *
 229  * @param cinfo the current packet row
 230  * @param col the column to use, e.g. COL_INFO
 231  * @param sep the separator string or NULL for default: ", "
 232  * @param str the string to append
 233  */
 234 WS_DLL_PUBLIC void      col_append_sep_str(column_info *cinfo, const gint col, const gchar *sep,
 235                 const gchar *str);
 236
 237 /** Append the given text (prepended by a separator) to a column element.
 238  *
 239  * Much like col_append_fstr() but will prepend the given separator if the column isn't empty.
 240  *
 241  * @param cinfo the current packet row
 242  * @param col the column to use, e.g. COL_INFO
 243  * @param sep the separator string or NULL for default: ", "
 244  * @param format the format string
 245  * @param ... the variable number of parameters
 246  */
 247 WS_DLL_PUBLIC void      col_append_sep_fstr(column_info *cinfo, const gint col, const gchar *sep,
 248                 const gchar *format, ...)
 249     G_GNUC_PRINTF(4, 5);
 250
 251 /** Set the given (relative) time to a column element.
 252  *
 253  * Used by multiple dissectors to set the time in the column
 254  * COL_DELTA_CONV_TIME
 255  *
 256  * @param cinfo         the current packet row
 257  * @param col           the column to use, e.g. COL_INFO
 258  * @param ts            the time to set in the column
 259  * @param fieldname     the fieldname to use for creating a filter (when
 260  *                        applying/preparing/copying as filter)
 261  */
 262 WS_DLL_PUBLIC void      col_set_time(column_info *cinfo, const int col,
 263                         const nstime_t *ts, const char *fieldname);
 264
 265 WS_DLL_PUBLIC void set_fd_time(const struct epan_session *epan, frame_data *fd, gchar *buf);
 266
 267 #ifdef __cplusplus
 268 }
 269 #endif /* __cplusplus */
 270
 271 #endif /* __COLUMN_UTILS_H__ */