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

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	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_STYLE_DEFAULT   0
#define	COLOR_STYLE_FLAT   1
#define	COLOR_STYLE_GRADIENT   2
#define	COLOR_STYLE_ALPHA   0.25
#define	COLOR_SCHEME_DEFAULT   0
#define	COLOR_SCHEME_LIGHT   1
#define	COLOR_SCHEME_DARK   2

Typedefs
typedef struct _e_prefs	e_prefs
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 }
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 }
enum	version_info_e { version_welcome_only , version_title_only , version_both , version_neither }
enum	splitter_layout_e { layout_vertical , layout_horizontal }
enum	pref_source_t { pref_default , pref_stashed , pref_current }
enum	elide_mode_e { ELIDE_LEFT , ELIDE_RIGHT , ELIDE_MIDDLE , ELIDE_NONE }
enum	copy_format_e { COPY_FORMAT_TEXT , COPY_FORMAT_CSV , COPY_FORMAT_YAML , COPY_FORMAT_HTML }
enum	abs_time_format_e { ABS_TIME_ASCII_NEVER , ABS_TIME_ASCII_TREE , ABS_TIME_ASCII_COLUMN , ABS_TIME_ASCII_ALWAYS }
enum	software_update_channel_e { UPDATE_CHANNEL_DEVELOPMENT , UPDATE_CHANNEL_STABLE }
enum	prefs_set_pref_e { PREFS_SET_OK , PREFS_SET_SYNTAX_ERR , PREFS_SET_NO_SUCH_PREF , PREFS_SET_OBSOLETE }

Functions
WS_DLL_PUBLIC char	string_to_name_resolve (const char *string, struct _e_addr_resolve *name_resolve)
void	prefs_init (void)
WS_DLL_PUBLIC void	prefs_reset (void)
void	prefs_cleanup (void)
WS_DLL_PUBLIC void	prefs_set_gui_theme_is_dark (bool is_dark)
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)
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 bool	prefs_module_has_submodules (module_t *module)
WS_DLL_PUBLIC unsigned	prefs_modules_foreach (module_cb callback, void *user_data)
WS_DLL_PUBLIC unsigned	prefs_modules_foreach_submodules (module_t *module, 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_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_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)
WS_DLL_PUBLIC void	prefs_register_uat_preference_qt (module_t *module, const char *name, const char *title, const char *description, struct epan_uat *uat)
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)
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)
WS_DLL_PUBLIC void	prefs_set_preference_effect_fields (module_t *module, const char *name)
WS_DLL_PUBLIC unsigned	prefs_pref_foreach (module_t *module, pref_cb callback, void *user_data)
WS_DLL_PUBLIC GList *	prefs_get_string_list (const char *str)
WS_DLL_PUBLIC void	prefs_clear_string_list (GList *sl)
WS_DLL_PUBLIC const char *	prefs_pref_type_name (pref_t *pref)
WS_DLL_PUBLIC char *	prefs_pref_type_description (pref_t *pref)
WS_DLL_PUBLIC char *	prefs_pref_to_str (pref_t *pref, pref_source_t source)
e_prefs *	read_prefs (void)
WS_DLL_PUBLIC int	write_prefs (char **pf_path_return)
WS_DLL_PUBLIC prefs_set_pref_e	prefs_set_pref (char *prefarg, char **errmsg)
bool	prefs_get_preference_obsolete (pref_t *pref)
prefs_set_pref_e	prefs_set_preference_obsolete (pref_t *pref)
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)
WS_DLL_PUBLIC bool	prefs_capture_device_monitor_mode (const char *name)
WS_DLL_PUBLIC bool	prefs_capture_options_dialog_column_is_visible (const char *column)
WS_DLL_PUBLIC bool	prefs_has_layout_pane_content (layout_pane_content_e layout_pane_content)

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

prefs_set_pref_e

enum prefs_set_pref_e

Result of setting a preference.

Function Documentation

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

)

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

bool prefs_get_preference_obsolete

(

pref_t *

pref

)

Get or set a preference's obsolete status. These can be used to make a preference obsolete after startup so that we can fetch its value but keep it from showing up in the prefrences dialog.

Parameters

pref	A preference.

Returns

true if the preference is obsolete, otherwise false

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

(

void

)

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

)

Returns true 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_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_foreach()

WS_DLL_PUBLIC unsigned prefs_modules_foreach	(	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

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	(	module_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	the top-level module to walk through the submodules, or NULL for the top-level list in the display tree of modules
callback	the callback to call
user_data	additional data to pass to the callback

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

WS_DLL_PUBLIC void prefs_register_uat_preference_qt	(	module_t *	module,
		const char *	name,
		const char *	title,
		const char *	description,
		struct epan_uat *	uat
	)

Register a uat 'preference' for QT only. 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

(

void

)

Reset preferences to default values. Called at profile change

prefs_set_gui_theme_is_dark()

WS_DLL_PUBLIC void prefs_set_gui_theme_is_dark

(

bool

is_dark

)

Store whether the current UI theme is dark so that we can adjust colors

Parameters

is_dark

set to true if the UI's theme is dark

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

prefs_set_preference_obsolete()

prefs_set_pref_e prefs_set_preference_obsolete

(

pref_t *

pref

)

Make a preference obsolete

Parameters

pref	a preference.

Returns

the result from attempting to set the preference

read_prefs()

e_prefs * read_prefs ( void  )

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.

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

(

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

pf_path_return

The path to write preferences to or NULL for stdout

Returns

0 if success, otherwise errno