| Wireshark 4.7.3 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Enumerations | Functions
tvbparse.h File Reference
`#include <epan/tvbuff.h>`
`#include "ws_symbol_export.h"`

Go to the source code of this file.

## Classes
struct | _tvbparse_wanted_t
| Describes a parsing rule or expectation for a tvbuff parser. More...
struct | _tvbparse_t
| Represents an instance of a per-packet parser for tvbuff data. More...
struct | _tvbparse_elem_t
| Represents a single token matched by the tvbuff parser, forming part of a linked tree of parse results. More...

## Macros
#define | tvbparse_one_or_more(id, private_data, before_cb, after_cb, wanted)

## Typedefs
typedef struct _tvbparse_elem_t | tvbparse_elem_t
typedef struct _tvbparse_wanted_t | tvbparse_wanted_t
typedef struct _tvbparse_t | tvbparse_t
typedef void(* | tvbparse_action_t) (void *tvbparse_data, const void *wanted_data, struct _tvbparse_elem_t *elem)
typedef int(* | tvbparse_condition_t) (tvbparse_t *, const int, const tvbparse_wanted_t *, tvbparse_elem_t **)

## Enumerations
enum | until_mode_t { TP_UNTIL_INCLUDE , TP_UNTIL_SPEND , TP_UNTIL_LEAVE }
| Controls how a parser consumes the terminal element when scanning up to the last token. More...

## Functions
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_char (const int id, const char *needles, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
| Create a single-character match element.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_not_char (const int id, const char *needle, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
| Create a single-character exclusion match element.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_chars (const int id, const unsigned min_len, const unsigned max_len, const char *needles, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
| Create a multi-character span match element.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_not_chars (const int id, const unsigned min_len, const unsigned max_len, const char *needles, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
| Create a multi-character exclusion span match element.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_string (const int id, const char *string, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
| Create a case-sensitive literal string match element.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_casestring (const int id, const char *str, const void *data, tvbparse_action_t before_cb, tvbparse_action_t after_cb)
| Create a case-insensitive literal string match element.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_until (const int id, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb, const tvbparse_wanted_t *ending, until_mode_t until_mode)
| Create an "until" match element that consumes bytes up to a terminator.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_set_oneof (const int id, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb,...)
| Create a one-of alternation element.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_hashed (const int id, const void *data, tvbparse_action_t before_cb, tvbparse_action_t after_cb, tvbparse_wanted_t *key, tvbparse_wanted_t *other,...)
| Create a hash-dispatch element that selects a sub-element by key.
WS_DLL_PUBLIC void | tvbparse_hashed_add (tvbparse_wanted_t *w,...)
| Adds a hashed element to the wanted list.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_set_seq (const int id, const void *private_data, tvbparse_action_t before_cb, tvbparse_action_t after_cb,...)
| Create a sequential composition element.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_some (const int id, const unsigned min, const unsigned max, const void *data, tvbparse_action_t before_cb, tvbparse_action_t after_cb, const tvbparse_wanted_t *wanted)
| Creates a parsing element that matches a given candidate a specified number of times.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_handle (tvbparse_wanted_t **handle)
| Create an indirect reference element for recursive grammars.
WS_DLL_PUBLIC tvbparse_wanted_t * | tvbparse_quoted (const int id, const void *data, tvbparse_action_t before_cb, tvbparse_action_t after_cb, const char quote, const char escape)
| Parses quoted strings in a given data buffer.
WS_DLL_PUBLIC void | tvbparse_shrink_token_cb (void *tvbparse_data, const void *wanted_data, tvbparse_elem_t *tok)
| Callback function to shrink token length and offset.
WS_DLL_PUBLIC tvbparse_t * | tvbparse_init (wmem_allocator_t *scope, tvbuff_t *tvb, const int offset, int len, void *private_data, const tvbparse_wanted_t *ignore)
| Initialize a new TVB parser.
WS_DLL_PUBLIC bool | tvbparse_reset (tvbparse_t *tt, const unsigned offset, unsigned len)
| Resets the token buffer parser to a new offset and length.
WS_DLL_PUBLIC unsigned | tvbparse_curr_offset (tvbparse_t *tt)
| Get the current offset in the TVB parse structure.
unsigned | tvbparse_len_left (tvbparse_t *tt)
| Get the number of bytes left to parse in the TVB parse structure.
WS_DLL_PUBLIC bool | tvbparse_peek (tvbparse_t *tt, const tvbparse_wanted_t *wanted)
| Peeks at the next token in the buffer without advancing the parser.
WS_DLL_PUBLIC tvbparse_elem_t * | tvbparse_get (tvbparse_t *tt, const tvbparse_wanted_t *wanted)
| Retrieves a token based on the specified conditions.
WS_DLL_PUBLIC tvbparse_elem_t * | tvbparse_find (tvbparse_t *tt, const tvbparse_wanted_t *wanted)
| Finds an element in a TVB parse structure based on a given condition.
WS_DLL_PUBLIC void | tvbparse_tree_add_elem (proto_tree *tree, tvbparse_elem_t *curr)
| Adds an element to a protocol tree.

## Detailed Description

an API for text tvb parsers

Copyright 2005, Luis E. Garcia Ontanon luis@.nosp@m.onta.nosp@m.non.o.nosp@m.rg

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

## ◆ tvbparse_one_or_more

#define tvbparse_one_or_more | ( |  | id,
|  |  | private_data,
|  |  | before_cb,
|  |  | after_cb,
|  |  | wanted )

Value:
tvbparse_some(id, 1, INT_MAX, private_data, before_cb, after_cb, wanted)

## Enumeration Type Documentation

## ◆ until_mode_t

enum until_mode_t

Controls how a parser consumes the terminal element when scanning up to the last token.

Enumerator
TP_UNTIL_INCLUDE | The last element is included in the result and its span is consumed by the parser
TP_UNTIL_SPEND | The last element is excluded from the result but its span is still consumed by the parser
TP_UNTIL_LEAVE | The last element is excluded from the result and its span is left unconsumed for the next parse step

## Function Documentation

## ◆ tvbparse_casestring()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_casestring | ( | const int | id,
|  | const char * | str,
|  | const void * | data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb )

Create a case-insensitive literal string match element.

When looked for it returns a simple element if we have a matching string at the current offset

Parameters

  id | Caller-assigned identifier stored in the returned element.
  str | The literal string to match case-insensitively.
  data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.

Returns
  A newly allocated `tvbparse_wanted_t` describing this element.

## ◆ tvbparse_char()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_char | ( | const int | id,
|  | const char * | needles,
|  | const void * | private_data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb )

Create a single-character match element.

Matches exactly one byte at the current parser offset if that byte is present in `needles`. On success returns a simple element one byte long.

Parameters

  id | Caller-assigned identifier stored in the returned element.
  needles | A string whose characters form the set of accepted bytes.
  private_data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.

Returns
  A newly allocated `tvbparse_wanted_t` describing this element.

## ◆ tvbparse_chars()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_chars | ( | const int | id,
|  | const unsigned | min_len,
|  | const unsigned | max_len,
|  | const char * | needles,
|  | const void * | private_data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb )

Create a multi-character span match element.

When looked for it returns a simple element one or more characters long if one or more char(s) starting from the current offset match one of the needles. An element will be returned if at least min_len chars are given (1 if it's 0) It will get at most max_len chars or as much as it can if max_len is 0.

Parameters

  id | Caller-assigned identifier stored in the returned element.
  min_len | Minimum number of matching bytes required for success; treated as 1 if 0.
  max_len | Maximum number of bytes to consume; 0 means unlimited.
  needles | A string whose characters form the set of accepted bytes.
  private_data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.

Returns
  A newly allocated `tvbparse_wanted_t` describing this element.

## ◆ tvbparse_curr_offset()

WS_DLL_PUBLIC unsigned tvbparse_curr_offset | ( | tvbparse_t * | tt | ) |

Get the current offset in the TVB parse structure.

Parameters

  tt | Pointer to the TVB parse structure.

Returns
  The current offset.

## ◆ tvbparse_find()

WS_DLL_PUBLIC tvbparse_elem_t * tvbparse_find | ( | tvbparse_t * | tt,
|  | const tvbparse_wanted_t * | wanted )

Finds an element in a TVB parse structure based on a given condition.

Like tvbparse_get but this will look for a wanted token even beyond the current offset. This function is slow.

Parameters

  tt | Pointer to the TVB parse structure.
  wanted | Pointer to the wanted element description, including the condition function.

Returns
  Pointer to the found element if successful, NULL otherwise.

## ◆ tvbparse_get()

WS_DLL_PUBLIC tvbparse_elem_t * tvbparse_get | ( | tvbparse_t * | tt,
|  | const tvbparse_wanted_t * | wanted )

Retrieves a token based on the specified conditions.

This will look for the wanted token at the current offset or after any given number of ignored tokens returning NULL if there's no match. if there is a match it will set the offset of the current parser after the end of the token

Parameters

  tt | Pointer to the TVB parse context.
  wanted | Pointer to the structure containing the conditions for the desired token.

Returns
  Pointer to the retrieved token if successful, NULL otherwise.

## ◆ tvbparse_handle()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_handle | ( | tvbparse_wanted_t ** | handle | ) |

Create an indirect reference element for recursive grammars.

this is a pointer to a pointer to a wanted element (that might have not been initialized yet) so that recursive structures

Parameters

  handle | Pointer to the `tvbparse_wanted_t*` that will be resolved at match time. The pointed-to value must be non-NULL before the first call to `tvbparse_get()` or `tvbparse_find()` that may reach this element.

Returns
  A newly allocated `tvbparse_wanted_t` that indirects through `handle` when matched.

## ◆ tvbparse_hashed()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_hashed | ( | const int | id,
|  | const void * | data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb,
|  | tvbparse_wanted_t * | key,
|  | tvbparse_wanted_t * | other,
|  |  | ... )

Create a hash-dispatch element that selects a sub-element by key.

Parameters

  id | Caller-assigned identifier stored in the returned element.
  data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.
  key | The element used to extract the dispatch key string.
  other | Fallback element used when the key has no hash entry; NULL to fail the match when no entry is found.
  ... | Optional additional NULL-terminated alternating pairs of `char*` key name and `tvbparse_wanted_t*` element.

Returns
  A newly allocated `tvbparse_wanted_t` describing this element.

## ◆ tvbparse_hashed_add()

WS_DLL_PUBLIC void tvbparse_hashed_add | ( | tvbparse_wanted_t * | w,
|  |  | ... )

Adds a hashed element to the wanted list.

Parameters

  w | Pointer to the tvbparse_wanted_t structure.
  ... | Variable arguments, alternating between name (char*) and element (tvbparse_wanted_t*).

## ◆ tvbparse_init()

WS_DLL_PUBLIC tvbparse_t * tvbparse_init | ( | wmem_allocator_t * | scope,
|  | tvbuff_t * | tvb,
|  | const int | offset,
|  | int | len,
|  | void * | private_data,
|  | const tvbparse_wanted_t * | ignore )

Initialize a new TVB parser.

initialize the parser (at every packet) scope: memory scope/pool tvb: what are we parsing? offset: from where len: for how many bytes private_data: will be passed to the action callbacks ignore: a wanted token type to be ignored (the associated cb WILL be called when it matches)

Parameters

  scope | Memory allocation scope for the parser.
  tvb | The input tvbuff to parse.
  offset | Starting offset within the tvbuff.
  len | Length of data to parse, or -1 to use the entire captured length.
  private_data | Private data to associate with the parser.
  ignore | Configuration for ignored elements during parsing.

Returns
  Pointer to the initialized tvbparse_t structure.

## ◆ tvbparse_len_left()

unsigned tvbparse_len_left | ( | tvbparse_t * | tt | ) |

Get the number of bytes left to parse in the TVB parse structure.

Parameters

  tt | Pointer to the TVB parse structure.

Returns
  The number of bytes left to parse.

## ◆ tvbparse_not_char()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_not_char | ( | const int | id,
|  | const char * | needle,
|  | const void * | private_data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb )

Create a single-character exclusion match element.

When looked for it returns a simple element one character long if the char at the current offset does not match one of the needles.

Parameters

  id | Caller-assigned identifier stored in the returned element.
  needle | A string whose characters form the set of rejected bytes.
  private_data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.

Returns
  A newly allocated `tvbparse_wanted_t` describing this element.

## ◆ tvbparse_not_chars()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_not_chars | ( | const int | id,
|  | const unsigned | min_len,
|  | const unsigned | max_len,
|  | const char * | needles,
|  | const void * | private_data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb )

Create a multi-character exclusion span match element.

When looked for it returns a simple element one or more characters long if one or more char(s) starting from the current offset do not match one of the needles. An element will be returned if at least min_len chars are given (1 if it's 0) It will get at most max_len chars or as much as it can if max_len is 0.

Parameters

  id | Caller-assigned identifier stored in the returned element.
  min_len | Minimum number of non-matching bytes required for success; treated as 1 if 0.
  max_len | Maximum number of bytes to consume; 0 means unlimited.
  needles | A string whose characters form the set of rejected bytes.
  private_data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.

Returns
  A newly allocated `tvbparse_wanted_t` describing this element.

## ◆ tvbparse_peek()

WS_DLL_PUBLIC bool tvbparse_peek | ( | tvbparse_t * | tt,
|  | const tvbparse_wanted_t * | wanted )

Peeks at the next token in the buffer without advancing the parser.

This will look for the wanted token at the current offset or after any given number of ignored tokens returning false if there's no match or true if there is a match. The parser will be left in its original state and no callbacks will be called.

Parameters

  tt | Pointer to the tvbparse_t structure representing the parser state.
  wanted | Pointer to the tvbparse_wanted_t structure describing the token to look for.

Returns
  True if a match is found, false otherwise.

## ◆ tvbparse_quoted()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_quoted | ( | const int | id,
|  | const void * | data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb,
|  | const char | quote,
|  | const char | escape )

Parses quoted strings in a given data buffer.

this is a composed candidate, that will try to match a quoted string (included the quotes) including into it every escaped quote.

C strings are matched with tvbparse_quoted(-1,NULL,NULL,NULL,"\"","\\")

Parameters

  id | Identifier for the parsed token.
  data | Pointer to the data buffer containing the quoted strings.
  before_cb | Callback function to be invoked before parsing.
  after_cb | Callback function to be invoked after parsing.
  quote | Character used as the quote delimiter.
  escape | Character used for escaping special characters within quotes.

Returns
  A tvbparse_wanted_t structure representing the parsed quoted strings.

## ◆ tvbparse_reset()

WS_DLL_PUBLIC bool tvbparse_reset | ( | tvbparse_t * | tt,
|  | const unsigned | offset,
|  | unsigned | len )

Resets the token buffer parser to a new offset and length.

Parameters

  tt | Pointer to the tvbparse_t structure.
  offset | The new starting offset for parsing.
  len | The new length of data to parse.

Returns
  true if the reset is successful, false otherwise.

## ◆ tvbparse_set_oneof()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_set_oneof | ( | const int | id,
|  | const void * | private_data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb,
|  |  | ... )

Create a one-of alternation element.

When looked for it will try to match to the given candidates and return a composed element whose subelement is the first match.

The list of candidates is terminated with a NULL

Parameters

  id | Caller-assigned identifier stored in the returned element.
  private_data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.
  ... | NULL-terminated list of `tvbparse_wanted_t*` candidates to try in order.

Returns
  A newly allocated `tvbparse_wanted_t` describing this alternation.

## ◆ tvbparse_set_seq()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_set_seq | ( | const int | id,
|  | const void * | private_data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb,
|  |  | ... )

Create a sequential composition element.

When looked for it will try to match in order all the given candidates. If every candidate is found in the given order it will return a composed element whose subelements are the matched elements.

The list of candidates is terminated with a NULL.

Parameters

  id | Caller-assigned identifier stored in the returned element.
  private_data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the sequence is consumed, or NULL.
  after_cb | Callback invoked after the sequence is consumed, or NULL.
  ... | NULL-terminated list of `tvbparse_wanted_t*` candidates to match in order.

Returns
  A newly allocated `tvbparse_wanted_t` describing this sequence.

## ◆ tvbparse_shrink_token_cb()

WS_DLL_PUBLIC void tvbparse_shrink_token_cb | ( | void * | tvbparse_data,
|  | const void * | wanted_data,
|  | tvbparse_elem_t * | tok )

Callback function to shrink token length and offset.

This callback is invoked before or after an element has been processed. It adjusts the token's offset and length by incrementing the offset and decrementing the length by 2.

Parameters

  tvbparse_data | User data passed to the callback (not used).
  wanted_data | Wanted data for the element (not used).
  tok | Pointer to the current token being processed.

## ◆ tvbparse_some()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_some | ( | const int | id,
|  | const unsigned | min,
|  | const unsigned | max,
|  | const void * | data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb,
|  | const tvbparse_wanted_t * | wanted )

Creates a parsing element that matches a given candidate a specified number of times.

When looked for it will try to match the given candidate at least min times and at most max times. If the given candidate is matched at least min times a composed element is returned.

Parameters

  id | Identifier for the parsing element.
  min | Minimum number of times the candidate should be matched.
  max | Maximum number of times the candidate should be matched.
  data | User-defined data to be associated with the parsing element.
  before_cb | Callback function to be called before parsing the element.
  after_cb | Callback function to be called after parsing the element.
  wanted | The candidate element to be matched repeatedly.

Returns
  A pointer to a tvbparse_wanted_t structure representing the parsing element.

## ◆ tvbparse_string()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_string | ( | const int | id,
|  | const char * | string,
|  | const void * | private_data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb )

Create a case-sensitive literal string match element.

When looked for it returns a simple element if we have the given string at the current offset

Parameters

  id | Caller-assigned identifier stored in the returned element.
  string | The literal byte sequence to match.
  private_data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.

Returns
  A newly allocated `tvbparse_wanted_t` describing this element.

## ◆ tvbparse_tree_add_elem()

WS_DLL_PUBLIC void tvbparse_tree_add_elem | ( | proto_tree * | tree,
|  | tvbparse_elem_t * | curr )

Adds an element to a protocol tree.

Parameters

  tree | The protocol tree to which the element will be added.
  curr | The current element being processed.

## ◆ tvbparse_until()

WS_DLL_PUBLIC tvbparse_wanted_t * tvbparse_until | ( | const int | id,
|  | const void * | private_data,
|  | tvbparse_action_t | before_cb,
|  | tvbparse_action_t | after_cb,
|  | const tvbparse_wanted_t * | ending,
|  | until_mode_t | until_mode )

Create an "until" match element that consumes bytes up to a terminator.

When looked for it returns a simple element containing all the characters found until the first match of the ending element if the ending element is

When looking for until elements it calls tvbparse_find so it can be very slow.

It won't have a subelement, the ending's callbacks won't get called. op_mode values determine how the terminating element and the current offset of the parser are handled

Parameters

  id | Caller-assigned identifier stored in the returned element.
  private_data | Opaque caller data passed to the callbacks.
  before_cb | Callback invoked before the match is consumed, or NULL.
  after_cb | Callback invoked after the match is consumed, or NULL.
  ending | The terminating element to search for.
  until_mode | Controls how the terminator affects the returned element and parser offset.

Returns
  A newly allocated `tvbparse_wanted_t` describing this element.