prefs.h File Reference

#include <glib.h>
#include <epan/params.h>
#include <epan/range.h>
#include <wsutil/color.h>
#include "ws_symbol_export.h"

Go to the source code of this file.

Classes
struct	_e_prefs
	Global Wireshark preferences structure holding all persistent configuration settings. More...

Macros
#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 arbitrary limit of 10 minutes */
#define	ST_MAX_BURSTBUCKETS   100 /* somewhat arbitrary limit - more buckets degrade performance */
#define	DEF_GUI_DECIMAL_PLACES1   2
#define	DEF_GUI_DECIMAL_PLACES2   4
#define	DEF_GUI_DECIMAL_PLACES3   6
#define	CONV_DEINT_KEY_CAPFILE   0x01 /* unused yet */
#define	CONV_DEINT_KEY_INTERFACE   0x02
#define	CONV_DEINT_KEY_MAC   0x04
#define	CONV_DEINT_KEY_VLAN   0x08
#define	PREF_EFFECT_DISSECTION   (1u << 0)
#define	PREF_EFFECT_CAPTURE   (1u << 1)
#define	PREF_EFFECT_GUI_LAYOUT   (1u << 2)
#define	PREF_EFFECT_FIELDS   (1u << 3)
#define	PREF_EFFECT_GUI   (1u << 4)
#define	PREF_EFFECT_GUI_COLOR   (1u << 5)
#define	PREF_EFFECT_AGGREGATION   (1u << 6)
#define	DEFAULT_UPDATE_INTERVAL   100
#define	FO_STYLE_LAST_OPENED   0 /* start in last directory we looked at */
#define	FO_STYLE_SPECIFIED   1 /* start in specified directory */
#define	FO_STYLE_CWD   2 /* start in current working directory at startup */
#define	TB_STYLE_ICONS   0
#define	TB_STYLE_TEXT   1
#define	TB_STYLE_BOTH   2
#define	COLOR_SCHEME_DEFAULT   0
#define	COLOR_SCHEME_LIGHT   1
#define	COLOR_SCHEME_DARK   2

Typedefs
typedef struct _e_prefs	e_prefs
	Global Wireshark preferences structure holding all persistent configuration settings.
typedef struct pref_module	module_t
typedef unsigned(*	module_cb) (module_t *module, void *user_data)
typedef struct preference	pref_t
typedef unsigned(*	pref_cb) (pref_t *pref, void *user_data)

Enumerations
enum	layout_type_e {   layout_unused , layout_type_5 , layout_type_2 , layout_type_1 ,   layout_type_4 , layout_type_3 , layout_type_6 , layout_type_max }
	Arrangement type of the summary, details, and hex panes in the main window. More...
enum	layout_pane_content_e {   layout_pane_content_none , layout_pane_content_plist , layout_pane_content_pdetails , layout_pane_content_pbytes ,   layout_pane_content_pdiagram }
	Content assigned to a single layout pane in the main window. More...
enum	version_info_e { version_welcome_only , version_title_only , version_both , version_neither }
	Controls where version information is displayed in the GUI. More...
enum	splitter_layout_e { layout_vertical , layout_horizontal }
	Orientation of a splitter divider between panes. More...
enum	pref_source_t { pref_default , pref_stashed , pref_current }
	Selects which copy of a preference value is used as the active source. More...
enum	elide_mode_e { ELIDE_LEFT , ELIDE_RIGHT , ELIDE_MIDDLE , ELIDE_NONE }
	Controls which end of a text string is elided when it is too long to display. More...
enum	copy_format_e { COPY_FORMAT_TEXT , COPY_FORMAT_CSV , COPY_FORMAT_YAML , COPY_FORMAT_HTML }
	Output format for copying packet list rows to the clipboard. More...
enum	abs_time_format_e { ABS_TIME_ASCII_NEVER , ABS_TIME_ASCII_TREE , ABS_TIME_ASCII_COLUMN , ABS_TIME_ASCII_ALWAYS }
	Controls whether absolute timestamps are rendered as ASCII in tree and column views. More...
enum	software_update_channel_e { UPDATE_CHANNEL_DEVELOPMENT , UPDATE_CHANNEL_STABLE }
	Automatic software update channel selection. More...
enum	gui_packet_list_multi_color_mode_e { PACKET_LIST_MULTI_COLOR_MODE_OFF = 0 , PACKET_LIST_MULTI_COLOR_MODE_SCROLLBAR_ONLY , PACKET_LIST_MULTI_COLOR_MODE_FULL , PACKET_LIST_MULTI_COLOR_MODE_SHIFT_RIGHT }
	Multi-color stripe display mode for the packet list scrollbar and rows. More...
enum	gui_packet_list_multi_color_separator_e { PACKET_LIST_MULTI_COLOR_SEPARATOR_VERTICAL = 0 , PACKET_LIST_MULTI_COLOR_SEPARATOR_DIAGONAL , PACKET_LIST_MULTI_COLOR_SEPARATOR_BUBBLE }
	Visual style of the separator between adjacent color stripes in the packet list. More...
enum	prefs_set_pref_e { PREFS_SET_OK , PREFS_SET_SYNTAX_ERR , PREFS_SET_NO_SUCH_PREF , PREFS_SET_OBSOLETE }
	Result of setting a preference. More...

Functions
WS_DLL_PUBLIC char	string_to_name_resolve (const char *string, struct _e_addr_resolve *name_resolve)
void	prefs_init (const char **col_fmt, int num_cols)
	Initialize preferences system.
WS_DLL_PUBLIC void	prefs_reset (const char *app_env_var_prefix, const char **col_fmt, int num_cols)
	Resets preferences to their default values.
void	prefs_cleanup (void)
	Clean up preferences.
WS_DLL_PUBLIC module_t *	prefs_register_protocol (int id, void(*apply_cb)(void))
WS_DLL_PUBLIC void	prefs_register_module_alias (const char *name, module_t *module)
	Register an alias for a preference module.
void	prefs_deregister_protocol (int id)
WS_DLL_PUBLIC module_t *	prefs_register_stat (const char *name, const char *title, const char *description, void(*apply_cb)(void))
WS_DLL_PUBLIC module_t *	prefs_register_codec (const char *name, const char *title, const char *description, void(*apply_cb)(void))
WS_DLL_PUBLIC module_t *	prefs_register_protocol_subtree (const char *subtree, int id, void(*apply_cb)(void))
WS_DLL_PUBLIC module_t *	prefs_register_protocol_obsolete (int id)
WS_DLL_PUBLIC module_t *	prefs_register_module (wmem_tree_t *pref_tree, wmem_tree_t *master_pref_tree, const char *name, const char *title, const char *description, const char *help, void(*apply_cb)(void), const bool use_gui)
	Register a module that will have preferences. Specify the module under which to register it, the name used for the module in the preferences file, the title used in the tab for it in a preferences dialog box, and a routine to call back when the preferences are applied.
WS_DLL_PUBLIC bool	prefs_module_has_submodules (module_t *module)
WS_DLL_PUBLIC unsigned	prefs_modules_foreach (const wmem_tree_t *module, module_cb callback, void *user_data)
WS_DLL_PUBLIC unsigned	prefs_modules_foreach_submodules (const wmem_tree_t *module, module_cb callback, void *user_data)
WS_DLL_PUBLIC unsigned	prefs_modules_for_all_modules (module_cb callback, void *user_data)
WS_DLL_PUBLIC void	prefs_apply_all (void)
WS_DLL_PUBLIC void	prefs_apply (module_t *module)
WS_DLL_PUBLIC bool	prefs_is_registered_protocol (const char *name)
WS_DLL_PUBLIC const char *	prefs_get_title_by_name (const char *name)
WS_DLL_PUBLIC module_t *	prefs_find_module (const char *name)
WS_DLL_PUBLIC pref_t *	prefs_find_preference (module_t *module, const char *pref)
WS_DLL_PUBLIC void	prefs_register_uint_preference (module_t *module, const char *name, const char *title, const char *description, unsigned base, unsigned *var)
WS_DLL_PUBLIC void	prefs_register_int_preference (module_t *module, const char *name, const char *title, const char *description, int *var)
WS_DLL_PUBLIC void	prefs_register_float_preference (module_t *module, const char *name, const char *title, const char *description, unsigned num_decimal, double *var)
WS_DLL_PUBLIC void	prefs_register_bool_preference (module_t *module, const char *name, const char *title, const char *description, bool *var)
WS_DLL_PUBLIC void	prefs_register_enum_preference (module_t *module, const char *name, const char *title, const char *description, int *var, const enum_val_t *enumvals, bool radio_buttons)
WS_DLL_PUBLIC void	prefs_register_string_preference (module_t *module, const char *name, const char *title, const char *description, const char **var)
WS_DLL_PUBLIC void	prefs_register_filename_preference (module_t *module, const char *name, const char *title, const char *description, const char **var, bool for_writing)
WS_DLL_PUBLIC void	prefs_register_directory_preference (module_t *module, const char *name, const char *title, const char *description, const char **var)
WS_DLL_PUBLIC void	prefs_register_list_string_preference (module_t *module, const char *name, const char *title, const char *description, wmem_list_t **var)
WS_DLL_PUBLIC void	prefs_register_multiple_string_preference (module_t *module, const char *name, const char *title, const char *description, wmem_list_t **var)
WS_DLL_PUBLIC void	prefs_register_range_preference (module_t *module, const char *name, const char *title, const char *description, range_t **var, uint32_t max_value)
WS_DLL_PUBLIC void	prefs_register_static_text_preference (module_t *module, const char *name, const char *title, const char *description)
WS_DLL_PUBLIC void	prefs_register_uat_preference (module_t *module, const char *name, const char *title, const char *description, struct epan_uat *uat)
void	prefs_register_color_preference (module_t *module, const char *name, const char *title, const char *description, color_t *color)
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)
void	prefs_register_decode_as_range_preference (module_t *module, const char *name, const char *title, const char *description, range_t **var, uint32_t max_value, const char *dissector_table, const char *dissector_description)
WS_DLL_PUBLIC void	prefs_register_password_preference (module_t *module, const char *name, const char *title, const char *description, const char **var)
WS_DLL_PUBLIC void	prefs_register_dissector_preference (module_t *module, const char *name, const char *title, const char *description, const char **var)
WS_DLL_PUBLIC void	prefs_register_obsolete_preference (module_t *module, const char *name)
	Register a preference that used to be supported but no longer is.
WS_DLL_PUBLIC void	prefs_register_custom_preference_TCP_Analysis (module_t *module, const char *name, const char *title, const char *description, int *var, const enum_val_t *enumvals, bool radio_buttons)
	Register a preference with an enumerated value.
WS_DLL_PUBLIC void	prefs_set_preference_effect_fields (module_t *module, const char *name)
	Mark a preference that affects fields change.
WS_DLL_PUBLIC void	prefs_set_preference_effect (module_t *module, const char *name, unsigned flags)
	Set the effect flags for a preference in a given module.
WS_DLL_PUBLIC unsigned	prefs_pref_foreach (module_t *module, pref_cb callback, void *user_data)
	Call a callback function, with a specified argument, for each preference in a given module.
WS_DLL_PUBLIC GList *	prefs_get_string_list (const char *str)
	Parse through a list of comma-separated, possibly quoted strings. Return a list of the string data.
WS_DLL_PUBLIC void	prefs_clear_string_list (GList *sl)
	Clear the given list of string data.
WS_DLL_PUBLIC const char *	prefs_pref_type_name (pref_t *pref)
	Fetch a short preference type name, e.g. "Integer".
WS_DLL_PUBLIC char *	prefs_pref_type_description (pref_t *pref)
	Fetch a long description of the preference type.
WS_DLL_PUBLIC char *	prefs_pref_to_str (pref_t *pref, pref_source_t source)
	Fetch a string representation of the preference.
WS_DLL_PUBLIC int	prefs_num_non_uat (module_t *module)
	Fetch the number of preferences in a module that are not UATs.
WS_DLL_PUBLIC bool	prefs_is_preference_obsolete (pref_t *pref)
	Fetch whether a preference is marked obsolete.
e_prefs *	read_prefs (const char *app_env_var_prefix)
	Read the preferences file, fill in "prefs", and return a pointer to it.
WS_DLL_PUBLIC int	write_prefs (const char *app_env_var_prefix, char **pf_path_return)
	Write out "prefs" to the user's preferences file, and return 0.
WS_DLL_PUBLIC void	pref_write_individual (void *data, void *user_data)
	Callback function for writing individual preferences.
WS_DLL_PUBLIC void	pref_free_individual (void *data, void *user_data)
	Callback function for freeing individual preferences.
WS_DLL_PUBLIC prefs_set_pref_e	prefs_set_pref (char *prefarg, char **errmsg)
WS_DLL_PUBLIC range_t *	prefs_get_range_value (const char *module_name, const char *pref_name)
WS_DLL_PUBLIC bool	prefs_is_capture_device_hidden (const char *name)
	Checks if the specified capture device is hidden.
WS_DLL_PUBLIC bool	prefs_capture_device_monitor_mode (const char *name)
	Returns true if the given device should capture in monitor mode by default.
WS_DLL_PUBLIC bool	prefs_capture_options_dialog_column_is_visible (const char *column)
	Returns true if the user has marked this column as visible.
WS_DLL_PUBLIC bool	prefs_has_layout_pane_content (layout_pane_content_e layout_pane_content)
	Returns true if the layout pane content is enabled.

Variables
WS_DLL_PUBLIC e_prefs	prefs

Detailed Description

Definitions for preference handling routines

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Typedef Documentation

module_cb

typedef unsigned(* module_cb) (module_t *module, void *user_data)

Callback function for module list scanners.

Enumeration Type Documentation

abs_time_format_e

enum abs_time_format_e

Controls whether absolute timestamps are rendered as ASCII in tree and column views.

Enumerator
ABS_TIME_ASCII_NEVER	Never render absolute timestamps as ASCII strings
ABS_TIME_ASCII_TREE	Render ASCII timestamps in the packet details tree only
ABS_TIME_ASCII_COLUMN	Render ASCII timestamps in packet list columns only
ABS_TIME_ASCII_ALWAYS	Always render absolute timestamps as ASCII strings

copy_format_e

enum copy_format_e

Output format for copying packet list rows to the clipboard.

Enumerator
COPY_FORMAT_TEXT	Plain text format
COPY_FORMAT_CSV	Comma-separated values (CSV) format
COPY_FORMAT_YAML	YAML format
COPY_FORMAT_HTML	HTML format

elide_mode_e

enum elide_mode_e

Controls which end of a text string is elided when it is too long to display.

Enumerator
ELIDE_LEFT	Elide (truncate with ellipsis) from the left end
ELIDE_RIGHT	Elide from the right end
ELIDE_MIDDLE	Elide from the middle
ELIDE_NONE	Do not elide; display the full string

gui_packet_list_multi_color_mode_e

enum gui_packet_list_multi_color_mode_e

Multi-color stripe display mode for the packet list scrollbar and rows.

Enumerator
PACKET_LIST_MULTI_COLOR_MODE_OFF	Multi-color display disabled
PACKET_LIST_MULTI_COLOR_MODE_SCROLLBAR_ONLY	Color stripes shown in scrollbar only; no row striping
PACKET_LIST_MULTI_COLOR_MODE_FULL	Full color stripes in both rows and scrollbar
PACKET_LIST_MULTI_COLOR_MODE_SHIFT_RIGHT	Color stripes shifted right by a configurable percentage in rows and scrollbar

gui_packet_list_multi_color_separator_e

enum gui_packet_list_multi_color_separator_e

Visual style of the separator between adjacent color stripes in the packet list.

Enumerator
PACKET_LIST_MULTI_COLOR_SEPARATOR_VERTICAL	Straight vertical separator between stripes
PACKET_LIST_MULTI_COLOR_SEPARATOR_DIAGONAL	Diagonal (candy-cane) separator between stripes
PACKET_LIST_MULTI_COLOR_SEPARATOR_BUBBLE	Bubble / half-moon separator between stripes

layout_pane_content_e

enum layout_pane_content_e

Content assigned to a single layout pane in the main window.

Enumerator
layout_pane_content_none	Pane is empty / not displayed
layout_pane_content_plist	Pane shows the packet list
layout_pane_content_pdetails	Pane shows the packet details tree
layout_pane_content_pbytes	Pane shows the packet bytes (hex dump)
layout_pane_content_pdiagram	Pane shows the packet diagram

layout_type_e

enum layout_type_e

Arrangement type of the summary, details, and hex panes in the main window.

Enumerator
layout_unused	Layout slot is currently unused
layout_type_5	Pane arrangement type 5
layout_type_2	Pane arrangement type 2
layout_type_1	Pane arrangement type 1
layout_type_4	Pane arrangement type 4
layout_type_3	Pane arrangement type 3
layout_type_6	Pane arrangement type 6
layout_type_max	Sentinel: one past the last valid layout type

pref_source_t

enum pref_source_t

Selects which copy of a preference value is used as the active source.

Enumerator
pref_default	The compiled-in default value
pref_stashed	A temporarily stashed value (e.g., before applying changes)
pref_current	The currently active/applied value

prefs_set_pref_e

enum prefs_set_pref_e

Result of setting a preference.

Enumerator
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

software_update_channel_e

enum software_update_channel_e

Automatic software update channel selection.

Enumerator
UPDATE_CHANNEL_DEVELOPMENT	Receive development/pre-release update builds
UPDATE_CHANNEL_STABLE	Receive stable release update builds only

splitter_layout_e

enum splitter_layout_e

Orientation of a splitter divider between panes.

Enumerator
layout_vertical	Panes are split vertically (side by side)
layout_horizontal	Panes are split horizontally (stacked)

version_info_e

enum version_info_e

Controls where version information is displayed in the GUI.

Enumerator
version_welcome_only	Version shown on the welcome splash screen only
version_title_only	Version shown in the window title bar only
version_both	Version shown in both the welcome screen and title bar
version_neither	Version not shown anywhere

Function Documentation

pref_free_individual()

WS_DLL_PUBLIC void pref_free_individual	(	void *	data,
		void *	user_data
	)

Callback function for freeing individual preferences.

Parameters

data	A preference pointer of type pref_t*
user_data	unused

pref_write_individual()

WS_DLL_PUBLIC void pref_write_individual	(	void *	data,
		void *	user_data
	)

Callback function for writing individual preferences.

Parameters

data	A preference pointer of type pref_t*
user_data	write_pref_arg_t* pointer

prefs_apply()

WS_DLL_PUBLIC void prefs_apply

(

module_t *

module

)

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.

Parameters

module

the module to call the 'apply' callback function for

prefs_apply_all()

WS_DLL_PUBLIC void prefs_apply_all

(

void

)

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.

prefs_capture_device_monitor_mode()

WS_DLL_PUBLIC bool prefs_capture_device_monitor_mode

(

const char *

name

)

Returns true if the given device should capture in monitor mode by default.

Parameters

name	the name of the capture device

Returns

true if the specified capture device should capture in monitor mode by default, otherwise false

prefs_capture_options_dialog_column_is_visible()

WS_DLL_PUBLIC bool prefs_capture_options_dialog_column_is_visible

(

const char *

column

)

Returns true if the user has marked this column as visible.

Parameters

column

the name of the column

Returns

true if this column as visible, otherwise false

prefs_cleanup()

void prefs_cleanup

(

void

)

Clean up preferences.

Frees memory used by proto routines. Called at program shutdown

prefs_clear_string_list()

WS_DLL_PUBLIC void prefs_clear_string_list

(

GList *

sl

)

Clear the given list of string data.

Parameters

sl	the GList to clear

prefs_deregister_protocol()

void prefs_deregister_protocol

(

int

id

)

Deregister preferences from a protocol.

Parameters

id	the value returned by "proto_register_protocol()" when the protocol was registered.

prefs_find_module()

WS_DLL_PUBLIC module_t * prefs_find_module

(

const char *

name

)

Given a module name, return a pointer to its pref_module struct, or NULL if it's not found.

Parameters

name	The preference module name. Usually the same as the protocol name, e.g. "tcp".

Returns

A pointer to the corresponding preference module, or NULL if it wasn't found.

prefs_find_preference()

WS_DLL_PUBLIC pref_t * prefs_find_preference	(	module_t *	module,
		const char *	pref
	)

Given a module and a preference name, return a pointer to the given module's given preference or NULL if it's not found.

Parameters

module	The preference module name. Usually the same as the protocol name, e.g. "tcp".
pref	The preference name, e.g. "desegment".

Returns

A pointer to the corresponding preference, or NULL if it wasn't found.

prefs_get_range_value()

WS_DLL_PUBLIC range_t * prefs_get_range_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.

Parameters

module_name	the preference module name. Usually the same as the protocol name, e.g. "tcp".
pref_name	the preference name, e.g. "desegment".

Returns

the preference's value

prefs_get_string_list()

WS_DLL_PUBLIC GList * prefs_get_string_list

(

const char *

str

)

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.

Parameters

str	a list of comma-separated, possibly quoted strings

Returns

a list of the string data, or NULL if there's an error

prefs_get_title_by_name()

WS_DLL_PUBLIC const char * prefs_get_title_by_name

(

const char *

name

)

Returns the module title of a registered protocol (or NULL if unknown).

Parameters

name	the name of the protocol to look up

Returns

the module title of a registered protocol, otherwise NULL

prefs_has_layout_pane_content()

WS_DLL_PUBLIC bool prefs_has_layout_pane_content

(

layout_pane_content_e

layout_pane_content

)

Returns true if the layout pane content is enabled.

Parameters

layout_pane_content

the layout pane content to check

Returns

true if the layout pane content is enabled, otherwise false

prefs_init()

void prefs_init	(	const char **	col_fmt,
		int	num_cols
	)

Initialize preferences system.

Sets up memory used by proto routines. Called at program startup

Parameters

col_fmt	Array of column format strings
num_cols	Number of columns in the display

Sets up memory used by proto routines. Called at program startup

prefs_is_capture_device_hidden()

WS_DLL_PUBLIC bool prefs_is_capture_device_hidden

(

const char *

name

)

Checks if the specified capture device is hidden.

Parameters

name	the name of the capture device

Returns

true if the specified capture device is hidden, otherwise false

prefs_is_preference_obsolete()

WS_DLL_PUBLIC bool prefs_is_preference_obsolete

(

pref_t *

pref

)

Fetch whether a preference is marked obsolete.

Parameters

pref	A preference.

Returns

A boolean indication the obsolescence of the preference.

prefs_is_registered_protocol()

WS_DLL_PUBLIC bool prefs_is_registered_protocol

(

const char *

name

)

Returns true if the provided protocol has registered preferences.

Parameters

name	the name of the protocol to look up

Returns

true if the given protocol has registered preferences, otherwise false

prefs_module_has_submodules()

WS_DLL_PUBLIC bool prefs_module_has_submodules

(

module_t *

module

)

Returns true if a preferences module has any submodules

Parameters

module

a preferences module which can be used to register a user 'preference'

Returns

true if a preferences module has any submodules, otherwise false

prefs_modules_for_all_modules()

WS_DLL_PUBLIC unsigned prefs_modules_for_all_modules	(	module_cb	callback,
		void *	user_data
	)

Call a callback function, with a specified argument, for all 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.

Parameters

callback	the callback to call
user_data	additional data to pass to the callback

prefs_modules_foreach()

WS_DLL_PUBLIC unsigned prefs_modules_foreach	(	const wmem_tree_t *	module,
		module_cb	callback,
		void *	user_data
	)

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.

Parameters

module	module to act on
callback	the callback to call
user_data	additional data to pass to the callback

prefs_modules_foreach_submodules()

WS_DLL_PUBLIC unsigned prefs_modules_foreach_submodules	(	const wmem_tree_t *	module,
		module_cb	callback,
		void *	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.

Parameters

module	module to walk through
callback	the callback to call
user_data	additional data to pass to the callback

prefs_num_non_uat()

WS_DLL_PUBLIC int prefs_num_non_uat

(

module_t *

module

)

Fetch the number of preferences in a module that are not UATs.

Parameters

module

A preference module.

Returns

The number of non-UAT preferences in the module.

prefs_pref_foreach()

WS_DLL_PUBLIC unsigned prefs_pref_foreach	(	module_t *	module,
		pref_cb	callback,
		void *	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.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
callback	the callback to call
user_data	additional data to pass to the callback

Returns

If any of the callbacks return a non-zero value, stop and return that value, otherwise return 0.

prefs_pref_to_str()

WS_DLL_PUBLIC char * prefs_pref_to_str	(	pref_t *	pref,
		pref_source_t	source
	)

Fetch a string representation of the preference.

Parameters

pref	A preference.
source	Which value of the preference to return, see pref_source_t.

Returns

A string representation of the preference. Must be g_free()d.

prefs_pref_type_description()

WS_DLL_PUBLIC char * prefs_pref_type_description

(

pref_t *

pref

)

Fetch a long description of the preference type.

Parameters

pref	A preference.

Returns

A description of the preference type including allowed values for enums. The description may include newlines. Must be g_free()d.

prefs_pref_type_name()

WS_DLL_PUBLIC const char * prefs_pref_type_name

(

pref_t *

pref

)

Fetch a short preference type name, e.g. "Integer".

Parameters

pref	A preference.

Returns

The preference type name. May be NULL.

prefs_register_bool_preference()

WS_DLL_PUBLIC void prefs_register_bool_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		bool *	var
	)

Register a preference with an Boolean value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
var	pointer to the storage location that is updated when the field is changed in the preference dialog box

prefs_register_codec()

WS_DLL_PUBLIC module_t * prefs_register_codec	(	const char *	name,
		const char *	title,
		const char *	description,
		void(*)(void)	apply_cb
	)

Register that a codec has preferences.

Parameters

name	is a name for the codec to use on the command line with "-o" and in preference files.
title	is a short human-readable name for the codec.
description	is a longer human-readable description of the codec.
apply_cb	routine to call back after we apply the preferences

Returns

a preferences module which can be used to register a user 'preference'

prefs_register_color_preference()

void prefs_register_color_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		color_t *	color
	)

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.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
color	the color object that will be updated when the field is changed in the preference dialog box

prefs_register_custom_preference()

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 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.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
custom_cbs	a structure with the custom preference's callbacks
custom_data	currently unused

prefs_register_custom_preference_TCP_Analysis()

WS_DLL_PUBLIC void prefs_register_custom_preference_TCP_Analysis	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		int *	var,
		const enum_val_t *	enumvals,
		bool	radio_buttons
	)

Register a preference with an enumerated value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
var	pointer to the storage location that is updated when the field is changed in the preference dialog box
enumvals	a null-terminated array of enum_val_t structures
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

prefs_register_decode_as_range_preference()

void prefs_register_decode_as_range_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		range_t **	var,
		uint32_t	max_value,
		const char *	dissector_table,
		const char *	dissector_description
	)

Register a (internal) "Decode As" preference with a ranged value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
var	pointer to the storage location that is updated when the field is changed in the preference dialog box.
max_value	the maximum allowed value for a range (0 is the minimum)
dissector_table	the name of the dissector table
dissector_description	the handle description

prefs_register_directory_preference()

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 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.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
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

prefs_register_dissector_preference()

WS_DLL_PUBLIC void prefs_register_dissector_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		const char **	var
	)

Register a preference with a dissector name.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
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

prefs_register_enum_preference()

WS_DLL_PUBLIC void prefs_register_enum_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		int *	var,
		const enum_val_t *	enumvals,
		bool	radio_buttons
	)

Register a preference with an enumerated value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
var	pointer to the storage location that is updated when the field is changed in the preference dialog box
enumvals	a null-terminated array of enum_val_t structures
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

prefs_register_filename_preference()

WS_DLL_PUBLIC void prefs_register_filename_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		const char **	var,
		bool	for_writing
	)

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.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
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
for_writing	true to display a Save dialog, false to display an Open dialog.

prefs_register_float_preference()

WS_DLL_PUBLIC void prefs_register_float_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		unsigned	num_decimal,
		double *	var
	)

Register a preference with a float (double) value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	the title in the preferences dialog
description	the description included in the preferences file and shown as tooltip in the GUI, or NULL
num_decimal	the number of decimal places to display for a value
var	pointer to the storage location that is updated when the field is changed in the preference dialog box

prefs_register_int_preference()

WS_DLL_PUBLIC void prefs_register_int_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		int *	var
	)

Register a preference with an integer value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	the title in the preferences dialog
description	the description included in the preferences file and shown as tooltip in the GUI, or NULL
var	pointer to the storage location that is updated when the field is changed in the preference dialog box

prefs_register_list_string_preference()

WS_DLL_PUBLIC void prefs_register_list_string_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		wmem_list_t **	var
	)

Register a preference with a comma-delimited string values.

This is currently not support in the UI for dissector use (internal UI preferences only)

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
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 list 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

prefs_register_module()

WS_DLL_PUBLIC module_t * prefs_register_module	(	wmem_tree_t *	pref_tree,
		wmem_tree_t *	master_pref_tree,
		const char *	name,
		const char *	title,
		const char *	description,
		const char *	help,
		void(*)(void)	apply_cb,
		const bool	use_gui
	)

Register a module that will have preferences. Specify the module under which to register it, the name used for the module in the preferences file, the title used in the tab for it in a preferences dialog box, and a routine to call back when the preferences are applied.

Parameters

pref_tree	"Parent" preference tree under which to register this module.
master_pref_tree	List of all preference modules.
name	is a name for the module to use on the command line with "-o" and in preference files.
title	the module title in the preferences UI
description	the description included in the preferences file and shown as tooltip in the GUI, or NULL
help	The help string associated with the module, or NULL
apply_cb	Callback routine that is called when preferences are applied. It may be NULL, which inhibits the callback.

Returns

a preferences module which can be used to register a user 'preference'

prefs_register_module_alias()

WS_DLL_PUBLIC void prefs_register_module_alias	(	const char *	name,
		module_t *	module
	)

Register an alias for a preference module.

Parameters

name	the preference module's alias. Only ASCII letters, numbers, underscores, hyphens, and dots may appear in the name
module	the module to create an alias for

prefs_register_multiple_string_preference()

WS_DLL_PUBLIC void prefs_register_multiple_string_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		wmem_list_t **	var
	)

Register a preference that has multiple string values This looks like multiple instances of the same preference in the file

This is currently not support in the UI for dissector use (internal UI preferences only)

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
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 list 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

prefs_register_obsolete_preference()

WS_DLL_PUBLIC void prefs_register_obsolete_preference	(	module_t *	module,
		const char *	name
	)

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()

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.

prefs_register_password_preference()

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 with an password (password is never stored).

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	the title in the preferences dialog
description	the description included in the preferences file and shown as tooltip in the GUI, or NULL
var	pointer to the storage location that is updated when the field is changed in the preference dialog box

prefs_register_protocol()

WS_DLL_PUBLIC module_t * prefs_register_protocol	(	int	id,
		void(*)(void)	apply_cb
	)

Register that a protocol has preferences.

Parameters

id	the value returned by "proto_register_protocol()" when the protocol was registered.
apply_cb	callback routine that is called when preferences are applied. It may be NULL, which inhibits the callback.

Returns

a preferences module which can be used to register a user 'preference'

prefs_register_protocol_obsolete()

WS_DLL_PUBLIC module_t * prefs_register_protocol_obsolete

(

int

id

)

Register that a protocol used to have preferences but no longer does, by creating an "obsolete" module for it.

Parameters

id	the value returned by "proto_register_protocol()" when the protocol was registered.

Returns

a preferences module which can be used to register a user 'preference'

prefs_register_protocol_subtree()

WS_DLL_PUBLIC module_t * prefs_register_protocol_subtree	(	const char *	subtree,
		int	id,
		void(*)(void)	apply_cb
	)

Register that a protocol has preferences and group it under a single subtree

Parameters

subtree	the tree node name for grouping preferences the protocol was registered.
id	the value returned by "proto_register_protocol()" when the protocol was registered.
apply_cb	Callback routine that is called when preferences are applied. It may be NULL, which inhibits the callback.

Returns

a preferences module which can be used to register a user 'preference'

prefs_register_range_preference()

WS_DLL_PUBLIC void prefs_register_range_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		range_t **	var,
		uint32_t	max_value
	)

Register a preference with a ranged value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
var	pointer to the storage location that is updated when the field is changed in the preference dialog box.
max_value	the maximum allowed value for a range (0 is the minimum)

prefs_register_stat()

WS_DLL_PUBLIC module_t * prefs_register_stat	(	const char *	name,
		const char *	title,
		const char *	description,
		void(*)(void)	apply_cb
	)

Register that a statistical tap has preferences.

Parameters

name	the name for the tap to use on the command line with "-o" and in preference files.
title	is a short human-readable name for the tap.
description	is a longer human-readable description of the tap.
apply_cb	routine to call back after we apply the preferences

Returns

a preferences module which can be used to register a user 'preference'

prefs_register_static_text_preference()

WS_DLL_PUBLIC void prefs_register_static_text_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description
	)

Register a static text 'preference'. It can be used to add some info/explanation.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL

prefs_register_string_preference()

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 character-string value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
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

prefs_register_uat_preference()

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 (User Accessible Table) 'preference'. It adds a button that opens the uat's window in the preferences tab of the module.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	Field's title in the preferences dialog
description	description to include in the preferences file and shown as tooltip in the GUI, or NULL
uat	the uat object that will be updated when the field is changed in the preference dialog box

prefs_register_uint_preference()

WS_DLL_PUBLIC void prefs_register_uint_preference	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		unsigned	base,
		unsigned *	var
	)

Register a preference with an unsigned integral value.

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.
title	the title in the preferences dialog
description	the description included in the preferences file and shown as tooltip in the GUI, or NULL
base	the base the unsigned integer is expected to be in. See strtoul(3)
var	pointer to the storage location that is updated when the field is changed in the preference dialog box

prefs_reset()

WS_DLL_PUBLIC void prefs_reset	(	const char *	app_env_var_prefix,
		const char **	col_fmt,
		int	num_cols
	)

Resets preferences to their default values.

Reset preferences to default values. Called at profile change

Parameters

app_env_var_prefix	Prefix for the application environment variables.
col_fmt	Array of column format strings.
num_cols	Number of columns in the format array.

prefs_set_pref()

WS_DLL_PUBLIC prefs_set_pref_e prefs_set_pref	(	char *	prefarg,
		char **	errmsg
	)

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.

Parameters

prefarg	a string of the form "<pref name>:<pref value>"
errmsg	storage for syntax error details

Returns

the result from attempting to set the preference

prefs_set_preference_effect()

WS_DLL_PUBLIC void prefs_set_preference_effect	(	module_t *	module,
		const char *	name,
		unsigned	flags
	)

Set the effect flags for a preference in a given module.

Parameters

module	The module containing the preference.
name	The name of the preference to set.
flags	The effect flags to set.

prefs_set_preference_effect_fields()

WS_DLL_PUBLIC void prefs_set_preference_effect_fields	(	module_t *	module,
		const char *	name
	)

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().

Parameters

module	the preferences module returned by prefs_register_protocol() or prefs_register_protocol_subtree()
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.

read_prefs()

e_prefs * read_prefs ( const char *  app_env_var_prefix )

extern

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.

Parameters

app_env_var_prefix

The prefix for the application environment variable used to get the global configuration directory.

Returns

a pointer to the filled in prefs object

string_to_name_resolve()

WS_DLL_PUBLIC char string_to_name_resolve	(	const char *	string,
		struct _e_addr_resolve *	name_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.

Parameters

string	a list of name resolution types
name_resolve	the bitmap of names to resolve to set

Returns

'\0' on success, the bad character in the string on error

write_prefs()

WS_DLL_PUBLIC int write_prefs	(	const char *	app_env_var_prefix,
		char **	pf_path_return
	)

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.

Parameters

app_env_var_prefix	The prefix for the application environment variable used to get the global configuration directory.
pf_path_return	The path to write preferences to or NULL for stdout

Returns

0 if success, otherwise errno