epan/prefs.h

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