| Wireshark 4.7.3 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Macros | Functions
strutil.h File Reference
`#include "ws_symbol_export.h"`
`#include <epan/wmem_scopes.h>`
`#include <wsutil/str_util.h>`

Go to the source code of this file.

## Macros
#define | FORMAT_LABEL_REPLACE_SPACE (0x1 << 0)

## Functions
WS_DLL_PUBLIC const unsigned char * | find_line_end (const unsigned char *data, const unsigned char *dataend, const unsigned char **eol)
WS_DLL_PUBLIC int | get_token_len (const unsigned char *linep, const unsigned char *lineend, const unsigned char **next_token)
WS_DLL_PUBLIC bool | hex_str_to_bytes (const char *hex_str, GByteArray *bytes, bool force_separators)
WS_DLL_PUBLIC bool | hex_str_to_bytes_encoding (const char *hex_str, GByteArray *bytes, const char **endptr, const unsigned encoding, const bool fail_if_partial)
| Turn a string of hex digits with optional separators (defined by encoding).
WS_DLL_PUBLIC bool | uri_to_bytes (const char *uri_str, GByteArray *bytes, size_t len)
WS_DLL_PUBLIC bool | uri_str_to_bytes (const char *uri_str, GByteArray *bytes)
WS_DLL_PUBLIC bool | rel_oid_str_to_bytes (const char *oid_str, GByteArray *bytes, bool is_absolute)
WS_DLL_PUBLIC bool | oid_str_to_bytes (const char *oid_str, GByteArray *bytes)
WS_DLL_PUBLIC GByteArray * | byte_array_dup (const GByteArray *ba)
WS_DLL_PUBLIC bool | byte_array_equal (GByteArray *ba1, GByteArray *ba2)
WS_DLL_PUBLIC char * | xml_escape (const char *unescaped)
WS_DLL_PUBLIC uint8_t * | convert_string_to_hex (const char *string, size_t *nbytes)
WS_DLL_PUBLIC char * | convert_string_case (const char *string, bool case_insensitive)
| Prep a string for case-sensitive vs case-insensitive searching.
WS_DLL_PUBLIC void | IA5_7BIT_decode (unsigned char *dest, const unsigned char *src, int len)
| Decodes an IA5-7BIT encoded string into a UTF-8 string.
WS_DLL_PUBLIC size_t | ws_label_strcpy (char *label_str, size_t bufsize, size_t pos, const uint8_t *str, int flags)
WS_DLL_PUBLIC size_t | ws_label_strcat (char *label_str, size_t bufsize, const uint8_t *str, int flags)
WS_DLL_LOCAL unsigned char | module_check_valid_name (const char *name, bool lower_only)
| Check if name is valid.

## Detailed Description

String handling and conversion utilities.

## Function Documentation

## ◆ byte_array_dup()

WS_DLL_PUBLIC GByteArray * byte_array_dup | ( | const GByteArray * | ba | ) |

Create a copy of a GByteArray

Parameters

  ba | The byte array to be copied.

Returns
  If ba exists, a freshly allocated copy. NULL otherwise.

Todo
  - Should this be in strutil.c?

Create a copy of a GByteArray

Parameters

  ba | The byte array to be copied.

Returns
  If ba exists, a freshly allocated copy. NULL otherwise.

## ◆ byte_array_equal()

WS_DLL_PUBLIC bool byte_array_equal | ( | GByteArray * | ba1,
|  | GByteArray * | ba2 )

Compare the contents of two GByteArrays

Parameters

  ba1 | A byte array
  ba2 | A byte array

Returns
  If both arrays are non-NULL and their lengths are equal and their contents are equal, returns true. Otherwise, returns false.

Todo
  - Should this be in strutil.c?

Compare the contents of two GByteArrays

Parameters

  ba1 | A byte array
  ba2 | A byte array

Returns
  If both arrays are non-NULL and their lengths are equal and their contents are equal, returns true. Otherwise, returns false.

XXX - Should this be in strutil.c?

## ◆ convert_string_case()

WS_DLL_PUBLIC char * convert_string_case | ( | const char * | string,
|  | bool | case_insensitive )

Prep a string for case-sensitive vs case-insensitive searching.

Parameters

  string | The search string
  case_insensitive | true if case-insensitive, false if not

Returns
  A direct copy of the string if it's a case-sensitive search and an uppercased version if not. In either case the string must be g_free()d by the caller.

## ◆ convert_string_to_hex()

WS_DLL_PUBLIC uint8_t * convert_string_to_hex | ( | const char * | string,
|  | size_t * | nbytes )

Scan a string to make sure it's valid hex.

Parameters

  string | The string to validate
  nbytes | The length of the return buffer

Returns
  A pointer to a buffer containing the converted raw bytes. This buffer must be g_free()d by the caller.

## ◆ find_line_end()

WS_DLL_PUBLIC const unsigned char * find_line_end | ( | const unsigned char * | data,
|  | const unsigned char * | dataend,
|  | const unsigned char ** | eol )

Given a pointer into a data buffer, and to the end of the buffer, find the end of the (putative) line at that position in the data buffer.

Parameters

  data | A pointer to the beginning of the data
  dataend | A pointer to the end of the data
  eol | A pointer that will receive the EOL location

Returns
  A pointer to the EOL character(s) in "*eol".

## ◆ get_token_len()

WS_DLL_PUBLIC int get_token_len | ( | const unsigned char * | linep,
|  | const unsigned char * | lineend,
|  | const unsigned char ** | next_token )

Get the length of the next token in a line, and the beginning of the next token after that (if any).

Parameters

  linep | A pointer to the beginning of the line
  lineend | A pointer to the end of the line
  next_token | Receives the location of the next token

Returns
  0 if there is no next token.

## ◆ hex_str_to_bytes()

WS_DLL_PUBLIC bool hex_str_to_bytes | ( | const char * | hex_str,
|  | GByteArray * | bytes,
|  | bool | force_separators )

Turn a string of hex digits with optional separators (defined by is_byte_sep() into a byte array.

Parameters

  hex_str | The string of hex digits.
  bytes | The GByteArray that will receive the bytes. This must be initialized by the caller.
  force_separators | If set to true, separators MUST exist between bytes.

Returns
  True if the string was converted successfully

## ◆ hex_str_to_bytes_encoding()

WS_DLL_PUBLIC bool hex_str_to_bytes_encoding | ( | const char * | hex_str,
|  | GByteArray * | bytes,
|  | const char ** | endptr,
|  | const unsigned | encoding,
|  | const bool | fail_if_partial )

Turn a string of hex digits with optional separators (defined by encoding).

Turn a string of hex digits with optional separators (defined by encoding) into a byte array. Unlike hex_str_to_bytes(), this will read as many hex-char pairs as possible and not error if it hits a non-hex-char; instead it just ends there. (i.e., like strtol()/atoi()/etc.) But it must see two hex chars at the beginning or it will return false.

Parameters

  hex_str | The string of hex digits.
  bytes | The GByteArray that will receive the bytes. This must be initialized by the caller.
  endptr | if not NULL, is set to the char after the last hex character consumed.
  encoding | set to one or more bitwise-or'ed ENC_SEP_* (see proto.h)
  fail_if_partial | If set to true, then the conversion fails if the whole hex_str is not consumed.

Returns
  false only if no bytes were generated; or if fail_if_partial is true and the entire hex_str was not consumed.

If no ENC_SEP_* is set, then no separators are allowed. If multiple ENC_SEP_* are bit-or'ed, any of them can be a separator, but once the separator is seen then only its same type is accepted for the rest of the string. (i.e., it won't convert a "01:23-4567" even if ENC_SEP_COLON|ENC_SEP_DASH|ENC_SEP_NONE is passed in)

This is done this way because it's likely a malformed scenario if they're mixed, and this routine is used by dissectors via tvb_get_string_XXX routines.

## ◆ IA5_7BIT_decode()

WS_DLL_PUBLIC void IA5_7BIT_decode | ( | unsigned char * | dest,
|  | const unsigned char * | src,
|  | int | len )

Decodes an IA5-7BIT encoded string into a UTF-8 string.

Parameters

  dest | Destination buffer for the decoded string.
  src | Source buffer containing the IA5-7BIT encoded data.
  len | Length of the source data to decode.

## ◆ module_check_valid_name()

WS_DLL_LOCAL unsigned char module_check_valid_name | ( | const char * | name,
|  | bool | lower_only )

Check if name is valid.

This covers names for display filter fields, dissector tables, preference modules, etc. Lower case is preferred.

Parameters

  name | The name to check.
  lower_only | If true, only lower case letters are allowed.

Returns
  0 if the name is valid, otherwise the first invalid character.

## ◆ oid_str_to_bytes()

WS_DLL_PUBLIC bool oid_str_to_bytes | ( | const char * | oid_str,
|  | GByteArray * | bytes )

Turn a OID string representation (dot notation) into a byte array.

Parameters

  oid_str | The OID string (dot notation).
  bytes | The GByteArray that will receive the bytes. This must be initialized by the caller.

Returns
  True if the string was converted successfully

## ◆ rel_oid_str_to_bytes()

WS_DLL_PUBLIC bool rel_oid_str_to_bytes | ( | const char * | oid_str,
|  | GByteArray * | bytes,
|  | bool | is_absolute )

Turn a OID string representation (dot notation) into a byte array.

Parameters

  oid_str | The OID string (dot notation).
  bytes | The GByteArray that will receive the bytes. This must be initialized by the caller.
  is_absolute | True if this is an absolute OID; false for relative OID.

Returns
  True if the string was converted successfully

## ◆ uri_str_to_bytes()

WS_DLL_PUBLIC bool uri_str_to_bytes | ( | const char * | uri_str,
|  | GByteArray * | bytes )

Turn an RFC 3986 percent-encoded string into a byte array.

Parameters

  uri_str | The string of hex digits.
  bytes | The GByteArray that will receive the bytes. This must be initialized by the caller.

Returns
  True if the string was converted successfully

## ◆ uri_to_bytes()

WS_DLL_PUBLIC bool uri_to_bytes | ( | const char * | uri_str,
|  | GByteArray * | bytes,
|  | size_t | len )

Turn an RFC 3986 percent-encoded array of characters, not necessarily null-terminated, into a byte array.

Parameters

  uri_str | The string of hex digits.
  bytes | The GByteArray that will receive the bytes. This must be initialized by the caller.

Returns
  True if the string was converted successfully

## ◆ ws_label_strcat()

WS_DLL_PUBLIC size_t ws_label_strcat | ( | char * | label_str,
|  | size_t | bufsize,
|  | const uint8_t * | str,
|  | int | flags )

Concatenate a string and escape any unprintable characters, truncating if necessary to fit into bufsize and guaranteeing null-termination. Copies whole UTF-8 characters, truncating to avoid splitting a multibyte character. Requires valid UTF-8 input; stops concatenating and returns the current position upon encountering an invalid character.

Parameters

  label_str | The destination string
  bufsize | The allocated size of the string
  str | The source string
  flags | FORMAT_LABEL_REPLACE_SPACE or 0

Returns
  The attempted length of label_str. If >= bufsize, truncation occurred.

## ◆ ws_label_strcpy()

WS_DLL_PUBLIC size_t ws_label_strcpy | ( | char * | label_str,
|  | size_t | bufsize,
|  | size_t | pos,
|  | const uint8_t * | str,
|  | int | flags )

Copy a string and escape any unprintable characters, truncating if necessary to fit into bufsize and guaranteeing null-termination. Copies whole UTF-8 characters, truncating to avoid splitting a multibyte character. Requires valid UTF-8 input; stops copying and returns the current position upon encountering an invalid character.

Parameters

  label_str | The destination string
  bufsize | The allocated size of the string
  pos | The offset into label_str at which to start copying
  str | The source string
  flags | FORMAT_LABEL_REPLACE_SPACE or 0

Returns
  The attempted length of label_str. If >= bufsize, truncation occurred.

## ◆ xml_escape()

WS_DLL_PUBLIC char * xml_escape | ( | const char * | unescaped | ) |

Return a XML escaped representation of the unescaped string. The returned string must be freed when no longer in use.

Parameters

  unescaped | The unescaped string

Returns
  An XML-escaped representation of the input string