epan/column.h

   1 /** @file
   2  * Definitions for column handling routines
   3  * Column preference and format settings.
   4  *
   5  * For internal Wireshark useonly. Don't include this header in dissectors!
   6  *
   7  * Wireshark - Network traffic analyzer
   8  * By Gerald Combs <gerald@wireshark.org>
   9  * Copyright 1998 Gerald Combs
  10  *
  11  * SPDX-License-Identifier: GPL-2.0-or-later
  12  */
  13
  14 #ifndef __COLUMN_H__
  15 #define __COLUMN_H__
  16
  17 #include "ws_symbol_export.h"
  18 #include <epan/column-utils.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif /* __cplusplus */
  23
  24 /** Defines used in fmt_data.display.
  25  * The values are legacy from U Unresolved and R Resolved stored in the preferences.
  26  */
  27 #define COLUMN_DISPLAY_VALUES  'U'
  28 #define COLUMN_DISPLAY_STRINGS 'R'
  29 #define COLUMN_DISPLAY_DETAILS 'D'
  30
  31 typedef struct _fmt_data {
  32   char *title;            /* title of the column */
  33   int fmt;                 /* format of column */
  34   char *custom_fields;    /* fields names for COL_CUSTOM */
  35   int custom_occurrence;  /* optional ordinal of occurrence of that field */
  36   bool visible;            /* if false, hide this column */
  37   char display;            /* how to display a custom field value */
  38 } fmt_data;
  39
  40 WS_DLL_PUBLIC
  41 const char          *col_format_to_string(const int);
  42 WS_DLL_PUBLIC
  43 const char          *col_format_desc(const int);
  44 WS_DLL_PUBLIC
  45 const char          *col_format_abbrev(const int);
  46 WS_DLL_PUBLIC
  47 int                  get_column_format(const int);
  48 WS_DLL_PUBLIC
  49 void                 set_column_format(const int, const int);
  50 WS_DLL_PUBLIC
  51 void                 get_column_format_matches(bool *, const int);
  52 WS_DLL_PUBLIC
  53 int                  get_column_format_from_str(const char *);
  54 WS_DLL_PUBLIC
  55 char                *get_column_title(const int);
  56 WS_DLL_PUBLIC
  57 void                 set_column_title(const int, const char *);
  58 WS_DLL_PUBLIC
  59 bool                 get_column_visible(const int);
  60 WS_DLL_PUBLIC
  61 void                 set_column_visible(const int, bool);
  62 WS_DLL_PUBLIC
  63 char                 get_column_display_format(const int);
  64 WS_DLL_PUBLIC
  65 void                 set_column_display_format(const int, char);
  66 WS_DLL_PUBLIC
  67 const char          *get_column_custom_fields(const int);
  68 WS_DLL_PUBLIC
  69 void                 set_column_custom_fields(const int, const char *);
  70 WS_DLL_PUBLIC
  71 int                  get_column_custom_occurrence(const int);
  72 WS_DLL_PUBLIC
  73 void                 set_column_custom_occurrence(const int, const int);
  74 WS_DLL_PUBLIC
  75 const char          *get_column_longest_string(const int);
  76 WS_DLL_PUBLIC
  77 const char          *get_column_width_string(const int, const int);
  78 WS_DLL_PUBLIC
  79 int                  get_column_char_width(const int format);
  80 WS_DLL_PUBLIC
  81 char                *get_column_tooltip(const int col);
  82
  83 /** Get the text of a column element. The string returned may
  84  * depend on whether the resolved member variable is set.
  85  * For internal Wireshark use, not to be called from dissectors.
  86  * Dissectors use col_get_text() in column-utils.h
  87  *
  88  * @param cinfo the column information
  89  * @param col the column index to use (not the format)
  90  *
  91  * @return the text string
  92  */
  93 WS_DLL_PUBLIC
  94 const char          *get_column_text(column_info *cinfo, const int col);
  95
  96 WS_DLL_PUBLIC
  97 void
  98 col_finalize(column_info *cinfo);
  99
 100 WS_DLL_PUBLIC
 101 void
 102 build_column_format_array(column_info *cinfo, const int num_cols, const bool reset_fences);
 103
 104 WS_DLL_PUBLIC
 105 void                 column_dump_column_formats(void);
 106
 107 /** Parse a column format string into a fmt_data struct.
 108  * If the format string possibly can be that of a deprecated column
 109  * that has been migrated to a custom column (e.g., upon first being
 110  * read from a preference file), call try_convert_to_custom_column() first.
 111  *
 112  * @param[out] cfmt The parsed cfmt, still owned by the caller.
 113  * For custom columns, the caller is responsible for freeing
 114  * the custom_fields member as well.
 115  * @param[in] fmt The column format to parse.
 116  *
 117  * @return true if conversion was successful, false if unsuccessful
 118  */
 119 WS_DLL_PUBLIC
 120 bool parse_column_format(fmt_data *cfmt, const char *fmt);
 121
 122 /** Given a fmt_data struct, returns the column format string that should
 123  * be written to the preferences to generate the fmt_data struct.
 124  * The inverse of parse_column_format() above.
 125  *
 126  * @param[in] cfmt The fmt_data struct.
 127  *
 128  * @return A column format string that corresponds to the fmt_data.
 129  * This string is owned by the caller, and must be freed. Returns
 130  * NULL if cfmt is NULL.
 131  */
 132 extern
 133 char * column_fmt_data_to_str(const fmt_data *cfmt);
 134
 135 /** Checks a column format string to see if it is a deprecated column
 136  * that has been migrated to a custom column, and converts the format
 137  * to the corresponding custom column format if so, otherwise leaving
 138  * it unchanged.
 139  *
 140  * @param[in,out] fmt The column format to check and possibly convert.
 141  */
 142 WS_DLL_PUBLIC
 143 void try_convert_to_custom_column(char **fmt);
 144
 145 /** Checks a column field string to see if it is a name of a filter
 146  * field created using a default column title (as used in tshark -e),
 147  * and alias it to the new column type based field.
 148  *
 149  * @param[in] field The old title based field, e.g. "_ws.col.Info"
 150  * @return The new field, e.g. "_ws.col.info", or NULL
 151  */
 152 WS_DLL_PUBLIC
 153 const char* try_convert_to_column_field(const char *field);
 154
 155 WS_DLL_PUBLIC
 156 void column_register_fields(void);
 157 #ifdef __cplusplus
 158 }
 159 #endif /* __cplusplus */
 160
 161 #endif /* column.h */