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  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __PREFS_INT_H__
  13 #define __PREFS_INT_H__
  14
  15 #include <stdio.h>
  16 #include "ws_symbol_export.h"
  17 #include <epan/wmem_scopes.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif /* __cplusplus */
  22
  23 /**
  24  *@file
  25  */
  26
  27 struct pref_module {
  28     const char *name;           /**< name of module */
  29     const char *title;          /**< title of module (displayed in preferences list) */
  30     const char *description;    /**< Description of module (displayed in preferences notebook) */
  31     const char *help;           /**< Module help page (passed to user_guide_url() to generate a URL) */
  32     void (*apply_cb)(void);     /**< routine to call when preferences applied */
  33     GList *prefs;               /**< list of its preferences */
  34     struct pref_module *parent; /**< parent module */
  35     wmem_tree_t *submodules;    /**< list of its submodules */
  36     int numprefs;               /**< number of non-obsolete preferences */
  37     unsigned int prefs_changed_flags;    /**< Bitmask of the types of changes done by module preferences since we last checked */
  38     bool obsolete;              /**< if true, this is a module that used to
  39                                  * exist but no longer does
  40                                  */
  41     bool use_gui;               /**< Determines whether or not the module will use the generic
  42                                   * GUI interface/APIs with the preference value or if its own
  43                                   * independent GUI will be provided.  This allows all preferences
  44                                   * to have a common API for reading/writing, but not require them to
  45                                   * use simple GUI controls to change the options.  In general, the "general"
  46                                   * Wireshark preferences should have this set to false, while the protocol
  47                                   * modules will have this set to true */
  48     unsigned int effect_flags;  /**< Flags of types effected by preference (PREF_TYPE_DISSECTION, PREF_EFFECT_CAPTURE, etc).
  49                                      These flags will be set in all module's preferences on creation. Flags must be non-zero
  50                                      to ensure saving to disk */
  51 };
  52
  53 typedef struct {
  54     module_t *module;
  55     FILE     *pf;
  56 } write_pref_arg_t;
  57
  58 /**
  59  * Module used for protocol preferences.
  60  * With MSVC and a libwireshark.dll, we need a special declaration.
  61  */
  62 WS_DLL_PUBLIC module_t *protocols_module;
  63
  64 typedef void (*pref_custom_free_cb) (pref_t* pref);
  65 typedef void (*pref_custom_reset_cb) (pref_t* pref);
  66 typedef prefs_set_pref_e (*pref_custom_set_cb) (pref_t* pref, const char* value, unsigned int* changed_flags);
  67 /* typedef void (*pref_custom_write_cb) (pref_t* pref, write_pref_arg_t* arg); Deprecated. */
  68 /* pref_custom_type_name_cb should return NULL for internal / hidden preferences. */
  69 typedef const char * (*pref_custom_type_name_cb) (void);
  70 typedef char * (*pref_custom_type_description_cb) (void);
  71 typedef bool (*pref_custom_is_default_cb) (pref_t* pref);
  72 typedef char * (*pref_custom_to_str_cb) (pref_t* pref, bool default_val);
  73
  74 /** Structure to hold callbacks for PREF_CUSTOM type */
  75 struct pref_custom_cbs {
  76     pref_custom_free_cb free_cb;
  77     pref_custom_reset_cb reset_cb;
  78     pref_custom_set_cb set_cb;
  79     /* pref_custom_write_cb write_cb; Deprecated. */
  80     pref_custom_type_name_cb type_name_cb;
  81     pref_custom_type_description_cb type_description_cb;
  82     pref_custom_is_default_cb is_default_cb;
  83     pref_custom_to_str_cb to_str_cb;
  84 };
  85
  86 /**
  87  * PREF_OBSOLETE is used for preferences that a module used to support
  88  * but no longer supports; we give different error messages for them.
  89  */
  90 #define PREF_UINT             (1u << 0)
  91 #define PREF_BOOL             (1u << 1)
  92 #define PREF_ENUM             (1u << 2)
  93 #define PREF_STRING           (1u << 3)
  94 #define PREF_RANGE            (1u << 4)
  95 #define PREF_STATIC_TEXT      (1u << 5)
  96 #define PREF_UAT              (1u << 6)
  97 #define PREF_SAVE_FILENAME    (1u << 7)
  98 #define PREF_COLOR            (1u << 8) /* XXX - These are only supported for "internal" (non-protocol) */
  99 #define PREF_CUSTOM           (1u << 9) /* use and not as a generic protocol preference */
 100 #define PREF_OBSOLETE         (1u << 10)
 101 #define PREF_DIRNAME          (1u << 11)
 102 // Was PREF_DECODE_AS_UINT   (1u << 12)
 103 #define PREF_DECODE_AS_RANGE  (1u << 13) /* XXX - Internal use only, not a generic protocol preference */
 104 #define PREF_OPEN_FILENAME    (1u << 14)
 105 #define PREF_PASSWORD         (1u << 15) /* like string, but never saved to prefs file */
 106 /**
 107  * Dedicated to TCP PROTOCOL for handling manual SEQ interpretation,
 108  * and allow users manage the sender traffic ambiguities
 109  */
 110 #define PREF_PROTO_TCP_SNDAMB_ENUM   (1u << 16)
 111
 112 #define PREF_DISSECTOR        (1u << 17) /* like string, but with dissector name syntax check */
 113
 114 /* read_prefs_file: read in a generic config file and do a callback to */
 115 /* pref_set_pair_fct() for every key/value pair found */
 116 /**
 117  * Given a string of the form "<pref name>:<pref value>", as might appear
 118  * as an argument to a "-o" option, parse it and set the preference in
 119  * question.
 120  * @return an indication of whether it succeeded or failed
 121  * in some fashion.
 122  */
 123 typedef prefs_set_pref_e (*pref_set_pair_cb) (char *key, const char *value, void *private_data, bool return_range_errors);
 124
 125 WS_DLL_PUBLIC
 126 const char* prefs_get_description(pref_t *pref);
 127
 128 WS_DLL_PUBLIC
 129 const char* prefs_get_title(pref_t *pref);
 130
 131 WS_DLL_PUBLIC
 132 const char* prefs_get_name(pref_t *pref);
 133
 134 WS_DLL_PUBLIC
 135 int prefs_get_type(pref_t *pref);
 136
 137 WS_DLL_PUBLIC uint32_t prefs_get_max_value(pref_t *pref);
 138
 139 /* Bitmask of flags for the effect of a preference in Wireshark */
 140 #define PREF_EFFECT_DISSECTION        (1u << 0)
 141 #define PREF_EFFECT_CAPTURE           (1u << 1)
 142 #define PREF_EFFECT_GUI_LAYOUT        (1u << 2)
 143 #define PREF_EFFECT_FIELDS            (1u << 3)
 144 #define PREF_EFFECT_GUI               (1u << 4)
 145 #define PREF_EFFECT_GUI_COLOR         (1u << 5)
 146
 147 /** Fetch flags that show the effect of the preference
 148  *
 149  * @param pref A preference.
 150  *
 151  * @return A bitmask of the types of things the preference will
 152  * effect.
 153  */
 154 WS_DLL_PUBLIC
 155 unsigned int prefs_get_effect_flags(pref_t *pref);
 156
 157 /** Set flags for the effect of the preference
 158  * The intention is to distinguish preferences that affect
 159  * dissection from those that don't. A bitmask was added to
 160  * provide greater flexibility in the types of effects
 161  * preferences can have.
 162  *
 163  * @param pref A preference.
 164  * @param flags Bitmask of flags to apply to preference. Note that flags
 165  * must be non-zero to ensure preference is properly saved to disk.
 166  *
 167  */
 168 WS_DLL_PUBLIC
 169 void prefs_set_effect_flags(pref_t *pref, unsigned int flags);
 170
 171 /** Same as prefs_set_effect_flags, just different way to get preference
 172  */
 173 WS_DLL_PUBLIC
 174 void prefs_set_effect_flags_by_name(module_t * module, const char *pref, unsigned int flags);
 175
 176 /** Fetch flags that show module's preferences effect
 177  * The flag values of the module will be applied to any individual preferences
 178  * of the module when they are created
 179  *
 180  * @param module A preference module.
 181  *
 182  * @return A bitmask of the types of things the module's preferences will
 183  * effect.
 184  */
 185 WS_DLL_PUBLIC
 186 unsigned int prefs_get_module_effect_flags(module_t * module);
 187
 188 /** Set flags for module's preferences effect
 189  * The intention is to distinguish preferences that affect
 190  * dissection from those that don't. Since modules are a grouping
 191  * of preferences, it's likely that a whole module will want the
 192  * same flags for its preferences. The flag values of the module will
 193  * be applied to any individual preferences of the module when they
 194  * are created
 195  *
 196  * @param module A preference module.
 197  * @param flags Bitmask of flags to apply to module. Note that flags
 198  * must be non-zero to ensure preferences are properly saved to disk.
 199  *
 200  */
 201 WS_DLL_PUBLIC
 202 void prefs_set_module_effect_flags(module_t * module, unsigned int flags);
 203
 204 WS_DLL_PUBLIC
 205 bool prefs_set_range_value_work(pref_t *pref, const char *value,
 206                            bool return_range_errors, unsigned int *changed_flags);
 207
 208 WS_DLL_PUBLIC
 209 unsigned int
 210 prefs_set_stashed_range_value(pref_t *pref, const char *value);
 211
 212 /** Add a range value of a range preference. */
 213 WS_DLL_PUBLIC
 214 void
 215 prefs_range_add_value(pref_t *pref, uint32_t val);
 216
 217 /** Remove a range value of a range preference. */
 218 WS_DLL_PUBLIC
 219 void
 220 prefs_range_remove_value(pref_t *pref, uint32_t val);
 221
 222
 223 WS_DLL_PUBLIC unsigned int prefs_set_bool_value(pref_t *pref, bool value, pref_source_t source);
 224 WS_DLL_PUBLIC bool prefs_get_bool_value(pref_t *pref, pref_source_t source);
 225 WS_DLL_PUBLIC void prefs_invert_bool_value(pref_t *pref, pref_source_t source);
 226
 227 WS_DLL_PUBLIC unsigned int prefs_set_uint_value(pref_t *pref, unsigned value, pref_source_t source);
 228 WS_DLL_PUBLIC unsigned prefs_get_uint_base(pref_t *pref);
 229 WS_DLL_PUBLIC unsigned prefs_get_uint_value_real(pref_t *pref, pref_source_t source);
 230
 231
 232 WS_DLL_PUBLIC unsigned int prefs_set_enum_value(pref_t *pref, int value, pref_source_t source);
 233 WS_DLL_PUBLIC unsigned int prefs_set_enum_string_value(pref_t *pref, const char *value, pref_source_t source);
 234 WS_DLL_PUBLIC int prefs_get_enum_value(pref_t *pref, pref_source_t source);
 235 WS_DLL_PUBLIC const enum_val_t* prefs_get_enumvals(pref_t *pref);
 236 WS_DLL_PUBLIC bool prefs_get_enum_radiobuttons(pref_t *pref);
 237
 238 WS_DLL_PUBLIC bool prefs_set_color_value(pref_t *pref, color_t value, pref_source_t source);
 239 WS_DLL_PUBLIC color_t* prefs_get_color_value(pref_t *pref, pref_source_t source);
 240
 241 WS_DLL_PUBLIC unsigned int prefs_set_custom_value(pref_t *pref, const char *value, pref_source_t source);
 242
 243 WS_DLL_PUBLIC unsigned int prefs_set_string_value(pref_t *pref, const char* value, pref_source_t source);
 244 WS_DLL_PUBLIC char* prefs_get_string_value(pref_t *pref, pref_source_t source);
 245
 246 WS_DLL_PUBLIC struct epan_uat* prefs_get_uat_value(pref_t *pref);
 247
 248 WS_DLL_PUBLIC bool prefs_set_range_value(pref_t *pref, range_t *value, pref_source_t source);
 249 WS_DLL_PUBLIC range_t* prefs_get_range_value_real(pref_t *pref, pref_source_t source);
 250
 251 WS_DLL_PUBLIC bool prefs_add_decode_as_value(pref_t *pref, unsigned value, bool replace);
 252 WS_DLL_PUBLIC bool prefs_remove_decode_as_value(pref_t *pref, unsigned value, bool set_default);
 253
 254 WS_DLL_PUBLIC unsigned int prefs_set_password_value(pref_t *pref, const char* value, pref_source_t source);
 255 WS_DLL_PUBLIC char* prefs_get_password_value(pref_t *pref, pref_source_t source);
 256
 257 WS_DLL_PUBLIC bool prefs_add_list_value(pref_t *pref, void *value, pref_source_t source);
 258 WS_DLL_PUBLIC GList* prefs_get_list_value(pref_t *pref, pref_source_t source);
 259
 260 WS_DLL_PUBLIC void reset_pref(pref_t *pref);
 261
 262 /** read the preferences file (or similar) and call the callback
 263  * function to set each key/value pair found
 264  */
 265 WS_DLL_PUBLIC
 266 int
 267 read_prefs_file(const char *pf_path, FILE *pf, pref_set_pair_cb pref_set_pair_fct, void *private_data);
 268
 269 /** Given a module name, read the preferences associated with only that module.
 270  * Checks for a file in the personal configuration directory named after the
 271  * module with a ".cfg" extension added first.
 272  *
 273  * @param name The preference module name, e.g. "extcap".
 274  */
 275 WS_DLL_PUBLIC
 276 void
 277 prefs_read_module(const char *name);
 278
 279 WS_DLL_PUBLIC
 280 bool
 281 prefs_pref_is_default(pref_t *pref);
 282
 283 /** "Stash" a preference.
 284  * Copy a preference to its stashed value. Can be called from prefs_pref_foreach().
 285  *
 286  * @param pref A preference.
 287  * @param unused unused
 288  */
 289 WS_DLL_PUBLIC
 290 unsigned pref_stash(pref_t *pref, void *unused);
 291
 292 typedef struct pref_unstash_data
 293 {
 294     /* Used to set prefs_changed member to true if the preference
 295        differs from its stashed values. */
 296     module_t *module;
 297     /* Qt uses stashed values to then "applies" them
 298       during unstash.  Use this flag for that behavior */
 299     bool handle_decode_as;
 300 } pref_unstash_data_t;
 301
 302 /** "Unstash" a preference.
 303  * Set a preference to its stashed value. Can be called from prefs_pref_foreach().
 304  *
 305  * @param pref A preference.
 306  * @param unstash_data_p A pointer to a pref_unstash_data_t structure.
 307  *
 308  * @return Always returns 0.
 309  */
 310 WS_DLL_PUBLIC
 311 unsigned pref_unstash(pref_t *pref, void *unstash_data_p);
 312
 313 /** Clean up a stashed preference.
 314  * Can be called from prefs_pref_foreach().
 315  *
 316  * @param pref A preference.
 317  * @param unused unused
 318  *
 319  * @return Always returns 0.
 320  */
 321 WS_DLL_PUBLIC
 322 unsigned pref_clean_stash(pref_t *pref, void *unused);
 323
 324 /** Set a stashed preference to its default value.
 325  *
 326  *@param pref A preference.
 327  */
 328 WS_DLL_PUBLIC
 329 void reset_stashed_pref(pref_t *pref);
 330
 331 /** Convert a string list preference to a preference string.
 332  *
 333  * Given a GList of char pointers, create a quoted, comma-separated
 334  * string. Should be used with prefs_get_string_list() and
 335  * prefs_clear_string_list().
 336  *
 337  * @param sl String list.
 338  * @return Quoted, joined, and wrapped string. May be empty.
 339  */
 340 WS_DLL_PUBLIC
 341 char *
 342 join_string_list(GList *sl);
 343
 344 #ifdef __cplusplus
 345 }
 346 #endif /* __cplusplus */
 347
 348 #endif /* prefs-int.h */