report_message.h File Reference

#include <wireshark.h>

Go to the source code of this file.

Classes
struct	report_message_routines

Functions
WS_DLL_PUBLIC void	init_report_message (const char *friendly_program_name, const struct report_message_routines *routines)
	Initialize the report message system with program context and output routines.
WS_DLL_PUBLIC void	report_failure (const char *msg_format,...)
	Report a general error message.
WS_DLL_PUBLIC void	report_warning (const char *msg_format,...)
	Report a general warning message.
WS_DLL_PUBLIC void	report_open_failure (const char *filename, int err, bool for_writing)
	Reports an error encountered while opening a file.
WS_DLL_PUBLIC void	report_read_failure (const char *filename, int err)
	Reports an error encountered while reading a file.
WS_DLL_PUBLIC void	report_write_failure (const char *filename, int err)
	Reports an error encountered while writing a file.
WS_DLL_PUBLIC void	report_rename_failure (const char *old_filename, const char *new_filename, int err)
	Reports an error encountered while renaming a file.
WS_DLL_PUBLIC void	report_cfile_open_failure (const char *filename, int err, char *err_info)
	Reports an error encountered while opening a capture file for reading.
WS_DLL_PUBLIC void	report_cfile_dump_open_failure (const char *filename, int err, char *err_info, int file_type_subtype)
	Reports an error encountered while opening a capture file for writing (dumping).
WS_DLL_PUBLIC void	report_cfile_read_failure (const char *filename, int err, char *err_info)
	Reports an error encountered while reading from a capture file.
WS_DLL_PUBLIC void	report_cfile_write_failure (const char *in_filename, const char *out_filename, int err, char *err_info, uint64_t framenum, int file_type_subtype)
	Reports an error encountered while writing to a capture file.
WS_DLL_PUBLIC void	report_cfile_close_failure (const char *filename, int err, char *err_info)
	Reports an error encountered while closing a capture file that was open for writing.
WS_DLL_PUBLIC const char *	get_friendly_program_name (void)
	Return the "friendly" program name.

Detailed Description

Declarations of routines for code that can run in GUI and command-line environments to use to report errors and warnings to the user (e.g., I/O errors, or problems with preference settings) if the message should be shown as a GUI error in a GUI environment.

The application using libwsutil will register message-reporting routines, and the routines declared here will call the registered routines. That way, these routines can be called by code that doesn't itself know whether to pop up a dialog or print something to the standard error.

XXX - Should the capture file (cfile) routines be moved to libwiretap?

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

Function Documentation

get_friendly_program_name()

WS_DLL_PUBLIC const char * get_friendly_program_name

(

void

)

Return the "friendly" program name.

Returns

The friendly program name registered with init_report_message(), or NULL if it has not been registered.

init_report_message()

WS_DLL_PUBLIC void init_report_message	(	const char *	friendly_program_name,
		const struct report_message_routines *	routines
	)

Initialize the report message system with program context and output routines.

This function sets up the global reporting mechanism used for error, warning, and informational messages. It registers the program name and the set of callback routines that handle message output.

Parameters

friendly_program_name	A human-readable name for the program (e.g., "Wireshark"). This name may be included in formatted messages.
routines	Pointer to a structure containing function pointers for handling different types of report messages (e.g., errors, warnings, debug).

Note

This function should be called early during application initialization, before any report messages are emitted.

report_cfile_close_failure()

WS_DLL_PUBLIC void report_cfile_close_failure	(	const char *	filename,
		int	err,
		char *	err_info
	)

Reports an error encountered while closing a capture file that was open for writing.

Parameters

filename	Path of the capture file that could not be closed cleanly.
err	Wiretap error code describing the failure.
err_info	Auxiliary error information string from Wiretap; may be NULL. The callee takes ownership and frees this string.

report_cfile_dump_open_failure()

WS_DLL_PUBLIC void report_cfile_dump_open_failure	(	const char *	filename,
		int	err,
		char *	err_info,
		int	file_type_subtype
	)

Reports an error encountered while opening a capture file for writing (dumping).

Parameters

filename	Path of the capture file that could not be opened.
err	Wiretap error code describing the failure.
err_info	Auxiliary error information string from Wiretap; may be NULL. The callee takes ownership and frees this string.
file_type_subtype	Wiretap file-type subtype that was requested for the output file.

report_cfile_open_failure()

WS_DLL_PUBLIC void report_cfile_open_failure	(	const char *	filename,
		int	err,
		char *	err_info
	)

Reports an error encountered while opening a capture file for reading.

Parameters

filename	Path of the capture file that could not be opened.
err	Wiretap error code describing the failure.
err_info	Auxiliary error information string from Wiretap; may be NULL. The callee takes ownership and frees this string.

report_cfile_read_failure()

WS_DLL_PUBLIC void report_cfile_read_failure	(	const char *	filename,
		int	err,
		char *	err_info
	)

Reports an error encountered while reading from a capture file.

Parameters

filename	Path of the capture file being read.
err	Wiretap error code describing the failure.
err_info	Auxiliary error information string from Wiretap; may be NULL. The callee takes ownership and frees this string.

report_cfile_write_failure()

WS_DLL_PUBLIC void report_cfile_write_failure	(	const char *	in_filename,
		const char *	out_filename,
		int	err,
		char *	err_info,
		uint64_t	framenum,
		int	file_type_subtype
	)

Reports an error encountered while writing to a capture file.

Parameters

in_filename	Path of the source capture file being read during the operation, or NULL if the operation is not a read-write conversion.
out_filename	Path of the destination capture file being written.
err	Wiretap error code describing the failure.
err_info	Auxiliary error information string from Wiretap; may be NULL. The callee takes ownership and frees this string.
framenum	One-based frame number of the packet that triggered the error.
file_type_subtype	Wiretap file-type subtype of the output file.

report_failure()

WS_DLL_PUBLIC void report_failure	(	const char *	msg_format,
			...
	)

Report a general error message.

Formats and emits an error message using the global reporting system.

Parameters

msg_format	printf-style format string.
...	Arguments matching the format string.

report_open_failure()

WS_DLL_PUBLIC void report_open_failure	(	const char *	filename,
		int	err,
		bool	for_writing
	)

Reports an error encountered while opening a file.

err is assumed to be a Wiretap error code; positive values are UNIX-style errnos, so this function may also be used for open failures that do not originate from Wiretap, provided the failure code is a plain errno.

Parameters

filename	Path of the file that could not be opened.
err	Wiretap or UNIX errno error code describing the failure.
for_writing	true if the file was being opened for writing; false if it was being opened for reading.

report_read_failure()

WS_DLL_PUBLIC void report_read_failure	(	const char *	filename,
		int	err
	)

Reports an error encountered while reading a file.

Parameters

filename	Path of the file that could not be read.
err	UNIX errno error code describing the failure.

report_rename_failure()

WS_DLL_PUBLIC void report_rename_failure	(	const char *	old_filename,
		const char *	new_filename,
		int	err
	)

Reports an error encountered while renaming a file.

Parameters

old_filename	Path of the file before the rename attempt.
new_filename	Intended path after the rename.
err	UNIX errno error code describing the failure.

report_warning()

WS_DLL_PUBLIC void report_warning	(	const char *	msg_format,
			...
	)

Report a general warning message.

Formats and emits a warning message using the global reporting system.

Parameters

msg_format	printf-style format string.
...	Arguments matching the format string.

report_write_failure()

WS_DLL_PUBLIC void report_write_failure	(	const char *	filename,
		int	err
	)

Reports an error encountered while writing a file.

Parameters

filename	Path of the file that could not be written.
err	UNIX errno error code describing the failure.