From 10b53eb3bbf3a15ab96d95dab1012880cb0b7d84 Mon Sep 17 00:00:00 2001 From: ulfl Date: Sun, 2 Oct 2005 14:56:27 +0000 Subject: add doxygen comments to column-utils.h and do a slight code cleanup git-svn-id: http://anonsvn.wireshark.org/wireshark/trunk@16066 f5534014-38df-0310-8fa8-9805f1628bb7 --- epan/column-utils.c | 34 +++++----- epan/column-utils.h | 180 ++++++++++++++++++++++++++++++++++++++++++++-------- epan/epan.c | 2 +- 3 files changed, 173 insertions(+), 43 deletions(-) (limited to 'epan') diff --git a/epan/column-utils.c b/epan/column-utils.c index 1510c1cfd7..de134a7e03 100644 --- a/epan/column-utils.c +++ b/epan/column-utils.c @@ -44,25 +44,25 @@ /* Allocate all the data structures for constructing column data, given the number of columns. */ void -col_setup(column_info *col_info, gint num_cols) +col_setup(column_info *cinfo, gint num_cols) { int i; - col_info->num_cols = num_cols; - col_info->col_fmt = (gint *) g_malloc(sizeof(gint) * num_cols); - col_info->fmt_matx = (gboolean **) g_malloc(sizeof(gboolean *) * num_cols); - col_info->col_first = (int *) g_malloc(sizeof(int) * (NUM_COL_FMTS)); - col_info->col_last = (int *) g_malloc(sizeof(int) * (NUM_COL_FMTS)); - col_info->col_title = (gchar **) g_malloc(sizeof(gchar *) * num_cols); - col_info->col_data = (const gchar **) g_malloc(sizeof(gchar *) * num_cols); - col_info->col_buf = (gchar **) g_malloc(sizeof(gchar *) * num_cols); - col_info->col_fence = (int *) g_malloc(sizeof(int) * num_cols); - col_info->col_expr = (gchar **) g_malloc(sizeof(gchar *) * num_cols); - col_info->col_expr_val = (gchar **) g_malloc(sizeof(gchar *) * num_cols); + cinfo->num_cols = num_cols; + cinfo->col_fmt = (gint *) g_malloc(sizeof(gint) * num_cols); + cinfo->fmt_matx = (gboolean **) g_malloc(sizeof(gboolean *) * num_cols); + cinfo->col_first = (int *) g_malloc(sizeof(int) * (NUM_COL_FMTS)); + cinfo->col_last = (int *) g_malloc(sizeof(int) * (NUM_COL_FMTS)); + cinfo->col_title = (gchar **) g_malloc(sizeof(gchar *) * num_cols); + cinfo->col_data = (const gchar **) g_malloc(sizeof(gchar *) * num_cols); + cinfo->col_buf = (gchar **) g_malloc(sizeof(gchar *) * num_cols); + cinfo->col_fence = (int *) g_malloc(sizeof(int) * num_cols); + cinfo->col_expr = (gchar **) g_malloc(sizeof(gchar *) * num_cols); + cinfo->col_expr_val = (gchar **) g_malloc(sizeof(gchar *) * num_cols); for (i = 0; i < NUM_COL_FMTS; i++) { - col_info->col_first[i] = -1; - col_info->col_last[i] = -1; + cinfo->col_first[i] = -1; + cinfo->col_last[i] = -1; } } @@ -734,7 +734,7 @@ col_set_abs_time(frame_data *fd, column_info *cinfo, int col) strcpy(cinfo->col_expr_val[col],cinfo->col_buf[col]); } -/* Add "command-line-specified" time. +/* Set the format of the variable time format. XXX - this is called from "file.c" when the user changes the time format they want for "command-line-specified" time; it's a bit ugly that we have to export it, but if we go to a CList-like widget that @@ -742,7 +742,7 @@ col_set_abs_time(frame_data *fd, column_info *cinfo, int col) requiring us to stuff the text into the widget from outside, we might be able to clean this up. */ void -col_set_cls_time(frame_data *fd, column_info *cinfo, int col) +col_set_cls_time(frame_data *fd, column_info *cinfo, gint col) { switch (timestamp_get_type()) { case TS_ABSOLUTE: @@ -1010,7 +1010,7 @@ col_set_circuit_id(packet_info *pinfo, int col) } void -fill_in_columns(packet_info *pinfo) +col_fill_in(packet_info *pinfo) { int i; diff --git a/epan/column-utils.h b/epan/column-utils.h index c503ddcbc9..f5dda5c560 100644 --- a/epan/column-utils.h +++ b/epan/column-utils.h @@ -27,42 +27,172 @@ #include -#define COL_MAX_LEN 256 -#define COL_MAX_INFO_LEN 4096 - #include "gnuc_format_check.h" #include "column_info.h" #include "packet_info.h" -/* Allocate all the data structures for constructing column data, given - the number of columns. */ -extern void col_setup(column_info *, gint); +/** Maximum length of columns (except COL_INFO). + * Internal, don't use this in dissectors! + */ + +#define COL_MAX_LEN 256 +/** Maximum length of info columns (COL_INFO only). + * Internal, don't use this in dissectors! + */ +#define COL_MAX_INFO_LEN 4096 + + +/** Allocate all the data structures for constructing column data, given + * the number of columns. + * + * Internal, don't use this in dissectors! + */ +extern void col_setup(column_info *cinfo, gint num_cols); + +/** Initialize the data structures for constructing column data. + * + * Internal, don't use this in dissectors! + */ +extern void col_init(column_info *cinfo); + +/** Set the format of the "variable time format". + * + * Internal, don't use this in dissectors! + */ +extern void col_set_cls_time(frame_data *, column_info *cinfo, gint col); -/* Initialize the data structures for constructing column data. */ -extern void col_init(column_info *); +/** Fill in all columns of the given packet. + * + * Internal, don't use this in dissectors! + */ +extern void col_fill_in(packet_info *pinfo); /* Utility routines used by packet*.c */ -extern gboolean col_get_writable(column_info *); -extern void col_set_writable(column_info *, gboolean); -extern gint check_col(column_info *, gint); -extern void col_set_fence(column_info *, gint); -extern void col_clear(column_info *, gint); -extern void col_set_str(column_info *, gint, const gchar *); -extern void col_add_fstr(column_info *, gint, const gchar *, ...) +/** Are the columns writable? + * + * @param cinfo the current packet row + * @return TRUE if it's writable, FALSE if not + */ +extern gboolean col_get_writable(column_info *cinfo); + +/** Set the columns writable. + * + * @param cinfo the current packet row + * @param writable TRUE if it's writable, FALSE if not + */ +extern void col_set_writable(column_info *cinfo, gboolean writable); + +/** Check if the given column be filled with data. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + */ +extern gint check_col(column_info *cinfo, gint 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. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + */ +extern void col_set_fence(column_info *cinfo, gint col); + +/** Clears the text of a column element. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + */ +extern void col_clear(column_info *cinfo, gint col); + +/** Set (replace) the text of a column element, the text won't be copied. + * + * Usually used to set const strings! + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + * @param str the string to set + */ +extern void col_set_str(column_info *cinfo, gint col, const gchar * str); + +/** Add (replace) the text of a column element, the text will be copied. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + * @param str the string to add + */ +extern void col_add_str(column_info *cinfo, gint col, const gchar *str); + +/** Add (replace) the text of a column element, the text will be formatted and copied. + * + * Same function as col_add_str() but using a printf-like format string. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + * @param format the format string + * @param ... the variable number of parameters + */ +extern void col_add_fstr(column_info *cinfo, gint col, const gchar *format, ...) GNUC_FORMAT_CHECK(printf, 3, 4); -extern void col_append_fstr(column_info *, gint, const gchar *, ...) + +/** Append the given text to a column element, the text will be copied. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + * @param str the string to append + */ +extern void col_append_str(column_info *cinfo, gint col, const gchar *str); + +/** Append the given text to a column element, the text will be formatted and copied. + * + * Same function as col_append_str() but using a printf-like format string. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + * @param format the format string + * @param ... the variable number of parameters + */ +extern void col_append_fstr(column_info *cinfo, gint col, const gchar *format, ...) GNUC_FORMAT_CHECK(printf, 3, 4); -extern void col_append_sep_fstr(column_info *, gint, const gchar *sep, - const gchar *fmt, ...) - GNUC_FORMAT_CHECK(printf, 4, 5); -extern void col_prepend_fstr(column_info *, gint, const gchar *, ...) + +/** Prepend the given text to a column element, the text will be formatted and copied. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + * @param format the format string + * @param ... the variable number of parameters + */ +extern void col_prepend_fstr(column_info *cinfo, gint col, const gchar *format, ...) GNUC_FORMAT_CHECK(printf, 3, 4); -extern void col_add_str(column_info *, gint, const gchar *); -extern void col_append_str(column_info *, gint, const gchar *); -extern void col_append_sep_str(column_info *, gint, const gchar *sep, + +/** Append the given text (prepended by a separator) to a column element. + * + * Much like col_append_str() but will prepend the given separator if the column isn't empty. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + * @param sep the separator string or NULL for default: ", " + * @param str the string to append + */ +extern void col_append_sep_str(column_info *cinfo, gint col, const gchar *sep, const gchar *str); -extern void col_set_cls_time(frame_data *, column_info *, int); -extern void fill_in_columns(packet_info *); + +/** Append the given text (prepended by a separator) to a column element. + * + * Much like col_append_fstr() but will prepend the given separator if the column isn't empty. + * + * @param cinfo the current packet row + * @param col the column to use, e.g. COL_INFO + * @param sep the separator string or NULL for default: ", " + * @param format the format string + * @param ... the variable number of parameters + */ +extern void col_append_sep_fstr(column_info *cinfo, gint col, const gchar *sep, + const gchar *format, ...) + GNUC_FORMAT_CHECK(printf, 4, 5); + #endif /* __COLUMN_UTILS_H__ */ diff --git a/epan/epan.c b/epan/epan.c index 895d3faa0d..4944e312de 100644 --- a/epan/epan.c +++ b/epan/epan.c @@ -186,5 +186,5 @@ epan_dissect_prime_dfilter(epan_dissect_t *edt, const dfilter_t* dfcode) void epan_dissect_fill_in_columns(epan_dissect_t *edt) { - fill_in_columns(&edt->pi); + col_fill_in(&edt->pi); } -- cgit v1.2.3