#include <glib.h>
#include <wsutil/plugins.h>
#include "epan/register.h"
#include "capture/capture_session.h"
#include <ui/capture_ui_utils.h>

Classes
struct	_extcap_info
	Metadata describing a registered extcap plugin binary. More...

Macros
#define	EXTCAP_BOOLEAN_REGEX "^.*([yt1-9])"

#define	EXTCAP_PIPE_PREFIX "wireshark_extcap"

#define	EXTCAP_CONTROL_IN_PREFIX "wireshark_control_ext_to_ws"

#define	EXTCAP_CONTROL_OUT_PREFIX "wireshark_control_ws_to_ext"

#define	EXTCAP_ARGUMENT_CONFIG "--extcap-config"

#define	EXTCAP_ARGUMENT_CONFIG_OPTION_NAME "--extcap-config-option-name"

#define	EXTCAP_ARGUMENT_CONFIG_OPTION_VALUE "--extcap-config-option-value"

#define	EXTCAP_ARGUMENT_RELOAD_OPTION "--extcap-reload-option"

#define	EXTCAP_ARGUMENT_LIST_INTERFACES "--extcap-interfaces"

#define	EXTCAP_ARGUMENT_INTERFACE "--extcap-interface"

#define	EXTCAP_ARGUMENT_LIST_DLTS "--extcap-dlts"

#define	EXTCAP_ARGUMENT_VERSION "--extcap-version"

#define	EXTCAP_ARGUMENT_RUN_CAPTURE "--capture"

#define	EXTCAP_ARGUMENT_CAPTURE_FILTER "--extcap-capture-filter"

#define	EXTCAP_ARGUMENT_RUN_PIPE "--fifo"

#define	EXTCAP_ARGUMENT_CLEANUP_POSTKILL "--extcap-cleanup-postkill"

#define	EXTCAP_ARGUMENT_CONTROL_IN "--extcap-control-in"

#define	EXTCAP_ARGUMENT_CONTROL_OUT "--extcap-control-out"

Typedefs
typedef struct _extcap_info	extcap_info
	Metadata describing a registered extcap plugin binary.

typedef void(*	extcap_plugin_description_callback) (const char , const char , const char , const char , void *)

Enumerations
enum	extcap_filter_status { EXTCAP_FILTER_UNKNOWN , EXTCAP_FILTER_VALID , EXTCAP_FILTER_INVALID }
	Result of validating a capture filter string against an extcap interface. More...

enum	extcap_argument_sufficient { EXTCAP_ARGUMENT_SUFFICIENT_NOTSET , EXTCAP_ARGUMENT_SUFFICIENT_REQUIRED , EXTCAP_ARGUMENT_SUFFICIENT_OK }
	Indicates whether all required extcap arguments have been provided. More...

Functions
void	extcap_register_preferences (register_cb cb, void *client_data)

if_capabilities_t *	extcap_get_if_dlts (const char ifname, char *err_str)

GList *	append_extcap_interface_list (GList *list)

extcap_info *	extcap_get_tool_info (const char *toolname)

extcap_info *	extcap_get_tool_by_ifname (const char *ifname)

char *	extcap_get_help_for_ifname (const char *ifname)

void	extcap_clear_interfaces (void)

void	extcap_get_descriptions (extcap_plugin_description_callback callback, void *callback_data)

void	extcap_dump_all (void)

GList *	extcap_get_if_configuration (const char *ifname)
	Returns the configuration for the given interface name, or an empty list, if no configuration has been found. Initializes the extcap interface list if that hasn't already been done.

GList *	extcap_get_if_configuration_option (const char ifname, const char argname, const char *argvalue)
	Returns the sub-configuration for a given argument name, or an empty list, if no configuration has been found. Initializes the extcap interface list if that hasn't already been done.

GList *	extcap_get_if_configuration_values (const char ifname, const char argname, GHashTable *arguments)

extcap_filter_status	extcap_verify_capture_filter (const char ifname, const char filter, char **err_str)
	Verifies a capture filter for an interface using extcap.

void	extcap_free_if_configuration (GList *list, bool free_args)

bool	extcap_has_configuration (const char *ifname)

bool	extcap_requires_configuration (const char *ifname)
	Checks if the specified interface requires configuration for extcap usage.

bool	extcap_has_toolbar (const char *ifname)

void	extcap_request_stop (capture_session *cap_session)

pref_t *	extcap_pref_for_argument (const char ifname, struct _extcap_arg arg)

void	extcap_cleanup (void)
	Clean up global extcap stuff on program exit.

Detailed Description

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

Enumeration Type Documentation

◆ extcap_argument_sufficient

enum extcap_argument_sufficient

Indicates whether all required extcap arguments have been provided.

Enumerator
EXTCAP_ARGUMENT_SUFFICIENT_NOTSET	Argument sufficiency has not yet been evaluated
EXTCAP_ARGUMENT_SUFFICIENT_REQUIRED	One or more required arguments have not been set
EXTCAP_ARGUMENT_SUFFICIENT_OK	All required arguments are set and capture may proceed

◆ extcap_filter_status

enum extcap_filter_status

Result of validating a capture filter string against an extcap interface.

Enumerator
EXTCAP_FILTER_UNKNOWN	Filter validity could not be determined
EXTCAP_FILTER_VALID	Filter was accepted as valid by the extcap
EXTCAP_FILTER_INVALID	Filter was rejected as invalid by the extcap

Function Documentation

◆ append_extcap_interface_list()

GList * append_extcap_interface_list ( GList * list )

Append a list of all extcap capture interfaces to the specified list. Initializes the extcap interface list if that hasn't already been done.

Parameters

list	An existing GList of if_info_t.

Returns: An updated list on success, an unchanged list on failure.

◆ extcap_cleanup()

void extcap_cleanup ( void )

Clean up global extcap stuff on program exit.

Releases the dynamic preference value pointers. Must not be called before prefs_cleanup since these pointers could still be in use.

◆ extcap_clear_interfaces()

void extcap_clear_interfaces ( void )

Remove all loaded extcap interfaces.

◆ extcap_dump_all()

void extcap_dump_all ( void )

Print information about all available extcap executables. Initializes the extcap interface list if that hasn't already been done.

◆ extcap_free_if_configuration()

void extcap_free_if_configuration	(	GList *	list,
		bool	free_args
	)

Frees the memory from extcap_get_if_configuration.

Parameters

list	The list returned by extcap_get_if_configuration.
free_args	true if all arguments in the list must be freed too or false if the ownership of the arguments is taken by the caller.

◆ extcap_get_descriptions()

void extcap_get_descriptions	(	extcap_plugin_description_callback	callback,
		void *	callback_data
	)

Retrieves information about all available extcap executables. Initializes the extcap interface list if that hasn't already been done.

Parameters

callback	The description callback routine.
callback_data	Data to be passed to the callback routine.

◆ extcap_get_help_for_ifname()

char * extcap_get_help_for_ifname ( const char * ifname )

Retrieves help information for an extcap interface. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname The extcap interface name.

Returns: A help string on success or NULL on failure.

◆ extcap_get_if_configuration()

GList * extcap_get_if_configuration ( const char * ifname )

Returns the configuration for the given interface name, or an empty list, if no configuration has been found. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname The interface name.

Returns: A list of configuration items on success, an empty list on failure.

◆ extcap_get_if_configuration_option()

GList * extcap_get_if_configuration_option	(	const char *	ifname,
		const char *	argname,
		const char *	argvalue
	)

Returns the sub-configuration for a given argument name, or an empty list, if no configuration has been found. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname	The interface name.
argname	The name of the argument for which the sub-configuration should be retrieved.
argvalue	The value of the argument for which the sub-configuration should be retrieved

Returns: A list of sub-configuration items on success, an empty list on failure.

◆ extcap_get_if_configuration_values()

GList * extcap_get_if_configuration_values	(	const char *	ifname,
		const char *	argname,
		GHashTable *	arguments
	)

Returns the configuration values for the given argument, or an empty list, if no values could been found. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname	The interface name.
argname	The name of the argument for which the values should be retrieved.
arguments	A hash table of argument name and value pairs to be passed to the extcap plugin.

Returns: A list of configuration values on success, an empty list on failure.

◆ extcap_get_if_dlts()

if_capabilities_t * extcap_get_if_dlts	(	const char *	ifname,
		char **	err_str
	)

Fetches the interface capabilities for the named extcap interface. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname	The interface name.
err_str	Set to NULL on success, error description on failure.

Returns: The interface capabilities on success, NULL on failure.

◆ extcap_get_tool_by_ifname()

extcap_info * extcap_get_tool_by_ifname ( const char * ifname )

Retrieves information about an extcap interface. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname The extcap interface name.

Returns: The extcap information on success, NULL on failure.

◆ extcap_get_tool_info()

extcap_info * extcap_get_tool_info ( const char * toolname )

Retrieves information about an extcap executable. Initializes the extcap interface list if that hasn't already been done.

Parameters

toolname The extcap name.

Returns: The extcap information on success, NULL on failure.

◆ extcap_has_configuration()

bool extcap_has_configuration ( const char * ifname )

Checks to see if an interface has configurable options. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname Interface to check.

◆ extcap_has_toolbar()

bool extcap_has_toolbar ( const char * ifname )

Checks to see if the interface has an associated toolbar. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname Interface to check.

Returns: true if the interface has a toolbar, false otherwise.

◆ extcap_pref_for_argument()

pref_t * extcap_pref_for_argument	(	const char *	ifname,
		struct _extcap_arg *	arg
	)

Fetch an extcap preference for a given argument. Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname	The interface to check.
arg	The command line argument to check.

Returns: The associated preference on success, NULL on failure.

◆ extcap_register_preferences()

void extcap_register_preferences	(	register_cb	cb,
		void *	client_data
	)

Registers preferences for all interfaces. Initializes the extcap interface list if that hasn't already been done.

Parameters

cb	Optional callback for progress reporting (may be NULL).
client_data	Data pointer passed through to the callback.

◆ extcap_request_stop()

void extcap_request_stop ( capture_session * cap_session )

Notify all extcaps that capture session should be stopped. Forcefully stop session if extcaps do not finish before timeout.

Parameters

cap_session Capture session.

◆ extcap_requires_configuration()

bool extcap_requires_configuration ( const char * ifname )

Checks if the specified interface requires configuration for extcap usage.

Checks if an interface has configurable options and if all are configured. Returns true when the extcap interface has configurable options that required modification. (For example, when an argument is required but empty.) Initializes the extcap interface list if that hasn't already been done.

Parameters

ifname Interface to check.

Returns: true If the interface requires configuration, false otherwise.

◆ extcap_verify_capture_filter()

extcap_filter_status extcap_verify_capture_filter	(	const char *	ifname,
		const char *	filter,
		char **	err_str
	)

Verifies a capture filter for an interface using extcap.

Parameters

ifname	The name of the network interface to verify the filter for.
filter	The capture filter to be verified.
err_str	A pointer to a string where any error message will be stored.

Returns: The status of the filter verification.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ extcap_argument_sufficient

◆ extcap_filter_status

Function Documentation

◆ append_extcap_interface_list()

◆ extcap_cleanup()

◆ extcap_clear_interfaces()

◆ extcap_dump_all()

◆ extcap_free_if_configuration()

◆ extcap_get_descriptions()

◆ extcap_get_help_for_ifname()

◆ extcap_get_if_configuration()

◆ extcap_get_if_configuration_option()

◆ extcap_get_if_configuration_values()

◆ extcap_get_if_dlts()

◆ extcap_get_tool_by_ifname()

◆ extcap_get_tool_info()

◆ extcap_has_configuration()

◆ extcap_has_toolbar()

◆ extcap_pref_for_argument()

◆ extcap_register_preferences()

◆ extcap_request_stop()

◆ extcap_requires_configuration()

◆ extcap_verify_capture_filter()