Struct ExtcapArgs

pub struct ExtcapArgs {
    pub extcap_interfaces: bool,
    pub extcap_version: Option<String>,
    pub extcap_config: bool,
    pub extcap_dlts: bool,
    pub capture: bool,
    pub extcap_interface: Option<String>,
    pub fifo: Option<PathBuf>,
    pub extcap_capture_filter: Option<String>,
    pub extcap_control_in: Option<PathBuf>,
    pub extcap_control_out: Option<PathBuf>,
    pub extcap_reload_option: Option<String>,
}

The arguments defined by extcap. These arguments are usable as a clap parser.

For example, if you use clap with the feature derive:

#[derive(Debug, Parser)]
#[command(author, version, about)]
pub struct ApplicationArgs {
   #[command(flatten)]
   extcap: r_extcap::ExtcapArgs,

   // Other application args
}

Wireshark will call extcap in 4 phases:

1. --extcap-interfaces: Declare all supported interfaces and controls.
2. --extcap-config: Called for each interface to declare configuration options that can be changed by the user in the UI. (This is used only in Wireshark, not available in tshark).
3. --extcap-dlts: Called for each interface returned in --extcap-interfaces to specify which Data Link Type is being captured.
4. --capture: Called to initiate capture of the packets. See the documentation on the field for details.

When the capturing stops (i.e. the user presses the red Stop button), SIGTERM is sent by Wireshark.

Fields

extcap_interfaces: bool

First step in the extcap exchange: this program is queried for its interfaces.

$ extcapbin --extcap-interfaces

This call must print the existing interfaces for this extcap and must return 0. The output must conform to the grammar specified in the doc/extcap.4 man pages.

extcap_version: Option<String>

The version of Wireshark (or tshark) calling into this extcap.

Wireshark 2.9 and later pass --extcap-version=x.x when querying for the list of interfaces, which provides the calling Wireshark’s major and minor version. This can be used to change behavior depending on the Wireshark version in question.

This argument is passed during the --extcap-interfaces call.

extcap_config: bool

Second step in the extcap exchange: this program is asked for the configuration of each specific interface

$ extcap_example.py --extcap-interface <iface> --extcap-config

Each interface can have custom options that are valid for this interface only. Those config options are specified on the command line when running the actual capture. To allow an end-user to specify certain options, such options may be provided using the extcap config argument.

To share which options are available for an interface, the extcap responds to the command --extcap-config, which shows all the available options (aka additional command line options).

Those options are used to build a configuration dialog for the interface.

extcap_dlts: bool

Third step in the extcap exchange: the extcap binary is queried for all valid DLTs for all the interfaces returned during --extcap-interfaces).

$ extcap_example.py --extcap-dlts --extcap-interface <iface>

This call must print the valid DLTs for the interface specified. This call is made for all the interfaces and must return exit code 0.

Example for the DLT query.

$ extcap_example.py --extcap-interface IFACE --extcap-dlts
dlt {number=147}{name=USER1}{display=Demo Implementation for Extcap}

A binary or script which neither provides an interface list or a DLT list will not show up in the extcap interfaces list.

capture: bool

Start the capturing phase.

In addition to --capture, the --extcap-capture-filter and --fifo options are also required in this phase.

Additionally, if {config} entries were returned during the --extcap-interfaces phase, then --extcap-control-in and --extcap-control-out will be passed, which are a pair of fifos in which control messages are sent.

extcap_interface: Option<String>

The extcap interface to perform the operation on.

This should match one of the values returned earlier in extcap_interfaces, and is used in the capture, extcap_config, and extcap_dlts phases.

fifo: Option<PathBuf>

Specifies the fifo for the packet captures. The extcap implementation should write the captured packets to this fifo in pcap or pcapng format.

extcap_capture_filter: Option<String>

The capture filter provided by wireshark. This extcap should avoid capturing packets that do not match this filter. Used during the --capture phase.

extcap_control_in: Option<PathBuf>

Used to get control messages from toolbar. Control messages are in the format documented in ControlPacket.

extcap_control_out: Option<PathBuf>

Used to send control messages to toolbar. Control messages are in the format documented in ControlPacket.

extcap_reload_option: Option<String>

A SelectorConfig may be reloaded from the configuration dialog of the extcap application within Wireshark. With SelectorConfig::reload (defaults to false), the entry can be marked as reloadable.

use r_extcap::config::{ConfigOptionValue, SelectorConfig, Reload};

SelectorConfig::builder()
    .config_number(3)
    .call("remote")
    .display("Remote Channel")
    .tooltip("Remote Channel Selector")
    .reload(Reload {
        label: String::from("Load interfaces..."),
        reload_fn: || {
            vec![
                ConfigOptionValue::builder()
                    .value("if3")
                    .display("Remote Interface 3")
                    .default(true)
                    .build(),
                ConfigOptionValue::builder()
                    .value("if4")
                    .display("Remote Interface 4")
                    .build(),
            ]
        }
    })
    .default_options([
        ConfigOptionValue::builder()
            .value("if1")
            .display("Remote1")
            .default(true)
            .build(),
        ConfigOptionValue::builder().value("if2").display("Remote2").build(),
    ])
    .build();

After this has been defined, the user will get a button displayed in the configuration dialog for this extcap application, with the text “Load interfaces…​”.

The extcap utility is then called again with all filled out arguments and the additional parameter --extcap-reload-option <option_name>. It is expected to return a value section for this option, as it would during normal configuration. The provided option list is then presented as the selection, a previous selected option will be reselected if applicable.

Implementations

impl ExtcapArgs

pub fn run(&self) -> Result<ExtcapStep<'_>, ExtcapError>

Runs the extcap program with the parsed arguments. This is the main entry point for the extcap program. Implementations should call this from their main functions.

For detailed usage, see the crate documentation

Trait Implementations

impl Args for ExtcapArgs

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

fn augment_args<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_args_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

impl Debug for ExtcapArgs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for ExtcapArgs

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.