summaryrefslogtreecommitdiffstats
path: root/epan/prefs.h
blob: 8addcf7fc91f321745822fb872f1482cb0d1ad79 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
/** @file prefs.h
 * Definitions for preference handling routines
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

#ifndef __PREFS_H__
#define __PREFS_H__

#include <glib.h>

#include <epan/params.h>
#include <epan/range.h>

#include <wsutil/color.h>

#include "ws_symbol_export.h"

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

#define DEF_WIDTH 750
#define DEF_HEIGHT 550

#define MAX_VAL_LEN  1024

#define TAP_UPDATE_DEFAULT_INTERVAL 3000
#define ST_DEF_BURSTRES 5
#define ST_DEF_BURSTLEN 100
#define ST_MAX_BURSTRES 600000 /* somewhat arbirary limit of 10 minutes */
#define ST_MAX_BURSTBUCKETS 100 /* somewhat arbirary limit - more buckets degrade performance */
#define DEF_GUI_DECIMAL_PLACES1 2
#define DEF_GUI_DECIMAL_PLACES2 4
#define DEF_GUI_DECIMAL_PLACES3 6

struct epan_uat;
struct _e_addr_resolve;

/**
 * Convert a string listing name resolution types to a bitmask of
 * those types.
 *
 * Set "*name_resolve" to the bitmask, and return '\0', on success;
 * return the bad character in the string on error.
 *
 * @param string a list of name resolution types
 * @param name_resolve the bitmap of names to resolve to set
 * @return '\0' on success, the bad character in the string on error
 */
WS_DLL_PUBLIC
char string_to_name_resolve(const char *string, struct _e_addr_resolve *name_resolve);

/*
 * Modes for the starting directory in File Open dialogs.
 */
#define FO_STYLE_LAST_OPENED    0 /* start in last directory we looked at */
#define FO_STYLE_SPECIFIED      1 /* start in specified directory */

/*
 * Toolbar styles.
 */
#define TB_STYLE_ICONS          0
#define TB_STYLE_TEXT           1
#define TB_STYLE_BOTH           2

/*
 * Color styles.
 */
#define COLOR_STYLE_DEFAULT     0
#define COLOR_STYLE_FLAT        1
#define COLOR_STYLE_GRADIENT    2

#define COLOR_STYLE_ALPHA       0.25

/*
 * Types of layout of summary/details/hex panes.
 */
typedef enum {
    layout_unused,  /* entry currently unused */
    layout_type_5,
    layout_type_2,
    layout_type_1,
    layout_type_4,
    layout_type_3,
    layout_type_6,
    layout_type_max
} layout_type_e;

/*
 * Types of pane.
 */
typedef enum {
    layout_pane_content_none,
    layout_pane_content_plist,
    layout_pane_content_pdetails,
    layout_pane_content_pbytes,
    layout_pane_content_pdiagram,
} layout_pane_content_e;

/*
 * Places version information will show up
 */
typedef enum {
    version_welcome_only,
    version_title_only,
    version_both,
    version_neither
} version_info_e;

typedef enum {
    pref_default,
    pref_stashed,
    pref_current
} pref_source_t;

typedef enum {
    ELIDE_LEFT,
    ELIDE_RIGHT,
    ELIDE_MIDDLE,
    ELIDE_NONE
} elide_mode_e;


/*
 * Update channel.
 */
typedef enum {
    UPDATE_CHANNEL_DEVELOPMENT,
    UPDATE_CHANNEL_STABLE
} software_update_channel_e;

typedef struct _e_prefs {
  GList       *col_list;
  gint         num_cols;
  color_t      st_client_fg, st_client_bg, st_server_fg, st_server_bg;
  color_t      gui_text_valid, gui_text_invalid, gui_text_deprecated;
  gboolean     restore_filter_after_following_stream;
  gint         gui_toolbar_main_style;
  gchar       *gui_font_name;
  color_t      gui_active_fg;
  color_t      gui_active_bg;
  gint         gui_active_style;
  color_t      gui_inactive_fg;
  color_t      gui_inactive_bg;
  gint         gui_inactive_style;
  color_t      gui_marked_fg;
  color_t      gui_marked_bg;
  color_t      gui_ignored_fg;
  color_t      gui_ignored_bg;
  gchar       *gui_colorized_fg;
  gchar       *gui_colorized_bg;
  gboolean     gui_geometry_save_position;
  gboolean     gui_geometry_save_size;
  gboolean     gui_geometry_save_maximized;
  guint        gui_recent_df_entries_max;
  guint        gui_recent_files_count_max;
  guint        gui_fileopen_style;
  gchar       *gui_fileopen_dir;
  guint        gui_fileopen_preview;
  gchar       *gui_tlskeylog_command;
  gboolean     gui_ask_unsaved;
  gboolean     gui_autocomplete_filter;
  gboolean     gui_find_wrap;
  gchar       *gui_window_title;
  gchar       *gui_prepend_window_title;
  gchar       *gui_start_title;
  version_info_e gui_version_placement;
  guint        gui_max_export_objects;
  guint        gui_max_tree_items;
  guint        gui_max_tree_depth;
  layout_type_e gui_layout_type;
  layout_pane_content_e gui_layout_content_1;
  layout_pane_content_e gui_layout_content_2;
  layout_pane_content_e gui_layout_content_3;
  gchar       *gui_interfaces_hide_types;
  gboolean     gui_interfaces_show_hidden;
  gboolean     gui_interfaces_remote_display;
  gboolean     gui_io_graph_automatic_update;
  gboolean     gui_io_graph_enable_legend;
  gboolean     gui_packet_details_show_byteview;
  gchar       *capture_device;
  gchar       *capture_devices_linktypes;
  gchar       *capture_devices_descr;
  gchar       *capture_devices_hide;
  gchar       *capture_devices_monitor_mode;
  gchar       *capture_devices_buffersize;
  gchar       *capture_devices_snaplen;
  gchar       *capture_devices_pmode;
  gchar       *capture_devices_filter; /* XXX - Mostly unused. Deprecate? */
  gboolean     capture_prom_mode;
  gboolean     capture_pcap_ng;
  gboolean     capture_real_time;
  guint        capture_update_interval;
  gboolean     capture_no_interface_load;
  gboolean     capture_no_extcap;
  gboolean     capture_show_info;
  GList       *capture_columns;
  guint        tap_update_interval;
  gboolean     display_hidden_proto_items;
  gboolean     display_byte_fields_with_spaces;
  gboolean     enable_incomplete_dissectors_check;
  gboolean     incomplete_dissectors_check_debug;
  gboolean     strict_conversation_tracking_heuristics;
  gboolean     ignore_dup_frames;
  guint        ignore_dup_frames_cache_entries;
  gboolean     filter_expressions_old;  /* TRUE if old filter expressions preferences were loaded. */
  gboolean     gui_update_enabled;
  software_update_channel_e gui_update_channel;
  gint         gui_update_interval;
  gint         gui_debounce_timer;
  gchar       *saved_at_version;
  gboolean     unknown_prefs; /* unknown or obsolete pref(s) */
  gboolean     gui_packet_list_separator;
  gboolean     gui_packet_header_column_definition;
  gboolean     gui_packet_list_hover_style; /* Enable/Disable mouse-over colorization */
  gboolean     gui_show_selected_packet;
  gboolean     gui_show_file_load_time;
  elide_mode_e gui_packet_list_elide_mode;
  gboolean     gui_packet_list_show_related;
  gboolean     gui_packet_list_show_minimap;
  gboolean     gui_packet_list_sortable;
  guint        gui_packet_list_cached_rows_max;
  gint         gui_decimal_places1; /* Used for type 1 calculations */
  gint         gui_decimal_places2; /* Used for type 2 calculations */
  gint         gui_decimal_places3; /* Used for type 3 calculations */
  gboolean     gui_rtp_player_use_disk1;
  gboolean     gui_rtp_player_use_disk2;
  gboolean     st_enable_burstinfo;
  gboolean     st_burst_showcount;
  gint         st_burst_resolution;
  gint         st_burst_windowlen;
  gboolean     st_sort_casesensitve;
  gboolean     st_sort_rng_fixorder;
  gboolean     st_sort_rng_nameonly;
  gint         st_sort_defcolflag;
  gboolean     st_sort_defdescending;
  gboolean     st_sort_showfullname;
  gboolean     extcap_save_on_start;
} e_prefs;

WS_DLL_PUBLIC e_prefs prefs;

/*
 * Routines to let modules that have preference settings register
 * themselves by name, and to let them register preference settings
 * by name.
 */
struct pref_module;

struct pref_custom_cbs;

typedef struct pref_module module_t;

/** Sets up memory used by proto routines. Called at program startup */
void prefs_init(void);

/** Reset preferences to default values.  Called at profile change */
WS_DLL_PUBLIC void prefs_reset(void);

/** Frees memory used by proto routines. Called at program shutdown */
void prefs_cleanup(void);

/** Store whether the current UI theme is dark so that we can adjust colors
* @param is_dark set to TRUE if the UI's theme is dark
*/
WS_DLL_PUBLIC void prefs_set_gui_theme_is_dark(gboolean is_dark);

/**
 * Register that a protocol has preferences.
 * @param id the value returned by "proto_register_protocol()" when
 *                the protocol was registered.
 * @param apply_cb callback routine that is called when preferences are
 *                      applied. It may be NULL, which inhibits the callback.
 * @return a preferences module which can be used to register a user 'preference'
 */
WS_DLL_PUBLIC module_t *prefs_register_protocol(int id, void (*apply_cb)(void));

/**
 * Register an alias for a preference module.
 * @param name the preference module's alias. Only ASCII letters, numbers,
 *                  underscores, hyphens, and dots may appear in the name
 * @param module the module to create an alias for
 */
WS_DLL_PUBLIC void prefs_register_module_alias(const char *name, module_t *module);

/**
 * Deregister preferences from a protocol.
 * @param id the value returned by "proto_register_protocol()" when
 *                the protocol was registered.
 */
void prefs_deregister_protocol(int id);

/**
 * Register that a statistical tap has preferences.
 *
 * @param name the name for the tap to use on the command line with "-o"
 *             and in preference files.
 * @param title is a short human-readable name for the tap.
 * @param description is a longer human-readable description of the tap.
 * @param apply_cb routine to call back after we apply the preferences
 * @return a preferences module which can be used to register a user 'preference'
 */
WS_DLL_PUBLIC module_t *prefs_register_stat(const char *name, const char *title,
    const char *description, void (*apply_cb)(void));

/**
 * Register that a codec has preferences.
 *
 * @param name is a name for the codec to use on the command line with "-o"
 *             and in preference files.
 * @param title is a short human-readable name for the codec.
 * @param description is a longer human-readable description of the codec.
 * @param apply_cb routine to call back after we apply the preferences
 * @return a preferences module which can be used to register a user 'preference'
 */
WS_DLL_PUBLIC module_t *prefs_register_codec(const char *name, const char *title,
    const char *description, void (*apply_cb)(void));

/**
 * Register that a protocol has preferences and group it under a single
 * subtree
 * @param subtree the tree node name for grouping preferences
 *                the protocol was registered.
 * @param id the value returned by "proto_register_protocol()" when
 *                the protocol was registered.
 * @param apply_cb Callback routine that is called when preferences are
 *                      applied. It may be NULL, which inhibits the callback.
 * @return a preferences module which can be used to register a user 'preference'
 */
WS_DLL_PUBLIC module_t *prefs_register_protocol_subtree(const char *subtree, int id,
    void (*apply_cb)(void));

/**
 * Register that a protocol used to have preferences but no longer does,
 * by creating an "obsolete" module for it.
 * @param id the value returned by "proto_register_protocol()" when
 *                the protocol was registered.
 * @return a preferences module which can be used to register a user 'preference'
 */
WS_DLL_PUBLIC module_t *prefs_register_protocol_obsolete(int id);

/**
 * Callback function for module list scanners.
 */
typedef guint (*module_cb)(module_t *module, gpointer user_data);

/**
 * Returns TRUE if a preferences module has any submodules
 * @param module a preferences module which can be used to register a user 'preference'
 * @return TRUE if a preferences module has any submodules, otherwise FALSE
 */
WS_DLL_PUBLIC gboolean prefs_module_has_submodules(module_t *module);

/**
 * Call a callback function, with a specified argument, for each module
 * in the list of all modules.  (This list does not include subtrees.)
 *
 * Ignores "obsolete" modules; their sole purpose is to allow old
 * preferences for dissectors that no longer have preferences to be
 * silently ignored in preference files.
 *
 * @param callback the callback to call
 * @param user_data additional data to pass to the callback
 */
WS_DLL_PUBLIC guint prefs_modules_foreach(module_cb callback, gpointer user_data);

/**
 * Call a callback function, with a specified argument, for each submodule
 * of a specified module. If the module is NULL, goes through the top-level
 * list in the display tree of modules.
 *
 * Ignores "obsolete" modules; their sole purpose is to allow old
 * preferences for dissectors that no longer have preferences to be
 * silently ignored in preference files.  Does not ignore subtrees,
 * as this can be used when walking the display tree of modules.
 *
 * @param module the top-level module to walk through the submodules,
 *               or NULL for the top-level list in the display tree of modules
 * @param callback the callback to call
 * @param user_data additional data to pass to the callback
 */
WS_DLL_PUBLIC guint prefs_modules_foreach_submodules(module_t *module, module_cb callback, gpointer user_data);

/**
 * Call the "apply" callback function for each module if any of its
 * preferences have changed, and then clear the flag saying its
 * preferences have changed, as the module has been notified of that
 * fact.
 */
WS_DLL_PUBLIC void prefs_apply_all(void);

/**
 * Call the "apply" callback function for a specific module if any of
 * its preferences have changed, and then clear the flag saying its
 * preferences have changed, as the module has been notified of that
 * fact.
 * @param module the module to call the 'apply' callback function for
 */
WS_DLL_PUBLIC void prefs_apply(module_t *module);


struct preference;

typedef struct preference pref_t;

/**
 * Returns TRUE if the provided protocol has registered preferences.
 * @param name the name of the protocol to look up
 * @return TRUE if the given protocol has registered preferences, otherwise FALSE
 */
WS_DLL_PUBLIC gboolean prefs_is_registered_protocol(const char *name);

/**
 * Returns the module title of a registered protocol (or NULL if unknown).
 * @param name the name of the protocol to look up
 * @return the module title of a registered protocol, otherwise NULL
 */
WS_DLL_PUBLIC const char *prefs_get_title_by_name(const char *name);

/** Given a module name, return a pointer to its pref_module struct,
 * or NULL if it's not found.
 *
 * @param name The preference module name.  Usually the same as the protocol
 * name, e.g. "tcp".
 * @return A pointer to the corresponding preference module, or NULL if it
 * wasn't found.
 */
WS_DLL_PUBLIC module_t *prefs_find_module(const char *name);

/** Given a module and a preference name, return a pointer to the given
 * module's given preference or NULL if it's not found.
 *
 * @param module The preference module name.  Usually the same as the protocol
 * name, e.g. "tcp".
 * @param pref The preference name, e.g. "desegment".
 * @return A pointer to the corresponding preference, or NULL if it
 * wasn't found.
 */
WS_DLL_PUBLIC pref_t *prefs_find_preference(module_t * module, const char *pref);

/**
 * Register a preference with an unsigned integral value.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title the title in the preferences dialog
 * @param description the description included in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param base the base the unsigned integer is expected to be in. See strtoul(3)
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box
 */
WS_DLL_PUBLIC void prefs_register_uint_preference(module_t *module, const char *name,
    const char *title, const char *description, guint base, guint *var);

/*
 * prefs_register_ callers must conform to the following:
 *
 * Names must be in lowercase letters only (underscore allowed).
 * Titles and descriptions must be valid UTF-8 or NULL.
 * Titles must be short (less than 80 characters)
 * Titles must not contain newlines.
 */

/**
 * Register a preference with an Boolean value.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box
 */
WS_DLL_PUBLIC void prefs_register_bool_preference(module_t *module, const char *name,
    const char *title, const char *description, gboolean *var);

/**
 * Register a preference with an enumerated value.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box
 * @param enumvals a null-terminated array of enum_val_t structures
 * @param radio_buttons TRUE if the field is to be displayed in the
 *                  preferences dialog as a set of radio buttons,
 *                  FALSE if it is to be displayed as an option menu
 */
WS_DLL_PUBLIC void prefs_register_enum_preference(module_t *module, const char *name,
    const char *title, const char *description, gint *var,
    const enum_val_t *enumvals, gboolean radio_buttons);

/**
 * Register a preference with a character-string value.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box. Note that
 *          with string preferences the given pointer is overwritten
 *          with a pointer to a new copy of the string during the
 *          preference registration. The passed-in string may be
 *          freed, but you must keep another pointer to the string
 *          in order to free it
 */
WS_DLL_PUBLIC void prefs_register_string_preference(module_t *module, const char *name,
    const char *title, const char *description, const char **var);

/**
 * Register a preference with a file name (string) value.
 *
 * File name preferences are basically like string preferences
 * except that the GUI gives the user the ability to browse for the
 * file.
 *
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box. Note that
 *          the given pointer is overwritten
 *          with a pointer to a new copy of the string during the
 *          preference registration. The passed-in string may be
 *          freed, but you must keep another pointer to the string
 *          in order to free it
 * @param for_writing TRUE to display a Save dialog, FALSE to display an Open dialog.
 */
WS_DLL_PUBLIC void prefs_register_filename_preference(module_t *module, const char *name,
    const char *title, const char *description, const char **var, gboolean for_writing);

/**
 * Register a preference with a directory name (string) value.
 * Directory name preferences are basically like string preferences
 * except that the GUI gives the user the ability to browse for a
 * directory.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box. Note that
 *          the given pointer is overwritten
 *          with a pointer to a new copy of the string during the
 *          preference registration. The passed-in string may be
 *          freed, but you must keep another pointer to the string
 *          in order to free it
 */
WS_DLL_PUBLIC void prefs_register_directory_preference(module_t *module, const char *name,
    const char *title, const char *description, const char **var);

/**
 * Register a preference with a ranged value.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box.
 * @param max_value the maximum allowed value for a range (0 is the minimum)
 */
WS_DLL_PUBLIC void prefs_register_range_preference(module_t *module, const char *name,
    const char *title, const char *description, range_t **var,
    guint32 max_value);

/**
 * Register a static text 'preference'. It can be used to add some info/explanation.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 */
WS_DLL_PUBLIC void prefs_register_static_text_preference(module_t *module, const char *name,
    const char *title, const char *description);

/**
 * Register a uat (User Accessible Table) 'preference'. It adds a button that opens the uat's window in the
 * preferences tab of the module.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param uat the uat object that will be updated when the
 *                    field is changed in the preference dialog box
 */
WS_DLL_PUBLIC void prefs_register_uat_preference(module_t *module,
    const char *name, const char* title, const char *description,  struct epan_uat* uat);

/**
 * Register a uat 'preference' for QT only. It adds a button that opens the uat's window in the
 * preferences tab of the module.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param uat the uat object that will be updated when the
 *                    field is changed in the preference dialog box
 */
WS_DLL_PUBLIC void prefs_register_uat_preference_qt(module_t *module,
    const char *name, const char* title, const char *description,  struct epan_uat* uat);


/**
 * Register a color preference.  Currently does not have any "GUI Dialog" support
 * so the color data needs to be managed independently.  Currently used by the
 * "GUI preferences" to aid in reading/writing the preferences file, but the
 * "data" is still managed by the specific "GUI preferences" dialog.
 *
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param color the color object that will be updated when the
 *                    field is changed in the preference dialog box
 */
void prefs_register_color_preference(module_t *module, const char *name,
    const char *title, const char *description, color_t *color);

/**
 * Register a custom preference.  Currently does not have any "GUI Dialog" support
 * so data needs to be managed independently.  Currently used by the
 * "GUI preferences" to aid in reading/writing the preferences file, but the
 * "data" is still managed by the specific "GUI preferences" dialog.
 *
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param custom_cbs a structure with the custom preference's callbacks
 * @param custom_data currently unused
 */
void prefs_register_custom_preference(module_t *module, const char *name,
    const char *title, const char *description, struct pref_custom_cbs* custom_cbs,
    void** custom_data);

/**
 * Register a (internal) "Decode As" preference with a ranged value.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box.
 * @param max_value the maximum allowed value for a range (0 is the minimum)
 */
void prefs_register_decode_as_range_preference(module_t *module, const char *name,
    const char *title, const char *description, range_t **var,
    guint32 max_value);

/**
 * Register a preference with an password (password is never stored).
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title the title in the preferences dialog
 * @param description the description included in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box
 */
WS_DLL_PUBLIC void prefs_register_password_preference(module_t *module, const char *name,
    const char *title, const char *description, const char **var);

/**
 * Register a preference that used to be supported but no longer is.
 *
 * Note that a warning will pop up if you've saved such preference to the
 * preference file and you subsequently take the code out. The way to make
 * a preference obsolete is to register it with prefs_register_obsolete_preference()
 *
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 */
WS_DLL_PUBLIC void prefs_register_obsolete_preference(module_t *module,
    const char *name);

/**
 * Register a preference with an enumerated value.
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 * @param title Field's title in the preferences dialog
 * @param description description to include in the preferences file
 *                    and shown as tooltip in the GUI, or NULL
 * @param var pointer to the storage location that is updated when the
 *                    field is changed in the preference dialog box
 * @param enumvals a null-terminated array of enum_val_t structures
 * @param radio_buttons TRUE if the field is to be displayed in the
 *                  preferences dialog as a set of radio buttons,
 *                  FALSE if it is to be displayed as an option menu
 */
WS_DLL_PUBLIC void prefs_register_custom_preference_TCP_Analysis(module_t *module, const char *name,
    const char *title, const char *description, gint *var,
    const enum_val_t *enumvals, gboolean radio_buttons);

/**
 * Mark a preference that affects fields change. This works for bool, enum,
 * int, string (containing filename), range preferences. UAT is not included,
 * because you can specified UAT_AFFECTS_FIELDS at uat_new().
  *
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param name the preference's identifier. This is appended to the name of the
 *             protocol, with a "." between them, to create a unique identifier.
 *             The identifier should not include the protocol name, as the name in
 *             the preference file will already have it. Make sure that
 *             only lower-case ASCII letters, numbers, underscores and
 *             dots appear in the preference name.
 */
WS_DLL_PUBLIC void prefs_set_preference_effect_fields(module_t *module,
    const char *name);


typedef guint (*pref_cb)(pref_t *pref, gpointer user_data);

/**
 * Call a callback function, with a specified argument, for each preference
 * in a given module.
 *
 * If any of the callbacks return a non-zero value, stop and return that
 * value, otherwise return 0.
 *
 * @param module the preferences module returned by prefs_register_protocol() or
 *               prefs_register_protocol_subtree()
 * @param callback the callback to call
 * @param user_data additional data to pass to the callback
 * @return If any of the callbacks return a non-zero value, stop and return that
 *         value, otherwise return 0.
 */
WS_DLL_PUBLIC guint prefs_pref_foreach(module_t *module, pref_cb callback,
    gpointer user_data);

/**
 * Parse through a list of comma-separated, possibly quoted strings.
 * Return a list of the string data.
 *
 * Commas, whitespace, and the quotes surrounding entries are removed.
 * Quotes and backslashes escaped with a backslash (\") will remain.
 *
 * @param str a list of comma-separated, possibly quoted strings
 * @return a list of the string data, or NULL if there's an error
 */
WS_DLL_PUBLIC GList *prefs_get_string_list(const gchar *str);

/**
 * Clear the given list of string data.
 * @param sl the GList to clear
 */
WS_DLL_PUBLIC void prefs_clear_string_list(GList *sl);

/** Fetch a short preference type name, e.g. "Integer".
 *
 * @param pref A preference.
 *
 * @return The preference type name. May be NULL.
 */
WS_DLL_PUBLIC
const char *prefs_pref_type_name(pref_t *pref);

/** Fetch a long description of the preference type
 *
 * @param pref A preference.
 *
 * @return A description of the preference type including allowed
 * values for enums. The description may include newlines. Must be
 * g_free()d.
 */
WS_DLL_PUBLIC
char *prefs_pref_type_description(pref_t *pref);

/** Fetch a string representation of the preference.
 *
 * @param pref A preference.
 * @param source Which value of the preference to return, see pref_source_t.
 *
 * @return A string representation of the preference. Must be g_free()d.
 */
WS_DLL_PUBLIC
char *prefs_pref_to_str(pref_t *pref, pref_source_t source);

/**
 * Read the preferences file, fill in "prefs", and return a pointer to it.
 * If we got an error (other than "it doesn't exist") we report it through
 * the UI.
 *
 * This is called by epan_load_settings(); programs should call that
 * rather than individually calling the routines it calls.
 *
 * @return a pointer to the filled in prefs object
*/
extern e_prefs *read_prefs(void);

/**
 * Write out "prefs" to the user's preferences file, and return 0.
 *
 * If we got an error, stuff a pointer to the path of the preferences file
 * into "*pf_path_return", and return the errno.
 *
 * @param pf_path_return The path to write preferences to or NULL for stdout
 * @return 0 if success, otherwise errno
*/
WS_DLL_PUBLIC int write_prefs(char **pf_path_return);

/**
 * Result of setting a preference.
 */
typedef enum {
    PREFS_SET_OK,               /* succeeded */
    PREFS_SET_SYNTAX_ERR,       /* syntax error in string */
    PREFS_SET_NO_SUCH_PREF,     /* no such preference */
    PREFS_SET_OBSOLETE          /* preference used to exist but no longer does */
} prefs_set_pref_e;

/**
 * Given a string of the form "<pref name>:<pref value>", as might appear
 * as an argument to a "-o" option, parse it and set the preference in
 * question.  Return an indication of whether it succeeded or failed
 * in some fashion.
 *
 * For syntax errors (return value PREFS_SET_SYNTAX_ERR), details (when
 * available) are written into "errmsg" which must be freed with g_free.
 *
 * @param prefarg a string of the form "<pref name>:<pref value>"
 * @param errmsg storage for syntax error details
 * @return the result from attempting to set the preference
 */
WS_DLL_PUBLIC prefs_set_pref_e prefs_set_pref(char *prefarg, char **errmsg);

/**
 * Get or set a preference's obsolete status. These can be used to make a
 * preference obsolete after startup so that we can fetch its value but
 * keep it from showing up in the prefrences dialog.
 *
 * @param pref A preference.
 * @return TRUE if the preference is obsolete, otherwise FALSE
 */
gboolean prefs_get_preference_obsolete(pref_t *pref);

/**
 * Make a preference obsolete
 *
 * @param pref a preference.
 * @return the result from attempting to set the preference
 */
prefs_set_pref_e prefs_set_preference_obsolete(pref_t *pref);

/**
 * Get current preference uint value. This allows the preference structure
 * to remain hidden from those that doesn't really need it
 *
 * @param module_name the preference module name. Usually the same as the protocol
 *                    name, e.g. "tcp".
 * @param pref_name the preference name, e.g. "desegment".
 * @return the preference's value
 */
WS_DLL_PUBLIC guint prefs_get_uint_value(const char *module_name, const char* pref_name);

/**
 * Get the current range preference value (maintained by pref, so it doesn't need to be freed). This allows the
 * preference structure to remain hidden from those that doesn't really need it.
 *
 * @param module_name the preference module name. Usually the same as the protocol
 *                    name, e.g. "tcp".
 * @param pref_name the preference name, e.g. "desegment".
 * @return the preference's value
 */
WS_DLL_PUBLIC range_t* prefs_get_range_value(const char *module_name, const char* pref_name);

/**
 * Returns TRUE if the specified capture device is hidden
 * @param name the name of the capture device
 * @return TRUE if the specified capture device is hidden, otherwise FALSE
 */
WS_DLL_PUBLIC gboolean prefs_is_capture_device_hidden(const char *name);

/**
 * Returns TRUE if the given device should capture in monitor mode by default
 * @param name the name of the capture device
 * @return TRUE if the specified capture device should capture in monitor mode by default, otherwise FALSE
 */
WS_DLL_PUBLIC gboolean prefs_capture_device_monitor_mode(const char *name);

/**
 * Returns TRUE if the user has marked this column as visible
 *
 * @param column the name of the column
 * @return TRUE if this column as visible, otherwise FALSE
 */
WS_DLL_PUBLIC gboolean prefs_capture_options_dialog_column_is_visible(const gchar *column);

/**
 * Returns TRUE if the layout pane content is enabled
 *
 * @param layout_pane_content the layout pane content to check
 * @return TRUE if the layout pane content is enabled, otherwise FALSE
 */
WS_DLL_PUBLIC gboolean prefs_has_layout_pane_content (layout_pane_content_e layout_pane_content);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* prefs.h */

/*
 * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 *
 * Local variables:
 * c-basic-offset: 4
 * tab-width: 8
 * indent-tabs-mode: nil
 * End:
 *
 * vi: set shiftwidth=4 tabstop=8 expandtab:
 * :indentSize=4:tabSize=8:noTabs=true:
 */