print.h File Reference

#include <stdio.h>
#include <epan/epan.h>
#include <epan/packet.h>
#include <epan/print_stream.h>
#include <wsutil/json_dumper.h>
#include "ws_symbol_export.h"

Go to the source code of this file.

Macros
#define	HEXDUMP_SOURCE_MASK   (0x0004U)
#define	HEXDUMP_SOURCE_OPTION(option)   ((option) & HEXDUMP_SOURCE_MASK)
#define	HEXDUMP_SOURCE_MULTI   (0x0000U) /* create hexdumps for all data sources assigned to a frame (legacy tshark behaviour) */
#define	HEXDUMP_SOURCE_PRIMARY   (0x0004U) /* create hexdumps for only the frame data */
#define	HEXDUMP_TIMESTAMP_MASK   (0x0008U)
#define	HEXDUMP_TIMESTAMP_OPTION(option)   ((option) & HEXDUMP_TIMESTAMP_MASK)
#define	HEXDUMP_TIMESTAMP_NONE   (0x0000U) /* create hexdumps for all data sources assigned to a frame (default behavior) */
#define	HEXDUMP_TIMESTAMP   (0x0008U) /* create hexdumps for only the frame data */

Typedefs
typedef struct _output_fields	output_fields_t
typedef GSList *(*	proto_node_children_grouper_func) (proto_node *node)

Enumerations
enum	print_format_e { PR_FMT_TEXT , PR_FMT_PS }
	Output format for printed packet data. More...
enum	print_dissections_e { print_dissections_none , print_dissections_collapsed , print_dissections_as_displayed , print_dissections_expanded }
	Controls the level of protocol dissection detail included in printed output. More...
enum	fields_format { FORMAT_CSV , FORMAT_JSON , FORMAT_EK , FORMAT_XML }
	Output serialization format for field export (e.g., via tshark -T). More...
enum	pf_flags { PF_NONE = 0x00 , PF_INCLUDE_CHILDREN = 0x01 }
	Bitmask flags controlling protocol field printing behavior. More...

Functions
WS_DLL_PUBLIC output_fields_t *	output_fields_new (void)
	Create a new instance of output_fields_t.
WS_DLL_PUBLIC void	output_fields_free (output_fields_t *info)
	Free the memory allocated for an output_fields_t structure.
WS_DLL_PUBLIC void	output_fields_add (output_fields_t *info, const char *field)
	Adds a field to the output fields list.
WS_DLL_PUBLIC GSList *	output_fields_valid (output_fields_t *info)
	Retrieves the list of valid output fields.
WS_DLL_PUBLIC size_t	output_fields_num_fields (output_fields_t *info)
	Gets the number of fields in the output fields list.
WS_DLL_PUBLIC bool	output_fields_set_option (output_fields_t *info, char *option)
	Sets an option for the output fields.
WS_DLL_PUBLIC void	output_fields_list_options (FILE *fh)
	Outputs the list of available fields to a file handle.
WS_DLL_PUBLIC bool	output_fields_add_protocolfilter (output_fields_t *info, const char *field, pf_flags filter_flags)
	Adds a protocol filter to the output fields.
WS_DLL_PUBLIC bool	output_fields_has_cols (output_fields_t *info)
	Checks if the output fields have columns.
WS_DLL_PUBLIC void	output_fields_prime_edt (struct epan_dissect *edt, output_fields_t *info)
	Outputs fields in a prime EDT format.
WS_DLL_PUBLIC bool	proto_tree_print (print_dissections_e print_dissections, bool print_hex_data, epan_dissect_t *edt, GHashTable *output_only_tables, print_stream_t *stream)
	Prints the protocol tree.
WS_DLL_PUBLIC bool	print_hex_data (print_stream_t *stream, epan_dissect_t *edt, unsigned hexdump_options)
	Prints hexadecimal data to a stream.
WS_DLL_PUBLIC void	write_pdml_preamble (FILE *fh, const char *filename, const char *doc_dir)
	Writes the preamble for a PDML (Packet Data Markup Language) file.
WS_DLL_PUBLIC void	write_pdml_proto_tree (output_fields_t *fields, epan_dissect_t *edt, column_info *cinfo, FILE *fh, bool use_color)
	Writes a protocol tree in PDML format to a file.
WS_DLL_PUBLIC void	write_pdml_finale (FILE *fh)
	Writes the final PDML tag to the file.
WS_DLL_PUBLIC GSList *	proto_node_group_children_by_unique (proto_node *node)
WS_DLL_PUBLIC GSList *	proto_node_group_children_by_json_key (proto_node *node)
WS_DLL_PUBLIC json_dumper	write_json_preamble (FILE *fh)
	Writes the JSON preamble to the specified file handle.
WS_DLL_PUBLIC void	write_json_proto_tree (output_fields_t *fields, print_dissections_e print_dissections, bool print_hex_data, epan_dissect_t *edt, column_info *cinfo, proto_node_children_grouper_func node_children_grouper, json_dumper *dumper)
	Writes a protocol tree to JSON format.
WS_DLL_PUBLIC void	write_json_finale (json_dumper *dumper)
	Ends JSON output.
WS_DLL_PUBLIC void	write_ek_proto_tree (output_fields_t *fields, bool print_summary, bool print_hex_data, epan_dissect_t *edt, column_info *cinfo, FILE *fh)
	Writes protocol tree data in a specific format to a file.
WS_DLL_PUBLIC void	write_psml_preamble (column_info *cinfo, FILE *fh)
	Writes the PSML preamble to the specified file.
WS_DLL_PUBLIC void	write_psml_columns (epan_dissect_t *edt, FILE *fh, bool use_color)
	Writes PSML columns to a file.
WS_DLL_PUBLIC void	write_psml_finale (FILE *fh)
	Writes the final PSML tag to the file.
WS_DLL_PUBLIC void	write_csv_column_titles (column_info *cinfo, FILE *fh)
	Writes CSV column titles to a file.
WS_DLL_PUBLIC void	write_csv_columns (epan_dissect_t *edt, FILE *fh)
	Writes CSV columns to a file.
WS_DLL_PUBLIC void	write_carrays_hex_data (uint32_t num, FILE *fh, epan_dissect_t *edt)
	Writes hexadecimal data from a list of data sources to a file.
WS_DLL_PUBLIC void	write_fields_preamble (output_fields_t *fields, FILE *fh)
	Writes the preamble for fields output.
WS_DLL_PUBLIC void	write_fields_proto_tree (output_fields_t *fields, epan_dissect_t *edt, column_info *cinfo, FILE *fh)
	Writes specified fields to a protocol tree.
WS_DLL_PUBLIC void	write_fields_finale (output_fields_t *fields, FILE *fh)
	Writes the finale for fields output.
WS_DLL_PUBLIC char *	get_node_field_value (field_info *fi, epan_dissect_t *edt)
	Retrieves the value of a node field.
void	print_cache_field_handles (void)
	Prints cache field handles.

Detailed Description

Definitions for printing packet analysis trees.

Gilbert Ramirez gram@.nosp@m.alum.nosp@m.ni.ri.nosp@m.ce.e.nosp@m.du

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

Enumeration Type Documentation

fields_format

enum fields_format

Output serialization format for field export (e.g., via tshark -T).

Enumerator
FORMAT_CSV	Comma-separated values (CSV)
FORMAT_JSON	JSON object output
FORMAT_EK	Newline-delimited JSON formatted for Elasticsearch bulk insert
FORMAT_XML	PDML (Packet Details Markup Language) XML output

pf_flags

enum pf_flags

Bitmask flags controlling protocol field printing behavior.

Enumerator
PF_NONE	No flags set; default behavior
PF_INCLUDE_CHILDREN	Also print all child fields of a matched field

print_dissections_e

enum print_dissections_e

Controls the level of protocol dissection detail included in printed output.

Enumerator
print_dissections_none	Omit all dissection output
print_dissections_collapsed	Include dissection tree nodes but no expanded detail
print_dissections_as_displayed	Include dissection detail exactly as shown in the GUI
print_dissections_expanded	Include all dissection detail, fully expanded

print_format_e

enum print_format_e

Output format for printed packet data.

Enumerator
PR_FMT_TEXT	Plain text output
PR_FMT_PS	PostScript output

Function Documentation

get_node_field_value()

WS_DLL_PUBLIC char * get_node_field_value	(	field_info *	fi,
		epan_dissect_t *	edt
	)

Retrieves the value of a node field.

Parameters

fi	Pointer to the field_info structure containing the field information.
edt	Pointer to the epan_dissect_t structure containing the dissection context.

Returns

char* The value of the field as a string, or NULL if not found.

output_fields_add()

WS_DLL_PUBLIC void output_fields_add	(	output_fields_t *	info,
		const char *	field
	)

Adds a field to the output fields list.

Parameters

info	Pointer to the output_fields_t structure.
field	The field to be added.

output_fields_add_protocolfilter()

WS_DLL_PUBLIC bool output_fields_add_protocolfilter	(	output_fields_t *	info,
		const char *	field,
		pf_flags	filter_flags
	)

Adds a protocol filter to the output fields.

Parameters

info	Pointer to the output_fields_t structure.
field	The name of the field to be added as a protocol filter.
filter_flags	Flags to specify how the protocol filter should be applied (e.g., whether to include child fields).

Returns

true if the protocol filter was successfully added, false otherwise

output_fields_free()

WS_DLL_PUBLIC void output_fields_free

(

output_fields_t *

info

)

Free the memory allocated for an output_fields_t structure.

Parameters

info	Pointer to the output_fields_t structure to be freed.

output_fields_has_cols()

WS_DLL_PUBLIC bool output_fields_has_cols

(

output_fields_t *

info

)

Checks if the output fields have columns.

Parameters

info	Pointer to the output_fields_t structure.

Returns

true if the output fields have columns, false otherwise.

output_fields_list_options()

WS_DLL_PUBLIC void output_fields_list_options

(

FILE *

fh

)

Outputs the list of available fields to a file handle.

Parameters

fh	File handle where the list of fields will be printed.

output_fields_new()

WS_DLL_PUBLIC output_fields_t * output_fields_new

(

void

)

Create a new instance of output_fields_t.

Returns

A pointer to the newly created output_fields_t structure.

output_fields_num_fields()

WS_DLL_PUBLIC size_t output_fields_num_fields

(

output_fields_t *

info

)

Gets the number of fields in the output fields list.

Parameters

info	Pointer to the output_fields_t structure.

Returns

The number of fields in the list.

output_fields_prime_edt()

WS_DLL_PUBLIC void output_fields_prime_edt	(	struct epan_dissect *	edt,
		output_fields_t *	info
	)

Outputs fields in a prime EDT format.

Parameters

edt	The epan_dissect structure containing packet information.
info	The output_fields_t structure containing field information.

output_fields_set_option()

WS_DLL_PUBLIC bool output_fields_set_option	(	output_fields_t *	info,
		char *	option
	)

Sets an option for the output fields.

Parameters

info	Pointer to the output_fields_t structure.
option	The option to set.

Returns

true if the option was successfully set, false otherwise.

output_fields_valid()

WS_DLL_PUBLIC GSList * output_fields_valid

(

output_fields_t *

info

)

Retrieves the list of valid output fields.

Parameters

info	Pointer to the output_fields_t structure.

Returns

A pointer to the list of valid output fields.

print_cache_field_handles()

void print_cache_field_handles ( void  )

extern

Prints cache field handles.

This function retrieves and prints the IDs of the "Data" and "Frame" protocol fields.

print_hex_data()

WS_DLL_PUBLIC bool print_hex_data	(	print_stream_t *	stream,
		epan_dissect_t *	edt,
		unsigned	hexdump_options
	)

Prints hexadecimal data to a stream.

Parameters

stream	The output stream where the hex data will be printed.
edt	The epan dissector context containing the packet information.
hexdump_options	Options for how the hex data should be displayed.

Returns

true if successful, false otherwise.

proto_node_group_children_by_json_key()

WS_DLL_PUBLIC GSList * proto_node_group_children_by_json_key

(

proto_node *

node

)

Groups the children of a node by their json key. Children are put in the same group if they have the same json key.

Returns

Linked list where each element is another linked list of nodes associated with the same json key.

For each different json key we store a linked list of values corresponding to that json key. These lists are kept in both a linked list and a hashmap. The hashmap is used to quickly retrieve the values of a json key. The linked list is used to preserve the ordering of keys as they are encountered which is not guaranteed when only using a hashmap.

For each child of the node get the key and get the list of values already associated with that key from the hashmap. If no list exist yet for that key create a new one and add it to both the linked list and hashmap. If a list already exists add the node to that list.

proto_node_group_children_by_unique()

WS_DLL_PUBLIC GSList * proto_node_group_children_by_unique

(

proto_node *

node

)

Groups each child of the node separately.

Returns

Linked list where each element is another linked list containing a single node.

proto_tree_print()

WS_DLL_PUBLIC bool proto_tree_print	(	print_dissections_e	print_dissections,
		bool	print_hex_data,
		epan_dissect_t *	edt,
		GHashTable *	output_only_tables,
		print_stream_t *	stream
	)

Prints the protocol tree.

Parameters

print_dissections	The level of dissection details to print.
print_hex_data	Whether to print hexadecimal data.
edt	The epan_dissect structure containing packet information.
output_only_tables	A hash table of tables to print, or NULL to print all tables.
stream	The print stream to which the output will be written.

Returns

true if successful, false otherwise.

write_carrays_hex_data()

WS_DLL_PUBLIC void write_carrays_hex_data	(	uint32_t	num,
		FILE *	fh,
		epan_dissect_t *	edt
	)

Writes hexadecimal data from a list of data sources to a file.

Parameters

num	Number of data sources to process.
fh	File handle where the data will be written.
edt	Pointer to the epan_dissect_t structure containing the data sources.

write_csv_column_titles()

WS_DLL_PUBLIC void write_csv_column_titles	(	column_info *	cinfo,
		FILE *	fh
	)

Writes CSV column titles to a file.

Parameters

cinfo	Pointer to the column information structure.
fh	File handle where the column titles will be written.

write_csv_columns()

WS_DLL_PUBLIC void write_csv_columns	(	epan_dissect_t *	edt,
		FILE *	fh
	)

Writes CSV columns to a file.

Parameters

edt	Pointer to the epan_dissect_t structure containing dissection data.
fh	File handle where the CSV columns will be written.

write_ek_proto_tree()

WS_DLL_PUBLIC void write_ek_proto_tree	(	output_fields_t *	fields,
		bool	print_summary,
		bool	print_hex_data,
		epan_dissect_t *	edt,
		column_info *	cinfo,
		FILE *	fh
	)

Writes protocol tree data in a specific format to a file.

Parameters

fields	Output fields structure containing relevant information.
print_summary	Flag indicating whether to print summary information.
print_hex_data	Flag indicating whether to print hexadecimal data.
edt	Pointer to the epan_dissect_t structure containing dissection data.
cinfo	Pointer to the column_info structure for column formatting.
fh	File handle where the output will be written.

write_fields_finale()

WS_DLL_PUBLIC void write_fields_finale	(	output_fields_t *	fields,
		FILE *	fh
	)

Writes the finale for fields output.

Parameters

fields	Pointer to the output_fields_t structure containing field information.
fh	File handle where the finale will be written.

write_fields_preamble()

WS_DLL_PUBLIC void write_fields_preamble	(	output_fields_t *	fields,
		FILE *	fh
	)

Writes the preamble for fields output.

Parameters

fields	Pointer to the output_fields_t structure containing field information.
fh	File handle where the preamble will be written.

write_fields_proto_tree()

WS_DLL_PUBLIC void write_fields_proto_tree	(	output_fields_t *	fields,
		epan_dissect_t *	edt,
		column_info *	cinfo,
		FILE *	fh
	)

Writes specified fields to a protocol tree.

Parameters

fields	The output fields to be written.
edt	The dissector information.
cinfo	Column information.
fh	File handle for output.

write_json_finale()

WS_DLL_PUBLIC void write_json_finale

(

json_dumper *

dumper

)

Ends JSON output.

Parameters

dumper

Pointer to the json_dumper structure.

write_json_preamble()

WS_DLL_PUBLIC json_dumper write_json_preamble

(

FILE *

fh

)

Writes the JSON preamble to the specified file handle.

Parameters

fh	File handle where the JSON output will be written.

Returns

json_dumper A json_dumper structure initialized with the provided file handle and pretty print flag.

write_json_proto_tree()

WS_DLL_PUBLIC void write_json_proto_tree	(	output_fields_t *	fields,
		print_dissections_e	print_dissections,
		bool	print_hex_data,
		epan_dissect_t *	edt,
		column_info *	cinfo,
		proto_node_children_grouper_func	node_children_grouper,
		json_dumper *	dumper
	)

Writes a protocol tree to JSON format.

Parameters

fields	Output fields configuration.
print_dissections	Type of dissection to print.
print_hex_data	Whether to include hexadecimal data in the output.
edt	The epan dissector context.
cinfo	Column information.
node_children_grouper	Function to group proto node children.
dumper	JSON dumper for output.

write_pdml_finale()

WS_DLL_PUBLIC void write_pdml_finale

(

FILE *

fh

)

Writes the final PDML tag to the file.

Parameters

fh	File handle where the PDML finale should be written.

write_pdml_preamble()

WS_DLL_PUBLIC void write_pdml_preamble	(	FILE *	fh,
		const char *	filename,
		const char *	doc_dir
	)

Writes the preamble for a PDML (Packet Data Markup Language) file.

Parameters

fh	File handle to write the preamble to.
filename	Name of the capture file, or NULL if not applicable.
doc_dir	Directory containing the XML stylesheet.

write_pdml_proto_tree()

WS_DLL_PUBLIC void write_pdml_proto_tree	(	output_fields_t *	fields,
		epan_dissect_t *	edt,
		column_info *	cinfo,
		FILE *	fh,
		bool	use_color
	)

Writes a protocol tree in PDML format to a file.

Parameters

fields	Output fields structure containing the fields to be printed.
edt	Epan dissector information.
cinfo	Column information.
fh	File handle where the PDML data will be written.
use_color	Whether to use color in the output.

write_psml_columns()

WS_DLL_PUBLIC void write_psml_columns	(	epan_dissect_t *	edt,
		FILE *	fh,
		bool	use_color
	)

Writes PSML columns to a file.

Parameters

edt	Pointer to epan_dissect_t structure containing dissection data.
fh	File handle where the PSML columns will be written.
use_color	Boolean indicating whether to use color filtering.

write_psml_finale()

WS_DLL_PUBLIC void write_psml_finale

(

FILE *

fh

)

Writes the final PSML tag to the file.

Parameters

fh	File handle where the PSML finale will be written.

write_psml_preamble()

WS_DLL_PUBLIC void write_psml_preamble	(	column_info *	cinfo,
		FILE *	fh
	)

Writes the PSML preamble to the specified file.

Parameters

cinfo	Pointer to column information structure.
fh	File handle where the PSML preamble will be written.