dfilter.h File Reference

#include <wireshark.h>
#include "dfilter-loc.h"
#include <epan/proto.h>

Go to the source code of this file.

Classes
struct	df_error_t

Macros
#define	DF_ERROR_GENERIC   -1
#define	DF_ERROR_UNEXPECTED_END   -2
#define	df_error_new_msg(msg)    df_error_new_printf(DF_ERROR_GENERIC, NULL, "%s", msg)
#define	DF_SAVE_TREE   (1U << 0)
#define	DF_EXPAND_MACROS   (1U << 1)
#define	DF_OPTIMIZE   (1U << 2)
#define	DF_DEBUG_FLEX   (1U << 3)
#define	DF_DEBUG_LEMON   (1U << 4)
#define	DF_RETURN_VALUES   (1U << 5)
#define	dfilter_compile(text, dfp, errp)
#define	DF_DUMP_REFERENCES   (1U << 0)
#define	DF_DUMP_SHOW_FTYPE   (1U << 1)
#define	dfilter_log(dfcode, msg)   (void)0
#define	DFILTER_DEBUG_HERE(dfcode)

Typedefs
typedef struct epan_dfilter	dfilter_t

Functions
df_error_t *	df_error_new (int code, char *msg, df_loc_t *loc)
	Create a new error object with a specific code and message.
df_error_t *	df_error_new_printf (int code, df_loc_t *loc, const char *fmt,...)
	Create a new error with formatted message.
df_error_t *	df_error_new_vprintf (int code, df_loc_t *loc, const char *fmt, va_list ap)
	Create a new error with formatted message and location information.
WS_DLL_PUBLIC void	df_error_free (df_error_t **ep)
	Frees a df_error_t structure.
void	dfilter_init (const char *app_env_var_prefix)
	Initialize the display filter module.
void	dfilter_cleanup (void)
	Perform module-level cleanup for the dfilter subsystem.
WS_DLL_PUBLIC char *	dfilter_expand (const char *expr, df_error_t **err_ret)
	Expand a display filter expression.
WS_DLL_PUBLIC bool	dfilter_compile_full (const char *text, dfilter_t **dfp, df_error_t **errpp, unsigned flags, const char *caller)
	Compiles a string to a dfilter_t.
WS_DLL_PUBLIC struct stnode *	dfilter_get_syntax_tree (const char *text)
	Build a syntax tree for a filter.
WS_DLL_PUBLIC void	dfilter_free (dfilter_t *df)
	Free a compiled dfilter.
WS_DLL_PUBLIC bool	dfilter_apply_edt (dfilter_t *df, struct epan_dissect *edt)
	Apply a compiled display filter to an epan_dissect structure.
bool	dfilter_apply (dfilter_t *df, proto_tree *tree)
	Apply a compiled dfilter to a protocol tree.
bool	dfilter_apply_full (dfilter_t *df, proto_tree *tree, GPtrArray **fvals)
	Apply a dfilter to a proto_tree and populate fvals.
void	dfilter_prime_proto_tree (const dfilter_t *df, proto_tree *tree)
	Prime a proto_tree using the fields/protocols used in a dfilter.
void	dfilter_prime_proto_tree_print (const dfilter_t *df, proto_tree *tree)
	Prime a proto_tree using the fields/protocols used in a dfilter, marked for print.
WS_DLL_PUBLIC void	dfilter_load_field_references (const dfilter_t *df, proto_tree *tree)
	Refresh references in a compiled display filter.
WS_DLL_PUBLIC void	dfilter_load_field_references_edt (const dfilter_t *df, struct epan_dissect *edt)
	Load field references for a display filter into an epan_dissect_t structure.
bool	dfilter_has_interesting_fields (const dfilter_t *df)
	Check if a display filter has any interesting fields.
bool	dfilter_interested_in_field (const dfilter_t *df, int hfid)
	Check if dfilter is interested in a given field.
bool	dfilter_interested_in_proto (const dfilter_t *df, int proto_id)
	Check if dfilter is interested in a given protocol.
WS_DLL_PUBLIC bool	dfilter_requires_columns (const dfilter_t *df)
	Check if a display filter requires specific columns.
WS_DLL_PUBLIC GPtrArray *	dfilter_deprecated_tokens (dfilter_t *df)
	Get deprecated tokens from a dfilter.
WS_DLL_PUBLIC GSList *	dfilter_get_warnings (dfilter_t *df)
	Get warnings associated with a display filter.
WS_DLL_PUBLIC void	dfilter_dump (FILE *fp, dfilter_t *df, uint16_t flags)
	Dump a dfilter to a file.
WS_DLL_PUBLIC const char *	dfilter_text (dfilter_t *df)
	Get the text representation of a syntax tree.
WS_DLL_PUBLIC const char *	dfilter_syntax_tree (dfilter_t *df)
	Get the syntax tree of a dfilter.
WS_DLL_PUBLIC ftenum_t	dfilter_get_return_type (dfilter_t *df)
	Get the return type of a display filter.
WS_DLL_PUBLIC void	dfilter_log_full (const char *domain, enum ws_log_level level, const char *file, long line, const char *func, dfilter_t *dfcode, const char *msg)
	Log a display filter with full details.

Detailed Description

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 2001 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Macro Definition Documentation

dfilter_compile

#define dfilter_compile	(		text,
			dfp,
			errp
	)

Value:

    dfilter_compile_full(text, dfp, errp, \
                DF_EXPAND_MACROS|DF_OPTIMIZE, \
                __func__)

DFILTER_DEBUG_HERE

#define DFILTER_DEBUG_HERE

(

dfcode

)

Value:

    dfilter_log_full(LOG_DOMAIN_DFILTER, LOG_LEVEL_ECHO,    \
                __FILE__, __LINE__, __func__,   \
                dfcode, #dfcode);

Function Documentation

df_error_free()

WS_DLL_PUBLIC void df_error_free

(

df_error_t **

ep

)

Frees a df_error_t structure.

This function releases memory associated with a df_error_t structure and sets the pointer to NULL.

Parameters

ep	Pointer to a pointer to the df_error_t structure to be freed.

df_error_new()

df_error_t * df_error_new	(	int	code,
		char *	msg,
		df_loc_t *	loc
	)

Create a new error object with a specific code and message.

Parameters

code	Error code.
msg	Error message.
loc	Location information for the error (can be NULL).

Returns

Pointer to the newly created error object.

df_error_new_printf()

df_error_t * df_error_new_printf	(	int	code,
		df_loc_t *	loc,
		const char *	fmt,
			...
	)

Create a new error with formatted message.

Parameters

code	Error code.
loc	Location information for the error.
fmt	Format string for the error message.

Returns

Pointer to the newly created error object.

df_error_new_vprintf()

df_error_t * df_error_new_vprintf	(	int	code,
		df_loc_t *	loc,
		const char *	fmt,
		va_list	ap
	)

Create a new error with formatted message and location information.

Parameters

code	Error code.
loc	Location information for the error, or NULL if not applicable.
fmt	Format string for the error message.
ap	Variable argument list corresponding to the format string.

Returns

Pointer to the newly created error object.

dfilter_apply()

bool dfilter_apply	(	dfilter_t *	df,
		proto_tree *	tree
	)

Apply a compiled dfilter to a protocol tree.

Parameters

df	The compiled dfilter to apply.
tree	The protocol tree to which the dfilter will be applied.

dfilter_apply_edt()

WS_DLL_PUBLIC bool dfilter_apply_edt	(	dfilter_t *	df,
		struct epan_dissect *	edt
	)

Apply a compiled display filter to an epan_dissect structure.

Parameters

df	The compiled display filter.
edt	The epan_dissect structure to apply the filter to.

Returns

true if the filter matches, false otherwise.

dfilter_apply_full()

bool dfilter_apply_full	(	dfilter_t *	df,
		proto_tree *	tree,
		GPtrArray **	fvals
	)

Apply a dfilter to a proto_tree and populate fvals.

Apply compiled dfilter and return final set of fvalues (if they exist) in addition to true/false determination.

Parameters

df	The dfilter to apply.
tree	The proto_tree to prime with fields/protocols used in the dfilter.
fvals	A pointer to a GPtrArray that will be populated with filter values.

dfilter_cleanup()

void dfilter_cleanup

(

void

)

Perform module-level cleanup for the dfilter subsystem.

This function cleans up resources used by the dfilter system, including plugins, macros, and syntax trees.

dfilter_compile_full()

WS_DLL_PUBLIC bool dfilter_compile_full	(	const char *	text,
		dfilter_t **	dfp,
		df_error_t **	errpp,
		unsigned	flags,
		const char *	caller
	)

Compiles a string to a dfilter_t.

On success, sets the dfilter* pointed to by dfp to either a NULL pointer (if the filter is a null filter, as generated by an all-blank string) or to a pointer to the newly-allocated dfilter_t structure.

On failure, err_msg is set to point to the error message. This error message is allocated with g_malloc(), and must be freed with g_free(). The dfilter will be set to NULL after a failure.

Returns true on success, false on failure.

dfilter_deprecated_tokens()

WS_DLL_PUBLIC GPtrArray * dfilter_deprecated_tokens

(

dfilter_t *

df

)

Get deprecated tokens from a dfilter.

Parameters

df	Pointer to the dfilter_t structure.

Returns

GSList* List of deprecated tokens, or NULL if none are present.

dfilter_dump()

WS_DLL_PUBLIC void dfilter_dump	(	FILE *	fp,
		dfilter_t *	df,
		uint16_t	flags
	)

Dump a dfilter to a file.

Parameters

fp	File pointer where the dfilter will be dumped.
df	The dfilter to dump.
flags	Flags controlling the dumping process.

dfilter_expand()

WS_DLL_PUBLIC char * dfilter_expand	(	const char *	expr,
		df_error_t **	err_ret
	)

Expand a display filter expression.

This function expands a display filter expression by applying macros and performing optimizations.

Parameters

expr	The input display filter expression to be expanded.
err_ret	Pointer to a pointer for storing any error that occurs during expansion.

Returns

A string representing the expanded display filter, or NULL if an error occurred.

dfilter_free()

WS_DLL_PUBLIC void dfilter_free

(

dfilter_t *

df

)

Free a compiled dfilter.

Frees all memory used by dfilter, and frees the dfilter itself.

Parameters

df	Pointer to the dfilter_t structure to be freed.

dfilter_get_return_type()

WS_DLL_PUBLIC ftenum_t dfilter_get_return_type

(

dfilter_t *

df

)

Get the return type of a display filter.

Parameters

df	Pointer to the dfilter_t structure.

Returns

ftenum_t The return type of the display filter.

dfilter_get_syntax_tree()

WS_DLL_PUBLIC struct stnode * dfilter_get_syntax_tree

(

const char *

text

)

Build a syntax tree for a filter.

Parameters

text	A display filter.

Returns

The root node of a syntax tree on success or NULL on failure.

dfilter_get_warnings()

WS_DLL_PUBLIC GSList * dfilter_get_warnings

(

dfilter_t *

df

)

Get warnings associated with a display filter.

Parameters

df	Pointer to the dfilter_t structure.

Returns

The warnings associated with the display filter.

dfilter_has_interesting_fields()

bool dfilter_has_interesting_fields

(

const dfilter_t *

df

)

Check if a display filter has any interesting fields.

Parameters

df	The display filter to check.

Returns

true if the display filter is interested in at least one field, false otherwise.

dfilter_init()

void dfilter_init

(

const char *

app_env_var_prefix

)

Initialize the display filter module.

This function initializes the display filter module by setting up the parser, syntax-tree subsystem, functions, macros, and plugins using the provided environment variable prefix.

Parameters

app_env_var_prefix

The prefix for application environment variables.

dfilter_interested_in_field()

bool dfilter_interested_in_field	(	const dfilter_t *	df,
		int	hfid
	)

Check if dfilter is interested in a given field.

Parameters

df	The dfilter
hfid	The header field info ID to check

Returns

true if the field is interesting to the dfilter

dfilter_interested_in_proto()

bool dfilter_interested_in_proto	(	const dfilter_t *	df,
		int	proto_id
	)

Check if dfilter is interested in a given protocol.

Parameters

df	The dfilter
proto_id	The protocol ID to check

Returns

true if the dfilter is interested in a field whose parent is proto_id

dfilter_load_field_references()

WS_DLL_PUBLIC void dfilter_load_field_references	(	const dfilter_t *	df,
		proto_tree *	tree
	)

Refresh references in a compiled display filter.

Parameters

df	Pointer to the display filter.
tree	Protocol tree where field references will be loaded.

dfilter_load_field_references_edt()

WS_DLL_PUBLIC void dfilter_load_field_references_edt	(	const dfilter_t *	df,
		struct epan_dissect *	edt
	)

Load field references for a display filter into an epan_dissect_t structure.

Parameters

df	The display filter to process.
edt	The epan_dissect_t structure where field references will be loaded.

dfilter_log_full()

WS_DLL_PUBLIC void dfilter_log_full	(	const char *	domain,
		enum ws_log_level	level,
		const char *	file,
		long	line,
		const char *	func,
		dfilter_t *	dfcode,
		const char *	msg
	)

Log a display filter with full details.

Logs a display filter along with its bytecode and an optional message at a specified log level.

Parameters

domain	The logging domain.
level	The log level.
file	The source file name where the log is generated.
line	The line number in the source file.
func	The function name where the log is generated.
dfcode	The display filter to log.
msg	An optional message to include with the log entry.

dfilter_prime_proto_tree()

void dfilter_prime_proto_tree	(	const dfilter_t *	df,
		proto_tree *	tree
	)

Prime a proto_tree using the fields/protocols used in a dfilter.

Parameters

df	The display filter to use for priming the tree.
tree	The protocol tree to prime.

dfilter_prime_proto_tree_print()

void dfilter_prime_proto_tree_print	(	const dfilter_t *	df,
		proto_tree *	tree
	)

Prime a proto_tree using the fields/protocols used in a dfilter, marked for print.

Parameters

df	Pointer to the compiled display filter.
tree	Pointer to the protocol tree.

dfilter_requires_columns()

WS_DLL_PUBLIC bool dfilter_requires_columns

(

const dfilter_t *

df

)

Check if a display filter requires specific columns.

Parameters

df	The display filter to check.

Returns

true If the filter requires specific columns, false otherwise.

dfilter_syntax_tree()

WS_DLL_PUBLIC const char * dfilter_syntax_tree

(

dfilter_t *

df

)

Get the syntax tree of a dfilter.

Text representation of syntax tree (if it was saved, NULL otherwise).

Parameters

df	Pointer to the dfilter_t structure.

Returns

const char* The syntax tree string.

dfilter_text()

WS_DLL_PUBLIC const char * dfilter_text

(

dfilter_t *

df

)

Get the text representation of a syntax tree.

Parameters

df	Pointer to the dfilter_t structure.

Returns

const char* The text representation of the syntax tree, or NULL if not saved.