epan/prefs-int.h

   1 /* prefs-int.h
   2  * Definitions for implementation of preference handling routines;
   3  * used by "friends" of the preferences type.
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * This program is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU General Public License
  11  * as published by the Free Software Foundation; either version 2
  12  * of the License, or (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  22  */
  23
  24 #ifndef __PREFS_INT_H__
  25 #define __PREFS_INT_H__
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif /* __cplusplus */
  30
  31 #include <stdio.h>
  32 #include "ws_symbol_export.h"
  33 #include <epan/wmem/wmem.h>
  34
  35 /**
  36  *@file
  37  */
  38
  39 struct pref_module {
  40     const char *name;           /**< name of module */
  41     const char *title;          /**< title of module (displayed in preferences list) */
  42     const char *description;    /**< Description of module (displayed in preferences notebook) */
  43     void (*apply_cb)(void);     /**< routine to call when preferences applied */
  44     GList *prefs;               /**< list of its preferences */
  45     struct pref_module *parent; /**< parent module */
  46     wmem_tree_t *submodules;    /**< list of its submodules */
  47     int numprefs;               /**< number of non-obsolete preferences */
  48     gboolean prefs_changed;     /**< if TRUE, a preference has changed since we last checked */
  49     gboolean obsolete;          /**< if TRUE, this is a module that used to
  50                                  * exist but no longer does
  51                                  */
  52     gboolean use_gui;           /**< Determines whether or not the module will use the generic
  53                                   * GUI interface/APIs with the preference value or if its own
  54                                   * independent GUI will be provided.  This allows all preferences
  55                                   * to have a common API for reading/writing, but not require them to
  56                                   * use simple GUI controls to change the options.  In general, the "general"
  57                                   * Wireshark preferences should have this set to FALSE, while the protocol
  58                                   * modules will have this set to TRUE */
  59 };
  60
  61 typedef struct {
  62     module_t *module;
  63     FILE     *pf;
  64 } write_pref_arg_t;
  65
  66 /**
  67  * Module used for protocol preferences.
  68  * With MSVC and a libwireshark.dll, we need a special declaration.
  69  */
  70 WS_DLL_PUBLIC module_t *protocols_module;
  71
  72 typedef void (*pref_custom_free_cb) (pref_t* pref);
  73 typedef void (*pref_custom_reset_cb) (pref_t* pref);
  74 typedef prefs_set_pref_e (*pref_custom_set_cb) (pref_t* pref, const gchar* value, gboolean* changed);
  75 /* typedef void (*pref_custom_write_cb) (pref_t* pref, write_pref_arg_t* arg); Deprecated. */
  76 /* pref_custom_type_name_cb should return NULL for internal / hidden preferences. */
  77 typedef const char * (*pref_custom_type_name_cb) (void);
  78 typedef char * (*pref_custom_type_description_cb) (void);
  79 typedef gboolean (*pref_custom_is_default_cb) (pref_t* pref);
  80 typedef char * (*pref_custom_to_str_cb) (pref_t* pref, gboolean default_val);
  81
  82 /** Structure to hold callbacks for PREF_CUSTOM type */
  83 struct pref_custom_cbs {
  84     pref_custom_free_cb free_cb;
  85     pref_custom_reset_cb reset_cb;
  86     pref_custom_set_cb set_cb;
  87     /* pref_custom_write_cb write_cb; Deprecated. */
  88     pref_custom_type_name_cb type_name_cb;
  89     pref_custom_type_description_cb type_description_cb;
  90     pref_custom_is_default_cb is_default_cb;
  91     pref_custom_to_str_cb to_str_cb;
  92 };
  93
  94 /**
  95  * PREF_OBSOLETE is used for preferences that a module used to support
  96  * but no longer supports; we give different error messages for them.
  97  */
  98 #define PREF_UINT        (1u << 0)
  99 #define PREF_BOOL        (1u << 1)
 100 #define PREF_ENUM        (1u << 2)
 101 #define PREF_STRING      (1u << 3)
 102 #define PREF_RANGE       (1u << 4)
 103 #define PREF_STATIC_TEXT (1u << 5)
 104 #define PREF_UAT         (1u << 6)
 105 #define PREF_FILENAME    (1u << 7)
 106 #define PREF_COLOR       (1u << 8) /* XXX - These are only supported for "internal" (non-protocol) */
 107 #define PREF_CUSTOM      (1u << 9) /* use and not as a generic protocol preference */
 108 #define PREF_OBSOLETE    (1u << 10)
 109 #define PREF_DIRNAME     (1u << 11)
 110 #define PREF_DECODE_AS_UINT  (1u << 12)     /* XXX - These are only supported for "internal" (non-protocol) */
 111 #define PREF_DECODE_AS_RANGE (1u << 13) /* use and not as a generic protocol preference */
 112
 113 typedef enum {
 114         GUI_ALL,
 115         GUI_GTK,
 116         GUI_QT
 117 } gui_type_t;
 118
 119 /* read_prefs_file: read in a generic config file and do a callback to */
 120 /* pref_set_pair_fct() for every key/value pair found */
 121 /**
 122  * Given a string of the form "<pref name>:<pref value>", as might appear
 123  * as an argument to a "-o" option, parse it and set the preference in
 124  * question.
 125  * @return an indication of whether it succeeded or failed
 126  * in some fashion.
 127  */
 128 typedef prefs_set_pref_e (*pref_set_pair_cb) (gchar *key, const gchar *value, void *private_data, gboolean return_range_errors);
 129
 130 WS_DLL_PUBLIC
 131 const char* prefs_get_description(pref_t *pref);
 132
 133 WS_DLL_PUBLIC
 134 const char* prefs_get_title(pref_t *pref);
 135
 136 WS_DLL_PUBLIC
 137 const char* prefs_get_name(pref_t *pref);
 138
 139 WS_DLL_PUBLIC
 140 int prefs_get_type(pref_t *pref);
 141
 142 WS_DLL_PUBLIC
 143 gui_type_t prefs_get_gui_type(pref_t *pref);
 144
 145 WS_DLL_PUBLIC guint32 prefs_get_max_value(pref_t *pref);
 146
 147 // GTK only
 148 WS_DLL_PUBLIC void* prefs_get_control(pref_t *pref);
 149 WS_DLL_PUBLIC void prefs_set_control(pref_t *pref, void* control);
 150 WS_DLL_PUBLIC int prefs_get_ordinal(pref_t *pref);
 151
 152 WS_DLL_PUBLIC
 153 gboolean prefs_set_range_value_work(pref_t *pref, const gchar *value,
 154                            gboolean return_range_errors, gboolean *changed);
 155
 156 WS_DLL_PUBLIC
 157 gboolean
 158 prefs_set_stashed_range_value(pref_t *pref, const gchar *value);
 159
 160 /** Add a range value of a range preference. */
 161 WS_DLL_PUBLIC
 162 void
 163 prefs_range_add_value(pref_t *pref, guint32 val);
 164
 165 /** Remove a range value of a range preference. */
 166 WS_DLL_PUBLIC
 167 void
 168 prefs_range_remove_value(pref_t *pref, guint32 val);
 169
 170
 171 WS_DLL_PUBLIC gboolean prefs_set_bool_value(pref_t *pref, gboolean value, pref_source_t source);
 172 WS_DLL_PUBLIC gboolean prefs_get_bool_value(pref_t *pref, pref_source_t source);
 173 WS_DLL_PUBLIC void prefs_invert_bool_value(pref_t *pref, pref_source_t source);
 174
 175 WS_DLL_PUBLIC gboolean prefs_set_uint_value(pref_t *pref, guint value, pref_source_t source);
 176 WS_DLL_PUBLIC guint prefs_get_uint_base(pref_t *pref);
 177 WS_DLL_PUBLIC guint prefs_get_uint_value_real(pref_t *pref, pref_source_t source);
 178
 179
 180 WS_DLL_PUBLIC gboolean prefs_set_enum_value(pref_t *pref, gint value, pref_source_t source);
 181 WS_DLL_PUBLIC gint prefs_get_enum_value(pref_t *pref, pref_source_t source);
 182 WS_DLL_PUBLIC const enum_val_t* prefs_get_enumvals(pref_t *pref);
 183 WS_DLL_PUBLIC gboolean prefs_get_enum_radiobuttons(pref_t *pref);
 184
 185 WS_DLL_PUBLIC gboolean prefs_set_color_value(pref_t *pref, color_t value, pref_source_t source);
 186 WS_DLL_PUBLIC color_t* prefs_get_color_value(pref_t *pref, pref_source_t source);
 187
 188 WS_DLL_PUBLIC gboolean prefs_set_string_value(pref_t *pref, const char* value, pref_source_t source);
 189 WS_DLL_PUBLIC char* prefs_get_string_value(pref_t *pref, pref_source_t source);
 190
 191 WS_DLL_PUBLIC struct epan_uat* prefs_get_uat_value(pref_t *pref);
 192
 193 WS_DLL_PUBLIC gboolean prefs_set_range_value(pref_t *pref, range_t *value, pref_source_t source);
 194 WS_DLL_PUBLIC range_t* prefs_get_range_value_real(pref_t *pref, pref_source_t source);
 195
 196 WS_DLL_PUBLIC gboolean prefs_add_decode_as_value(pref_t *pref, guint value, gboolean replace);
 197 WS_DLL_PUBLIC gboolean prefs_remove_decode_as_value(pref_t *pref, guint value, gboolean set_default);
 198
 199 WS_DLL_PUBLIC void reset_pref(pref_t *pref);
 200
 201 /** read the preferences file (or similar) and call the callback
 202  * function to set each key/value pair found
 203  */
 204 WS_DLL_PUBLIC
 205 int
 206 read_prefs_file(const char *pf_path, FILE *pf, pref_set_pair_cb pref_set_pair_fct, void *private_data);
 207
 208 WS_DLL_PUBLIC
 209 gboolean
 210 prefs_pref_is_default(pref_t *pref);
 211
 212 /** "Stash" a preference.
 213  * Copy a preference to its stashed value. Can be called from prefs_pref_foreach().
 214  *
 215  * @param pref A preference.
 216  * @param unused unused
 217  */
 218 WS_DLL_PUBLIC
 219 guint pref_stash(pref_t *pref, gpointer unused _U_);
 220
 221 typedef struct pref_unstash_data
 222 {
 223     /* Used to set prefs_changed member to TRUE if the preference
 224        differs from its stashed values. Also used by "decode as" types
 225        to look up dissector short name */
 226     module_t *module;
 227     /* Qt uses stashed values to then "applies" them
 228       during unstash.  Use this flag for that behavior */
 229     gboolean handle_decode_as;
 230 } pref_unstash_data_t;
 231
 232 /** "Unstash" a preference.
 233  * Set a preference to its stashed value. Can be called from prefs_pref_foreach().
 234  *
 235  * @param pref A preference.
 236  * @param unstash_data_p A pointer to a pref_unstash_data_t structure.
 237  *
 238  * @return Always returns 0.
 239  */
 240 WS_DLL_PUBLIC
 241 guint pref_unstash(pref_t *pref, gpointer unstash_data_p);
 242
 243 /** Clean up a stashed preference.
 244  * Can be called from prefs_pref_foreach().
 245  *
 246  * @param pref A preference.
 247  * @param unused unused
 248  *
 249  * @return Always returns 0.
 250  */
 251 WS_DLL_PUBLIC
 252 guint pref_clean_stash(pref_t *pref, gpointer unused _U_);
 253
 254 /** Set a stashed preference to its default value.
 255  *
 256  *@param pref A preference.
 257  */
 258 WS_DLL_PUBLIC
 259 void reset_stashed_pref(pref_t *pref);
 260
 261 /** Convert a string list preference to a preference string.
 262  *
 263  * Given a GList of gchar pointers, create a quoted, comma-separated
 264  * string. Should be used with prefs_get_string_list() and
 265  * prefs_clear_string_list().
 266  *
 267  * @param sl String list.
 268  * @return Quoted, joined, and wrapped string. May be empty.
 269  */
 270 WS_DLL_PUBLIC
 271 char *
 272 join_string_list(GList *sl);
 273
 274 #ifdef __cplusplus
 275 }
 276 #endif /* __cplusplus */
 277
 278 #endif /* prefs-int.h */