2 * Definitions for implementation of preference handling routines;
3 * used by "friends" of the preferences type.
5 * Wireshark - Network traffic analyzer
6 * By Gerald Combs <gerald@wireshark.org>
7 * Copyright 1998 Gerald Combs
9 * SPDX-License-Identifier: GPL-2.0-or-later
12 #ifndef __PREFS_INT_H__
13 #define __PREFS_INT_H__
17 #endif /* __cplusplus */
20 #include "ws_symbol_export.h"
21 #include <epan/wmem/wmem.h>
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 void (*apply_cb)(void); /**< routine to call when preferences applied */
32 GList *prefs; /**< list of its preferences */
33 struct pref_module *parent; /**< parent module */
34 wmem_tree_t *submodules; /**< list of its submodules */
35 int numprefs; /**< number of non-obsolete preferences */
36 unsigned int prefs_changed_flags; /**< Bitmask of the types of changes done by module preferences since we last checked */
37 gboolean obsolete; /**< if TRUE, this is a module that used to
38 * exist but no longer does
40 gboolean use_gui; /**< Determines whether or not the module will use the generic
41 * GUI interface/APIs with the preference value or if its own
42 * independent GUI will be provided. This allows all preferences
43 * to have a common API for reading/writing, but not require them to
44 * use simple GUI controls to change the options. In general, the "general"
45 * Wireshark preferences should have this set to FALSE, while the protocol
46 * modules will have this set to TRUE */
47 unsigned int effect_flags; /**< Flags of types effected by preference (PREF_TYPE_DISSECTION, PREF_EFFECT_CAPTURE, etc).
48 These flags will be set in all module's preferences on creation. Flags must be non-zero
49 to ensure saving to disk */
58 * Module used for protocol preferences.
59 * With MSVC and a libwireshark.dll, we need a special declaration.
61 WS_DLL_PUBLIC module_t *protocols_module;
63 typedef void (*pref_custom_free_cb) (pref_t* pref);
64 typedef void (*pref_custom_reset_cb) (pref_t* pref);
65 typedef prefs_set_pref_e (*pref_custom_set_cb) (pref_t* pref, const gchar* value, unsigned int* changed_flags);
66 /* typedef void (*pref_custom_write_cb) (pref_t* pref, write_pref_arg_t* arg); Deprecated. */
67 /* pref_custom_type_name_cb should return NULL for internal / hidden preferences. */
68 typedef const char * (*pref_custom_type_name_cb) (void);
69 typedef char * (*pref_custom_type_description_cb) (void);
70 typedef gboolean (*pref_custom_is_default_cb) (pref_t* pref);
71 typedef char * (*pref_custom_to_str_cb) (pref_t* pref, gboolean default_val);
73 /** Structure to hold callbacks for PREF_CUSTOM type */
74 struct pref_custom_cbs {
75 pref_custom_free_cb free_cb;
76 pref_custom_reset_cb reset_cb;
77 pref_custom_set_cb set_cb;
78 /* pref_custom_write_cb write_cb; Deprecated. */
79 pref_custom_type_name_cb type_name_cb;
80 pref_custom_type_description_cb type_description_cb;
81 pref_custom_is_default_cb is_default_cb;
82 pref_custom_to_str_cb to_str_cb;
86 * PREF_OBSOLETE is used for preferences that a module used to support
87 * but no longer supports; we give different error messages for them.
89 #define PREF_UINT (1u << 0)
90 #define PREF_BOOL (1u << 1)
91 #define PREF_ENUM (1u << 2)
92 #define PREF_STRING (1u << 3)
93 #define PREF_RANGE (1u << 4)
94 #define PREF_STATIC_TEXT (1u << 5)
95 #define PREF_UAT (1u << 6)
96 #define PREF_SAVE_FILENAME (1u << 7)
97 #define PREF_COLOR (1u << 8) /* XXX - These are only supported for "internal" (non-protocol) */
98 #define PREF_CUSTOM (1u << 9) /* use and not as a generic protocol preference */
99 #define PREF_OBSOLETE (1u << 10)
100 #define PREF_DIRNAME (1u << 11)
101 #define PREF_DECODE_AS_UINT (1u << 12) /* XXX - These are only supported for "internal" (non-protocol) */
102 #define PREF_DECODE_AS_RANGE (1u << 13) /* use and not as a generic protocol preference */
103 #define PREF_OPEN_FILENAME (1u << 14)
111 /* read_prefs_file: read in a generic config file and do a callback to */
112 /* pref_set_pair_fct() for every key/value pair found */
114 * Given a string of the form "<pref name>:<pref value>", as might appear
115 * as an argument to a "-o" option, parse it and set the preference in
117 * @return an indication of whether it succeeded or failed
120 typedef prefs_set_pref_e (*pref_set_pair_cb) (gchar *key, const gchar *value, void *private_data, gboolean return_range_errors);
123 const char* prefs_get_description(pref_t *pref);
126 const char* prefs_get_title(pref_t *pref);
129 const char* prefs_get_name(pref_t *pref);
132 int prefs_get_type(pref_t *pref);
135 gui_type_t prefs_get_gui_type(pref_t *pref);
137 WS_DLL_PUBLIC guint32 prefs_get_max_value(pref_t *pref);
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 (1u << 2)
143 #define PREF_EFFECT_FONT (1u << 3)
144 #define PREF_EFFECT_GUI_LAYOUT (1u << 4)
145 #define PREF_EFFECT_CUSTOM (1u << 31)
147 /** Fetch flags that show the effect of the preference
149 * @param pref A preference.
151 * @return A bitmask of the types of things the preference will
155 unsigned int prefs_get_effect_flags(pref_t *pref);
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.
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.
169 void prefs_set_effect_flags(pref_t *pref, unsigned int flags);
171 /** Same as prefs_set_effect_flags, just different way to get preference
174 void prefs_set_effect_flags_by_name(module_t * module, const char *pref, unsigned int flags);
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
180 * @param module A preference module.
182 * @return A bitmask of the types of things the module's preferences will
186 unsigned int prefs_get_module_effect_flags(module_t * module);
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
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.
202 void prefs_set_module_effect_flags(module_t * module, unsigned int flags);
205 gboolean prefs_set_range_value_work(pref_t *pref, const gchar *value,
206 gboolean return_range_errors, unsigned int *changed_flags);
210 prefs_set_stashed_range_value(pref_t *pref, const gchar *value);
212 /** Add a range value of a range preference. */
215 prefs_range_add_value(pref_t *pref, guint32 val);
217 /** Remove a range value of a range preference. */
220 prefs_range_remove_value(pref_t *pref, guint32 val);
223 WS_DLL_PUBLIC unsigned int prefs_set_bool_value(pref_t *pref, gboolean value, pref_source_t source);
224 WS_DLL_PUBLIC gboolean 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);
227 WS_DLL_PUBLIC unsigned int prefs_set_uint_value(pref_t *pref, guint value, pref_source_t source);
228 WS_DLL_PUBLIC guint prefs_get_uint_base(pref_t *pref);
229 WS_DLL_PUBLIC guint prefs_get_uint_value_real(pref_t *pref, pref_source_t source);
232 WS_DLL_PUBLIC unsigned int prefs_set_enum_value(pref_t *pref, gint value, pref_source_t source);
233 WS_DLL_PUBLIC gint prefs_get_enum_value(pref_t *pref, pref_source_t source);
234 WS_DLL_PUBLIC const enum_val_t* prefs_get_enumvals(pref_t *pref);
235 WS_DLL_PUBLIC gboolean prefs_get_enum_radiobuttons(pref_t *pref);
237 WS_DLL_PUBLIC gboolean prefs_set_color_value(pref_t *pref, color_t value, pref_source_t source);
238 WS_DLL_PUBLIC color_t* prefs_get_color_value(pref_t *pref, pref_source_t source);
240 WS_DLL_PUBLIC unsigned int prefs_set_string_value(pref_t *pref, const char* value, pref_source_t source);
241 WS_DLL_PUBLIC char* prefs_get_string_value(pref_t *pref, pref_source_t source);
243 WS_DLL_PUBLIC struct epan_uat* prefs_get_uat_value(pref_t *pref);
245 WS_DLL_PUBLIC gboolean prefs_set_range_value(pref_t *pref, range_t *value, pref_source_t source);
246 WS_DLL_PUBLIC range_t* prefs_get_range_value_real(pref_t *pref, pref_source_t source);
248 WS_DLL_PUBLIC gboolean prefs_add_decode_as_value(pref_t *pref, guint value, gboolean replace);
249 WS_DLL_PUBLIC gboolean prefs_remove_decode_as_value(pref_t *pref, guint value, gboolean set_default);
251 WS_DLL_PUBLIC void reset_pref(pref_t *pref);
253 /** read the preferences file (or similar) and call the callback
254 * function to set each key/value pair found
258 read_prefs_file(const char *pf_path, FILE *pf, pref_set_pair_cb pref_set_pair_fct, void *private_data);
262 prefs_pref_is_default(pref_t *pref);
264 /** "Stash" a preference.
265 * Copy a preference to its stashed value. Can be called from prefs_pref_foreach().
267 * @param pref A preference.
268 * @param unused unused
271 guint pref_stash(pref_t *pref, gpointer unused _U_);
273 typedef struct pref_unstash_data
275 /* Used to set prefs_changed member to TRUE if the preference
276 differs from its stashed values. Also used by "decode as" types
277 to look up dissector short name */
279 /* Qt uses stashed values to then "applies" them
280 during unstash. Use this flag for that behavior */
281 gboolean handle_decode_as;
282 } pref_unstash_data_t;
284 /** "Unstash" a preference.
285 * Set a preference to its stashed value. Can be called from prefs_pref_foreach().
287 * @param pref A preference.
288 * @param unstash_data_p A pointer to a pref_unstash_data_t structure.
290 * @return Always returns 0.
293 guint pref_unstash(pref_t *pref, gpointer unstash_data_p);
295 /** Clean up a stashed preference.
296 * Can be called from prefs_pref_foreach().
298 * @param pref A preference.
299 * @param unused unused
301 * @return Always returns 0.
304 guint pref_clean_stash(pref_t *pref, gpointer unused _U_);
306 /** Set a stashed preference to its default value.
308 *@param pref A preference.
311 void reset_stashed_pref(pref_t *pref);
313 /** Convert a string list preference to a preference string.
315 * Given a GList of gchar pointers, create a quoted, comma-separated
316 * string. Should be used with prefs_get_string_list() and
317 * prefs_clear_string_list().
319 * @param sl String list.
320 * @return Quoted, joined, and wrapped string. May be empty.
324 join_string_list(GList *sl);
328 #endif /* __cplusplus */
330 #endif /* prefs-int.h */