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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  23  */
  24
  25 #ifndef __PREFS_H__
  26 #define __PREFS_H__
  27
  28 #include <glib.h>
  29
  30 #include "color.h"
  31
  32 #include <epan/range.h>
  33
  34 #define PR_DEST_CMD  0
  35 #define PR_DEST_FILE 1
  36
  37 #define DEF_WIDTH 750
  38 #define DEF_HEIGHT 550
  39
  40 #define MAX_VAL_LEN  1024
  41
  42 #define RTP_PLAYER_DEFAULT_VISIBLE 4
  43 #define TAP_UPDATE_DEFAULT_INTERVAL 3000
  44
  45 /*
  46  * Convert a string listing name resolution types to a bitmask of
  47  * those types.
  48  *
  49  * Set "*name_resolve" to the bitmask, and return '\0', on success;
  50  * return the bad character in the string on error.
  51  */
  52 char string_to_name_resolve(char *string, guint32 *name_resolve);
  53
  54 /*
  55  * Modes for the starting directory in File Open dialogs.
  56  */
  57 #define FO_STYLE_LAST_OPENED    0       /* start in last directory we looked at */
  58 #define FO_STYLE_SPECIFIED      1       /* start in specified directory */
  59
  60 /*
  61  * Toolbar styles.
  62  */
  63 #define TB_STYLE_ICONS          0
  64 #define TB_STYLE_TEXT           1
  65 #define TB_STYLE_BOTH           2
  66
  67 /*
  68  * Types of layout of summary/details/hex panes.
  69  */
  70 typedef enum {
  71     layout_unused,  /* entry currently unused */
  72     layout_type_5,
  73     layout_type_2,
  74     layout_type_1,
  75     layout_type_4,
  76     layout_type_3,
  77     layout_type_6,
  78     layout_type_max
  79 } layout_type_e;
  80
  81 /*
  82  * Types of pane.
  83  */
  84 typedef enum {
  85     layout_pane_content_none,
  86     layout_pane_content_plist,
  87     layout_pane_content_pdetails,
  88     layout_pane_content_pbytes
  89 } layout_pane_content_e;
  90
  91 /*
  92  * open console behaviour (win32 only)
  93  */
  94 typedef enum {
  95     console_open_never,
  96     console_open_auto,
  97     console_open_always
  98 } console_open_e;
  99
 100
 101 typedef struct _e_prefs {
 102   gint     pr_format;
 103   gint     pr_dest;
 104   gchar   *pr_file;
 105   gchar   *pr_cmd;
 106   GList   *col_list;
 107   gint     num_cols;
 108   color_t  st_client_fg, st_client_bg, st_server_fg, st_server_bg;
 109   gboolean gui_scrollbar_on_right;
 110   gboolean gui_plist_sel_browse;
 111   gboolean gui_ptree_sel_browse;
 112   gboolean gui_altern_colors;
 113   gboolean filter_toolbar_show_in_statusbar;
 114   gint     gui_ptree_line_style;
 115   gint     gui_ptree_expander_style;
 116   gboolean gui_hex_dump_highlight_style;
 117   gint     gui_toolbar_main_style;
 118   gint     gui_toolbar_filter_style;
 119   gchar   *gui_font_name;
 120   color_t  gui_marked_fg;
 121   color_t  gui_marked_bg;
 122   color_t  gui_ignored_fg;
 123   color_t  gui_ignored_bg;
 124   gchar   *gui_colorized_fg;
 125   gchar   *gui_colorized_bg;
 126   gboolean gui_geometry_save_position;
 127   gboolean gui_geometry_save_size;
 128   gboolean gui_geometry_save_maximized;
 129   gboolean gui_macosx_style;
 130   console_open_e gui_console_open;
 131   guint    gui_recent_df_entries_max;
 132   guint    gui_recent_files_count_max;
 133   guint    gui_fileopen_style;
 134   gchar    *gui_fileopen_dir;
 135   guint    gui_fileopen_preview;
 136   gboolean gui_ask_unsaved;
 137   gboolean gui_find_wrap;
 138   gboolean gui_use_pref_save;
 139   gchar   *gui_webbrowser;
 140   gchar   *gui_window_title;
 141   gchar   *gui_start_title;
 142   gboolean gui_version_in_start_page;
 143   layout_type_e gui_layout_type;
 144   layout_pane_content_e gui_layout_content_1;
 145   layout_pane_content_e gui_layout_content_2;
 146   layout_pane_content_e gui_layout_content_3;
 147   gint     console_log_level;
 148   guint32  name_resolve;
 149   gint     name_resolve_concurrency;
 150   gchar   *capture_device;
 151   gchar   *capture_devices_linktypes;
 152   gchar   *capture_devices_descr;
 153   gchar   *capture_devices_hide;
 154   gboolean capture_prom_mode;
 155   gboolean capture_pcap_ng;
 156   gboolean capture_real_time;
 157   gboolean capture_auto_scroll;
 158   gboolean capture_show_info;
 159   guint    rtp_player_max_visible;
 160   guint    tap_update_interval;
 161   gboolean display_hidden_proto_items;
 162 } e_prefs;
 163
 164 WS_VAR_IMPORT e_prefs prefs;
 165
 166 /*
 167  * Routines to let modules that have preference settings register
 168  * themselves by name, and to let them register preference settings
 169  * by name.
 170  */
 171 struct pref_module;
 172
 173 typedef struct pref_module module_t;
 174
 175 /** Sets up memory used by proto routines. Called at program startup */
 176 extern void prefs_init(void);
 177
 178 /** Reset preferences to default values.  Called at profile change */
 179 extern void prefs_reset(void);
 180
 181 /** Frees memory used by proto routines. Called at program shutdown */
 182 extern void prefs_cleanup(void);
 183
 184 /*
 185  * Register a module that will have preferences.
 186  * Specify the module under which to register it or NULL to register it
 187  * at the top level, the name used for the module in the preferences file,
 188  * the title used in the tab for it in a preferences dialog box, and a
 189  * routine to call back when we apply the preferences.
 190  *
 191  * This should not be used for dissector preferences;
 192  * "prefs_register_protocol()" should be used for that, so that the
 193  * preferences go under the "Protocols" subtree, and so that the
 194  * name is the protocol name specified at the "proto_register_protocol()"
 195  * call so that the "Protocol Properties..." menu item works.
 196  */
 197 extern module_t *prefs_register_module(module_t *parent, const char *name,
 198     const char *title, const char *description, void (*apply_cb)(void));
 199
 200 /*
 201  * Register a subtree that will have modules under it.
 202  * Specify the module under which to register it or NULL to register it
 203  * at the top level and the title used in the tab for it in a preferences
 204  * dialog box.
 205  */
 206 extern module_t *prefs_register_subtree(module_t *parent, const char *title,
 207     const char *description);
 208
 209 /*
 210  * Register that a protocol has preferences.
 211  */
 212 extern module_t *prefs_register_protocol(int id, void (*apply_cb)(void));
 213
 214 /*
 215  * Register that a protocol has preferences and group it under a single
 216  * subtree
 217  */
 218 #define PREFERENCE_GROUPING
 219 extern module_t *prefs_register_protocol_subtree(const char *subtree, int id,
 220                                                  void (*apply_cb)(void));
 221
 222 /*
 223  * Register that a protocol used to have preferences but no longer does,
 224  * by creating an "obsolete" module for it.
 225  */
 226 extern module_t *prefs_register_protocol_obsolete(int id);
 227
 228 /*
 229  * Callback function for module list scanners.
 230  */
 231 typedef guint (*module_cb)(module_t *module, gpointer user_data);
 232
 233 /*
 234  * Returns TRUE if module has any submodules
 235  */
 236 extern gboolean prefs_module_has_submodules(module_t *module);
 237
 238 /*
 239  * Call a callback function, with a specified argument, for each module
 240  * in the list of all modules.  (This list does not include subtrees.)
 241  *
 242  * Ignores "obsolete" modules; their sole purpose is to allow old
 243  * preferences for dissectors that no longer have preferences to be
 244  * silently ignored in preference files.
 245  */
 246 extern guint prefs_modules_foreach(module_cb callback, gpointer user_data);
 247
 248 /*
 249  * Call a callback function, with a specified argument, for each submodule
 250  * of specified modules.  If the module is NULL, goes through the top-level
 251  * list in the display tree of modules.
 252  *
 253  * Ignores "obsolete" modules; their sole purpose is to allow old
 254  * preferences for dissectors that no longer have preferences to be
 255  * silently ignored in preference files.  Does not ignore subtrees,
 256  * as this can be used when walking the display tree of modules.
 257  */
 258 extern guint prefs_modules_foreach_submodules(module_t *module, module_cb callback, gpointer user_data);
 259
 260 /*
 261  * Call the "apply" callback function for each module if any of its
 262  * preferences have changed, and then clear the flag saying its
 263  * preferences have changed, as the module has been notified of that
 264  * fact.
 265  */
 266 extern void prefs_apply_all(void);
 267
 268 /*
 269  * Call the "apply" callback function for a specific module if any of
 270  * its preferences have changed, and then clear the flag saying its
 271  * preferences have changed, as the module has been notified of that
 272  * fact.
 273  */
 274 extern void prefs_apply(module_t *module);
 275
 276
 277 struct preference;
 278
 279 typedef struct preference pref_t;
 280
 281 /*
 282  * Returns TRUE if the given protocol has registered preferences.
 283  */
 284 extern gboolean prefs_is_registered_protocol(const char *name);
 285
 286 /*
 287  * Returns the module title of a registered protocol (or NULL if unknown).
 288  */
 289 extern const char *prefs_get_title_by_name(const char *name);
 290
 291 /** Given a module name, return a pointer to its pref_module struct,
 292  * or NULL if it's not found.
 293  *
 294  * @param name The preference module name.  Usually the same as the protocol
 295  * name, e.g. "tcp".
 296  * @return A pointer to the corresponding preference module, or NULL if it
 297  * wasn't found.
 298  */
 299 extern module_t *prefs_find_module(const char *name);
 300
 301 /** Given a module name, and a preference name return a pointer to the given
 302  * module's given preference or NULL if it's not found.
 303  *
 304  * @param module The preference module name.  Usually the same as the protocol
 305  * name, e.g. "tcp".
 306  * @param pref The preference name, e.g. "desegment".
 307  * @return A pointer to the corresponding preference, or NULL if it
 308  * wasn't found.
 309  */
 310 extern pref_t *prefs_find_preference(module_t * module, const char *pref);
 311
 312 /*
 313  * Register a preference with an unsigned integral value.
 314  */
 315 extern void prefs_register_uint_preference(module_t *module, const char *name,
 316     const char *title, const char *description, guint base, guint *var);
 317
 318 /*
 319  * Register a preference with an Boolean value.
 320  * Note that the name must be in lowercase letters only (underscore allowed).
 321  */
 322 extern void prefs_register_bool_preference(module_t *module, const char *name,
 323     const char *title, const char *description, gboolean *var);
 324
 325 /*
 326  * Register a preference with an enumerated value.
 327  */
 328 typedef struct {
 329         const char      *name;
 330         const char      *description;
 331         gint            value;
 332 } enum_val_t;
 333
 334 extern void prefs_register_enum_preference(module_t *module, const char *name,
 335     const char *title, const char *description, gint *var,
 336     const enum_val_t *enumvals, gboolean radio_buttons);
 337
 338 /*
 339  * Register a preference with a character-string value.
 340  */
 341 extern void prefs_register_string_preference(module_t *module, const char *name,
 342     const char *title, const char *description, const char **var);
 343
 344 /*
 345  * Register a preference with a ranged value.
 346  */
 347 extern void prefs_register_range_preference(module_t *module, const char *name,
 348     const char *title, const char *description, range_t **var,
 349     guint32 max_value);
 350
 351 /*
 352  * Register a static text 'preference'. It can be used to add some info/explanation.
 353  */
 354 extern void prefs_register_static_text_preference(module_t *module, const char *name,
 355     const char *title, const char *description);
 356
 357 /*
 358  * Register a uat 'preference'. It adds a button that opens the uat's window in the
 359  * preferences tab of the module.
 360  */
 361 extern void prefs_register_uat_preference(module_t *module,
 362                                                                                   const char *name,
 363                                                                                   const char* title,
 364                                                                                   const char *description,
 365                                                                                   void* uat);
 366
 367 /*
 368  * Register a preference that used to be supported but no longer is.
 369  */
 370 extern void prefs_register_obsolete_preference(module_t *module,
 371     const char *name);
 372
 373 typedef guint (*pref_cb)(pref_t *pref, gpointer user_data);
 374
 375 /*
 376  * Call a callback function, with a specified argument, for each preference
 377  * in a given module.
 378  *
 379  * If any of the callbacks return a non-zero value, stop and return that
 380  * value, otherwise return 0.
 381  */
 382 extern guint prefs_pref_foreach(module_t *module, pref_cb callback,
 383     gpointer user_data);
 384
 385 /* Parse through a list of comma-separated, possibly quoted strings.
 386  *  Return a list of the string data.
 387  */
 388 extern GList *prefs_get_string_list(gchar *str);
 389
 390 /* Clear the given list of string data. */
 391 extern void prefs_clear_string_list(GList *sl);
 392
 393 /*
 394  * Register all non-dissector modules' preferences.
 395  */
 396 extern void prefs_register_modules(void);
 397
 398 /* Read the preferences file, fill in "prefs", and return a pointer to it.
 399
 400    If we got an error (other than "it doesn't exist") trying to read
 401    the global preferences file, stuff the errno into "*gpf_errno_return"
 402    on an open error and into "*gpf_read_errno_return" on a read error,
 403    stuff a pointer to the path of the file into "*gpf_path_return", and
 404    return NULL.
 405
 406    If we got an error (other than "it doesn't exist") trying to read
 407    the user's preferences file, stuff the errno into "*pf_errno_return"
 408    on an open error and into "*pf_read_errno_return" on a read error,
 409    stuff a pointer to the path of the file into "*pf_path_return", and
 410    return NULL. */
 411 extern e_prefs *read_prefs(int *, int *, char **, int *, int *, char **);
 412
 413 /* Write out "prefs" to the user's preferences file, and return 0.
 414
 415    If we got an error, stuff a pointer to the path of the preferences file
 416    into "*pf_path_return", and return the errno. */
 417 extern int write_prefs(char **);
 418
 419 /* Copy a set of preferences. */
 420 extern void copy_prefs(e_prefs *dest, e_prefs *src);
 421
 422 /* Free a set of preferences. */
 423 extern void free_prefs(e_prefs *pr);
 424
 425 /*
 426  * Given a string of the form "<pref name>:<pref value>", as might appear
 427  * as an argument to a "-o" option, parse it and set the preference in
 428  * question.  Return an indication of whether it succeeded or failed
 429  * in some fashion.
 430  *
 431  * XXX - should supply, for syntax errors, a detailed explanation of
 432  * the syntax error.
 433  */
 434 typedef enum {
 435     PREFS_SET_OK,               /* succeeded */
 436     PREFS_SET_SYNTAX_ERR,       /* syntax error in string */
 437     PREFS_SET_NO_SUCH_PREF,     /* no such preference */
 438     PREFS_SET_OBSOLETE          /* preference used to exist but no longer does */
 439 } prefs_set_pref_e;
 440
 441 extern prefs_set_pref_e prefs_set_pref(char *prefarg);
 442
 443 /*
 444  * Returns TRUE if the given device is hidden
 445  */
 446 extern gboolean prefs_is_capture_device_hidden(const char *name);
 447
 448 #endif /* prefs.h */