#include <stdio.h>
#include "ws_symbol_export.h"
#include <epan/wmem_scopes.h>

Classes
struct	pref_module
	Represents a preference module grouping related preferences under a named, hierarchical entry in the preferences system. More...

struct	write_pref_arg_t
	Bundles a preference module with a file handle for use during preference serialization. More...

struct	pref_custom_cbs
	Callback table for a PREF_CUSTOM preference, providing lifecycle and serialization hooks. More...

struct	pref_unstash_data
	Carries context data used when unstashing preferences back to their live values. More...

Typedefs
typedef void(*	pref_custom_free_cb) (pref_t *pref)
	Callback invoked to free any resources allocated by a custom preference.

typedef void(*	pref_custom_reset_cb) (pref_t *pref)
	Callback invoked to reset a custom preference to its default value.

typedef prefs_set_pref_e(*	pref_custom_set_cb) (pref_t pref, const char value, unsigned int *changed_flags)
	Callback invoked to set a custom preference from a string value, reporting which flags changed.

typedef const char (	pref_custom_type_name_cb) (void)
	Callback that returns the type name string for a custom preference; returns NULL for internal or hidden preferences.

typedef char (	pref_custom_type_description_cb) (void)
	Callback that returns a newly allocated human-readable description of a custom preference type.

typedef bool(*	pref_custom_is_default_cb) (pref_t *pref)
	Callback that reports whether a custom preference currently holds its default value.

typedef char (	pref_custom_to_str_cb) (pref_t *pref, bool default_val)
	Callback that serializes a custom preference to a newly allocated string.

typedef prefs_set_pref_e(*	pref_set_pair_cb) (char key, const char value, void *private_data, bool return_range_errors)
	Set a preference based on a key-value pair.

typedef struct pref_unstash_data	pref_unstash_data_t
	Carries context data used when unstashing preferences back to their live values.

Enumerations
enum	pref_type_e { PREF_UINT , PREF_BOOL , PREF_ENUM , PREF_STRING , PREF_RANGE , PREF_STATIC_TEXT , PREF_UAT , PREF_SAVE_FILENAME , PREF_COLOR , PREF_CUSTOM , PREF_DIRNAME , PREF_DECODE_AS_RANGE , PREF_OPEN_FILENAME , PREF_PASSWORD , PREF_PROTO_TCP_SNDAMB_ENUM , PREF_DISSECTOR , PREF_INT , PREF_FLOAT }
	Discriminator tag identifying the type and UI representation of a preference entry. More...

Functions
WS_DLL_PUBLIC const char *	prefs_get_description (pref_t *pref)
	Get the description of a preference.

WS_DLL_PUBLIC const char *	prefs_get_title (pref_t *pref)
	Get the title of a preference.

WS_DLL_PUBLIC const char *	prefs_get_name (pref_t *pref)
	Fetch the name of a preference.

WS_DLL_PUBLIC int	prefs_get_type (pref_t *pref)
	Retrieves the type of a preference.

WS_DLL_PUBLIC uint32_t	prefs_get_max_value (pref_t *pref)
	Fetches the maximum value for a preference.

WS_DLL_PUBLIC unsigned int	prefs_get_effect_flags (pref_t *pref)
	Fetch flags that show the effect of the preference.

WS_DLL_PUBLIC void	prefs_set_effect_flags (pref_t *pref, unsigned int flags)
	Set flags for the effect of the preference.

WS_DLL_PUBLIC void	prefs_set_effect_flags_by_name (module_t module, const char pref, unsigned int flags)
	Same as prefs_set_effect_flags, just different way to get preference.

WS_DLL_PUBLIC unsigned int	prefs_get_module_effect_flags (module_t *module)
	Fetch flags that show module's preferences effect.

WS_DLL_PUBLIC unsigned	prefs_module_list_foreach (const wmem_tree_t module_list, module_cb callback, void user_data, bool skip_obsolete)
	Iterate through all modules with preferences.

WS_DLL_PUBLIC void	prefs_set_module_effect_flags (module_t *module, unsigned int flags)
	Set flags for module's preferences effect.

WS_DLL_PUBLIC bool	prefs_set_range_value_work (pref_t pref, const char value, bool return_range_errors, unsigned int *changed_flags)
	Set a range value for a range preference.

WS_DLL_PUBLIC unsigned int	prefs_set_stashed_range_value (pref_t pref, const char value)
	Set a stashed range value for a preference.

WS_DLL_PUBLIC void	prefs_range_add_value (pref_t *pref, uint32_t val)
	Add a range value of a range preference.

WS_DLL_PUBLIC void	prefs_range_remove_value (pref_t *pref, uint32_t val)
	Remove a range value of a range preference.

WS_DLL_PUBLIC unsigned int	prefs_set_bool_value (pref_t *pref, bool value, pref_source_t source)
	Set a boolean preference value.

WS_DLL_PUBLIC bool	prefs_get_bool_value (pref_t *pref, pref_source_t source)
	Get the boolean value of a preference.

WS_DLL_PUBLIC void	prefs_invert_bool_value (pref_t *pref, pref_source_t source)
	Inverts the boolean value of a preference based on the specified source.

WS_DLL_PUBLIC unsigned int	prefs_set_uint_value (pref_t *pref, unsigned value, pref_source_t source)
	Set an unsigned integer preference value.

WS_DLL_PUBLIC unsigned	prefs_get_uint_base (pref_t *pref)
	Get the base value of an unsigned integer preference.

WS_DLL_PUBLIC unsigned	prefs_get_uint_value (pref_t *pref, pref_source_t source)
	Get the unsigned integer value of a preference.

WS_DLL_PUBLIC unsigned int	prefs_set_int_value (pref_t *pref, int value, pref_source_t source)
	Set an integer preference value.

WS_DLL_PUBLIC int	prefs_get_int_value (pref_t *pref, pref_source_t source)
	Get the integer value of a preference based on the specified source.

WS_DLL_PUBLIC unsigned int	prefs_set_float_value (pref_t *pref, double value, pref_source_t source)
	Set a float value for a preference.

WS_DLL_PUBLIC double	prefs_get_float_value (pref_t *pref, pref_source_t source)
	Get the float value of a preference.

WS_DLL_PUBLIC unsigned int	prefs_set_enum_value (pref_t *pref, int value, pref_source_t source)
	Set an enum preference value.

WS_DLL_PUBLIC unsigned int	prefs_set_enum_string_value (pref_t pref, const char value, pref_source_t source)
	Set an enum value for a preference.

WS_DLL_PUBLIC int	prefs_get_enum_value (pref_t *pref, pref_source_t source)
	Get the current value of an enumeration preference.

WS_DLL_PUBLIC const enum_val_t *	prefs_get_enumvals (pref_t *pref)
	Get the enumeration values for a preference.

WS_DLL_PUBLIC bool	prefs_get_enum_radiobuttons (pref_t *pref)
	Get the radio button values for an enumeration preference.

WS_DLL_PUBLIC bool	prefs_set_color_value (pref_t *pref, color_t value, pref_source_t source)
	Set a color value for a preference.

WS_DLL_PUBLIC color_t *	prefs_get_color_value (pref_t *pref, pref_source_t source)
	Get the color value for a preference based on the specified source.

WS_DLL_PUBLIC unsigned int	prefs_set_custom_value (pref_t pref, const char value, pref_source_t source)
	Set a custom value for a preference.

WS_DLL_PUBLIC unsigned int	prefs_set_string_value (pref_t pref, const char value, pref_source_t source)
	Set a string value for a preference.

WS_DLL_PUBLIC const char *	prefs_get_string_value (pref_t *pref, pref_source_t source)
	Get the string value of a preference.

WS_DLL_PUBLIC struct epan_uat *	prefs_get_uat_value (pref_t *pref)
	Get the UAT value for a preference.

WS_DLL_PUBLIC bool	prefs_set_range_value (pref_t pref, range_t value, pref_source_t source)
	Set a range value for a preference.

WS_DLL_PUBLIC range_t *	prefs_get_range_value_real (pref_t *pref, pref_source_t source)
	Get the range value for a preference based on the specified source.

WS_DLL_PUBLIC bool	prefs_add_decode_as_value (pref_t *pref, unsigned value, bool replace)
	Adds or replaces a decode-as value for a preference.

WS_DLL_PUBLIC bool	prefs_remove_decode_as_value (pref_t *pref, unsigned value, bool set_default)
	Removes a decode-as value from a preference.

WS_DLL_PUBLIC unsigned int	prefs_set_password_value (pref_t pref, const char value, pref_source_t source)
	Set a password value for a preference.

WS_DLL_PUBLIC const char *	prefs_get_password_value (pref_t *pref, pref_source_t source)
	Get the password value for a preference.

WS_DLL_PUBLIC bool	prefs_add_list_value (pref_t pref, void value, pref_source_t source)
	Add a list value to a preference.

WS_DLL_PUBLIC GList *	prefs_get_list_value (pref_t *pref, pref_source_t source)
	Get the list value for a preference based on the source.

WS_DLL_PUBLIC void	reset_pref (pref_t *pref)
	Reset a preference to its default value.

WS_DLL_PUBLIC const wmem_tree_t *	prefs_get_module_tree (void)
	Get the list of all modules with preferences (used for iterating through all preferences)

WS_DLL_PUBLIC int	read_prefs_file (const char pf_path, FILE pf, pref_set_pair_cb pref_set_pair_fct, void *private_data)
	Read the preferences file (or similar) and call the callback function to set each key/value pair found.

WS_DLL_PUBLIC void	prefs_read_module (const char name, const char app_env_var_prefix)
	Read the preferences for a specific module.

WS_DLL_PUBLIC bool	prefs_pref_is_default (pref_t *pref)
	Check if a preference is at its default value.

WS_DLL_PUBLIC unsigned	pref_stash (pref_t pref, void unused)
	"Stash" a preference. Copy a preference to its stashed value. Can be called from prefs_pref_foreach().

WS_DLL_PUBLIC unsigned	pref_unstash (pref_t pref, void unstash_data_p)
	"Unstash" a preference. Set a preference to its stashed value. Can be called from prefs_pref_foreach().

WS_DLL_PUBLIC unsigned	pref_clean_stash (pref_t pref, void unused)
	Clean up a stashed preference. Can be called from prefs_pref_foreach().

WS_DLL_PUBLIC void	reset_stashed_pref (pref_t *pref)
	Set a stashed preference to its default value.

WS_DLL_PUBLIC char *	join_string_list (GList *sl)
	Convert a string list preference to a preference string.

WS_DLL_PUBLIC char *	prefs_sanitize_string (const char *str)
	Sanitize a string so that it can be written to a preference file.

Typedef Documentation

◆ pref_custom_free_cb

typedef void(* pref_custom_free_cb) (pref_t *pref)

Callback invoked to free any resources allocated by a custom preference.

Parameters

pref	The custom preference to free.

◆ pref_custom_is_default_cb

typedef bool(* pref_custom_is_default_cb) (pref_t *pref)

Callback that reports whether a custom preference currently holds its default value.

Parameters

pref	The custom preference to check.

Returns: True if the preference is set to its default value, false otherwise.

◆ pref_custom_reset_cb

typedef void(* pref_custom_reset_cb) (pref_t *pref)

Callback invoked to reset a custom preference to its default value.

Parameters

pref	The custom preference to reset.

◆ pref_custom_set_cb

typedef prefs_set_pref_e(* pref_custom_set_cb) (pref_t *pref, const char *value, unsigned int *changed_flags)

Callback invoked to set a custom preference from a string value, reporting which flags changed.

Parameters

pref	The custom preference to update.
value	The new value as a string to parse and apply.
changed_flags	Bitmask updated to indicate which aspects of the preference changed.

Returns: A prefs_set_pref_e result code indicating success or the nature of any error.

◆ pref_custom_to_str_cb

typedef char *(* pref_custom_to_str_cb) (pref_t *pref, bool default_val)

Callback that serializes a custom preference to a newly allocated string.

Parameters

pref	The custom preference to serialize.
default_val	True to serialize the default value, false to serialize the current value.

Returns: A newly allocated string representation of the preference value; caller is responsible for freeing it.

◆ pref_custom_type_description_cb

typedef char *(* pref_custom_type_description_cb) (void)

Callback that returns a newly allocated human-readable description of a custom preference type.

Returns: A newly allocated string describing the preference type; caller is responsible for freeing it.

◆ pref_custom_type_name_cb

typedef const char *(* pref_custom_type_name_cb) (void)

Callback that returns the type name string for a custom preference; returns NULL for internal or hidden preferences.

Returns: A string identifying the preference type, or NULL if the preference should be hidden.

◆ pref_set_pair_cb

typedef prefs_set_pref_e(* pref_set_pair_cb) (char *key, const char *value, void *private_data, bool return_range_errors)

Set a preference based on a key-value pair.

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.

Parameters

key	The name of the preference to set.
value	The value to set the preference to.
private_data	Private data to pass to the callback function.
return_range_errors	If true, return errors related to range values.

Returns: an indication of whether it succeeded or failed in some fashion.

Enumeration Type Documentation

◆ pref_type_e

enum pref_type_e

Discriminator tag identifying the type and UI representation of a preference entry.

Annotations:

(1) Not used in new code; retained for backward compatibility.
(2) Like PREF_RANGE but also registers the value as a Decode As handler.
(3) Value is stored but never written to the preferences file.
(4) TCP simultaneous-open ambiguity resolution enum.
(5) Selects a subdissector by name from a dissector table.

Enumerator
PREF_UINT	Unsigned integer preference
PREF_BOOL	Boolean (true/false) preference
PREF_ENUM	Enumerated value preference, chosen from a fixed value_string list
PREF_STRING	Free-form string preference
PREF_RANGE	Port/value range preference (e.g., "80,443,8080-8090")
PREF_STATIC_TEXT	Non-editable informational label displayed in the preferences UI
PREF_UAT	User Accessible Table (UAT) preference
PREF_SAVE_FILENAME	File path preference for a file to be written/saved
PREF_COLOR	Color preference (1); not used in new code
PREF_CUSTOM	Custom preference with user-supplied callbacks (1); not used in new code
PREF_DIRNAME	Directory path preference
PREF_DECODE_AS_RANGE	Range preference that also registers a Decode As mapping (2)
PREF_OPEN_FILENAME	File path preference for a file to be read/opened
PREF_PASSWORD	Sensitive string preference; stored in memory but never persisted to disk (3)
PREF_PROTO_TCP_SNDAMB_ENUM	Enum preference for resolving TCP simultaneous-open ambiguity (4)
PREF_DISSECTOR	Subdissector selection preference; names a dissector within a table (5)
PREF_INT	Signed integer preference
PREF_FLOAT	Floating-point preference

Function Documentation

◆ join_string_list()

WS_DLL_PUBLIC char * join_string_list ( GList * sl )

Convert a string list preference to a preference string.

Given a GList of char pointers, create a quoted, comma-separated string. Should be used with prefs_get_string_list() and prefs_clear_string_list().

Parameters

sl	String list.

Returns: Quoted, joined, and wrapped string. May be empty.

◆ pref_clean_stash()

WS_DLL_PUBLIC unsigned pref_clean_stash	(	pref_t *	pref,
		void *	unused
	)

Clean up a stashed preference. Can be called from prefs_pref_foreach().

Parameters

pref	A preference.
unused	unused

Returns: Always returns 0.

◆ pref_stash()

WS_DLL_PUBLIC unsigned pref_stash	(	pref_t *	pref,
		void *	unused
	)

"Stash" a preference. Copy a preference to its stashed value. Can be called from prefs_pref_foreach().

Parameters

pref	A preference.
unused	unused

◆ pref_unstash()

WS_DLL_PUBLIC unsigned pref_unstash	(	pref_t *	pref,
		void *	unstash_data_p
	)

"Unstash" a preference. Set a preference to its stashed value. Can be called from prefs_pref_foreach().

Parameters

pref	A preference.
unstash_data_p	A pointer to a pref_unstash_data_t structure.

Returns: Always returns 0.

◆ prefs_add_decode_as_value()

WS_DLL_PUBLIC bool prefs_add_decode_as_value	(	pref_t *	pref,
		unsigned	value,
		bool	replace
	)

Adds or replaces a decode-as value for a preference.

Parameters

pref	Pointer to the preference structure.
value	The value to add or replace.
replace	If true, replace the existing value if it exists.

Returns: True if the operation was successful, false otherwise.

◆ prefs_add_list_value()

WS_DLL_PUBLIC bool prefs_add_list_value	(	pref_t *	pref,
		void *	value,
		pref_source_t	source
	)

Add a list value to a preference.

Parameters

pref	Pointer to the preference structure.
value	The value to add to the list.
source	The source of the preference value.

Returns: true if the value was added successfully, false otherwise.

◆ prefs_get_bool_value()

WS_DLL_PUBLIC bool prefs_get_bool_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the boolean value of a preference.

Parameters

pref	Pointer to the preference structure.
source	The source from which to retrieve the value (default, stashed, or current).

Returns: true if the preference is set to true, false otherwise.

◆ prefs_get_color_value()

WS_DLL_PUBLIC color_t * prefs_get_color_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the color value for a preference based on the specified source.

Parameters

pref	The preference structure.
source	The source of the preference value (default, stashed, or current).

Returns: Pointer to the color value.

◆ prefs_get_description()

WS_DLL_PUBLIC const char * prefs_get_description ( pref_t * pref )

Get the description of a preference.

Parameters

pref	Pointer to the preference structure.

Returns: Description of the preference.

◆ prefs_get_effect_flags()

WS_DLL_PUBLIC unsigned int prefs_get_effect_flags ( pref_t * pref )

Fetch flags that show the effect of the preference.

Parameters

pref	A preference.

Returns: A bitmask of the types of things the preference will effect.

◆ prefs_get_enum_radiobuttons()

WS_DLL_PUBLIC bool prefs_get_enum_radiobuttons ( pref_t * pref )

Get the radio button values for an enumeration preference.

Parameters

pref	Pointer to the preference structure.

Returns: bool True if the enumeration has radio buttons, false otherwise.

◆ prefs_get_enum_value()

WS_DLL_PUBLIC int prefs_get_enum_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the current value of an enumeration preference.

Parameters

pref	Pointer to the preference structure.
source	The source from which to retrieve the value (default, stashed, or current).

Returns: int The current value of the enumeration preference.

◆ prefs_get_enumvals()

WS_DLL_PUBLIC const enum_val_t * prefs_get_enumvals ( pref_t * pref )

Get the enumeration values for a preference.

Parameters

pref	Pointer to the preference structure.

Returns: const enum_val_t* Pointer to the enumeration values.

◆ prefs_get_float_value()

WS_DLL_PUBLIC double prefs_get_float_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the float value of a preference.

Parameters

pref	Pointer to the preference structure.
source	The source from which to retrieve the value (default, stashed, or current).

Returns: double The float value of the preference.

◆ prefs_get_int_value()

WS_DLL_PUBLIC int prefs_get_int_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the integer value of a preference based on the specified source.

Parameters

pref	Pointer to the preference structure.
source	The source from which to retrieve the value (default, stashed, or current).

Returns: int The integer value of the preference.

◆ prefs_get_list_value()

WS_DLL_PUBLIC GList * prefs_get_list_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the list value for a preference based on the source.

Parameters

pref	The preference to retrieve the list value from.
source	The source of the preference value (default, stashed, or current).

Returns: GList* The list value corresponding to the preference and source.

◆ prefs_get_max_value()

WS_DLL_PUBLIC uint32_t prefs_get_max_value ( pref_t * pref )

Fetches the maximum value for a preference.

Parameters

pref	Pointer to the preference structure.

Returns: The name of the preference as a constant string.

◆ prefs_get_module_effect_flags()

WS_DLL_PUBLIC unsigned int prefs_get_module_effect_flags ( module_t * module )

Fetch flags that show module's preferences effect.

The flag values of the module will be applied to any individual preferences of the module when they are created

Parameters

module A preference module.

Returns: A bitmask of the types of things the module's preferences will effect.

◆ prefs_get_module_tree()

WS_DLL_PUBLIC const wmem_tree_t * prefs_get_module_tree ( void )

Get the list of all modules with preferences (used for iterating through all preferences)

Returns: The tree of modules with preferences.

◆ prefs_get_name()

WS_DLL_PUBLIC const char * prefs_get_name ( pref_t * pref )

Fetch the name of a preference.

Parameters

pref	Pointer to the preference structure.

Returns: The name of the preference as a constant string.

◆ prefs_get_password_value()

WS_DLL_PUBLIC const char * prefs_get_password_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the password value for a preference.

Parameters

pref	The preference to get the value from.
source	The source of the preference value.

Returns: const char* The password value, or NULL if not found.

◆ prefs_get_range_value_real()

WS_DLL_PUBLIC range_t * prefs_get_range_value_real	(	pref_t *	pref,
		pref_source_t	source
	)

Get the range value for a preference based on the specified source.

Parameters

pref	Pointer to the preference structure.
source	The source of the preference value (default, stashed, or current).

Returns: Pointer to the range value of the preference.

◆ prefs_get_string_value()

WS_DLL_PUBLIC const char * prefs_get_string_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the string value of a preference.

Parameters

pref	Pointer to the preference structure.
source	The source from which to retrieve the value (default, stashed, or current).

Returns: The string value of the preference.

◆ prefs_get_title()

WS_DLL_PUBLIC const char * prefs_get_title ( pref_t * pref )

Get the title of a preference.

Parameters

pref	Pointer to the preference structure.

Returns: Title of the preference.

◆ prefs_get_type()

WS_DLL_PUBLIC int prefs_get_type ( pref_t * pref )

Retrieves the type of a preference.

Parameters

pref	Pointer to the preference structure.

Returns: Type of the preference.

◆ prefs_get_uat_value()

WS_DLL_PUBLIC struct epan_uat * prefs_get_uat_value ( pref_t * pref )

Get the UAT value for a preference.

Parameters

pref	The preference to get the UAT value from.

Returns: Pointer to the UAT value, or NULL if not set.

◆ prefs_get_uint_base()

WS_DLL_PUBLIC unsigned prefs_get_uint_base ( pref_t * pref )

Get the base value of an unsigned integer preference.

Parameters

pref	Pointer to the preference structure.

Returns: The base value of the unsigned integer preference.

◆ prefs_get_uint_value()

WS_DLL_PUBLIC unsigned prefs_get_uint_value	(	pref_t *	pref,
		pref_source_t	source
	)

Get the unsigned integer value of a preference.

Parameters

pref	Pointer to the preference structure.
source	The source from which to retrieve the value (default, stashed, or current).

Returns: The unsigned integer value of the preference.

◆ prefs_invert_bool_value()

WS_DLL_PUBLIC void prefs_invert_bool_value	(	pref_t *	pref,
		pref_source_t	source
	)

Inverts the boolean value of a preference based on the specified source.

Parameters

pref	Pointer to the preference structure.
source	The source from which to invert the value (default, stashed, or current).

◆ prefs_module_list_foreach()

WS_DLL_PUBLIC unsigned prefs_module_list_foreach	(	const wmem_tree_t *	module_list,
		module_cb	callback,
		void *	user_data,
		bool	skip_obsolete
	)

Iterate through all modules with preferences.

Parameters

module_list	The tree of modules to iterate through
callback	The callback function to call for each module
user_data	User data to pass to the callback function
skip_obsolete	If true, skip obsolete preferences

Returns: The return value of the callback function if it returns non-zero, otherwise 0

◆ prefs_pref_is_default()

WS_DLL_PUBLIC bool prefs_pref_is_default ( pref_t * pref )

Check if a preference is at its default value.

Parameters

pref	The preference to check.

Returns: true if the preference is at its default value, false otherwise.

◆ prefs_range_add_value()

WS_DLL_PUBLIC void prefs_range_add_value	(	pref_t *	pref,
		uint32_t	val
	)

Add a range value of a range preference.

Parameters

pref	Pointer to the preference structure.
val	The value to add.

◆ prefs_range_remove_value()

WS_DLL_PUBLIC void prefs_range_remove_value	(	pref_t *	pref,
		uint32_t	val
	)

Remove a range value of a range preference.

Parameters

pref	Pointer to the preference structure.
val	The value to remove.

◆ prefs_read_module()

WS_DLL_PUBLIC void prefs_read_module	(	const char *	name,
		const char *	app_env_var_prefix
	)

Read the preferences for a specific module.

Given a module name, read the preferences associated with only that module. Checks for a file in the personal configuration directory named after the module with a ".cfg" extension added first.

Parameters

name	The preference module name, e.g. "extcap".
app_env_var_prefix	The prefix for the application environment variable.

◆ prefs_remove_decode_as_value()

WS_DLL_PUBLIC bool prefs_remove_decode_as_value	(	pref_t *	pref,
		unsigned	value,
		bool	set_default
	)

Removes a decode-as value from a preference.

Parameters

pref	The preference to modify.
value	The value to remove.
set_default	Whether to set the default if the value is the only one in the range.

Returns: true If the operation was successful, false otherwise.

◆ prefs_sanitize_string()

WS_DLL_PUBLIC char * prefs_sanitize_string ( const char * str )

Sanitize a string so that it can be written to a preference file.

The preference file format (along with some other Wireshark file formats) expects one entry per line. This takes a string, which may come from user input, and converts line terminators (along with adjacent whitespace) into a single space.

◆ prefs_set_bool_value()

WS_DLL_PUBLIC unsigned int prefs_set_bool_value	(	pref_t *	pref,
		bool	value,
		pref_source_t	source
	)

Set a boolean preference value.

Parameters

pref	Pointer to the preference structure.
value	The new boolean value.
source	The source of the preference change.

Returns: unsigned int Flags indicating changes made.

◆ prefs_set_color_value()

WS_DLL_PUBLIC bool prefs_set_color_value	(	pref_t *	pref,
		color_t	value,
		pref_source_t	source
	)

Set a color value for a preference.

Parameters

pref	Pointer to the preference structure.
value	The new color value.
source	The source of the preference value.

Returns: true if the value was changed, false otherwise.

◆ prefs_set_custom_value()

WS_DLL_PUBLIC unsigned int prefs_set_custom_value	(	pref_t *	pref,
		const char *	value,
		pref_source_t	source
	)

Set a custom value for a preference.

Parameters

pref	Pointer to the preference structure.
value	The new value to set.
source	The source of the preference change.

Returns: unsigned int Number of preferences that have changed.

◆ prefs_set_effect_flags()

WS_DLL_PUBLIC void prefs_set_effect_flags	(	pref_t *	pref,
		unsigned int	flags
	)

Set flags for the effect of the preference.

The intention is to distinguish preferences that affect dissection from those that don't. A bitmask was added to provide greater flexibility in the types of effects preferences can have.

Parameters

pref	A preference.
flags	Bitmask of flags to apply to preference. Note that flags must be non-zero to ensure preference is properly saved to disk.

◆ prefs_set_effect_flags_by_name()

WS_DLL_PUBLIC void prefs_set_effect_flags_by_name	(	module_t *	module,
		const char *	pref,
		unsigned int	flags
	)

Same as prefs_set_effect_flags, just different way to get preference.

Parameters

module	A preference module.
pref	The name of the preference to set the flags for.
flags	Bitmask of flags to apply to preference. Note that flags must be non-zero to ensure preference is properly saved to disk.

◆ prefs_set_enum_string_value()

WS_DLL_PUBLIC unsigned int prefs_set_enum_string_value	(	pref_t *	pref,
		const char *	value,
		pref_source_t	source
	)

Set an enum value for a preference.

Parameters

pref	The preference to set.
value	The string representation of the enum value.
source	The source of the preference change.

Returns: unsigned int The new enum value.

◆ prefs_set_enum_value()

WS_DLL_PUBLIC unsigned int prefs_set_enum_value	(	pref_t *	pref,
		int	value,
		pref_source_t	source
	)

Set an enum preference value.

Parameters

pref	Pointer to the preference structure.
value	The new enum value.
source	The source of the preference change.

Returns: unsigned int Flags indicating changes made.

◆ prefs_set_float_value()

WS_DLL_PUBLIC unsigned int prefs_set_float_value	(	pref_t *	pref,
		double	value,
		pref_source_t	source
	)

Set a float value for a preference.

Parameters

pref	Pointer to the preference structure.
value	The new float value to set.
source	The source of the preference change (default, stashed, or current).

Returns: unsigned int Flags indicating the effect of the change.

◆ prefs_set_int_value()

WS_DLL_PUBLIC unsigned int prefs_set_int_value	(	pref_t *	pref,
		int	value,
		pref_source_t	source
	)

Set an integer preference value.

Parameters

pref	Pointer to the preference structure.
value	The new integer value to set.
source	The source of the preference change (default, stashed, or current).

Returns: unsigned int Flags indicating the effects of the change.

◆ prefs_set_module_effect_flags()

WS_DLL_PUBLIC void prefs_set_module_effect_flags	(	module_t *	module,
		unsigned int	flags
	)

Set flags for module's preferences effect.

The intention is to distinguish preferences that affect dissection from those that don't. Since modules are a grouping of preferences, it's likely that a whole module will want the same flags for its preferences. The flag values of the module will be applied to any individual preferences of the module when they are created

Parameters

module	A preference module.
flags	Bitmask of flags to apply to module. Note that flags must be non-zero to ensure preferences are properly saved to disk.

◆ prefs_set_password_value()

WS_DLL_PUBLIC unsigned int prefs_set_password_value	(	pref_t *	pref,
		const char *	value,
		pref_source_t	source
	)

Set a password value for a preference.

Parameters

pref	Pointer to the preference structure.
value	The new password value to set.
source	The source of the preference change (default, stashed, or current).

Returns: unsigned int Flags indicating the effect of the change.

◆ prefs_set_range_value()

WS_DLL_PUBLIC bool prefs_set_range_value	(	pref_t *	pref,
		range_t *	value,
		pref_source_t	source
	)

Set a range value for a preference.

Parameters

pref	Pointer to the preference structure.
value	Pointer to the new range value.
source	Source of the preference value (default, stashed, or current).

Returns: true if the value was changed, false otherwise.

◆ prefs_set_range_value_work()

WS_DLL_PUBLIC bool prefs_set_range_value_work	(	pref_t *	pref,
		const char *	value,
		bool	return_range_errors,
		unsigned int *	changed_flags
	)

Set a range value for a range preference.

Parameters

pref	Pointer to the preference structure.
value	The new range value as a string.
return_range_errors	If true, return errors related to range values.
changed_flags	Pointer to store flags indicating changes.

Returns: True if the value was successfully set, false otherwise.

◆ prefs_set_stashed_range_value()

WS_DLL_PUBLIC unsigned int prefs_set_stashed_range_value	(	pref_t *	pref,
		const char *	value
	)

Set a stashed range value for a preference.

Parameters

pref	Pointer to the preference structure.
value	String representation of the range value.

Returns: unsigned int Effect flags after setting the stashed value.

◆ prefs_set_string_value()

WS_DLL_PUBLIC unsigned int prefs_set_string_value	(	pref_t *	pref,
		const char *	value,
		pref_source_t	source
	)

Set a string value for a preference.

Parameters

pref	Pointer to the preference structure.
value	The new string value to set.
source	The source of the preference change.

Returns: Flags indicating changes, or 0 if no change.

◆ prefs_set_uint_value()

WS_DLL_PUBLIC unsigned int prefs_set_uint_value	(	pref_t *	pref,
		unsigned	value,
		pref_source_t	source
	)

Set an unsigned integer preference value.

Parameters

pref	Pointer to the preference structure.
value	The new unsigned integer value.
source	The source of the preference change (default, stashed, or current).

Returns: unsigned int Flags indicating the effect of the change.

◆ read_prefs_file()

WS_DLL_PUBLIC int read_prefs_file	(	const char *	pf_path,
		FILE *	pf,
		pref_set_pair_cb	pref_set_pair_fct,
		void *	private_data
	)

Read the preferences file (or similar) and call the callback function to set each key/value pair found.

Parameters

pf_path	The path to the preferences file.
pf	The file pointer to the preferences file.
pref_set_pair_fct	The callback function to set each key/value pair.
private_data	User data to pass to the callback function.

Returns: The result of reading the preferences file, or an error code if it fails

◆ reset_pref()

WS_DLL_PUBLIC void reset_pref ( pref_t * pref )

Reset a preference to its default value.

Parameters

pref	Pointer to the preference to be reset.

◆ reset_stashed_pref()

WS_DLL_PUBLIC void reset_stashed_pref ( pref_t * pref )

Set a stashed preference to its default value.

Parameters

pref	A preference.

Classes

Typedefs

Enumerations

Functions

Typedef Documentation

◆ pref_custom_free_cb

◆ pref_custom_is_default_cb

◆ pref_custom_reset_cb

◆ pref_custom_set_cb

◆ pref_custom_to_str_cb

◆ pref_custom_type_description_cb

◆ pref_custom_type_name_cb

◆ pref_set_pair_cb

Enumeration Type Documentation

◆ pref_type_e

Function Documentation

◆ join_string_list()

◆ pref_clean_stash()

◆ pref_stash()

◆ pref_unstash()

◆ prefs_add_decode_as_value()

◆ prefs_add_list_value()

◆ prefs_get_bool_value()

◆ prefs_get_color_value()

◆ prefs_get_description()

◆ prefs_get_effect_flags()

◆ prefs_get_enum_radiobuttons()

◆ prefs_get_enum_value()

◆ prefs_get_enumvals()

◆ prefs_get_float_value()

◆ prefs_get_int_value()

◆ prefs_get_list_value()

◆ prefs_get_max_value()

◆ prefs_get_module_effect_flags()

◆ prefs_get_module_tree()

◆ prefs_get_name()

◆ prefs_get_password_value()

◆ prefs_get_range_value_real()

◆ prefs_get_string_value()

◆ prefs_get_title()

◆ prefs_get_type()

◆ prefs_get_uat_value()

◆ prefs_get_uint_base()

◆ prefs_get_uint_value()

◆ prefs_invert_bool_value()

◆ prefs_module_list_foreach()

◆ prefs_pref_is_default()

◆ prefs_range_add_value()

◆ prefs_range_remove_value()

◆ prefs_read_module()

◆ prefs_remove_decode_as_value()

◆ prefs_sanitize_string()

◆ prefs_set_bool_value()

◆ prefs_set_color_value()

◆ prefs_set_custom_value()

◆ prefs_set_effect_flags()

◆ prefs_set_effect_flags_by_name()

◆ prefs_set_enum_string_value()

◆ prefs_set_enum_value()

◆ prefs_set_float_value()

◆ prefs_set_int_value()

◆ prefs_set_module_effect_flags()

◆ prefs_set_password_value()

◆ prefs_set_range_value()

◆ prefs_set_range_value_work()

◆ prefs_set_stashed_range_value()

◆ prefs_set_string_value()

◆ prefs_set_uint_value()

◆ read_prefs_file()

◆ reset_pref()

◆ reset_stashed_pref()