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