| Wireshark 4.7.3 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
value_string.h File Reference
`#include <stdint.h>`
`#include "ws_symbol_export.h"`
`#include <wsutil/nstime.h>`

Go to the source code of this file.

## Classes
struct | _value_string
| Mapping between a 32-bit integer value and its string representation. More...
struct | _val64_string
| Mapping between a 64-bit integer value and its string representation. More...
struct | _value_string_ext
| Extended metadata for a value_string array. More...
struct | _val64_string_ext
| Extended metadata for a 64-bit value-string mapping array. More...
struct | _string_string
| Maps a string key to a string value, used for table-driven string-to-string lookups. More...
struct | _range_string
| Maps an inclusive numeric range to a string value, used for table-driven range-to-string lookups. More...
struct | _time_value_string
| Maps a timestamp key to a string value, used for table-driven time-to-string lookups. More...
struct | _bytes_string
| Maps a byte sequence key to a string value, used for table-driven binary-pattern-to-string lookups. More...

## Macros
#define | VALUE_STRING_ENUM( array_name)
#define | VALUE_STRING_ARRAY( array_name)
#define | VALUE_STRING_ARRAY_GLOBAL_DEF( array_name)
#define | VALUE_STRING_ARRAY_GLOBAL_DCL( array_name)
#define | VALUE_STRING_ENUM2( array_name)
#define | VALUE_STRING_ARRAY2( array_name)
#define | VALUE_STRING_ARRAY2_GLOBAL_DEF(array_name)
#define | VALUE_STRING_ARRAY2_GLOBAL_DCL(array_name)
#define | _VS_ENUM_XXX(array_name, macro)
#define | _VS_ARRAY_SC_XXX(array_name, macro, sc)
#define | _VS_ARRAY_XXX(array_name, macro)
#define | _VS_ARRAY_SC_TYPE_NAME(array_name, sc)
#define | _VS_ARRAY_TYPE_NAME(array_name)
#define | _VS_ENUM_ENTRY(name, value, string)
#define | _VS_ARRAY_ENTRY(name, value, string)
#define | _VS_ENUM_ENTRY2(name, value)
#define | _VS_ARRAY_ENTRY2(name, value)
#define | VALUE_STRING_EXT_VS_P(x)
#define | VALUE_STRING_EXT_VS_NUM_ENTRIES(x)
#define | VALUE_STRING_EXT_VS_NAME(x)
#define | VALUE_STRING_EXT_INIT(x)
#define | VAL64_STRING_EXT_VS_P(x)
#define | VAL64_STRING_EXT_VS_NUM_ENTRIES(x)
#define | VAL64_STRING_EXT_VS_NAME(x)
#define | VAL64_STRING_EXT_INIT(x)

## Typedefs
typedef struct _value_string | value_string
| Mapping between a 32-bit integer value and its string representation.
typedef struct _val64_string | val64_string
| Mapping between a 64-bit integer value and its string representation.
typedef struct _value_string_ext | value_string_ext
typedef const value_string *(* | _value_string_match2_t) (const uint32_t, value_string_ext *)
typedef struct _val64_string_ext | val64_string_ext
typedef const val64_string *(* | _val64_string_match2_t) (const uint64_t, val64_string_ext *)
typedef struct _string_string | string_string
| Maps a string key to a string value, used for table-driven string-to-string lookups.
typedef struct _range_string | range_string
| Maps an inclusive numeric range to a string value, used for table-driven range-to-string lookups.
typedef struct _time_value_string | time_value_string
| Maps a timestamp key to a string value, used for table-driven time-to-string lookups.
typedef struct _bytes_string | bytes_string
| Maps a byte sequence key to a string value, used for table-driven binary-pattern-to-string lookups.

## Functions
WS_DLL_PUBLIC char * | val_to_str (wmem_allocator_t *scope, const uint32_t val, const value_string *vs, const char *fmt)
| Convert a numeric value to a string using a value-string mapping.
WS_DLL_PUBLIC const char * | val_to_str_const (const uint32_t val, const value_string *vs, const char *unknown_str)
| Convert a numeric value to a constant string using a value-string mapping.
WS_DLL_PUBLIC const char * | try_val_to_str (const uint32_t val, const value_string *vs)
| Attempt to convert a numeric value to a string using a value-string mapping.
WS_DLL_PUBLIC const char * | try_val_to_str_idx (const uint32_t val, const value_string *vs, int *idx)
| Attempt to convert a numeric value to a string and retrieve its index.
WS_DLL_PUBLIC const char * | val64_to_str_wmem (wmem_allocator_t *scope, const uint64_t val, const val64_string *vs, const char *fmt)
| Convert a 64-bit value to a string using a value-string mapping.
WS_DLL_PUBLIC const char * | val64_to_str_const (const uint64_t val, const val64_string *vs, const char *unknown_str)
| Convert a 64-bit value to a constant string using a value-string mapping.
WS_DLL_PUBLIC const char * | try_val64_to_str (const uint64_t val, const val64_string *vs)
| Attempt to convert a 64-bit value to a string using a value-string mapping.
WS_DLL_PUBLIC const char * | try_val64_to_str_idx (const uint64_t val, const val64_string *vs, int *idx)
| Attempt to convert a 64-bit value to a string and retrieve its index.
WS_DLL_PUBLIC uint32_t | str_to_val (const char *val, const value_string *vs, const uint32_t err_val)
| Convert a string to its corresponding numeric value using a value-string mapping.
WS_DLL_PUBLIC int | str_to_val_idx (const char *val, const value_string *vs)
| Retrieve the index of a string in a value-string mapping array.
WS_DLL_PUBLIC const value_string * | _try_val_to_str_ext_init (const uint32_t val, value_string_ext *vse)
| Attempt to initialize and retrieve a value-string entry from an extended mapping.
WS_DLL_PUBLIC value_string_ext * | value_string_ext_new (wmem_allocator_t *scope, const value_string *vs, unsigned vs_tot_num_entries, const char *vs_name)
| Create a new extended value-string mapping structure.
WS_DLL_PUBLIC void | value_string_ext_free (value_string_ext *vse)
| Free an extended value-string mapping structure.
WS_DLL_PUBLIC char * | val_to_str_ext (wmem_allocator_t *scope, const uint32_t val, value_string_ext *vse, const char *fmt)
| Convert a numeric value to a string using an extended value-string mapping.
WS_DLL_PUBLIC const char * | val_to_str_ext_const (const uint32_t val, value_string_ext *vs, const char *unknown_str)
| Convert a numeric value to a constant string using an extended value-string mapping.
WS_DLL_PUBLIC const char * | try_val_to_str_ext (const uint32_t val, value_string_ext *vse)
| Attempt to convert a numeric value to a string using an extended value-string mapping.
WS_DLL_PUBLIC const char * | try_val_to_str_idx_ext (const uint32_t val, value_string_ext *vse, int *idx)
| Attempt to convert a numeric value to a string and retrieve its index from an extended mapping.
WS_DLL_PUBLIC int | value_str_value_compare (const void *a, const void *b)
| Compare two value_string entries by their numeric value.
WS_DLL_PUBLIC const val64_string * | _try_val64_to_str_ext_init (const uint64_t val, val64_string_ext *vse)
| Attempt to initialize and retrieve a 64-bit value-string entry from an extended mapping.
WS_DLL_PUBLIC val64_string_ext * | val64_string_ext_new (wmem_allocator_t *scope, const val64_string *vs, unsigned vs_tot_num_entries, const char *vs_name)
| Create a new extended value string structure.
WS_DLL_PUBLIC void | val64_string_ext_free (val64_string_ext *vse)
| Frees a val64_string_ext structure.
WS_DLL_PUBLIC char * | val64_to_str_ext_wmem (wmem_allocator_t *scope, const uint64_t val, val64_string_ext *vse, const char *fmt)
| Convert a 64-bit unsigned integer to a string using an extended value string structure.
WS_DLL_PUBLIC const char * | val64_to_str_ext_const (const uint64_t val, val64_string_ext *vs, const char *unknown_str)
| Convert a 64-bit unsigned integer to a string using an extended value string structure.
WS_DLL_PUBLIC const char * | try_val64_to_str_ext (const uint64_t val, val64_string_ext *vse)
| Convert a 64-bit value to its corresponding string index and pointer.
WS_DLL_PUBLIC const char * | try_val64_to_str_idx_ext (const uint64_t val, val64_string_ext *vse, int *idx)
| Convert a 64-bit value to its corresponding string index and pointer.
WS_DLL_PUBLIC const char * | str_to_str_wmem (wmem_allocator_t *scope, const char *val, const string_string *vs, const char *fmt)
| Converts a string value to a formatted string using a value string table.
WS_DLL_PUBLIC const char * | try_str_to_str (const char *val, const string_string *vs)
| Converts a string to another string based on a value-string mapping.
WS_DLL_PUBLIC const char * | try_str_to_str_idx (const char *val, const string_string *vs, int *idx)
| Converts a string to an index in a string-string mapping table.
WS_DLL_PUBLIC const char * | rval_to_str_wmem (wmem_allocator_t *scope, const uint32_t val, const range_string *rs, const char *fmt)
| Convert a 32-bit unsigned integer to its corresponding string representation based on a range string.
WS_DLL_PUBLIC const char * | rval_to_str_const (const uint32_t val, const range_string *rs, const char *unknown_str)
| Convert a 32-bit unsigned integer to its corresponding string representation based on a range string.
WS_DLL_PUBLIC const char * | try_rval_to_str (const uint32_t val, const range_string *rs)
| Convert a 32-bit unsigned integer to its corresponding string representation based on a range string.
WS_DLL_PUBLIC const char * | try_rval_to_str_idx (const uint32_t val, const range_string *rs, int *idx)
| Converts a 32-bit unsigned integer value to its corresponding string representation based on a range_string array.
WS_DLL_PUBLIC const char * | try_rval64_to_str (const uint64_t val, const range_string *rs)
| Convert a 64-bit unsigned integer value to a string based on a range of strings.
WS_DLL_PUBLIC const char * | try_rval64_to_str_idx (const uint64_t val, const range_string *rs, int *idx)
| Converts a 64-bit unsigned integer value to its corresponding string representation based on a range of values.
WS_DLL_PUBLIC const char * | try_time_val_to_str (const nstime_t *val, const time_value_string *vs)
| Tries to match a time value against an array of time_value_string entries.
WS_DLL_PUBLIC const char * | bytesval_to_str_wmem (wmem_allocator_t *scope, const uint8_t *val, const size_t val_len, const bytes_string *bs, const char *fmt)
| Converts a byte value to a string using a format string.
WS_DLL_PUBLIC const char * | try_bytesval_to_str (const uint8_t *val, const size_t val_len, const bytes_string *bs)
| Convert a byte prefix to a string using a value_string array.
WS_DLL_PUBLIC const char * | bytesprefix_to_str (wmem_allocator_t *scope, const uint8_t *haystack, const size_t haystack_len, const bytes_string *bs, const char *fmt)
| Convert a byte prefix to a string using a value_string array.
WS_DLL_PUBLIC const char * | try_bytesprefix_to_str (const uint8_t *haystack, const size_t haystack_len, const bytes_string *bs)
| Tries to find a string representation for a byte prefix in a bytes_string array.
WS_DLL_PUBLIC void | register_external_value_string (const char *name, const value_string *vs)
| Registers an external value string with a given name.
WS_DLL_PUBLIC value_string * | get_external_value_string (const char *name)
| Retrieves an external value string by name.
WS_DLL_PUBLIC void | register_external_value_string_ext (const char *name, const value_string_ext *vse)
| Registers an external value string extension.
WS_DLL_PUBLIC value_string_ext * | get_external_value_string_ext (const char *name)
| Retrieves an external value string extension by name.
WS_DLL_PUBLIC void | value_string_externals_init (void)
| Initializes external value string and extension registries.
WS_DLL_PUBLIC void | value_string_externals_cleanup (void)
| Cleans up external value string resources.
WS_DLL_PUBLIC bool | value_string_ext_validate (const value_string_ext *vse)
| Validates a value_string_ext structure.
WS_DLL_PUBLIC const char * | value_string_ext_match_type_str (const value_string_ext *vse)
| Returns a string representation of the match type for a value_string_ext.
WS_DLL_PUBLIC bool | val64_string_ext_validate (const val64_string_ext *vse)
| Validates a value_string_ext structure.
WS_DLL_PUBLIC const char * | val64_string_ext_match_type_str (const val64_string_ext *vse)
| Returns a string representation of the match type for a 64-bit value string extension.

## Detailed Description

Definitions for value_string structures and 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

## Macro Definition Documentation

## ◆ _VS_ARRAY_ENTRY

#define _VS_ARRAY_ENTRY | ( |  | name,
|  |  | value,
|  |  | string )

Value:
{ value, string },

## ◆ _VS_ARRAY_ENTRY2

#define _VS_ARRAY_ENTRY2 | ( |  | name,
|  |  | value )

Value:
{ value, #name },

## ◆ _VS_ARRAY_SC_TYPE_NAME

#define _VS_ARRAY_SC_TYPE_NAME | ( |  | array_name,
|  |  | sc )

Value:
sc const value_string array_name[]
value_string
struct _value_string value_string
Mapping between a 32-bit integer value and its string representation.

## ◆ _VS_ARRAY_SC_XXX

#define _VS_ARRAY_SC_XXX | ( |  | array_name,
|  |  | macro,
|  |  | sc )

Value:
_VS_ARRAY_SC_TYPE_NAME(array_name, sc) = { \
array_name##_VALUE_STRING_LIST(macro) \
{ 0, NULL } \
}

## ◆ _VS_ARRAY_TYPE_NAME

#define _VS_ARRAY_TYPE_NAME | ( |  | array_name | ) |

Value:
const value_string array_name[]

## ◆ _VS_ARRAY_XXX

#define _VS_ARRAY_XXX | ( |  | array_name,
|  |  | macro )

Value:
_VS_ARRAY_TYPE_NAME(array_name) = { \
array_name##_VALUE_STRING_LIST(macro) \
{ 0, NULL } \
}

## ◆ _VS_ENUM_ENTRY

#define _VS_ENUM_ENTRY | ( |  | name,
|  |  | value,
|  |  | string )

Value:
name = value,

## ◆ _VS_ENUM_ENTRY2

#define _VS_ENUM_ENTRY2 | ( |  | name,
|  |  | value )

Value:
name = value,

## ◆ _VS_ENUM_XXX

#define _VS_ENUM_XXX | ( |  | array_name,
|  |  | macro )

Value:
enum { \
array_name##_VALUE_STRING_LIST(macro) \
_##array_name##_ENUM_DUMMY = 0 \
}

## ◆ VAL64_STRING_EXT_INIT

#define VAL64_STRING_EXT_INIT | ( |  | x | ) |

Value:
{ _try_val64_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x, NULL }

## ◆ VAL64_STRING_EXT_VS_NAME

#define VAL64_STRING_EXT_VS_NAME | ( |  | x | ) |

Value:
(x)->_vs_name

## ◆ VAL64_STRING_EXT_VS_NUM_ENTRIES

#define VAL64_STRING_EXT_VS_NUM_ENTRIES | ( |  | x | ) |

Value:
(x)->_vs_num_entries

## ◆ VAL64_STRING_EXT_VS_P

#define VAL64_STRING_EXT_VS_P | ( |  | x | ) |

Value:
(x)->_vs_p

## ◆ VALUE_STRING_ARRAY

#define VALUE_STRING_ARRAY | ( |  | array_name | ) |

Value:
_VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY, static)

## ◆ VALUE_STRING_ARRAY2

#define VALUE_STRING_ARRAY2 | ( |  | array_name | ) |

Value:
_VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY2, static)

## ◆ VALUE_STRING_ARRAY2_GLOBAL_DCL

#define VALUE_STRING_ARRAY2_GLOBAL_DCL | ( |  | array_name | ) |

Value:
_VS_ARRAY_SC_TYPE_NAME(array_name, extern)

## ◆ VALUE_STRING_ARRAY2_GLOBAL_DEF

#define VALUE_STRING_ARRAY2_GLOBAL_DEF | ( |  | array_name | ) |

Value:
_VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY2)

## ◆ VALUE_STRING_ARRAY_GLOBAL_DCL

#define VALUE_STRING_ARRAY_GLOBAL_DCL | ( |  | array_name | ) |

Value:
_VS_ARRAY_SC_TYPE_NAME(array_name, extern)

## ◆ VALUE_STRING_ARRAY_GLOBAL_DEF

#define VALUE_STRING_ARRAY_GLOBAL_DEF | ( |  | array_name | ) |

Value:
_VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY)

## ◆ VALUE_STRING_ENUM

#define VALUE_STRING_ENUM | ( |  | array_name | ) |

Value:
_VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY)

## ◆ VALUE_STRING_ENUM2

#define VALUE_STRING_ENUM2 | ( |  | array_name | ) |

Value:
_VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY2)

## ◆ VALUE_STRING_EXT_INIT

#define VALUE_STRING_EXT_INIT | ( |  | x | ) |

Value:
{ _try_val_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x, NULL }

## ◆ VALUE_STRING_EXT_VS_NAME

#define VALUE_STRING_EXT_VS_NAME | ( |  | x | ) |

Value:
(x)->_vs_name

## ◆ VALUE_STRING_EXT_VS_NUM_ENTRIES

#define VALUE_STRING_EXT_VS_NUM_ENTRIES | ( |  | x | ) |

Value:
(x)->_vs_num_entries

## ◆ VALUE_STRING_EXT_VS_P

#define VALUE_STRING_EXT_VS_P | ( |  | x | ) |

Value:
(x)->_vs_p

## Typedef Documentation

## ◆ val64_string

typedef struct _val64_string val64_string

Mapping between a 64-bit integer value and its string representation.

Used to associate a uint64_t value with a human-readable string. This is useful for converting large numeric constants to descriptive labels in protocol dissectors, debug output, or UI elements.

## ◆ value_string

typedef struct _value_string value_string

Mapping between a 32-bit integer value and its string representation.

Used to associate a uint32_t value with a human-readable string. This is commonly employed in protocol dissectors and diagnostic tools to convert numeric constants into descriptive labels.

## Function Documentation

## ◆ _try_val64_to_str_ext_init()

WS_DLL_PUBLIC const val64_string * _try_val64_to_str_ext_init | ( | const uint64_t | val,
|  | val64_string_ext * | vse )

Attempt to initialize and retrieve a 64-bit value-string entry from an extended mapping.

Searches the extended val64_string_ext structure vse for an entry matching val. If found, returns a pointer to the corresponding val64_string entry. If not found, returns NULL. This function may also perform internal initialization of the val64_string_ext structure if required.

This is useful for advanced lookup scenarios where metadata and scoped memory management are involved, and where direct access to the matched entry is needed for further processing.

Parameters

  val | 64-bit value to look up.
  vse | Pointer to an extended 64-bit value-string mapping structure.

Returns
  Pointer to the matching val64_string entry, or NULL if not found.

## ◆ _try_val_to_str_ext_init()

WS_DLL_PUBLIC const value_string * _try_val_to_str_ext_init | ( | const uint32_t | val,
|  | value_string_ext * | vse )

Attempt to initialize and retrieve a value-string entry from an extended mapping.

Searches the extended value-string structure vse for an entry matching val. If found, returns a pointer to the corresponding value_string entry. If not found, returns NULL. This function may also perform internal initialization of the value_string_ext structure if needed.

Parameters

  val | Numeric value to look up.
  vse | Pointer to an extended value-string mapping structure.

Returns
  Pointer to the matching value_string entry, or NULL if not found.

## ◆ bytesprefix_to_str()

WS_DLL_PUBLIC const char * bytesprefix_to_str | ( | wmem_allocator_t * | scope,
|  | const uint8_t * | haystack,
|  | const size_t | haystack_len,
|  | const bytes_string * | bs,
|  | const char * | fmt )

Convert a byte prefix to a string using a value_string array.

This function attempts to find a prefix match of any prefix from the bytes_string array against the haystack and returns the corresponding string if found. If no match is found, it uses a format string to create a new string.

Parameters

  scope | Memory allocator scope for the returned string.
  haystack | The byte array to search within.
  haystack_len | Length of the haystack array.
  bs | Pointer to the bytes_string array containing prefix-value pairs.
  fmt | Format string to use if no prefix match is found.

Returns
  A newly allocated string representing the matched prefix or formatted value, or NULL on error.

## ◆ bytesval_to_str_wmem()

WS_DLL_PUBLIC const char * bytesval_to_str_wmem | ( | wmem_allocator_t * | scope,
|  | const uint8_t * | val,
|  | const size_t | val_len,
|  | const bytes_string * | bs,
|  | const char * | fmt )

Converts a byte value to a string using a format string.

This function attempts to convert a byte value to a string based on a provided format string. If the conversion is successful, it returns the converted string; otherwise, it returns an error message.

Parameters

  scope | The memory allocator scope for the returned string.
  val | The byte value to be converted.
  val_len | The length of the byte value.
  bs | A pointer to a bytes_string structure containing possible values and their corresponding strings.
  fmt | The format string used for conversion. If NULL, an error message is returned.

Returns
  A pointer to the converted string or an error message if the conversion fails.

## ◆ get_external_value_string()

WS_DLL_PUBLIC value_string * get_external_value_string | ( | const char * | name | ) |

Retrieves an external value string by name.

Parameters

  name | The name of the value string to retrieve.

Returns
  A pointer to the value_string if found, otherwise NULL.

## ◆ get_external_value_string_ext()

WS_DLL_PUBLIC value_string_ext * get_external_value_string_ext | ( | const char * | name | ) |

Retrieves an external value string extension by name.

Parameters

  name | The name of the external value string extension to retrieve.

Returns
  A pointer to the external value string extension, or NULL if not found.

## ◆ register_external_value_string()

WS_DLL_PUBLIC void register_external_value_string | ( | const char * | name,
|  | const value_string * | vs )

Registers an external value string with a given name.

Parameters

  name | The name under which the value string is registered.
  vs | The value string to be registered.

## ◆ register_external_value_string_ext()

WS_DLL_PUBLIC void register_external_value_string_ext | ( | const char * | name,
|  | const value_string_ext * | vse )

Registers an external value string extension.

Parameters

  name | The name of the value string extension to register.
  vse | The value string extension to register.

## ◆ rval_to_str_const()

WS_DLL_PUBLIC const char * rval_to_str_const | ( | const uint32_t | val,
|  | const range_string * | rs,
|  | const char * | unknown_str )

Convert a 32-bit unsigned integer to its corresponding string representation based on a range string.

Parameters

  val | The 32-bit unsigned integer value to convert.
  rs | Pointer to the range_string structure containing the mapping of values to strings.

Returns
  const char* The corresponding string representation, or NULL if not found.

## ◆ rval_to_str_wmem()

WS_DLL_PUBLIC const char * rval_to_str_wmem | ( | wmem_allocator_t * | scope,
|  | const uint32_t | val,
|  | const range_string * | rs,
|  | const char * | fmt )

Convert a 32-bit unsigned integer to its corresponding string representation based on a range string.

Parameters

  scope | Memory allocator for the returned string.
  val | The 32-bit unsigned integer value to convert.
  rs | Pointer to an array of range_string structures defining the mapping from values to strings.
  fmt | Format string to use if no matching range is found. Must not be NULL.

Returns
  const char* The corresponding string representation, or a default string if no match is found and fmt is provided.

## ◆ str_to_str_wmem()

WS_DLL_PUBLIC const char * str_to_str_wmem | ( | wmem_allocator_t * | scope,
|  | const char * | val,
|  | const string_string * | vs,
|  | const char * | fmt )

Converts a string value to a formatted string using a value string table.

Parameters

  scope | The memory allocator scope for the returned string.
  val | The input string value to convert.
  vs | The value string table containing mappings from values to strings.
  fmt | The format string to use if no exact match is found in the value string table.

Returns
  The converted string, or a default error message if both the value string table and format are NULL.

## ◆ str_to_val()

WS_DLL_PUBLIC uint32_t str_to_val | ( | const char * | val,
|  | const value_string * | vs,
|  | const uint32_t | err_val )

Convert a string to its corresponding numeric value using a value-string mapping.

Searches the provided value_string array vs for an entry whose string matches val. If found, returns the associated numeric value. If not found, returns err_val.

This function is useful for parsing user input or protocol fields that use string representations of enumerated values.

Parameters

  val | String to convert.
  vs | Array of value-string mappings.
  err_val | Value to return if val is not found in vs.

Returns
  The numeric value corresponding to val, or err_val if not found.

## ◆ str_to_val_idx()

WS_DLL_PUBLIC int str_to_val_idx | ( | const char * | val,
|  | const value_string * | vs )

Retrieve the index of a string in a value-string mapping array.

Searches the provided value_string array vs for an entry whose string matches val. If found, returns the index of the matching entry. If not found, returns -1.

This function is useful when the caller needs the position of a matched string for further processing or lookup.

Parameters

  val | String to search for.
  vs | Array of value-string mappings.

Returns
  Index of the matching entry, or -1 if not found.

## ◆ try_bytesprefix_to_str()

WS_DLL_PUBLIC const char * try_bytesprefix_to_str | ( | const uint8_t * | haystack,
|  | const size_t | haystack_len,
|  | const bytes_string * | bs )

Tries to find a string representation for a byte prefix in a bytes_string array.

Parameters

  haystack | The buffer containing the byte sequence to search.
  haystack_len | The length of the byte sequence.
  bs | The bytes_string array to search within.

Returns
  const char* A pointer to the corresponding string if found, NULL otherwise.

## ◆ try_bytesval_to_str()

WS_DLL_PUBLIC const char * try_bytesval_to_str | ( | const uint8_t * | val,
|  | const size_t | val_len,
|  | const bytes_string * | bs )

Convert a byte prefix to a string using a value_string array.

This function attempts to find a prefix match of any prefix from the bytes_string array against the haystack and returns the corresponding string if found. If no match is found, it uses a format string to create a new string.

Parameters

  val | Pointer to the byte array to be matched.
  val_len | Length of the byte array.
  bs | Pointer to the bytes_string array containing prefix-value pairs.

Returns
  const char* The corresponding string if a match is found, otherwise NULL.

## ◆ try_rval64_to_str()

WS_DLL_PUBLIC const char * try_rval64_to_str | ( | const uint64_t | val,
|  | const range_string * | rs )

Convert a 64-bit unsigned integer value to a string based on a range of strings.

Parameters

  val | The 64-bit unsigned integer value to convert.
  rs | Pointer to the range_string structure containing the mapping from values to strings.

Returns
  const char* A pointer to the corresponding string, or NULL if no match is found.

## ◆ try_rval64_to_str_idx()

WS_DLL_PUBLIC const char * try_rval64_to_str_idx | ( | const uint64_t | val,
|  | const range_string * | rs,
|  | int * | idx )

Converts a 64-bit unsigned integer value to its corresponding string representation based on a range of values.

This function searches through an array of range_string structures to find a match for the given value. If a match is found, it sets the index parameter to the position of the matching range and returns the corresponding string pointer. If no match is found, it sets the index to -1 and returns NULL.

Parameters

  val | The 64-bit unsigned integer value to convert.
  rs | Pointer to an array of range_string structures containing the ranges and their corresponding strings.
  idx | Pointer to an integer where the index of the matching range will be stored.

Returns
  A pointer to the string representation of the value, or NULL if no match is found.

## ◆ try_rval_to_str()

WS_DLL_PUBLIC const char * try_rval_to_str | ( | const uint32_t | val,
|  | const range_string * | rs )

Convert a 32-bit unsigned integer to its corresponding string representation based on a range string.

Parameters

  val | The 32-bit unsigned integer value to convert.
  rs | Pointer to the range_string structure containing the mapping of values to strings.

Returns
  const char* The corresponding string representation, or NULL if not found.

## ◆ try_rval_to_str_idx()

WS_DLL_PUBLIC const char * try_rval_to_str_idx | ( | const uint32_t | val,
|  | const range_string * | rs,
|  | int * | idx )

Converts a 32-bit unsigned integer value to its corresponding string representation based on a range_string array.

Parameters

  val | The 32-bit unsigned integer value to convert.
  rs | Pointer to the range_string array containing the value ranges and their corresponding strings.
  idx | Pointer to an integer where the index of the matched range will be stored. If no match is found, -1 is stored.

Returns
  const char* The string representation of the value if a match is found; otherwise, NULL.

## ◆ try_str_to_str()

WS_DLL_PUBLIC const char * try_str_to_str | ( | const char * | val,
|  | const string_string * | vs )

Converts a string to another string based on a value-string mapping.

Parameters

  val | The input string to convert.
  vs | The value-string mapping table.

Returns
  The converted string, or NULL if no match is found.

## ◆ try_str_to_str_idx()

WS_DLL_PUBLIC const char * try_str_to_str_idx | ( | const char * | val,
|  | const string_string * | vs,
|  | int * | idx )

Converts a string to an index in a string-string mapping table.

Parameters

  val | The string to look up.
  vs | The string-string mapping table.
  idx | Pointer to store the resulting index.

Returns
  The corresponding string from the table, or NULL if not found.

## ◆ try_time_val_to_str()

WS_DLL_PUBLIC const char * try_time_val_to_str | ( | const nstime_t * | val,
|  | const time_value_string * | vs )

Tries to match a time value against an array of time_value_string entries.

Parameters

  val | Pointer to the nstime_t structure representing the time value to be matched.
  vs | Pointer to the time_value_string array containing possible matches.

Returns
  const char* The associated string pointer if a match is found, otherwise NULL.

## ◆ try_val64_to_str()

WS_DLL_PUBLIC const char * try_val64_to_str | ( | const uint64_t | val,
|  | const val64_string * | vs )

Attempt to convert a 64-bit value to a string using a value-string mapping.

Searches the provided val64_string array vs for an entry matching val. If found, returns the corresponding string. If not found, returns NULL.

This function is useful when the caller wants to detect unknown values without falling back to a default string or allocating memory.

Parameters

  val | 64-bit value to convert.
  vs | Array of 64-bit value-string mappings.

Returns
  A constant string if found, or NULL if not found.

## ◆ try_val64_to_str_ext()

WS_DLL_PUBLIC const char * try_val64_to_str_ext | ( | const uint64_t | val,
|  | val64_string_ext * | vse )

Convert a 64-bit value to its corresponding string index and pointer.

Parameters

  val | The 64-bit value to convert.
  vse | Pointer to the value_string_ext structure containing the mapping.

Returns
  The corresponding string pointer, or NULL if not found.

## ◆ try_val64_to_str_idx()

WS_DLL_PUBLIC const char * try_val64_to_str_idx | ( | const uint64_t | val,
|  | const val64_string * | vs,
|  | int * | idx )

Attempt to convert a 64-bit value to a string and retrieve its index.

Searches the provided val64_string array vs for an entry matching val. If found, returns the corresponding string and sets *idx to the index of the matching entry. If not found, returns NULL and leaves *idx unchanged.

This function is useful when both the string representation and its position in the mapping array are needed for further processing or diagnostics.

Parameters

  val | 64-bit value to convert.
  vs | Array of 64-bit value-string mappings.
  idx | Pointer to an integer to receive the index of the match.

Returns
  A constant string if found, or NULL if not found.

## ◆ try_val64_to_str_idx_ext()

WS_DLL_PUBLIC const char * try_val64_to_str_idx_ext | ( | const uint64_t | val,
|  | val64_string_ext * | vse,
|  | int * | idx )

Convert a 64-bit value to its corresponding string index and pointer.

Parameters

  val | The 64-bit value to convert.
  vse | Pointer to the value_string_ext structure containing the mapping.
  idx | Pointer to store the resulting index.

Returns
  The corresponding string pointer, or NULL if not found.

## ◆ try_val_to_str()

WS_DLL_PUBLIC const char * try_val_to_str | ( | const uint32_t | val,
|  | const value_string * | vs )

Attempt to convert a numeric value to a string using a value-string mapping.

Searches the provided value_string array vs for an entry matching val. If found, returns the corresponding string. If not found, returns NULL.

This function is useful when the caller wants to distinguish between known and unknown values without falling back to a default string.

Parameters

  val | Numeric value to convert.
  vs | Array of value-string mappings.

Returns
  A constant string if found, or NULL if not found.

## ◆ try_val_to_str_ext()

WS_DLL_PUBLIC const char * try_val_to_str_ext | ( | const uint32_t | val,
|  | value_string_ext * | vse )

Attempt to convert a numeric value to a string using an extended value-string mapping.

Searches the extended value-string structure vse for an entry matching val. If found, returns the corresponding string. If not found, returns NULL.

This function is useful when the caller wants to detect unknown values without allocating memory or falling back to a default string.

Parameters

  val | Numeric value to convert.
  vse | Pointer to the extended value-string mapping structure.

Returns
  A constant string if found, or NULL if not found.

## ◆ try_val_to_str_idx()

WS_DLL_PUBLIC const char * try_val_to_str_idx | ( | const uint32_t | val,
|  | const value_string * | vs,
|  | int * | idx )

Attempt to convert a numeric value to a string and retrieve its index.

Searches the provided value_string array vs for an entry matching val. If found, returns the corresponding string and sets *idx to the index of the matching entry. If not found, returns NULL and leaves *idx unchanged.

This function is useful when both the string representation and its position in the mapping array are needed.

Parameters

  val | Numeric value to convert.
  vs | Array of value-string mappings.
  idx | Pointer to an integer to receive the index of the match.

Returns
  A constant string if found, or NULL if not found.

## ◆ try_val_to_str_idx_ext()

WS_DLL_PUBLIC const char * try_val_to_str_idx_ext | ( | const uint32_t | val,
|  | value_string_ext * | vse,
|  | int * | idx )

Attempt to convert a numeric value to a string and retrieve its index from an extended mapping.

Searches the extended value-string structure vse for an entry matching val. If found, returns the corresponding string and sets *idx to the index of the matching entry within the original value_string array. If not found, returns NULL and leaves *idx unchanged.

This function is useful when both the string representation and its position in the mapping array are needed for diagnostics or further processing.

Parameters

  val | Numeric value to convert.
  vse | Pointer to the extended value-string mapping structure.
  idx | Pointer to an integer to receive the index of the match.

Returns
  A constant string if found, or NULL if not found.

## ◆ val64_string_ext_free()

WS_DLL_PUBLIC void val64_string_ext_free | ( | val64_string_ext * | vse | ) |

Frees a val64_string_ext structure.

Parameters

  vse | Pointer to the val64_string_ext structure to be freed.

## ◆ val64_string_ext_match_type_str()

WS_DLL_PUBLIC const char * val64_string_ext_match_type_str | ( | const val64_string_ext * | vse | ) |

Returns a string representation of the match type for a 64-bit value string extension.

Parameters

  vse | Pointer to the val64_string_ext structure containing the match type information.

Returns
  const char* A string describing the match type, or "[Invalid]" if the type is not recognized.

## ◆ val64_string_ext_new()

WS_DLL_PUBLIC val64_string_ext * val64_string_ext_new | ( | wmem_allocator_t * | scope,
|  | const val64_string * | vs,
|  | unsigned | vs_tot_num_entries,
|  | const char * | vs_name )

Create a new extended value string structure.

Parameters

  scope | Memory allocator scope for the new structure.
  vs | Pointer to the base value string array.
  vs_tot_num_entries | Total number of entries in the value string array.
  vs_name | Name of the value string.

Returns
  A pointer to the newly created val64_string_ext structure, or NULL if an error occurred.

## ◆ val64_string_ext_validate()

WS_DLL_PUBLIC bool val64_string_ext_validate | ( | const val64_string_ext * | vse | ) |

Validates a value_string_ext structure.

This function checks if the provided value_string_ext pointer is valid and if its match function is one of the allowed types.

Parameters

  vse | Pointer to the value_string_ext structure to validate.

Returns
  true if the validation passes, false otherwise.

## ◆ val64_to_str_const()

WS_DLL_PUBLIC const char * val64_to_str_const | ( | const uint64_t | val,
|  | const val64_string * | vs,
|  | const char * | unknown_str )

Convert a 64-bit value to a constant string using a value-string mapping.

Searches the provided val64_string array vs for an entry matching val. If found, returns the corresponding constant string. If not found, returns the specified unknown_str.

This function does not allocate memory and is suitable for use in contexts where a constant string is sufficient and memory management must be avoided.

Parameters

  val | 64-bit value to convert.
  vs | Array of 64-bit value-string mappings.
  unknown_str | Fallback string if val is not found in vs.

Returns
  A constant string representing the value or unknown_str.

## ◆ val64_to_str_ext_const()

WS_DLL_PUBLIC const char * val64_to_str_ext_const | ( | const uint64_t | val,
|  | val64_string_ext * | vs,
|  | const char * | unknown_str )

Convert a 64-bit unsigned integer to a string using an extended value string structure.

Parameters

  val | The 64-bit unsigned integer to convert.
  vs | The extended value string structure containing the mapping.
  unknown_str | The string to return if the value is not found in the mapping.

Returns
  const char* The converted string or the unknown string if not found.

## ◆ val64_to_str_ext_wmem()

WS_DLL_PUBLIC char * val64_to_str_ext_wmem | ( | wmem_allocator_t * | scope,
|  | const uint64_t | val,
|  | val64_string_ext * | vse,
|  | const char * | fmt )

Convert a 64-bit unsigned integer to a string using an extended value string structure.

Parameters

  scope | Memory allocator scope for the returned string.
  val | The 64-bit unsigned integer to convert.
  vse | Pointer to the extended value string structure containing the mapping.
  fmt | Format string used if val is not found in vse.

Returns
  A newly allocated string representing the value, or a formatted string if not found.

## ◆ val64_to_str_wmem()

WS_DLL_PUBLIC const char * val64_to_str_wmem | ( | wmem_allocator_t * | scope,
|  | const uint64_t | val,
|  | const val64_string * | vs,
|  | const char * | fmt )

Convert a 64-bit value to a string using a value-string mapping.

Searches the provided val64_string array vs for an entry matching val. If found, returns the corresponding string. If not found, formats the value using the provided fmt string and returns the result. The returned string is allocated using the specified wmem_allocator_t scope.

Parameters

  scope | Memory allocator scope for the returned string.
  val | 64-bit value to convert.
  vs | Array of 64-bit value-string mappings.
  fmt | Format string used if val is not found in vs.

Returns
  A newly allocated string representing the value.

## ◆ val_to_str()

WS_DLL_PUBLIC char * val_to_str | ( | wmem_allocator_t * | scope,
|  | const uint32_t | val,
|  | const value_string * | vs,
|  | const char * | fmt )

Convert a numeric value to a string using a value-string mapping.

Searches the provided value_string array vs for a matching entry with value val. If found, returns the corresponding string. If not found, formats the value using the provided fmt string and returns the result. Memory is allocated using the specified wmem_allocator_t scope.

Parameters

  scope | Memory allocator scope for the returned string.
  val | Numeric value to convert.
  vs | Array of value-string mappings.
  fmt | Format string used if val is not found in vs.

Returns
  A newly allocated string representing the value.

## ◆ val_to_str_const()

WS_DLL_PUBLIC const char * val_to_str_const | ( | const uint32_t | val,
|  | const value_string * | vs,
|  | const char * | unknown_str )

Convert a numeric value to a constant string using a value-string mapping.

Searches the provided value_string array vs for an entry matching val. If found, returns the corresponding constant string. If not found, returns the provided unknown_str.

This function does not allocate memory and is suitable for use in contexts where a constant string is sufficient and memory management must be avoided.

Parameters

  val | Numeric value to convert.
  vs | Array of value-string mappings.
  unknown_str | Fallback string if val is not found in vs.

Returns
  A constant string representing the value or unknown_str.

## ◆ val_to_str_ext()

WS_DLL_PUBLIC char * val_to_str_ext | ( | wmem_allocator_t * | scope,
|  | const uint32_t | val,
|  | value_string_ext * | vse,
|  | const char * | fmt )

Convert a numeric value to a string using an extended value-string mapping.

Searches the extended value-string structure vse for an entry matching val. If found, returns the corresponding string. If not found, formats the value using the provided fmt string. The result is allocated using the specified wmem_allocator_t scope.

This function is useful for enhanced lookup scenarios where additional metadata or scoped memory management is required.

Parameters

  scope | Memory allocator scope for the returned string.
  val | Numeric value to convert.
  vse | Pointer to the extended value-string mapping structure.
  fmt | Format string used if val is not found in vse.

Returns
  A newly allocated string representing the value.

## ◆ val_to_str_ext_const()

WS_DLL_PUBLIC const char * val_to_str_ext_const | ( | const uint32_t | val,
|  | value_string_ext * | vs,
|  | const char * | unknown_str )

Convert a numeric value to a constant string using an extended value-string mapping.

Searches the extended value-string structure vs for an entry matching val. If found, returns the corresponding constant string. If not found, returns the specified unknown_str.

This function does not allocate memory and is suitable for contexts where a constant string is sufficient and memory management must be avoided.

Parameters

  val | Numeric value to convert.
  vs | Pointer to the extended value-string mapping structure.
  unknown_str | Fallback string if val is not found in vs.

Returns
  A constant string representing the value or unknown_str.

## ◆ value_str_value_compare()

WS_DLL_PUBLIC int value_str_value_compare | ( | const void * | a,
|  | const void * | b )

Compare two value_string entries by their numeric value.

Used primarily for sorting or searching operations on arrays of value_string structures. This function compares the value fields of the two entries pointed to by a and b.

Parameters

  a | Pointer to the first value_string entry.
  b | Pointer to the second value_string entry.

Returns
  Negative if a < b, zero if a == b, positive if a > b.

## ◆ value_string_ext_free()

WS_DLL_PUBLIC void value_string_ext_free | ( | value_string_ext * | vse | ) |

Free an extended value-string mapping structure.

Releases any memory associated with the given value_string_ext structure, including its internal scope if applicable. This function should be called when the extended mapping is no longer needed to avoid memory leaks.

Parameters

  vse | Pointer to the value_string_ext structure to be freed.

## ◆ value_string_ext_match_type_str()

WS_DLL_PUBLIC const char * value_string_ext_match_type_str | ( | const value_string_ext * | vse | ) |

Returns a string representation of the match type for a value_string_ext.

Parameters

  vse | Pointer to the value_string_ext structure.

Returns
  const char* A string describing the match type, or "[Invalid]" if unknown.

## ◆ value_string_ext_new()

WS_DLL_PUBLIC value_string_ext * value_string_ext_new | ( | wmem_allocator_t * | scope,
|  | const value_string * | vs,
|  | unsigned | vs_tot_num_entries,
|  | const char * | vs_name )

Create a new extended value-string mapping structure.

Allocates and initializes a value_string_ext object using the provided value_string array.

Parameters

  scope | Memory allocator scope for the new structure.
  vs | Pointer to the value-string array.
  vs_tot_num_entries | Total number of entries in the array (excluding the final {0, NULL}).
  vs_name | Descriptive name for the mapping (used in diagnostics).

Returns
  Pointer to the newly created value_string_ext structure.

## ◆ value_string_ext_validate()

WS_DLL_PUBLIC bool value_string_ext_validate | ( | const value_string_ext * | vse | ) |

Validates a value_string_ext structure.

This function checks if the provided value_string_ext pointer is valid and if its match function pointer is one of the allowed types.

Parameters

  vse | Pointer to the value_string_ext structure to validate.

Returns
  true if the validation passes, false otherwise.

## ◆ value_string_externals_cleanup()

WS_DLL_PUBLIC void value_string_externals_cleanup | ( | void |  | ) |

Cleans up external value string resources.

This function destroys the hash tables used to store registered value strings and their extensions.

## ◆ value_string_externals_init()

WS_DLL_PUBLIC void value_string_externals_init | ( | void |  | ) |

Initializes external value string and extension registries.

This function initializes two hash tables to store registered external value strings and their extensions.