Wireshark  2.9.0-477-g68ec514b
The Wireshark network protocol analyzer
prefs.h
1 /* prefs.h
2  * Definitions for preference handling routines
3  *
4  * Wireshark - Network traffic analyzer
5  * By Gerald Combs <gerald@wireshark.org>
6  * Copyright 1998 Gerald Combs
7  *
8  * SPDX-License-Identifier: GPL-2.0-or-later
9  */
10 
11 #ifndef __PREFS_H__
12 #define __PREFS_H__
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif /* __cplusplus */
17 
18 #include <glib.h>
19 
20 #include <epan/params.h>
21 #include <epan/range.h>
22 
23 #include <wsutil/color.h>
24 
25 #include "ws_symbol_export.h"
26 
27 #define PR_DEST_CMD 0
28 #define PR_DEST_FILE 1
29 
30 #define DEF_WIDTH 750
31 #define DEF_HEIGHT 550
32 
33 #define MAX_VAL_LEN 1024
34 
35 #define TAP_UPDATE_DEFAULT_INTERVAL 3000
36 #define ST_DEF_BURSTRES 5
37 #define ST_DEF_BURSTLEN 100
38 #define ST_MAX_BURSTRES 600000 /* somewhat arbirary limit of 10 minutes */
39 #define ST_MAX_BURSTBUCKETS 100 /* somewhat arbirary limit - more buckets degrade performance */
40 
41 struct epan_uat;
42 struct _e_addr_resolve;
43 
44 /*
45  * Convert a string listing name resolution types to a bitmask of
46  * those types.
47  *
48  * Set "*name_resolve" to the bitmask, and return '\0', on success;
49  * return the bad character in the string on error.
50  */
51 WS_DLL_PUBLIC
52 char string_to_name_resolve(const char *string, struct _e_addr_resolve *name_resolve);
53 
54 /*
55  * Modes for the starting directory in File Open dialogs.
56  */
57 #define FO_STYLE_LAST_OPENED 0 /* start in last directory we looked at */
58 #define FO_STYLE_SPECIFIED 1 /* start in specified directory */
59 
60 /*
61  * Toolbar styles.
62  */
63 #define TB_STYLE_ICONS 0
64 #define TB_STYLE_TEXT 1
65 #define TB_STYLE_BOTH 2
66 
67 /*
68  * Types of layout of summary/details/hex panes.
69  */
70 typedef enum {
71  layout_unused, /* entry currently unused */
72  layout_type_5,
73  layout_type_2,
74  layout_type_1,
75  layout_type_4,
76  layout_type_3,
77  layout_type_6,
78  layout_type_max
79 } layout_type_e;
80 
81 /*
82  * Types of pane.
83  */
84 typedef enum {
85  layout_pane_content_none,
86  layout_pane_content_plist,
87  layout_pane_content_pdetails,
88  layout_pane_content_pbytes
89 } layout_pane_content_e;
90 
91 /*
92  * open console behaviour (win32 only)
93  */
94 typedef enum {
95  console_open_never,
96  console_open_auto,
97  console_open_always
98 } console_open_e;
99 
100 /*
101  * Places version information will show up
102  */
103 typedef enum {
104  version_welcome_only,
105  version_title_only,
106  version_both,
107  version_neither
108 } version_info_e;
109 
110 typedef enum {
111  pref_default,
112  pref_stashed,
113  pref_current
114 } pref_source_t;
115 
116 typedef enum {
117  ELIDE_LEFT,
118  ELIDE_RIGHT,
119  ELIDE_MIDDLE,
120  ELIDE_NONE
121 } elide_mode_e;
122 
123 
124 /*
125  * Update channel.
126  */
127 typedef enum {
128  UPDATE_CHANNEL_DEVELOPMENT,
129  UPDATE_CHANNEL_STABLE
130 } software_update_channel_e;
131 
132 typedef struct _e_prefs {
133  gint pr_format;
134  gint pr_dest;
135  gchar *pr_file;
136  gchar *pr_cmd;
137  GList *col_list;
138  gint num_cols;
139  color_t st_client_fg, st_client_bg, st_server_fg, st_server_bg;
140  color_t gui_text_valid, gui_text_invalid, gui_text_deprecated;
141  gboolean gui_expert_composite_eyecandy;
142  gboolean filter_toolbar_show_in_statusbar;
143  gboolean restore_filter_after_following_stream;
144  gint gui_ptree_line_style;
145  gint gui_ptree_expander_style;
146  gint gui_toolbar_main_style;
147  gint gui_toolbar_filter_style;
148  gchar *gui_qt_font_name;
149  color_t gui_marked_fg;
150  color_t gui_marked_bg;
151  color_t gui_ignored_fg;
152  color_t gui_ignored_bg;
153  gchar *gui_colorized_fg;
154  gchar *gui_colorized_bg;
155  gboolean gui_geometry_save_position;
156  gboolean gui_geometry_save_size;
157  gboolean gui_geometry_save_maximized;
158  console_open_e gui_console_open;
159  guint gui_recent_df_entries_max;
160  guint gui_recent_files_count_max;
161  guint gui_fileopen_style;
162  gchar *gui_fileopen_dir;
163  guint gui_fileopen_preview;
164  gboolean gui_ask_unsaved;
165  gboolean gui_find_wrap;
166  gboolean gui_use_pref_save;
167  gchar *gui_webbrowser;
168  gchar *gui_window_title;
169  gchar *gui_prepend_window_title;
170  gchar *gui_start_title;
171  version_info_e gui_version_placement;
172  layout_type_e gui_layout_type;
173  layout_pane_content_e gui_layout_content_1;
174  layout_pane_content_e gui_layout_content_2;
175  layout_pane_content_e gui_layout_content_3;
176  gchar *gui_interfaces_hide_types;
177  gboolean gui_interfaces_show_hidden;
178 #ifdef HAVE_PCAP_REMOTE
179  gboolean gui_interfaces_remote_display;
180 #endif
181  gint console_log_level;
182  gchar *capture_device;
183  gchar *capture_devices_linktypes;
184  gchar *capture_devices_descr;
185  gchar *capture_devices_hide;
186  gchar *capture_devices_monitor_mode;
187 #ifdef CAN_SET_CAPTURE_BUFFER_SIZE
188  gchar *capture_devices_buffersize;
189 #endif
190  gchar *capture_devices_snaplen;
191  gchar *capture_devices_pmode;
192  gchar *capture_devices_filter; /* XXX - Mostly unused. Deprecate? */
193  gboolean capture_prom_mode;
194  gboolean capture_pcap_ng;
195  gboolean capture_real_time;
196  gboolean capture_auto_scroll; /* XXX - Move to recent */
197  gboolean capture_no_extcap;
198  gboolean capture_show_info;
199  GList *capture_columns;
200  guint tap_update_interval;
201  gboolean display_hidden_proto_items;
202  gboolean display_byte_fields_with_spaces;
203  gboolean enable_incomplete_dissectors_check;
204  gboolean incomplete_dissectors_check_debug;
205  gboolean strict_conversation_tracking_heuristics;
206  gboolean gui_update_enabled;
207  software_update_channel_e gui_update_channel;
208  gint gui_update_interval;
209  gchar *saved_at_version;
210  gboolean unknown_prefs; /* unknown or obsolete pref(s) */
211  gboolean unknown_colorfilters; /* Warn when saving unknown or obsolete color filters. */
212  gboolean gui_qt_packet_list_separator;
213  gboolean gui_qt_show_selected_packet;
214  gboolean gui_qt_show_file_load_time;
215  gboolean gui_packet_editor; /* Enable Packet Editor */
216  elide_mode_e gui_packet_list_elide_mode;
217  gboolean gui_packet_list_show_related;
218  gboolean gui_packet_list_show_minimap;
219  gboolean st_enable_burstinfo;
220  gboolean st_burst_showcount;
221  gint st_burst_resolution;
222  gint st_burst_windowlen;
223  gboolean st_sort_casesensitve;
224  gboolean st_sort_rng_fixorder;
225  gboolean st_sort_rng_nameonly;
226  gint st_sort_defcolflag;
227  gboolean st_sort_defdescending;
228  gboolean st_sort_showfullname;
229  gboolean extcap_save_on_start;
230 } e_prefs;
231 
232 WS_DLL_PUBLIC e_prefs prefs;
233 
234 /*
235  * Routines to let modules that have preference settings register
236  * themselves by name, and to let them register preference settings
237  * by name.
238  */
239 struct pref_module;
240 
241 struct pref_custom_cbs;
242 
243 typedef struct pref_module module_t;
244 
246 void prefs_init(void);
247 
249 WS_DLL_PUBLIC void prefs_reset(void);
250 
252 void prefs_cleanup(void);
253 
255 WS_DLL_PUBLIC void prefs_set_gui_theme_is_dark(gboolean is_dark);
256 
257 /*
258  * Register that a protocol has preferences.
259  */
260 WS_DLL_PUBLIC module_t *prefs_register_protocol(int id, void (*apply_cb)(void));
261 
265 void prefs_deregister_protocol(int id);
266 
267 /*
268  * Register that a statistical tap has preferences.
269  *
270  * "name" is a name for the tap to use on the command line with "-o"
271  * and in preference files.
272  *
273  * "title" is a short human-readable name for the tap.
274  *
275  * "description" is a longer human-readable description of the tap.
276  */
277 WS_DLL_PUBLIC module_t *prefs_register_stat(const char *name, const char *title,
278  const char *description, void (*apply_cb)(void));
279 
280 /*
281  * Register that a codec has preferences.
282  *
283  * "name" is a name for the codec to use on the command line with "-o"
284  * and in preference files.
285  *
286  * "title" is a short human-readable name for the codec.
287  *
288  * "description" is a longer human-readable description of the codec.
289  */
290 WS_DLL_PUBLIC module_t *prefs_register_codec(const char *name, const char *title,
291  const char *description, void (*apply_cb)(void));
292 
293 /*
294  * Register that a protocol has preferences and group it under a single
295  * subtree
296  */
297 #define PREFERENCE_GROUPING
298 WS_DLL_PUBLIC module_t *prefs_register_protocol_subtree(const char *subtree, int id,
299  void (*apply_cb)(void));
300 
301 /*
302  * Register that a protocol used to have preferences but no longer does,
303  * by creating an "obsolete" module for it.
304  */
305 module_t *prefs_register_protocol_obsolete(int id);
306 
307 /*
308  * Callback function for module list scanners.
309  */
310 typedef guint (*module_cb)(module_t *module, gpointer user_data);
311 
312 /*
313  * Returns TRUE if module has any submodules
314  */
315 WS_DLL_PUBLIC gboolean prefs_module_has_submodules(module_t *module);
316 
317 /*
318  * Call a callback function, with a specified argument, for each module
319  * in the list of all modules. (This list does not include subtrees.)
320  *
321  * Ignores "obsolete" modules; their sole purpose is to allow old
322  * preferences for dissectors that no longer have preferences to be
323  * silently ignored in preference files.
324  */
325 WS_DLL_PUBLIC guint prefs_modules_foreach(module_cb callback, gpointer user_data);
326 
327 /*
328  * Call a callback function, with a specified argument, for each submodule
329  * of specified modules. If the module is NULL, goes through the top-level
330  * list in the display tree of modules.
331  *
332  * Ignores "obsolete" modules; their sole purpose is to allow old
333  * preferences for dissectors that no longer have preferences to be
334  * silently ignored in preference files. Does not ignore subtrees,
335  * as this can be used when walking the display tree of modules.
336  */
337 WS_DLL_PUBLIC guint prefs_modules_foreach_submodules(module_t *module, module_cb callback, gpointer user_data);
338 
339 /*
340  * Call the "apply" callback function for each module if any of its
341  * preferences have changed, and then clear the flag saying its
342  * preferences have changed, as the module has been notified of that
343  * fact.
344  */
345 WS_DLL_PUBLIC void prefs_apply_all(void);
346 
347 /*
348  * Call the "apply" callback function for a specific module if any of
349  * its preferences have changed, and then clear the flag saying its
350  * preferences have changed, as the module has been notified of that
351  * fact.
352  */
353 WS_DLL_PUBLIC void prefs_apply(module_t *module);
354 
355 
356 struct preference;
357 
358 typedef struct preference pref_t;
359 
360 /*
361  * Returns TRUE if the given protocol has registered preferences.
362  */
363 WS_DLL_PUBLIC gboolean prefs_is_registered_protocol(const char *name);
364 
365 /*
366  * Returns the module title of a registered protocol (or NULL if unknown).
367  */
368 WS_DLL_PUBLIC const char *prefs_get_title_by_name(const char *name);
369 
378 WS_DLL_PUBLIC module_t *prefs_find_module(const char *name);
379 
389 WS_DLL_PUBLIC pref_t *prefs_find_preference(module_t * module, const char *pref);
390 
391 /*
392  * Register a preference with an unsigned integral value.
393  */
394 WS_DLL_PUBLIC void prefs_register_uint_preference(module_t *module, const char *name,
395  const char *title, const char *description, guint base, guint *var);
396 
397 /*
398  * prefs_register_ callers must conform to the following:
399  *
400  * Names must be in lowercase letters only (underscore allowed).
401  * Titles and descriptions must be valid UTF-8 or NULL.
402  * Titles must be short (less than 80 characters)
403  * Titles must not contain newlines.
404  */
405 
406 /*
407  * Register a preference with an Boolean value.
408  */
409 WS_DLL_PUBLIC void prefs_register_bool_preference(module_t *module, const char *name,
410  const char *title, const char *description, gboolean *var);
411 
412 /*
413  * Register a preference with an enumerated value.
414  */
415 WS_DLL_PUBLIC void prefs_register_enum_preference(module_t *module, const char *name,
416  const char *title, const char *description, gint *var,
417  const enum_val_t *enumvals, gboolean radio_buttons);
418 
419 /*
420  * Register a preference with a character-string value.
421  */
422 WS_DLL_PUBLIC void prefs_register_string_preference(module_t *module, const char *name,
423  const char *title, const char *description, const char **var);
424 
425 /*
426  * Register a preference with a file name (string) value.
427  * File name preferences are basically like string preferences
428  * except that the GUI gives the user the ability to browse for the
429  * file.
430  */
431 WS_DLL_PUBLIC void prefs_register_filename_preference(module_t *module, const char *name,
432  const char *title, const char *description, const char **var, gboolean for_writing);
433 
434 /*
435  * Register a preference with a directory name (string) value.
436  * Directory name preferences are basically like string preferences
437  * except that the GUI gives the user the ability to browse for a
438  * directory.
439  */
440 WS_DLL_PUBLIC void prefs_register_directory_preference(module_t *module, const char *name,
441  const char *title, const char *description, const char **var);
442 
443 /*
444  * Register a preference with a ranged value.
445  */
446 WS_DLL_PUBLIC void prefs_register_range_preference(module_t *module, const char *name,
447  const char *title, const char *description, range_t **var,
448  guint32 max_value);
449 
450 /*
451  * Register a static text 'preference'. It can be used to add some info/explanation.
452  */
453 WS_DLL_PUBLIC void prefs_register_static_text_preference(module_t *module, const char *name,
454  const char *title, const char *description);
455 
456 /*
457  * Register a uat 'preference'. It adds a button that opens the uat's window in the
458  * preferences tab of the module.
459  */
460 WS_DLL_PUBLIC void prefs_register_uat_preference(module_t *module,
461  const char *name, const char* title, const char *description, struct epan_uat* uat);
462 
463 /*
464  * Register a uat 'preference' for QT only. It adds a button that opens the uat's window in the
465  * preferences tab of the module.
466  */
467 WS_DLL_PUBLIC void prefs_register_uat_preference_qt(module_t *module,
468  const char *name, const char* title, const char *description, struct epan_uat* uat);
469 
470 
471 /*
472  * Register a color preference. Currently does not have any "GUI Dialog" support
473  * so the color data needs to be managed independently. Currently used by the
474  * "GUI preferences" to aid in reading/writing the preferences file, but the
475  * "data" is still managed by the specific "GUI preferences" dialog.
476  */
477 void prefs_register_color_preference(module_t *module, const char *name,
478  const char *title, const char *description, color_t *color);
479 
480 /*
481  * Register a custom preference. Currently does not have any "GUI Dialog" support
482  * so data needs to be managed independently. Currently used by the
483  * "GUI preferences" to aid in reading/writing the preferences file, but the
484  * "data" is still managed by the specific "GUI preferences" dialog.
485  */
486 void prefs_register_custom_preference(module_t *module, const char *name,
487  const char *title, const char *description, struct pref_custom_cbs* custom_cbs,
488  void** custom_data);
489 
490 /*
491  * Register a (internal) "Decode As" preference with a ranged value.
492  */
493 void prefs_register_decode_as_range_preference(module_t *module, const char *name,
494  const char *title, const char *description, range_t **var,
495  guint32 max_value);
496 
497 /*
498  * Register a (internal) "Decode As" preference with an unsigned integral value
499  * for a dissector table.
500  */
501 void prefs_register_decode_as_preference(module_t *module, const char *name,
502  const char *title, const char *description, guint *var);
503 
504 /*
505  * Register a preference that used to be supported but no longer is.
506  */
507 WS_DLL_PUBLIC void prefs_register_obsolete_preference(module_t *module,
508  const char *name);
509 
510 
511 typedef guint (*pref_cb)(pref_t *pref, gpointer user_data);
512 
513 /*
514  * Call a callback function, with a specified argument, for each preference
515  * in a given module.
516  *
517  * If any of the callbacks return a non-zero value, stop and return that
518  * value, otherwise return 0.
519  */
520 WS_DLL_PUBLIC guint prefs_pref_foreach(module_t *module, pref_cb callback,
521  gpointer user_data);
522 
523 /* Parse through a list of comma-separated, possibly quoted strings.
524  * Return a list of the string data.
525  */
526 WS_DLL_PUBLIC GList *prefs_get_string_list(const gchar *str);
527 
528 /* Clear the given list of string data. */
529 WS_DLL_PUBLIC void prefs_clear_string_list(GList *sl);
530 
537 WS_DLL_PUBLIC
538 const char *prefs_pref_type_name(pref_t *pref);
539 
548 WS_DLL_PUBLIC
549 char *prefs_pref_type_description(pref_t *pref);
550 
558 WS_DLL_PUBLIC
559 char *prefs_pref_to_str(pref_t *pref, pref_source_t source);
560 
561 /* Read the preferences file, fill in "prefs", and return a pointer to it.
562 
563  If we got an error (other than "it doesn't exist") we report it through
564  the UI.
565 
566  This is called by epan_load_settings(); programs should call that
567  rather than individually calling the routines it calls. */
568 extern e_prefs *read_prefs(void);
569 
570 /* Write out "prefs" to the user's preferences file, and return 0.
571 
572  If we got an error, stuff a pointer to the path of the preferences file
573  into "*pf_path_return", and return the errno. */
574 WS_DLL_PUBLIC int write_prefs(char **);
575 
579 typedef enum {
580  PREFS_SET_OK, /* succeeded */
581  PREFS_SET_SYNTAX_ERR, /* syntax error in string */
582  PREFS_SET_NO_SUCH_PREF, /* no such preference */
583  PREFS_SET_OBSOLETE /* preference used to exist but no longer does */
584 } prefs_set_pref_e;
585 
586 /*
587  * Given a string of the form "<pref name>:<pref value>", as might appear
588  * as an argument to a "-o" option, parse it and set the preference in
589  * question. Return an indication of whether it succeeded or failed
590  * in some fashion.
591  *
592  * For syntax errors (return value PREFS_SET_SYNTAX_ERR), details (when
593  * available) are written into "errmsg" which must be freed with g_free.
594  */
595 WS_DLL_PUBLIC prefs_set_pref_e prefs_set_pref(char *prefarg, char **errmsg);
596 
597 /*
598  * Get or set a preference's obsolete status. These can be used to make a
599  * preference obsolete after startup so that we can fetch its value but
600  * keep it from showing up in the prefrences dialog.
601  */
602 gboolean prefs_get_preference_obsolete(pref_t *pref);
603 prefs_set_pref_e prefs_set_preference_obsolete(pref_t *pref);
604 
605 /*
606  * Get current preference uint value. This allows the preference structure
607  * to remain hidden from those that doesn't really need it
608  */
609 WS_DLL_PUBLIC guint prefs_get_uint_value(const char *module_name, const char* pref_name);
610 
611 /*
612  * Get the current range preference value (maintained by pref, so it doesn't need to be freed). This allows the
613  * preference structure to remain hidden from those that doesn't really need it.
614  */
615 WS_DLL_PUBLIC range_t* prefs_get_range_value(const char *module_name, const char* pref_name);
616 
617 /*
618  * Returns TRUE if the given device is hidden
619  */
620 WS_DLL_PUBLIC gboolean prefs_is_capture_device_hidden(const char *name);
621 
622 /*
623  * Returns TRUE if the given device should capture in monitor mode by default
624  */
625 WS_DLL_PUBLIC gboolean prefs_capture_device_monitor_mode(const char *name);
626 
627 WS_DLL_PUBLIC gboolean prefs_capture_options_dialog_column_is_visible(const gchar *column);
628 
629 /*
630  * Returns TRUE if the layout pane content is enabled
631  */
632 WS_DLL_PUBLIC gboolean prefs_has_layout_pane_content (layout_pane_content_e layout_pane_content);
633 
634 #ifdef __cplusplus
635 }
636 #endif /* __cplusplus */
637 
638 #endif /* prefs.h */
639 
640 /*
641  * Editor modelines - http://www.wireshark.org/tools/modelines.html
642  *
643  * Local variables:
644  * c-basic-offset: 4
645  * tab-width: 8
646  * indent-tabs-mode: nil
647  * End:
648  *
649  * vi: set shiftwidth=4 tabstop=8 expandtab:
650  * :indentSize=4:tabSize=8:noTabs=true:
651  */
Flags to control name resolution.
Definition: addr_resolv.h:48
const char * description
Definition: prefs-int.h:30
Definition: prefs-int.h:27
const char * title
Definition: prefs-int.h:29
guint32 max_value
Definition: prefs.c:231
const enum_val_t * enumvals
Definition: prefs.c:233
Definition: prefs-int.h:74
Definition: color.h:20
Definition: sttype-range.c:22
Definition: prefs.c:192
Definition: prefs.h:132
Definition: params.h:22
struct pref_custom_cbs custom_cbs
Definition: prefs.c:240
gboolean radio_buttons
Definition: prefs.c:234
Definition: uat-int.h:39
guint base
Definition: prefs.c:230
const char * name
Definition: prefs-int.h:28
void(* apply_cb)(void)
Definition: prefs-int.h:31