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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, 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
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif /* __cplusplus */
  37
  38 /** @file
  39  *  Helper routines for column utility structures and routines.
  40  */
  41
  42 /** Allocate all the data structures for constructing column data, given
  43  * the number of columns.
  44  *
  45  * Internal, don't use this in dissectors!
  46  */
  47 extern void     col_setup(column_info *cinfo, const gint num_cols);
  48
  49 /** Initialize the data structures for constructing column data.
  50  *
  51  * Internal, don't use this in dissectors!
  52  */
  53 extern void     col_init(column_info *cinfo);
  54
  55 /** Set the format of the "variable time format".
  56  *
  57  * Internal, don't use this in dissectors!
  58  */
  59 extern void     col_set_fmt_time(const frame_data *fd, column_info *cinfo, const gint fmt, const gint col);
  60
  61 /** Fill in all columns of the given packet which are based on values from frame_data.
  62  *
  63  * Internal, don't use this in dissectors!
  64  */
  65 extern void col_fill_in_frame_data(const frame_data *fd, column_info *cinfo, const gint col, gboolean const fill_col_exprs);
  66
  67 /** Fill in all columns of the given packet.
  68  *
  69  * Internal, don't use this in dissectors!
  70  */
  71 extern void     col_fill_in(packet_info *pinfo, const gboolean fill_col_exprs, const gboolean fill_fd_colums);
  72
  73 /* Utility routines used by packet*.c */
  74
  75 /** Are the columns writable?
  76  *
  77  * @param cinfo the current packet row
  78  * @return TRUE if it's writable, FALSE if not
  79  */
  80 extern gboolean col_get_writable(column_info *cinfo);
  81
  82 /** Set the columns writable.
  83  *
  84  * @param cinfo the current packet row
  85  * @param writable TRUE if it's writable, FALSE if not
  86  */
  87 extern void     col_set_writable(column_info *cinfo, const gboolean writable);
  88
  89 /**
  90  * Checks if the given column can be filled with data.
  91  *
  92  * @param cinfo the current packet row
  93  * @param col the column to use, e.g. COL_INFO
  94  *
  95  * @deprecated Not needed in new code the check is done in
  96  * in the column function calls.
  97  */
  98 extern gint     check_col(column_info *cinfo, const gint col);
  99
 100 /** Sets a fence for the current column content,
 101  * so this content won't be affected by further col_... function calls.
 102  *
 103  * This can be useful if a protocol is more than once in a single packet,
 104  * e.g. multiple HTTP calls in a single TCP packet.
 105  *
 106  * @param cinfo the current packet row
 107  * @param col the column to use, e.g. COL_INFO
 108  */
 109 extern void     col_set_fence(column_info *cinfo, const gint col);
 110
 111 /** Clears the text of a column element.
 112  *
 113  * @param cinfo the current packet row
 114  * @param col the column to use, e.g. COL_INFO
 115  */
 116 extern void     col_clear(column_info *cinfo, const gint col);
 117
 118 /** Set (replace) the text of a column element, the text won't be copied.
 119  *
 120  * Usually used to set const strings!
 121  *
 122  * @param cinfo the current packet row
 123  * @param col the column to use, e.g. COL_INFO
 124  * @param str the string to set
 125  */
 126 extern void     col_set_str(column_info *cinfo, const gint col, const gchar * str);
 127
 128 /** Add (replace) the text of a column element, the text will be copied.
 129  *
 130  * @param cinfo the current packet row
 131  * @param col the column to use, e.g. COL_INFO
 132  * @param str the string to add
 133  */
 134 extern void     col_add_str(column_info *cinfo, const gint col, const gchar *str);
 135
 136 /** Add (replace) the text of a column element, the text will be formatted and copied.
 137  *
 138  * Same function as col_add_str() but using a printf-like format string.
 139  *
 140  * @param cinfo the current packet row
 141  * @param col the column to use, e.g. COL_INFO
 142  * @param format the format string
 143  * @param ... the variable number of parameters
 144  */
 145 extern void     col_add_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 146     G_GNUC_PRINTF(3, 4);
 147
 148 /** For internal Wireshark use only.  Not to be called from dissectors. */
 149 void col_custom_set_edt(epan_dissect_t *edt, column_info *cinfo);
 150
 151 /** For internal Wireshark use only.  Not to be called from dissectors. */
 152 void col_custom_prime_edt(epan_dissect_t *edt, column_info *cinfo);
 153
 154 /** For internal Wireshark use only.  Not to be called from dissectors. */
 155 gboolean have_custom_cols(column_info *cinfo);
 156 /** For internal Wireshark use only.  Not to be called from dissectors. */
 157 gboolean col_has_time_fmt(column_info *cinfo, const gint col);
 158 /** For internal Wireshark use only.  Not to be called from dissectors. */
 159 gboolean col_based_on_frame_data(column_info *cinfo, const gint col);
 160
 161 /** Append the given text to a column element, the text will be copied.
 162  *
 163  * @param cinfo the current packet row
 164  * @param col the column to use, e.g. COL_INFO
 165  * @param str the string to append
 166  */
 167 extern void     col_append_str(column_info *cinfo, const gint col, const gchar *str);
 168
 169 /** Append the given text to a column element, the text will be formatted and copied.
 170  *
 171  * Same function as col_append_str() but using a printf-like format string.
 172  *
 173  * @param cinfo the current packet row
 174  * @param col the column to use, e.g. COL_INFO
 175  * @param format the format string
 176  * @param ... the variable number of parameters
 177  */
 178 extern void     col_append_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 179     G_GNUC_PRINTF(3, 4);
 180
 181 /** Prepend the given text to a column element, the text will be formatted and copied.
 182  *
 183  * @param cinfo the current packet row
 184  * @param col the column to use, e.g. COL_INFO
 185  * @param format the format string
 186  * @param ... the variable number of parameters
 187  */
 188 extern void     col_prepend_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 189     G_GNUC_PRINTF(3, 4);
 190
 191 /**Prepend the given text to a column element, the text will be formatted and copied.
 192  * This function is similar to col_prepend_fstr() but this function will
 193  * unconditionally set a fence to the end of the prepended data even if there
 194  * were no fence before.
 195  * The col_prepend_fstr() will only prepend the data before the fence IF
 196  * there is already a fence created. This function will create a fence in case
 197  * it does not yet exist.
 198  */
 199 extern void     col_prepend_fence_fstr(column_info *cinfo, const gint col, const gchar *format, ...)
 200     G_GNUC_PRINTF(3, 4);
 201
 202 /** Append the given text (prepended by a separator) to a column element.
 203  *
 204  * Much like col_append_str() but will prepend the given separator if the column isn't empty.
 205  *
 206  * @param cinfo the current packet row
 207  * @param col the column to use, e.g. COL_INFO
 208  * @param sep the separator string or NULL for default: ", "
 209  * @param str the string to append
 210  */
 211 extern void     col_append_sep_str(column_info *cinfo, const gint col, const gchar *sep,
 212                 const gchar *str);
 213
 214 /** Append the given text (prepended by a separator) to a column element.
 215  *
 216  * Much like col_append_fstr() but will prepend the given separator if the column isn't empty.
 217  *
 218  * @param cinfo the current packet row
 219  * @param col the column to use, e.g. COL_INFO
 220  * @param sep the separator string or NULL for default: ", "
 221  * @param format the format string
 222  * @param ... the variable number of parameters
 223  */
 224 extern void     col_append_sep_fstr(column_info *cinfo, const gint col, const gchar *sep,
 225                 const gchar *format, ...)
 226     G_GNUC_PRINTF(4, 5);
 227
 228 /** Set the given (relative) time to a column element.
 229  *
 230  * Used by multiple dissectors to set the time in the column
 231  * COL_DELTA_CONV_TIME
 232  *
 233  * @param cinfo         the current packet row
 234  * @param col           the column to use, e.g. COL_INFO
 235  * @param ts            the time to set in the column
 236  * @param fieldname     the fieldname to use for creating a filter (when
 237  *                        applying/preparing/copying as filter)
 238  */
 239 extern void     col_set_time(column_info *cinfo, const int col,
 240                         const nstime_t *ts, char *fieldname);
 241
 242 #ifdef __cplusplus
 243 }
 244 #endif /* __cplusplus */
 245
 246 #endif /* __COLUMN_UTILS_H__ */