stat_tap_ui.h File Reference

#include "ws_symbol_export.h"
#include <epan/params.h>
#include <epan/stat_groups.h>
#include <epan/packet_info.h>
#include <epan/tap.h>
#include <epan/wmem_scopes.h>

Go to the source code of this file.

Classes
struct	_tap_param
	Describes a single configurable parameter accepted by a tap statistic. More...
struct	_stat_tap_ui
	Registration descriptor for a tap-based statistics dialog or CLI report. More...
struct	_stat_tap_table_item_type
	Represents a single item in a statistics tap table. More...
struct	_stat_tap_table_item
	Schema descriptor for a single column in a statistics tap table. More...
struct	_stat_tap_table
	A single statistics table instance, holding rows of tap-collected data. More...
struct	_stat_tap_table_ui
	Registration descriptor and runtime state for a table-based tap statistics UI. More...
struct	_stat_data_t
	Per-tap-instance data passed between the tap engine and the statistics UI. More...

Typedefs
typedef struct _tap_param	tap_param
	Describes a single configurable parameter accepted by a tap statistic.
typedef bool(*	stat_tap_init_cb) (const char *opt_arg, void *userdata)
	Callback invoked to initialize a tap statistic with its CLI argument string.
typedef struct _stat_tap_ui	stat_tap_ui
	Registration descriptor for a tap-based statistics dialog or CLI report.
typedef struct _stat_tap_table_item_type	stat_tap_table_item_type
	Represents a single item in a statistics tap table.
typedef struct _stat_tap_table_item	stat_tap_table_item
	Schema descriptor for a single column in a statistics tap table.
typedef struct _stat_tap_table	stat_tap_table
	A single statistics table instance, holding rows of tap-collected data.
typedef struct _stat_tap_table_ui	stat_tap_table_ui
	Registration descriptor and runtime state for a table-based tap statistics UI.
typedef struct _stat_data_t	stat_data_t
	Per-tap-instance data passed between the tap engine and the statistics UI.

Enumerations
enum	param_type {   PARAM_UINT , PARAM_STRING , PARAM_ENUM , PARAM_UUID ,   PARAM_FILTER }
	Parameter types for tap statistics dialogs and CLI argument parsing. More...
enum	stat_tap_table_item_enum {   TABLE_ITEM_NONE = 0 , TABLE_ITEM_UINT , TABLE_ITEM_INT , TABLE_ITEM_STRING ,   TABLE_ITEM_FLOAT , TABLE_ITEM_ENUM }
	Value type for a cell within a statistics tap table. More...
enum	tap_alignment_type { TAP_ALIGN_LEFT = 0 , TAP_ALIGN_RIGHT }
	Horizontal alignment for a statistics table column. More...

Functions
void	stat_tap_init (void)
	Initializes the statistics tap system, setting up necessary data structures.
WS_DLL_PUBLIC void	register_stat_tap_ui (stat_tap_ui *ui, void *userdata)
WS_DLL_PUBLIC void	register_stat_tap_table_ui (stat_tap_table_ui *ui)
	Register a table-based statistics tap UI descriptor.
WS_DLL_PUBLIC void	stat_tap_iterate_tables (wmem_foreach_func func, void *user_data)
	Iterate over all registered table-based statistics tap UIs.
WS_DLL_PUBLIC void	stat_tap_get_filter (stat_tap_table_ui *new_stat, const char *opt_arg, const char **filter, char **err)
	Parse the display filter from a statistics option argument string.
WS_DLL_PUBLIC stat_tap_table *	stat_tap_init_table (const char *name, int num_fields, int num_elements, const char *filter_string)
	Allocate and initialise a stat_tap_table.
WS_DLL_PUBLIC void	stat_tap_add_table (stat_tap_table_ui *new_stat, stat_tap_table *table)
	Adds a new table to the statistics tap.
WS_DLL_PUBLIC stat_tap_table *	stat_tap_find_table (stat_tap_table_ui *ui, const char *name)
	Finds a table by its UI structure and name.
WS_DLL_PUBLIC void	stat_tap_init_table_row (stat_tap_table *stat_table, unsigned table_index, unsigned num_fields, const stat_tap_table_item_type *fields)
	Initialise a row in a stat_tap_table with field values.
WS_DLL_PUBLIC stat_tap_table_item_type *	stat_tap_get_field_data (const stat_tap_table *stat_table, unsigned table_index, unsigned field_index)
	Return a pointer to the field value at a given row and column.
WS_DLL_PUBLIC void	stat_tap_set_field_data (stat_tap_table *stat_table, unsigned table_index, unsigned field_index, stat_tap_table_item_type *field_data)
	Set field data for a specific table and field index.
WS_DLL_PUBLIC void	reset_stat_table (stat_tap_table_ui *new_stat)
	Reset all tables belonging to a statistics tap UI to their initial state.
WS_DLL_PUBLIC stat_tap_table_ui *	stat_tap_by_name (const char *name)
	Look up a registered table-based statistics tap UI by its option name.
WS_DLL_PUBLIC void	free_stat_tables (stat_tap_table_ui *new_stat)
	Free all of the tables associated with a stat_tap_table_ui.
WS_DLL_PUBLIC bool	process_stat_cmd_arg (const char *optstr)
	Processes a command argument for statistics.
WS_DLL_PUBLIC void	list_stat_cmd_args (void)
	List command-line arguments for requested statistics.
WS_DLL_PUBLIC bool	start_requested_stats (void)
	Start requested statistics.

Detailed Description

Declarations of routines to register UI information for stats

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

Typedef Documentation

stat_tap_init_cb

typedef bool(* stat_tap_init_cb) (const char *opt_arg, void *userdata)

Callback invoked to initialize a tap statistic with its CLI argument string.

Parameters

opt_arg	The full "-z" option argument string passed by the user.
userdata	Opaque user data pointer passed through from the registration.

Returns

True if initialization succeeded; false on error.

stat_tap_table_item_type

typedef struct _stat_tap_table_item_type stat_tap_table_item_type

Represents a single item in a statistics tap table.

This structure holds a typed value used in statistical reporting, such as counters, labels, or computed metrics. It also includes a scratchpad area (user_data) for dissector-specific temporary storage or extended metadata.

Enumeration Type Documentation

param_type

enum param_type

Parameter types for tap statistics dialogs and CLI argument parsing.

Enumerator
PARAM_UINT	Unsigned integer parameter (currently unused)
PARAM_STRING	String parameter (currently unused)
PARAM_ENUM	Enumerated value parameter; used by SCSI SRT and similar taps
PARAM_UUID	UUID parameter for DCE-RPC (currently unused)
PARAM_FILTER	Display filter string parameter

stat_tap_table_item_enum

enum stat_tap_table_item_enum

Value type for a cell within a statistics tap table.

Enumerator
TABLE_ITEM_NONE	No value; uninitialized or empty cell
TABLE_ITEM_UINT	Unsigned integer cell value
TABLE_ITEM_INT	Signed integer cell value
TABLE_ITEM_STRING	String cell value
TABLE_ITEM_FLOAT	Floating-point cell value
TABLE_ITEM_ENUM	Enumerated cell value

tap_alignment_type

enum tap_alignment_type

Horizontal alignment for a statistics table column.

Enumerator
TAP_ALIGN_LEFT	Left-align column content
TAP_ALIGN_RIGHT	Right-align column content

Function Documentation

free_stat_tables()

WS_DLL_PUBLIC void free_stat_tables

(

stat_tap_table_ui *

new_stat

)

Free all of the tables associated with a stat_tap_table_ui.

Frees data created by stat_tap_ui.stat_tap_init_cb. stat_tap_table_ui.stat_tap_free_table_item_cb is called for each index in each row.

Parameters

new_stat

Parent stat_tap_table_ui struct, provided by the dissector.

list_stat_cmd_args()

WS_DLL_PUBLIC void list_stat_cmd_args

(

void

)

List command-line arguments for requested statistics.

This function iterates through a list of command-line arguments and processes them to request specific statistics.

process_stat_cmd_arg()

WS_DLL_PUBLIC bool process_stat_cmd_arg

(

const char *

optstr

)

Processes a command argument for statistics.

Parameters

optstr

The option string to process.

Returns

true if the command is recognized and processed, false otherwise.

register_stat_tap_table_ui()

WS_DLL_PUBLIC void register_stat_tap_table_ui

(

stat_tap_table_ui *

ui

)

Register a table-based statistics tap UI descriptor.

Parameters

ui	The stat_tap_table_ui descriptor to register. The caller retains ownership; the descriptor must remain valid for the lifetime of the session.

register_stat_tap_ui()

WS_DLL_PUBLIC void register_stat_tap_ui	(	stat_tap_ui *	ui,
		void *	userdata
	)

Register UI information for a tap.

Parameters

ui	UI information for the tap.
userdata	Additional data for the init routine.

reset_stat_table()

WS_DLL_PUBLIC void reset_stat_table

(

stat_tap_table_ui *

new_stat

)

Reset all tables belonging to a statistics tap UI to their initial state.

Parameters

new_stat

The stat_tap_table_ui whose tables should be reset.

start_requested_stats()

WS_DLL_PUBLIC bool start_requested_stats

(

void

)

Start requested statistics.

This function processes and initializes all registered statistics taps that have been requested.

Returns

true if all statistics taps were successfully initialized, false otherwise.

stat_tap_add_table()

WS_DLL_PUBLIC void stat_tap_add_table	(	stat_tap_table_ui *	new_stat,
		stat_tap_table *	table
	)

Adds a new table to the statistics tap.

Parameters

new_stat	Pointer to the statistics tap UI structure.
table	Pointer to the statistics tap table structure.

stat_tap_by_name()

WS_DLL_PUBLIC stat_tap_table_ui * stat_tap_by_name

(

const char *

name

)

Look up a registered table-based statistics tap UI by its option name.

Parameters

name	The -z option name to search for (e.g. "http,tree").

Returns

The matching stat_tap_table_ui descriptor, or NULL if no registered statistic has that name.

stat_tap_find_table()

WS_DLL_PUBLIC stat_tap_table * stat_tap_find_table	(	stat_tap_table_ui *	ui,
		const char *	name
	)

Finds a table by its UI structure and name.

Parameters

ui	The UI structure containing the tables.
name	The name of the table to find.

Returns

stat_tap_table* Pointer to the found table, or NULL if not found.

stat_tap_get_field_data()

WS_DLL_PUBLIC stat_tap_table_item_type * stat_tap_get_field_data	(	const stat_tap_table *	stat_table,
		unsigned	table_index,
		unsigned	field_index
	)

Return a pointer to the field value at a given row and column.

Parameters

stat_table	The table to query.
table_index	Zero-based row index within stat_table.
field_index	Zero-based column index within the row.

Returns

A pointer to the live stat_tap_table_item_type for that cell, or NULL if table_index or field_index is out of range. The pointer is valid until the table is freed or reset.

stat_tap_get_filter()

WS_DLL_PUBLIC void stat_tap_get_filter	(	stat_tap_table_ui *	new_stat,
		const char *	opt_arg,
		const char **	filter,
		char **	err
	)

Parse the display filter from a statistics option argument string.

Parameters

new_stat	The stat_tap_table_ui descriptor for the statistic being initialised.
opt_arg	The raw option argument string (e.g. "http,tree,ip.src==1.2.3.4").
filter	Receives a pointer to the filter substring within opt_arg, or NULL if no filter was supplied. The pointer aliases opt_arg and must not be freed separately.
err	Receives a newly allocated error string if opt_arg cannot be parsed, or NULL on success. The caller must free any non-NULL value with g_free().

stat_tap_init()

void stat_tap_init ( void  )

extern

Initializes the statistics tap system, setting up necessary data structures.

Initialize statistics tap system.

stat_tap_init_table()

WS_DLL_PUBLIC stat_tap_table * stat_tap_init_table	(	const char *	name,
		int	num_fields,
		int	num_elements,
		const char *	filter_string
	)

Allocate and initialise a stat_tap_table.

Parameters

name	Human-readable title shown as the table heading.
num_fields	Number of columns (field descriptors) in the table.
num_elements	Initial number of rows to pre-allocate.
filter_string	Base display filter prefix to which a procedure number can be appended (e.g. "rpc.procedure=="), or NULL if per-row filters are not needed.

Returns

A newly allocated and initialised stat_tap_table. Freed by the statistics framework when the table is destroyed.

stat_tap_init_table_row()

WS_DLL_PUBLIC void stat_tap_init_table_row	(	stat_tap_table *	stat_table,
		unsigned	table_index,
		unsigned	num_fields,
		const stat_tap_table_item_type *	fields
	)

Initialise a row in a stat_tap_table with field values.

Parameters

stat_table	The table whose row is being initialised.
table_index	Zero-based row index within stat_table.
num_fields	Number of column values provided in fields. Must not exceed the num_fields value passed to stat_tap_init_table().
fields	Array of num_fields stat_tap_table_item_type values to copy into the row. The caller retains ownership of the array; values are copied into the table's internal storage.

stat_tap_iterate_tables()

WS_DLL_PUBLIC void stat_tap_iterate_tables	(	wmem_foreach_func	func,
		void *	user_data
	)

Iterate over all registered table-based statistics tap UIs.

Parameters

func	The callback to invoke for each registered descriptor. Signature: bool func(const void *key, void *value, void *user_data)
user_data	Caller-supplied context pointer passed through to func.

stat_tap_set_field_data()

WS_DLL_PUBLIC void stat_tap_set_field_data	(	stat_tap_table *	stat_table,
		unsigned	table_index,
		unsigned	field_index,
		stat_tap_table_item_type *	field_data
	)

Set field data for a specific table and field index.

Parameters

stat_table	Pointer to the stat_tap_table structure.
table_index	Index of the table within the stat_tap_table.
field_index	Index of the field within the specified table.
field_data	Pointer to the new field data to be set.