| Wireshark 4.7.3 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Typedefs | Enumerations | Functions
prefs-int.h File Reference
`#include <stdio.h>`
`#include "ws_symbol_export.h"`
`#include <epan/wmem_scopes.h>`

Go to the source code of this file.

## 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_get_changed_flags (pref_t *pref, void *unstash_data_p)
| Get the effect_flags from a stashed preference. 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_get_changed_flags()

WS_DLL_PUBLIC unsigned pref_get_changed_flags | ( | pref_t * | pref,
|  | void * | unstash_data_p )

Get the effect_flags from a stashed preference. 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.

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